AST-Based Validation for React Components in Stitch-Skills: Rules and Implementation

The AST-based validator in stitch-skills analyzes React component source code using @swc/core to enforce naming conventions, prevent hard-coded styling values, and ensure platform-specific constraints, exiting with status code 1 when violations are detected.

The stitch-skills repository provides two command-line validators that perform AST-based validation on React components by traversing the abstract syntax tree generated from TypeScript TSX files. These validators support both web-focused React components and React Native mobile components, catching structural and stylistic violations before code reaches production.

How the AST-Based Validator Works

The validator relies on @swc/core to parse component source code into an AST using swc.parse(code, { syntax: "typescript", tsx: true }). A recursive depth-first traversal (implemented in the walk function) inspects node types and properties to detect violations without executing the code or performing type-checking.

The walk function recursively processes AST nodes, aggregates violations, and ignores the span property (which contains location metadata). This purely static analysis enables rapid validation of component structure without runtime overhead.

Validation Rules for React Components

The web-focused validator located at plugins/stitch-build/skills/react-components/scripts/validate.js enforces three specific rules for UI components.

Props Interface Naming Conventions

The validator searches for TsInterfaceDeclaration nodes whose identifiers end with Props. This ensures components define clear, discoverable prop types following the project's naming standards.

• ✅ Pass: "Props declaration found."
• ❌ Fail: "Missing Props interface (must end in 'Props')"

Hard-Coded Colour Detection

The validator scans StringLiteral nodes for hexadecimal patterns (/#[0-9A-Fa-f]{3,8}\b/) and RGB/RGBA values (/^rgba?\(/). When detected, the validator reports: "Found X hardcoded colours. Use theme.ts instead."

Class-Name Hard-Coded Styles

For web components, the validator examines JSXAttribute nodes with the name className, checking their values against the hex colour regex. This prevents developers from embedding hard-coded hex codes directly into CSS class assignments.

Validation Rules for React Native Components

The React Native validator at plugins/stitch-build/skills/react-native/scripts/validate.js extends the base rules with additional mobile-specific constraints.

Exported Props Interface Requirements

React Native components must export their Props interface. The validator checks if the TsInterfaceDeclaration resides within an ExportDeclaration node.

• ✅ Pass: "Exported Props interface found."
• ⚠️ Warning: "Props interface found but not exported."
• ❌ Fail: "Missing Props interface (must be exported)"

HTML Element Usage Restrictions

Since React Native does not support HTML tags, the validator inspects JSXOpeningElement nodes against a whitelist of HTML tags (div, span, p, etc.). When found, it reports: "Found HTML elements: [tag names]. Replace with React Native components."

Shared Hard-Coded Colour Checks

Both validators implement identical colour literal detection using StringLiteral node analysis, ensuring mobile components also reference the centralized theme system rather than inline colour values.

Running the Validators

Execute the web component validator from the repository root:

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

Execute the React Native validator:

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

Example Output

Valid component output:

--- Validation for: Button.tsx ---
✅ Props declaration found.
✅ No hardcoded hex values found.

✨ COMPONENT VALID.

Invalid component output:

--- Validation for: Card.tsx ---
FAIL: Missing Props interface (must end in 'Props' and be exported).
FAIL: Found 2 hardcoded colours. Use theme.ts instead.
FAIL: Found HTML elements: div, img. Replace with React Native components.

VALIDATION FAILED.

CI Integration and Exit Codes

The validator aggregates all violations during the AST walk and prints a summary. It exits with status 0 for valid components or status 1 when violations exist, enabling CI pipelines to fail builds automatically when components violate the established rules.

Summary

• AST-based validation in stitch-skills uses @swc/core to parse TypeScript TSX files into traversable syntax trees via swc.parse().
• The React Components validator (plugins/stitch-build/skills/react-components/scripts/validate.js) enforces Props interface naming and prevents hard-coded colours in both string literals and className attributes.
• The React Native validator (plugins/stitch-build/skills/react-native/scripts/validate.js) adds checks for exported Props interfaces and bans HTML element usage in JSX.
• Both validators employ a recursive depth-first traversal (walk function) to inspect TsInterfaceDeclaration, StringLiteral, JSXOpeningElement, and JSXAttribute nodes.
• The process exits with status 1 on validation failures, supporting automated CI/CD quality gates.

Frequently Asked Questions

What AST parser does the stitch-skills validator use?

The validator uses @swc/core to generate the AST, calling swc.parse(code, { syntax: "typescript", tsx: true }) to handle TypeScript TSX syntax. This provides a high-performance, Rust-based parsing solution that produces the node tree traversed by the validation rules.

How does the validator detect hard-coded colours in React components?

The validator identifies StringLiteral AST nodes and tests their values against regular expressions for hexadecimal colours (/#[0-9A-Fa-f]{3,8}\b/) and RGB/RGBA formats (/^rgba?\(/). For web components, it additionally inspects JSXAttribute nodes with the name className to catch hex values embedded in CSS class strings.

Why does the React Native validator require exported Props interfaces?

React Native components must expose their type definitions for external consumption and tool integration. The validator checks if the TsInterfaceDeclaration is a child of an ExportDeclaration node, ensuring the Props interface is publicly accessible rather than defined as a private internal type.

Can the validator be integrated into CI/CD pipelines?

Yes. The validator exits with status 0 when a component passes all checks and status 1 when violations are detected. This exit code behavior allows build systems to automatically fail commits or pull requests that contain components with hard-coded colours, missing Props interfaces, or platform-specific violations.

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