eslint-plugin-react-render-types: Instructions file for Codex

CLAUDE.md

Project

ESLint plugin that brings Flow's Render Types to TypeScript via JSDoc @renders annotations. Enforces component composition constraints at lint time using typed linting.

Commands

pnpm build          # Compile TypeScript (tsc → dist/)
pnpm test:run       # Run all tests once (vitest)
pnpm test           # Run tests in watch mode
pnpm typecheck      # Type-check without emitting
pnpm lint           # Lint src/ and tests/

Example project (example/)

pnpm install                # Separate install (not a workspace)
pnpm lint                   # Run ESLint — errors expected in InvalidUsage.tsx
pnpm lint:update-snapshot   # Regenerate lint-snapshot.txt after changing expected errors
pnpm typecheck              # Type-check the example

Architecture

src/
  index.ts                  # Plugin entry — exports rules + recommended config
  rules/                    # 5 ESLint rules
    valid-render-return.ts    Validates component returns match @renders declaration
    valid-render-prop.ts      Validates props/children with @renders receive correct components
    valid-renders-jsdoc.ts    Validates @renders JSDoc syntax (braces, PascalCase)
    require-renders-annotation.ts   Requires @renders on all components (off by default)
    renders-uses-vars.ts      Marks @renders references as used (prevents no-unused-vars)
  utils/
    cross-file-resolver.ts    Resolves @renders and @transparent annotations across files via TypeScript's type checker
    render-chain.ts           Follows @renders chains (A → B → C) using type IDs
    jsdoc-parser.ts           Parses @renders/@transparent JSDoc annotations
    jsx-extraction.ts         Extracts component names from JSX (ternary, &&, .map())
    component-utils.ts        Component detection helpers
    settings.ts               Reads shared ESLint settings (additionalTransparentComponents)
  types/
    index.ts                  RendersAnnotation, ResolvedRendersAnnotation, ComponentTypeInfo