--- name: audit-react-vite-tsx-codebase description: "Critical audit of a React + Vite + TSX codebase — strict TypeScript, JSDoc, component architecture, error boundaries, a11y, performance, Vitest. Re-invoke until converged." version: 1.0.0 --- # audit-react-vite-tsx-codebase Perform a single critical audit pass on a React + Vite + TypeScript (TSX) codebase folder. Designed to be re-invoked until convergence (zero remaining issues). ## Instructions You are performing a **single audit pass** on the React/Vite/TypeScript codebase at `$ARGUMENTS`. This skill is idempotent and convergent — each invocation examines the current state, fixes what it can, and reports what remains. ### Phase 0: Baseline Snapshot 1. Run the TypeScript compiler in check mode: `npx tsc --noEmit` — capture error count. 2. Run the linter: `npm run lint` (or `npx oxlint` / `npx eslint .`) — capture violation count. 3. Run tests if they exist: `npx vitest run --reporter=verbose` — capture pass/fail count. 4. Check build: `npm run build` — does it succeed? 5. Record all counts — you will compare at the end. ### Phase 1: TypeScript Strictness & Type Safety Ensure the project uses strict TypeScript and every value is properly typed. **tsconfig.json requirements:** ```json { "compilerOptions": { "strict": true, "noUncheckedIndexedAccess": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "exactOptionalPropertyTypes": true, "noPropertyAccessFromIndexSignature": true } } ``` **Rules:** - No `any` type — use `unknown` with type guards, or define proper types. - No `// @ts-ignore` or `// @ts-expect-error` without a comment explaining why. - Every function has explicit parameter types and return types. - Every component has a typed `Props` interface (not inline object types). - Event handlers are typed: `React.MouseEvent`, not `any`. - API responses have proper interfaces (not `any` or untyped JSON). - Use discriminated unions for state that can be in multiple shapes. - Prefer `interface` for object shapes (extendable), `type` for unions/intersections. - Use `satisfies` operator where appropriate for type narrowing without widening. - Run `npx tsc --noEmit` — target zero errors. **Pattern to enforce:** ```tsx // Props interface above component interface UserCardProps { user: User; onSelect: (userId: string) => void; variant?: "compact" | "full"; } // Explicit return type on components with complex returns export function UserCard({ user, onSelect, variant = "full" }: UserCardProps): React.ReactElement { // ... } ``` ### Phase 2: Component Documentation (JSDoc + TSDoc) **Module/File-level:** Every `.tsx`/`.ts` file with exports gets a top-of-file JSDoc comment. ```tsx /** * @module PipelineStatus * @description Real-time pipeline execution dashboard with SSE-driven updates. * Displays agent progress, HITL gates, and final decision rendering. */ ``` **Component documentation:** ```tsx /** * Displays the coverage determination result with approval/denial reasoning. * * @remarks * Subscribes to the pipeline SSE stream and updates in real-time. * Renders a skeleton loader until the first event arrives. * * @example * ```tsx * * ``` */ export function DecisionCard({ caseId, onAppeal }: DecisionCardProps): React.ReactElement { ``` **Hook documentation:** ```tsx /** * Manages WebSocket connection for HITL gate interactions. * * @param caseId - Active case identifier * @param onGateReached - Callback when pipeline hits a HITL gate * @returns Connection state, gate data, and approval/rejection actions * * @example * ```tsx * const { gateData, approve, reject } = useHITLGate("PA-001", handleGate); * ``` */ export function useHITLGate(caseId: string, onGateReached: GateCallback): HITLGateHook { ``` **Rules:** - Every exported component, hook, utility function, and type gets a JSDoc block. - Include `@remarks` for non-obvious behavior (side effects, subscriptions, performance). - Include `@example` with a usage snippet for components and hooks. - Include `@param` and `@returns` for hooks and utility functions. - Internal/private helpers get at minimum a one-line `/** ... */` comment. - Type interfaces get `/** */` on the interface AND on non-obvious properties. ### Phase 3: Component Architecture & React Best Practices **Rules for component structure:** | Principle | Smell | Action | |-----------|-------|--------| | Single Responsibility | Component > 150 LOC or renders unrelated sections | Extract sub-components | | Separation of concerns | Business logic mixed with rendering | Extract to custom hooks | | DRY | Same JSX pattern in 3+ places | Extract shared component | | Pure components | Component re-renders without prop changes | Add `React.memo` or fix parent | | Colocation | Related files scattered across folders | Co-locate component + hook + test + types | | Composition over config | Component with 10+ boolean props | Use compound component or slots pattern | **Specific checks:** - No direct DOM manipulation (`document.querySelector`) — use refs. - No `useEffect` for derived state — compute inline or use `useMemo`. - No `useEffect` for event responses — handle in the event handler. - `useEffect` dependencies are correct and exhaustive. - No `eslint-disable` on exhaustive-deps without justification. - State that is always set together lives in one `useState` or `useReducer`. - Expensive computations are wrapped in `useMemo` with correct deps. - Event handlers passed to children are wrapped in `useCallback` when children are memoized. - No prop drilling beyond 2 levels — use context or composition. - Keys on lists are stable and unique (not array index unless list is static). **Folder structure enforcement:** ``` src/ ├── components/ # Reusable UI components │ └── ComponentName/ │ ├── ComponentName.tsx │ ├── ComponentName.test.tsx │ ├── useComponentLogic.ts # (if complex logic) │ └── index.ts ├── hooks/ # Shared custom hooks ├── pages/ # Route-level components ├── services/ # API layer ├── types/ # Shared TypeScript types ├── utils/ # Pure utility functions └── constants/ # App-wide constants ``` ### Phase 4: Error Handling & Error Boundaries **Rules:** - Every page/route has an Error Boundary wrapping it. - API calls have proper error handling (try/catch or `.catch()`). - Loading and error states are handled for every async operation (not just happy path). - User-facing errors show meaningful messages (not raw error strings or stack traces). - No unhandled promise rejections — every `.then()` has a `.catch()` or is `await`-ed in a try/catch. - Network failures are retried or gracefully degraded (not silent failures). - Form validation shows inline errors, not just console logs. **Pattern to enforce:** ```tsx // Error boundary at route level }> }> // Async state pattern interface AsyncState { data: T | null; loading: boolean; error: Error | null; } ``` **Custom error types:** ```tsx export class APIError extends Error { constructor( message: string, public readonly statusCode: number, public readonly endpoint: string, ) { super(message); this.name = "APIError"; } } ``` ### Phase 5: Accessibility (a11y) **Rules:** - Every interactive element is keyboard-accessible (Tab, Enter, Escape). - Every image has an `alt` attribute (empty `alt=""` for decorative images). - Form inputs have associated `