@hero-design/snowflake-guard/README.md

A hero-design bot detecting snowflake usage

# @hero-design/snowflake-guard

## Overview

A GitHub App built with [Probot](https://github.com/probot/probot) that analyzes PR changes and reports snowflake usage of Hero Design components. The bot detects when components are customized using inline styles, styled-components, sx props, or className attributes that may violate design system guidelines.

## Prerequisites

- Node.js >= 10.13.0
- Yarn package manager
- Access to [internal-tool-integrations service](https://github.com/Thinkei/internal-tool-integrations) for storing reports
- GitHub App installation permissions for the repository

## Development

### Setup

1. Copy `.env.example` to `.env` and ask Andromeda team for variable details.

```sh
cp .env.example .env
```

For React Native projects, include your repo name in the `MOBILE_REPO_NAMES` env variable.

2. Set up [internal-tool-integrations service](https://github.com/Thinkei/internal-tool-integrations) for the bot to store report.

- Replace `DB_HOST` with the host of the internal-tool-integrations service.
- Use the same `SNOWFLAKE_GUARD_SECRET` as the one in the internal-tool-integrations service.

In case you don't want to store snowflake report, comment out the `saving report` section in `src/index.ts`.

3. Install snowflake-guard[Dev] [app](https://github.com/apps/hero-design-snowflake-guard-dev) to a repository that you wish to run the app on.

4. Start `internal-tool-integrations` service.

5. Start the bot.

```sh
# Install dependencies
yarn install

# Run the bot
yarn start
```

6. Open or update a pull request to trigger webhook events.

### Scripts

- `yarn build` - Compile TypeScript to JavaScript
- `yarn start` - Build and run the bot with Probot
- `yarn test` - Run tests with Jest
- `yarn lint` - Run ESLint
- `yarn type-check` - Type check without emitting files
- `yarn deploy` - Deploy to Netlify
- `yarn publish:npm` - Publish package to npm

## Project Structure

```
apps/snowflake-guard/
├── src/
│   ├── index.ts              # Main entry point, Probot app setup
│   ├── parseSource.ts        # Web source code parser
│   ├── parseMobileSource.ts  # Mobile source code parser
│   ├── parsers/              # TypeScript and Flow parsers
│   ├── reports/              # Snowflake detection logic
│   │   ├── constants.ts      # Report constants and configurations
│   │   ├── mobile/           # Mobile-specific report generators
│   │   └── ...               # Web report generators
│   ├── graphql/              # GraphQL queries for report storage
│   └── utils/                # Utility functions
├── netlify/                  # Netlify serverless functions
├── lib/                      # Compiled JavaScript output
└── package.json
```

## Deployment

The app is deployed to Netlify as a serverless function. Deployment is automated via GitHub Actions when a new version is published.

To deploy manually:

```sh
yarn deploy
```

This requires the `NETLIFY_AUTH_TOKEN` environment variable to be set.

## Contributing

This bot does not support hot-reload yet, please restart the app once you make any changes to the code.

To contribute:

1. Make changes to the source code in `src/`
2. Test locally with `yarn start`
3. Ensure tests pass with `yarn test`
4. Submit a pull request

Note: The bot analyzes PR diffs and comments on potential snowflake usage violations. Approved patterns can be marked with special comments like `@snowflake-guard/approved-inline-style` or `@snowflake-guard/approved-classname`.