DEVBOOK.md

Gardisto Development Book

This document tracks the development progress of Gardisto following Test-Driven Development principles.

Current State Assessment 🏗️

Existing Implementation

• ✅ Basic project structure
• ✅ Core files created in src/
• ✅ Initial test setup with Jest
• 🏗️ Partial test coverage (envVariableChecker.test.ts, errors.test.ts)

Immediate Next Steps

1. Create test suites for existing modules:

   • ✅ envVariableChecker.test.ts
   • ✅ errors.test.ts
   • fileUtils.test.ts
   • logger.test.ts
   • types.test.ts

2. Apply TDD for each untested feature:

   • Write failing tests
   • Verify existing implementation or modify as needed
   • Refactor if necessary

Development Phases

Phase 1: Core Environment Variable Detection ✅

Rule: TDD Workflow - Write one test at a time

Tasks

• Environment Variable Detection Tests

  • Test .env file presence detection
  • Test environment variable parsing
  • Test variable format validation
  • Test missing variable handling

• Implementation (envVariableChecker.ts)

  • Environment file detection
  • Variable parsing logic
  • Basic validation functionality

Phase 2: Error Handling System ✅

Rules:

• Error Handling - Use custom error classes
• TypeScript Guidelines - Implement proper error types

Tasks

• Error Handling Tests

  • Test custom error classes
  • Test error message formatting
  • Test error context inclusion

• Implementation (errors.ts)

  • Custom error classes (GardistoError, ConfigurationError, FileSystemError, EnvironmentError, ValidationError)
  • Error context handling through constructor parameters
  • Error message formatting with toJSON method

Phase 3: File System Operations ⏳

Rules:

• Performance - Optimize file scanning
• Testing Standards - Mock file system operations

Tasks

• File Utility Tests

  • Test file reading operations
  • Test directory scanning
  • Test file pattern matching
  • Test file operation errors

• Implementation (fileUtils.ts)

  • File reading functionality
  • Directory scanning logic
  • Pattern matching implementation

Phase 4: Logging System ⏳

Rules:

• Error Handling - Use logger.ts for consistent logging
• Documentation - Document all public APIs

Tasks

• Logger Tests

  • Test log levels
  • Test log formatting
  • Test debug mode
  • Test output configuration

• Implementation (logger.ts)

  • Log level management
  • Formatting utilities
  • Debug mode functionality

Phase 5: Type System ⏳

Rules:

• TypeScript Guidelines - Use explicit type annotations
• Naming Conventions - Use PascalCase for types

Tasks

• Type System Tests

  • Test type validations
  • Test interface implementations
  • Test generic type usage

• Implementation (types.ts)

  • Core interfaces
  • Type guards
  • Generic type utilities

Phase 6: Main Entry Point ⏳

Rules:

• Code Style - Follow functional programming principles
• Documentation - Include usage examples

Tasks

• Main Functionality Tests

  • Test configuration options
  • Test API endpoints
  • Test integration scenarios

• Implementation (gardisto.ts)

  • Main API implementation
  • Configuration handling
  • Integration logic

Phase 7: Public API ⏳

Rules:

• Documentation - Document public APIs
• TypeScript Guidelines - Document with JSDoc

Tasks

• API Tests

  • Test public interface
  • Test API versioning
  • Test backwards compatibility

• Implementation (index.ts)

  • Public API exports
  • Version management
  • Documentation

TDD Workflow for Each Task

For each task in the phases above:

1. 🔴 Red Phase

   • Write failing test
   • Verify test failure

2. 💚 Green Phase

   • Write minimal implementation
   • Verify test passes

3. 🔄 Refactor Phase

   • Improve code quality
   • Maintain passing tests

Progress Legend

• ⏳ Not Started
• 🏗️ In Progress
• ✅ Completed

Notes

• Each phase must be completed before moving to the next
• All tests must pass before marking a phase as completed
• Code quality checks must pass before completion
• Documentation must be updated with each phase