Data Schemas & Validation
Relevant source files
The following files were used as context for generating this wiki page:
Data Schemas and Validation in TDD Guard ensure that all internal communications, test results, and AI-driven decisions adhere to strict structural contracts. By utilizing Zod for runtime validation, the system guarantees that inputs from various language-specific reporters (Go, Rust, Vitest, etc.) and Claude Code hooks are correctly parsed before being processed by the validation logic.
The architecture relies on centralized contracts defined in src/contracts/, which separate the definition of data structures from the logic that processes them. This ensures that features like Test-First Enforcement operate on predictable, well-formatted data.
Core Schema Architecture
TDD Guard uses a multi-layered validation approach to handle different types of data inputs: tool operations, test reports, and linting results.
Tool Operation Schemas
These schemas validate the data received from Claude Code hooks when an agent attempts to modify files. The primary operations include Edit, MultiEdit, Write, and TodoWrite.
The diagram above illustrates the hierarchy of tool operations captured by TDD Guard hooks.
Sources: src/contracts/schemas/toolSchemas.ts, src/contracts/schemas/toolSchemas.test.ts:246-347
Reporter & Test Results Schemas
Test result schemas are critical for parsing output from various test runners. They follow a hierarchical structure: TestResult contains TestModule objects, which in turn contain individual Test objects.
| Schema | Purpose | Key Fields |
|---|---|---|
TestResultSchema | Top-level container for a test run | testModules, unhandledErrors, reason |
TestModuleSchema | Results for a single file/module | moduleId, tests |
TestSchema | Result for a single test case | name, fullName, state, errors |
TestErrorSchema | Details of a specific test failure | message, stack, expected, actual |
Sources: src/contracts/schemas/reporterSchemas.ts, src/contracts/schemas/reporterSchemas.test.ts:98-175
Validation Flow & Decision Logic
The validator component processes context data and interacts with the AI model to determine TDD compliance. It expects responses in a specific JSON format.
This flow shows how data moves from initial hook capture through schema validation to the final AI decision.
Sources: src/validation/validator.test.ts:37-184, src/validation/prompts/response.ts:4-10
Decision Schema
The AI model must respond with a JSON object following this contract:
{
"decision": "block" | null,
"reason": "Clear explanation with actionable next steps"
}
If the decision is "block", TDD Guard prevents the file operation and presents the reason to the user. A null decision allows the operation to proceed.
Sources: src/validation/prompts/response.ts:4-10, src/validation/validator.test.ts:38-42
Language-Specific Validations
TDD Guard supports multiple languages by normalizing their specific test outputs into the shared TestResultSchema.
Linting Schemas
Static analysis results are validated through specialized schemas to ensure consistency across different linters (e.g., ESLint, Golangci-lint).
- LintIssue: Captures
file,line,column,severity, andmessage. - GolangciLintResult: Specifically handles the output structure of the Go linter, including the
Pos(position) andFromLinterfields.
Sources: src/contracts/schemas/lintSchemas.test.ts:13-88, src/contracts/schemas/lintSchemas.test.ts:187-252
Type Guards and Utilities
The system provides runtime type guards to safely differentiate between operation types:
isEditOperation(op): Returns true if the operation is a standard edit.isFailingTest(test): Validates if a test state is explicitly 'failed'.isFileModification(op): AggregatesEdit,MultiEdit, andWriteoperations while excludingTodoWrite.
Sources: src/contracts/schemas/toolSchemas.test.ts:387-463, src/contracts/schemas/reporterSchemas.test.ts:252-272
Summary
Data Schemas and Validation provide the backbone for TDD Guard's enforcement capabilities. By defining rigid Zod schemas for tool operations and test reports, the project ensures that AI-driven TDD enforcement is based on accurate, validated data, regardless of the programming language or test framework being used.