@hero-design/snowflake-guard

Overview

A GitHub App built with 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 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.

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 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 to a repository that you wish to run the app on.

4. Start internal-tool-integrations service.

5. Start the bot.

# 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:

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.