Repository Verification Gate

Status: Production — documents the scripts/verify-repo.sh pipeline.

Objective

Single command that asserts repo health before merge (local + CI) across install integrity, schema validation, graph safety, type safety, build viability, and bundle size regression guards.

Stages

The verification pipeline runs the following stages in order:

1. InstallIntegrity: Verifies yarn install succeeded without errors
2. RegistrySchemaValidation: Validates packages/brands/registry.json against Zod schema (fail-fast)
3. TailwindGuard: Enforces Tailwind v3 monorepo setup and bans v4-only artifacts (yarn tailwind:guard)
4. BrandTypesCheck: Ensures generated brand types are up-to-date (detects stale types)
5. VitePathValidation: Checks Vite path configurations (scripts/check-vite-paths.mjs)
6. ProjectTargets: Validates project.json targets across workspace
7. Lint: Runs eslint across the workspace (parallel where possible)
8. Typecheck: Runs TypeScript type checking (parallel, no emit)
9. Build: Builds all packages (nx run-many)
10. UITreeShake: Verifies web bundle doesn’t include React Native code (tree-shake check)
11. SizeThresholds: Checks bundle sizes against configured thresholds (size-thresholds.json)
12. BundleScan: (Placeholder for future bundle analysis)

Exit Codes

• 0: All stages passed
• 1: One or more verification failures (lint, type, build, cycles, schema, size)
• 2: Prerequisite tooling missing (jq, node, etc.)
• 3: Registry schema validation failed (critical - brand configuration invalid)

Usage

yarn verify   # Alias defined in root package.json
./scripts/verify-repo.sh  # Direct invocation

Output & Artifacts

Verification results are saved to .verify/ directory:

.verify/summary.json

Machine-readable summary with stage-by-stage status and timings:

{
  "success": true,
  "duration": {
    "seconds": 124.5,
    "formatted": "2m 4s"
  },
  "stages": [
    {
      "name": "InstallIntegrity",
      "status": "success",
      "duration": "1s"
    },
    {
      "name": "RegistrySchemaValidation",
      "status": "success",
      "duration": "0s"
    }
    // ... more stages
  ]
}

Query examples:

# Check which stages failed
jq '.stages[] | select(.status == "error")' .verify/summary.json

# Get total verification time
jq '.duration.seconds' .verify/summary.json

# Check specific stage timing
jq '.stages[] | select(.name == "Build") | .duration' .verify/summary.json

# Count failed stages
jq '[.stages[] | select(.status == "error")] | length' .verify/summary.json

.verify/full-output.log

Complete verification log with all command output, useful for debugging failures.

.verify/size-results.json

Bundle size measurements from SizeThresholds stage:

{
  "packages/brands": {
    "totalSize": 38421,
    "softLimit": 40000,
    "hardLimit": 50000,
    "percentOfSoft": 96.05,
    "percentOfHard": 76.84,
    "status": "pass"
  }
}

Performance Metrics (Actual)

Based on M2-M5 implementation:

• Total runtime (local, cold): ~90-120s (includes build)
• Incremental (few changes, Nx cache hit): ~30-45s
• Schema validation: <1s (fail-fast)
• Tree-shake check: <2s
• Size threshold check: <1s

Schema Validation (M2)

Added fail-fast brand registry validation:

• Script: scripts/validate-brand-registry.mjs
• Schema: Zod schema matching json-loader.node.ts structure
• Features: navigation, auth, messaging, search, bookings, payments
• Platforms: web, mobile
• Exit: Code 1 if validation fails, prevents downstream errors

Brand Types Generation (M2)

Automated type generation with stale detection:

• Script: scripts/generate-brand-types.mjs
• Output: packages/brands/src/generated-types.ts, generated-constants.ts
• Stale Check: Verification fails if types out of sync with registry

Tree-Shake Validation (M4)

Web vs Native bundle split verification:

• Script: scripts/check-ui-tree-shake.mjs
• Check: Web bundle must not contain React Native imports
• Metrics: Reports size savings percentage (target: >40%)
• Result: 47.7% size reduction achieved (7.74KB web vs 14.79KB native)

Size Regression Guards (M5)

Bundle size threshold enforcement:

• Script: scripts/check-size-thresholds.mjs
• Config: size-thresholds.json (softLimit/hardLimit per package)
• Modes: Warning mode (default) or strict mode (—strict for CI)
• Current Thresholds:
  • packages/brands: 40KB / 50KB
  • packages/common: 792KB / 950KB
  • packages/ui: 224KB / 270KB

CI Integration

Verification is integrated into GitHub Actions:

.github/workflows/verify.yml

name: Verify Monorepo
on: [push, pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 20
      - name: Install Dependencies
        run: yarn install
      - name: Run Verification
        run: ./scripts/verify-repo.sh
      - name: Upload Summary
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: verification-summary
          path: .verify/summary.json

Troubleshooting

Symptom	Likely Cause	Resolution
Missing graph file	nx upgraded / path issue	Clear cache, rerun verify
Cycle fail	New import created loop	Break chain by moving shared code to library
Typecheck slow	Unnecessary wide rootDir	Introduce explicit tsconfig.build.json per package

Metrics Logging (Future)

Emit JSON summary (.verify/last-run.json) for CI trend graphs.