ESLint Integration
Relevant source files
The following files were used as context for generating this wiki page:
The ESLint Integration within TDD Guard serves as a static analysis layer that ensures code quality during the Test-Driven Development (TDD) cycle. It intercepts file modifications to verify that refactoring phases adhere to established linting rules. The system executes ESLint via a child process, parses the JSON output, and transforms it into a standardized format used for AI-driven TDD validation.
This integration is primarily active during the Green Phase (passing tests), where lint issues must be addressed before proceeding to new features, while it remains secondary during the Red Phase to allow developers to focus on fixing failing tests first.
Sources: src/validation/prompts/tools/lint-results.ts:3-13, src/linters/eslint/ESLint.ts:1-12
Architecture and Components
The ESLint integration follows an interface-driven design, implementing a generic Linter interface. It consists of the execution logic, output parsing, and a processing pipeline that prepares the data for the AI validator.
The ESLint Class
The core logic resides in the ESLint class, which manages the lifecycle of a linting operation. It constructs command-line arguments, executes the npx eslint command, and handles both successful runs (no issues) and execution errors (issues found).
The diagram shows the execution flow from the initial method call to the generation of the standardized LintResult.
Sources: src/linters/eslint/ESLint.ts:13-31
Data Flow and Transformation
The data undergoes multiple transformations to convert raw ESLint JSON into a format suitable for the AI context.
- Raw Output: ESLint produces a JSON array of
ESLintResultobjects. - Internal Schema: The linter extracts
ESLintMessageobjects and maps them to a genericLintIssuestructure. - Processed Data: The
lintProcessorgroups these issues by file and generates a human-readable summary.
| Component | Responsibility |
|---|---|
buildArgs | Configures eslint with --format json and optional config paths. |
parseResults | Safely parses the CLI stdout into JSON. |
toIssue | Maps ESLint-specific severity (2 for error, others for warning) and fields to the LintIssue schema. |
processLintData | Aggregates issues and calculates errorCount and warningCount. |
Sources: src/linters/eslint/ESLint.ts:34-75, src/processors/lintProcessor.ts:7-35
Implementation Details
Execution Logic
The integration uses execFile from Node.js's child_process module. A key platform-specific consideration is the use of shell: true on Windows systems to correctly execute the npx command.
// src/linters/eslint/ESLint.ts:21-21
await execFileAsync('npx', args, { shell: process.platform === 'win32' })
Sources: src/linters/eslint/ESLint.ts:21, src/linters/eslint/ESLint.test.ts:98-105
Schema Mapping
The system maps ESLint's numerical severity levels to descriptive strings.
- Severity 2: Mapped to
error. - Other (Severity 1): Mapped to
warning.
Sources: src/linters/eslint/ESLint.ts:70-73, src/contracts/schemas/lintSchemas.test.ts:153-170
Context Generation for AI
The processed lint results are injected into the AI's dynamic context. The lintProcessor converts the data into a string that identifies the file, line, column, severity, and the specific rule violated (e.g., (no-unused-vars)).
The sequence shows how linting information is prepared as part of the validation context.
Sources: src/processors/lintProcessor.ts:46-60, src/validation/context/context.ts:114-119
TDD Enforcement Rules
The linting status is used by the AI to enforce specific TDD principles:
- Red Phase: Lint issues are displayed but generally ignored. The priority is making the test pass.
- Green Phase: If tests are passing, the AI will block further implementation or new tests if lint issues are present. This forces the "Refactor" step of the Red-Green-Refactor cycle.
- Refactoring: Logic changes during refactoring are allowed only if they don't introduce new behavior and strictly address code quality issues or abstractions.
Sources: src/validation/prompts/tools/lint-results.ts:7-13, src/validation/prompts/rules.ts:40-45
Summary
The ESLint Integration provides TDD Guard with the "Refactor" enforcement of the TDD cycle. By wrapping the standard ESLint CLI and providing a robust parsing and processing pipeline, it ensures that code quality status is a first-class citizen in the AI's decision-making process for blocking or allowing file modifications.