Linter Processing

Relevant source files

The following files were used as context for generating this wiki page:

• src/processors/lintProcessor.ts
• src/linters/eslint/ESLint.ts
• src/linters/golangci/GolangciLint.ts
• src/validation/context/context.ts
• src/validation/prompts/tools/lint-results.ts
• src/hooks/processHookData.test.ts

Linter Processing in TDD Guard is a subsystem responsible for executing static analysis tools, aggregating their results, and presenting code quality status as context for TDD validation. It ensures that code quality is maintained during the Refactor phase of the TDD cycle while allowing focus on making tests pass during the Red phase.

The system integrates with popular linters like ESLint and Golangci-lint, transforming their native outputs into a standardized format used by the AI validator to block or allow operations based on the current state of the codebase.

Sources: src/processors/lintProcessor.ts, src/validation/prompts/tools/lint-results.ts:1-12, README.md

Architecture and Data Flow

The linter processing logic follows a pipeline where raw tool output is captured, normalized, and then formatted for consumption by the AI agent.

Linter Execution and Normalization

Linters are implemented as classes adhering to a common Linter interface. They execute external shell commands (e.g., npx eslint or golangci-lint run) and parse the resulting JSON or text output into a unified LintResult structure.

Processing for Validation Context

Once standardized data is available, the lintProcessor transforms it into ProcessedLintData. This includes grouping issues by file and generating human-readable summaries that include error and warning counts.

Key Components

Data Structures

The system uses specific structures to maintain consistency across different linter implementations.

Component	Description
LintResult	The output from a linter execution containing timestamp, files, issues, and counts.
ProcessedLintData	An optimized view of lint data containing a map of issues by file and a summary string.
LintIssue	A standardized object representing a single diagnostic (file, line, column, severity, message, rule).

Sources: src/processors/lintProcessor.ts:7-15, src/linters/eslint/ESLint.ts:60-70

Linter Implementations

1. ESLint: Runs eslint via npx with JSON formatting. It maps ESLint severities (1 for warning, 2 for error) to the project's internal error and warning types.
   • Sources: src/linters/eslint/ESLint.ts:33-40, src/linters/eslint/ESLint.ts:63-71
2. GolangciLint: Runs golangci-lint run. It handles complex multi-line output where the first line typically contains the JSON result and subsequent lines might contain summaries.
   • Sources: src/linters/golangci/GolangciLint.ts:35-50, src/linters/golangci/GolangciLint.ts:58-75

TDD Integration Rules

Linter results directly influence the AI's decision to block or allow file modifications based on the current TDD phase:

• Red Phase (Failing Tests): The agent is instructed to focus on making tests pass. Lint issues are present but usually do not block the "Green" transition.
• Green Phase (Passing Tests): When tests are green, the agent MUST address lint issues before proceeding to new features or further implementation.
• Hook Blocking: The processHookData logic can preemptively block an operation if tests are passing but new lint issues have been introduced or exist without notification.

Sources: src/validation/prompts/tools/lint-results.ts:7-12, src/hooks/processHookData.test.ts:153-170

Validation Context Formatting

The formatLintDataForContext function converts processed data into a structured string for the AI prompt:

// Example Output Format
Code Quality Status: 2 lint issues found (1 error, 1 warning)

Lint Issues by File:

src/example.ts:
  Line 10:5 - error: Missing semicolon (semi)
  Line 12:1 - warning: Unused variable (no-unused-vars)

Sources: src/processors/lintProcessor.ts:54-70

Conclusion

Linter Processing serves as a critical bridge between static analysis tools and TDD enforcement. By normalizing disparate linter outputs and providing clear, file-grouped context to the AI validator, it ensures that code quality remains a first-class citizen in the TDD cycle without obstructing the primary goal of achieving passing tests.