Audit Components

Audit Components

Verify the health of the modular component architecture after code changes. Catches broken imports, prop mismatches, unused exports, and drift between shared utilities and their consumers.

What This Checks

1. Import Resolution

Verify every import in each component resolves to an actual export:

• Check all component .jsx files in each project
• Check shared utility files
• Check root App.jsx imports

2. Props Consistency

Verify props passed from App.jsx match what each component destructures.

Derive the render-site list fresh every audit — don't maintain a static table of components and their expected props. A hardcoded table rots: a rename, a removed prop, or a component added after the table was written all escape the audit while the table's presence reads as complete coverage. A checklist that covers some render sites is worse than none — it converts "verify everything" into "verify these rows."

Derive the full set, then read every site:

git fetch origin -q || { echo "ABORT: fetch failed — deriving from a stale tree recreates the exact staleness this check exists to catch"; exit 1; }
git show origin/main:src/App.jsx | grep -oE '<[A-Z][A-Za-z0-9_]*' | sort -u

• Every capitalized JSX tag is a render site — not just names ending in a common suffix like View or Panel. A suffix-only pattern silently omits any component whose name doesn't happen to match it, often including the app's own primary/root component. A letter-only regex additionally drops any name containing a digit.
• For each site, read the JSX attributes actually passed, then read the component's function signature, and compare. Flag:
  • Props passed but never destructured (wasted, non-breaking)
  • Props destructured but never passed (will be undefined, likely a bug)
• Derive against the remote tracking branch (origin/main), not your local checkout — a feature branch can sit many commits behind and hand you stale answers.
• In the report, state the derived count ("App.jsx renders N distinct component tags; N/N checked") so a partial pass is visible as partial.

3. Shared Utility Usage

Verify no component has local copies of functions that exist in shared utilities:

• Search for duplicate function definitions across all component files in all projects
• Flag any local reimplementation of shared functions

4. Unused Exports

Check if any export from shared files is not imported anywhere:

• For each export in shared utility files
• Search all .jsx files for matching import statements
• Flag exports with zero consumers

5. Lint and Build (all projects)

cd project-a && npx biome lint src/ && npm run build
cd project-b && npx biome lint src/ && npm run build
# ... repeat for each project

All must pass with 0 errors. Report any warnings.

6. Cross-Project Shared Re-exports

If your projects re-export shared utilities, verify each project's local utils file re-exports ALL functions from the shared source. Flag any missing re-exports.

Steps

Phase 1 — Parallel Per-Project Audit

Dispatch agents simultaneously (model: "opus"), one per project. Each agent independently performs checks 1-2 and 5 for its project:

• Agent: Project A Auditor — Read App.jsx, check all component imports resolve, verify props passed vs destructured, run lint + build
• Agent: Project B Auditor — Same for project B
• (etc.)

Each agent returns a structured report: { project, importIssues[], propIssues[], lintWarnings[], buildResult }.

Phase 2 — Parallel Cross-Project Checks

Dispatch 2 agents simultaneously (model: "opus") for checks 3, 4, and 6:

• Agent: Shared Utility Auditor — Check for duplicate utility definitions across all projects (check 3). Verify re-exports match shared source exports (check 6). Flag any missing re-exports or local duplicates.
• Agent: Unused Export Auditor — Check all shared exports have at least one consumer across all projects (check 4). Flag orphaned exports with zero consumers.

Each agent returns: { duplicates[], missingReexports[], unusedExports[] }.

Phase 3 — Synthesize

Main agent compiles results from all agents into the final PASS/WARN/FAIL table.

Agent Teams Architecture

Phase 1 (parallel, model: "opus"):
  +-- Project A Auditor -----> imports + props + lint/build
  +-- Project B Auditor -----> imports + props + lint/build
  +-- Project C Auditor -----> imports + props + lint/build

Phase 2 (parallel, model: "opus"):
  +-- Shared Utility Auditor -> duplicates + re-exports (checks 3, 6)
  +-- Unused Export Auditor --> orphaned exports (check 4)

Phase 3 (main agent):
  Compile agent results -> PASS / WARN / FAIL table

All agents are read-only (no code modifications), so isolation: "worktree" is not required.

Output Format

Report results as:

• PASS items (green) - everything correct
• WARN items (yellow) - non-breaking but worth noting (unused props, etc.)
• FAIL items (red) - will cause bugs or build failures

Pre-Edit Consumer Scan

Before editing or removing CSS classes or data field references:

1. Grep for the class/field across ALL projects
2. Check both JSX references (className=) and CSS definitions (.class-name {)
3. Check both component CSS files AND App.css in each project

Post-Edit Completeness Check

After applying changes across multiple files:

1. Re-grep for the changed pattern to confirm ALL instances updated
2. This catches files you didn't know about (e.g., a third project copy)

Post-Edit Re-Grep Verification

After any multi-file pattern edit (renaming a prop, removing a CSS class, swapping an import, adding a parameter to a shared function), re-run the ORIGINAL pre-edit grep against the codebase AFTER your edits:

# Example: after adding a param to a shared utility across all consumers
grep -rn "mySharedFn" project-a/src/ project-b/src/ shared/

# Example: after renaming a CSS class
grep -rn "old-class-name" project-a/src/ project-b/src/

# Example: after converting a prop to an import
grep -rn "propsName\|OldPropPattern" --include="*.jsx" .

The re-grep catches:

• Files added between Edit operations that weren't in the initial scan
• Import aliases that resolve differently across projects
• Test files that import or mock the changed symbol
• Index re-exports that forward the old signature

Zero results = all instances updated. Any remaining hits = missed site. Fix before committing.

This is the post-edit equivalent of the pre-edit consumer scan — both are required for complete coverage. Running only the pre-edit scan leaves a gap for files created or modified after your initial grep.

UI Label Audits

When hiding or renaming a UI label, the same text is often rendered in multiple places: sidebar, main header, document title, tab labels, tooltip titles, breadcrumbs. Fixing one site and shipping leaves the others leaking.

Before claiming a label change is done:

1. grep -rn '"YourLabel"' src/ — find ALL render sites
2. Check any default-fallback code paths that humanize a route ID (e.g. activeView.charAt(0).toUpperCase() + activeView.slice(1) turns admin → "Admin" for free, bypassing any lookup map)
3. Visual verification is mandatory — HTTP 200 and unit tests don't prove what the user sees

When to Use

• After modifying shared utilities or constants
• After adding/removing props from a component
• After adding a new component
• Before merging to main (part of the release checklist)