How to Run the AST-Based Validator for React Components in Stitch Skills

Run the AST-based validator by executing node plugins/stitch-build/skills/react-components/scripts/validate.js <component-file> after ensuring @swc/core is installed, or invoke it via the skill command stitch::react-components --validate <path> from your Codex session.

The AST-based validator is a specialized tool in the google-labs-code/stitch-skills repository that statically analyzes React component files to enforce coding standards. It parses TypeScript/TSX source code into an abstract syntax tree using SWC, then walks the tree to verify interface naming conventions and detect hard-coded color values in Tailwind classes.

What the Validator Checks

The validator enforces two specific rules on React components:

1. Props Interface Requirement – The component must declare a TypeScript interface ending in Props (e.g., ButtonProps, CardProps).
2. No Hard-Coded Hex Colors – The component must not contain hexadecimal color literals (e.g., #ff0000) inside className JSX attributes, ensuring colors are managed through Tailwind's theme system rather than arbitrary values.

How the Validation Pipeline Works

The validator operates in three distinct phases as implemented in plugins/stitch-build/skills/react-components/scripts/validate.js.

Parsing with SWC

The script begins by invoking swc.parse from @swc/core to generate a JavaScript/TypeScript AST from the source file. This step handles both TypeScript syntax and TSX markup, producing a traversable tree structure at line 27 of the validator.

Walking the AST

A recursive walk function traverses every node in the tree (lines 33-39). During traversal, the validator specifically targets:

• TsInterfaceDeclaration nodes whose identifier ends with the suffix Props
• JSXAttribute nodes named className that contain string literals matching hex color patterns

When the walker encounters a className attribute, it inspects the string value for hard-coded hex codes using regex detection.

Reporting Results

After completing the tree traversal, the script prints a validation summary to the console (lines 43-63). It exits with status 0 if the component passes all checks, or 1 if violations are detected, making it suitable for integration into CI/CD pipelines or pre-commit hooks.

Running the Validator from the Command Line

Execute the validator directly against any .tsx or .jsx file using Node.js.

First, ensure the SWC dependency is available. If you are working within the react-components skill directory, the dependency is already declared in package.json; otherwise install it:

npm install @swc/core

Navigate to the repository root and run the validator script, passing the component path as the first argument:

node plugins/stitch-build/skills/react-components/scripts/validate.js src/components/MyComponent.tsx

Example Output

For a valid component that follows conventions:

🔍 Scanning AST...
--- Validation for: MyComponent.tsx ---
✅ Props declaration found.
✅ No hardcoded hex values found.

✨ COMPONENT VALID.

For a component missing a Props interface and containing hard-coded colors:

🔍 Scanning AST...
--- Validation for: BadComponent.tsx ---
❌ MISSING: Props interface (must end in 'Props').
❌ STYLE: Found 1 hardcoded hex codes.
 - #ff0000

🚫 VALIDATION FAILED.

Running the Validator via the Skill Interface

According to plugins/stitch-build/skills/react-components/SKILL.md, you can invoke the validator through the Stitch skill system without referencing the script path directly:

stitch::react-components --validate path/to/MyComponent.tsx

This command forwards the file path to the same validate.js script under the hood, providing a unified interface when working within Codex or Claude Code sessions.

Summary

• The AST-based validator is located at plugins/stitch-build/skills/react-components/scripts/validate.js in the google-labs-code/stitch-skills repository.
• It uses SWC (@swc/core) to parse TypeScript/TSX into an AST and walks the tree to check for Props interfaces and hard-coded hex colors.
• Run it via command line: node plugins/stitch-build/skills/react-components/scripts/validate.js <file>.
• Run it via skill interface: stitch::react-components --validate <file>.
• The script exits with code 0 for valid components and 1 for violations, supporting automation workflows.

Frequently Asked Questions

What dependencies does the AST-based validator require?

The validator requires @swc/core, which is listed as a dependency in plugins/stitch-build/skills/react-components/package.json. SWC handles the parsing of TypeScript and TSX syntax into an AST that the validator can traverse.

How does the validator detect hard-coded hex colors in Tailwind classes?

During the AST walk, the validator inspects JSXAttribute nodes with the name className. It extracts the string literal value and applies regex pattern matching to identify hexadecimal color codes (e.g., #ff0000), flagging them as style violations regardless of where they appear in the class string.

Can I run the validator on multiple files at once?

The current implementation in validate.js accepts a single file path as the first command-line argument. To validate multiple files, you must invoke the script separately for each file or wrap it in a shell loop that iterates over your component directory.

What exit codes does the validator return?

The validator returns exit code 0 when the component passes all checks (Props interface present, no hex colors found) and exit code 1 when any validation rule fails. This behavior allows the script to function as a gate in automated build systems or git hooks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}