GolangCI-Lint Integration
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The GolangCI-Lint integration in TDD Guard provides automated static analysis for Go projects as part of the Test-Driven Development enforcement workflow. It allows the system to identify code quality issues, such as type-checking errors or unused variables, which are critical during the Refactor phase of the TDD cycle. Sources: README.md:16, src/validation/prompts/tools/lint-results.ts:1-13
By integrating with the TDD validation logic, lint results are used to ensure that code quality is addressed once tests are passing (Green phase) before proceeding to new features. Sources: src/validation/prompts/tools/lint-results.ts:10-13
Architecture and Implementation
The integration is centered around the GolangciLint class, which implements a standard Linter interface. It interacts with the golangci-lint binary via asynchronous child process execution. Sources: src/linters/golangci/GolangciLint.ts:13-15
Core Components
The implementation consists of the main execution logic, argument building, and response parsing.
This diagram illustrates the internal flow of the linting process from argument construction to the final result mapping.
Sources: src/linters/golangci/GolangciLint.ts:13-30
Key Methods and Functions
| Function | Purpose |
|---|---|
lint(filePaths, configPath) | Orchestrates the linting process by executing the binary and processing results. |
buildArgs(filePaths, configPath) | Constructs the CLI arguments for golangci-lint, converting file paths to unique directories. |
parseResults(stdout) | Extracts JSON data from the first line of the command output. |
toIssue(issue) | Maps the tool-specific GolangciLintIssue to the internal LintIssue format, handling multi-line outputs. |
Sources: src/linters/golangci/GolangciLint.ts:14-118
Data Flow and Logic
Execution Logic
The linter executes the command golangci-lint run. Because golangci-lint typically returns a non-zero exit code when issues are found, the integration catches the execution error and parses the stdout from that error object. Sources: src/linters/golangci/GolangciLint.ts:18-29
Directory-Based Scanning
Unlike some linters that operate on individual files, golangci-lint is directory-oriented. The integration extracts unique directory names from the provided filePaths list and passes these directories as arguments to the tool. Sources: src/linters/golangci/GolangciLint.ts:46-52, src/linters/golangci/GolangciLint.test.ts:117-124
Result Parsing
The linter expects JSON output. It specifically targets the first line of stdout for the JSON payload, as subsequent lines may contain summaries or unrelated text. Sources: src/linters/golangci/GolangciLint.ts:63-71
The sequence of communication between the TypeScript class and the external Go linting tool.
Sources: src/linters/golangci/GolangciLint.ts:13-30
Validation Integration
Lint results are formatted for use within the AI validation context. This context informs the AI model whether there are outstanding code quality issues that should be addressed before the developer moves to a new TDD cycle. Sources: src/validation/context/context.ts:121-126, src/validation/prompts/tools/lint-results.ts:1-13
Lint Result Schema
The system enforces strict data structures for linting results using Zod schemas. These include position data (filename, line, column) and issue metadata (linter rule, message, severity). Sources: src/contracts/schemas/lintSchemas.test.ts:186-215
| Field | Type | Description |
|---|---|---|
FromLinter | string | The specific Go linter rule triggered (e.g., typecheck). |
Text | string | The description of the linting violation. |
Pos | object | Contains Filename, Line, and Column. |
Sources: src/linters/golangci/GolangciLint.ts:91-100, src/contracts/schemas/lintSchemas.test.ts:218-235
Conclusion
The GolangCI-Lint integration bridges the gap between Go-specific static analysis and the language-agnostic TDD Guard validation engine. By handling the directory-based nature of Go linting and accurately parsing multi-line tool outputs, it ensures that Go developers maintain high code quality standards while following the Red-Green-Refactor cycle.