State & File Storage
Relevant source files
The following files were used as context for generating this wiki page:
The State & File Storage system in TDD Guard is responsible for the persistence and retrieval of critical data required to validate Test-Driven Development (TDD) principles. It acts as the central repository for test results, file modifications, linting issues, and configuration settings. By abstracting the storage mechanism, the system allows the CLI and various language-specific reporters to interact with state data consistently across different environments.
The system is designed around an interface-driven architecture, supporting multiple implementations such as FileStorage for persistent disk-based storage and MemoryStorage for volatile testing scenarios. This flexibility ensures that the TDD validation logic can access a "context" of the current development state regardless of which test runner or language reporter generated the data.
Sources: CLAUDE.md:65, src/storage/Storage.test.ts:162-187
Architecture and Implementations
The storage system follows a strict interface-driven design. The core functionality is defined by a Storage contract, which is implemented by concrete classes tailored for different use cases.
Storage Hierarchy
The project provides two primary implementations:
- FileStorage: The default production implementation. It persists data to the local filesystem within a specific data directory (e.g.,
.claude/tdd-guard/data/). It handles directory creation and file I/O operations. - MemoryStorage: Primarily used for unit testing and internal state management where persistence is not required. It stores data in-memory and is wiped when the process ends.
The diagram above illustrates the relationship between the storage interface and its concrete implementations.
Sources: src/storage/FileStorage.test.ts:18-36, src/storage/Storage.test.ts:162-187, src/guard/GuardManager.test.ts:24-30
Data Categories
The storage system categorizes data based on its lifecycle and purpose. This distinction allows the system to clear temporary session data while preserving long-term configurations.
Transient Data vs. Persistent Config
Storage identifies "Transient Data" as information that is only relevant to the current TDD cycle or session. This data is removed when calling clearTransientData().
| Category | Data Types | Purpose |
|---|---|---|
| Transient | Test, Todo, Modifications, Lint | Captured results and proposed changes used for immediate AI validation. |
| Persistent | Config, Instructions | User settings (like ignore patterns) and custom TDD rule overrides. |
Sources: src/storage/Storage.test.ts:109-158, src/cli/buildContext.test.ts:15-60
Key Storage Operations
The system supports saving and retrieving specific strings or JSON-serialized objects for the following:
- Test Results: Captured by reporters (e.g., Vitest, Go) and saved to disk to be analyzed by the validator.
- Modifications: JSON data representing file edits, writes, or multi-edits proposed by the AI agent.
- Lint Data: Issues found by code quality tools, including error counts and file-specific messages.
- Instructions: Custom TDD rules provided by the user to override default behavior.
Sources: src/cli/buildContext.test.ts:110-150, reporters/go/cmd/tdd-guard-go/main.go:56-62
Integration with Reporters
Language-specific reporters serve as the primary "writers" to the storage system. When a test suite runs, the reporter intercepts the output, transforms it into a standard JSON format, and uses an instance of FileStorage to persist it.
Data Flow: Go Reporter Example
The Go reporter demonstrates how external tools interact with the storage system:
- Capture: It reads
go test -jsonoutput fromStdin. - Validation: It validates the
projectRoot(must be absolute and an ancestor of the CWD). - Transformation: It converts Go's test events into the unified
TestResultformat. - Persistence: It uses
storage.Save(result)to write to the project's data directory.
The flow shows how raw test data is processed and stored for later validation.
Sources: reporters/go/cmd/tdd-guard-go/main.go:34-62, reporters/vitest/src/VitestReporter.test.ts:182-192
Context Building
The buildContext module acts as the "reader," aggregating data from multiple storage keys to create a unified object for the AI validator.
Formatting and Parsing
When retrieving data, the system performs several quality-of-life transformations:
- JSON Pretty-Printing: Modifications are parsed and re-stringified with indentation for better AI readability.
- Lint Summarization: Raw lint JSON is transformed into a human-readable summary (e.g., "1 lint issue found (1 error, 0 warnings)").
- Graceful Fallbacks: If JSON is corrupted or missing, the system returns default empty states rather than throwing errors.
// Example of building context from storage
const context = await buildContext(storage);
// Resulting object:
// {
// modifications: "{ ... pretty printed ... }",
// test: "Captured test results...",
// lint: { hasIssues: true, summary: "...", issuesByFile: Map(...) }
// }
Sources: src/cli/buildContext.test.ts:62-110, src/cli/buildContext.test.ts:152-160
Configuration Management
The GuardManager uses storage to track the operational state of TDD Guard and custom ignore patterns.
- Guard State: A boolean
guardEnabledflag is stored in the config JSON. - Ignore Patterns: A list of glob patterns (e.g.,
dist/**,*.min.js) is persisted. TheGuardManagerpreserves these patterns even when the guard is toggled on or off.
Sources: src/guard/GuardManager.test.ts:32-55, src/guard/GuardManager.test.ts:77-101
Conclusion
The State & File Storage system provides the essential data plumbing for TDD Guard. By enforcing a common Storage interface, it decouples the diverse sources of data—ranging from Go test binaries to Vitest reporters—from the AI-driven validation logic. Its ability to distinguish between transient session data and persistent user configuration ensures a clean, reliable state management that supports the incremental Red-Green-Refactor cycle.