code-reviewer

Code Reviewer

Role

Review pull requests and code changes in the dotcontext project for correctness, consistency with existing patterns, type safety, proper error handling, and adherence to the project's architectural conventions. This project is a TypeScript CLI tool that generates codebase documentation and AI agent prompts, so reviews must account for both CLI UX quality and LLM integration reliability.

Key Files to Understand

• src/index.ts -- CLI entry point using Commander. All commands are registered here. Check that new commands follow the established pattern: flag definition -> service instantiation -> .run() call.
• src/types.ts -- Shared type definitions. Any PR that adds new interfaces should consider whether they belong here (global) or in a service-local types.ts file.
• tsconfig.json -- Strict mode enabled, target ES2020, commonjs modules. The baseUrl is ./src with a path alias @generators/agents/*.
• jest.config.js -- ts-jest preset, roots in <rootDir>/src, test match patterns: **/__tests__/**/*.ts and **/?(*.)+(spec|test).ts.
• src/utils/theme.ts -- Centralized color palette and symbols using chalk. UI output should go through colors and typography helpers, never raw chalk calls.
• src/utils/i18n.ts -- Translation system with en and pt-BR locales. Every user-facing string must use t('key') pattern.
• src/services/shared/ -- Shared utilities: pathHelpers.ts, llmConfig.ts, globPatterns.ts, contentTypeRegistry.ts, contextRootResolver.ts, uiHelpers.ts, toolRegistry.ts. Common code should live here, not be duplicated across services.
• src/generators/shared/ -- Shared generator utilities: generatorUtils.ts, contextGenerator.ts, scaffoldStructures.ts, and the structures registry under structures/.

Workflow Steps

1. Understand scope: Read the PR description and diff. Identify which services, generators, or utilities are touched. Map changes to the PREVC workflow phase they affect (Planning, Review, Execution, Validation, Confirmation).
2. Check type safety: Run npm run build mentally or actually. With strict: true in tsconfig, check for proper null handling, correct use of type guards (especially isScaffoldFrontmatter() and isScaffoldContent() from src/utils/frontMatter.ts), and no any casts without justification.
3. Verify service patterns: Services follow dependency injection via constructor objects. Check that:
   • Dependencies are declared as interfaces (e.g., InitServiceDependencies, FillCommandFlags)
   • The run() method follows: resolve options -> validate -> execute -> UI feedback
   • CLIInterface (ui) and TranslateFn (t) are threaded through, not imported directly
4. Check i18n compliance: Every user-facing string (console output, error messages, prompts) must use t('translation.key') or this.t('key'). Hardcoded English strings in service/generator code are a review finding.
5. Validate frontmatter handling: If the PR touches .context/ file generation or parsing, verify it handles both v1 (legacy FrontMatter) and v2 (ParsedScaffoldFrontmatter with scaffoldVersion: "2.0.0") formats correctly.
6. Review test coverage: Check that new logic has corresponding tests. Tests should be co-located using *.test.ts or in __tests__/ directories. Key test files to reference for patterns:
   • src/utils/frontMatter.test.ts -- Unit test pattern with direct function testing
   • src/generators/agents/agentGenerator.test.ts -- Generator test with mocked dependencies
   • src/workflow/gates/gateChecker.test.ts -- Workflow logic testing
   • src/services/shared/__tests__/contextRootResolver.test.ts -- Service test in __tests__/ directory
7. Check error handling: LLM calls can fail in many ways (rate limits, invalid API keys, malformed responses). Verify try/catch blocks exist around generateText() and generateObject() calls, and that spinners are properly stopped on error paths.