Skip to content

CLAUDE.md

Latest commit

 

History

History
101 lines (72 loc) · 3.45 KB

CLAUDE.md

File metadata and controls

101 lines (72 loc) · 3.45 KB
Raw

CLAUDE.md

Code analysis system using ast-grep and Schema.org. Analyzes codebases for quality issues, test coverage, and dependencies. Generates interactive dashboards.

Live: https://integrityaistudio.com/ | Status: Phase 5C Complete

Quick Start

python3 scripts/run_analysis.py --root /path/to/code --parallel --cache  # Analysis
npm run dev         # Dashboard at localhost:5173/dashboard
npm run build       # Production build
npm run verify      # Check dependencies

Stack

Backend: Python + ast-grep analyzers (code_quality, dependencies, test_coverage) Frontend: React 18 + TypeScript + MUI v7 + TanStack Query/Router + Vite Secrets: Doppler (integrity-studio / dev)

Structure

src/
├── analyzers/           # Python: code_quality, dependencies, test_coverage
├── generators/          # Python: schema, dashboard, rss
├── features/dashboard/  # React: api/, components/, hooks/, stores/, types/
├── routes/dashboard/    # TanStack Router pages
├── theme/               # MUI v7 theme + dark mode
└── components/          # Shared: ErrorBoundary, SuspenseLoader
public/data/             # JSON reports (quality, coverage, dependencies, insights, predictions)

Data Flow

Python analyzers → outputs/ → copy to public/data/ → Dashboard fetches via TanStack Query

React Patterns

  • import type { X } not React.X
  • function Component() not const Component: React.FC
  • useSuspenseQuery with Suspense boundaries
  • MUI v7: use size prop for Grid
  • Theme: useTheme() from @/theme

CI/CD

Analysis Pipeline (analysis-pipeline.yml): Tests → Benchmarks → Analysis GitHub Pages (deploy-pages.yml): Push to main → Build → Deploy to https://integrityaistudio.com/

SPA routing: public/404.html redirects to index.html, root (/) redirects to /dashboard

Testing

python3 scripts/run_tests.py                    # All tests
python3 scripts/run_tests.py --unit-only        # Unit only
python3 scripts/run_tests.py --integration-only # Integration only

Performance

--parallel (3x) + --cache (8x) = 10-20x speedup

Common Issues

Issue Solution
ast-grep not found brew install ast-grep
Dashboard no data Copy reports to public/data/
TypeScript errors npx tsc --noEmit
CI fails with EBADPLATFORM for rollup/esbuild See "Platform-Specific Dependencies" below

Platform-Specific Dependencies

DO NOT add platform-specific packages like @rollup/rollup-darwin-arm64 to package.json. These cause CI failures:

npm error code EBADPLATFORM
npm error notsup Unsupported platform for @rollup/rollup-darwin-arm64

Why: CI runs on Linux (x64), but darwin-arm64 packages only work on macOS.

Solution: Let bundlers (Rollup, esbuild, SWC) manage their own native bindings. They install the correct platform package automatically via their own optionalDependencies.

If this error appears:

  1. Check package.json for explicit platform packages (@rollup/rollup-*, @esbuild/*, @swc/core-*)
  2. Remove them from dependencies/devDependencies
  3. Run npm install to update lockfile
  4. Commit and push

ast-grep Meta Variables

def get_meta_var(match, var_name):
    meta = match.get('metaVariables', {})
    node = meta.get('single', {}).get(var_name) or meta.get(var_name)
    return node.get('text') if isinstance(node, dict) else str(node) if node else None