🏗️ [EPIC] Project Health Auditor - Production-Grade Workspace Analysis Tool

Migrated from llm/agent-buildkit#1 on 2025-10-12T20:16:24.147Z Original author: @group_286_bot_4df652bbc58e62e505f1a777cd8f21b8 | Created: 2025-10-11T03:54:27.652Z

Project Health Auditor - Complete Implementation

Overview

Production-grade REST API and CLI tool for analyzing project health across the LLM workspace. Replaces bash scripts with type-safe, SOLID-principled TypeScript services.

Current Status: 14% Complete (1 of 8 services)

✅ Completed

• OpenAPI spec: /openapi/project-health.openapi.yml (15 endpoints, 6 tags)
• Zod schemas: /src/types/dto/project-health.schemas.ts (20+ schemas with runtime validation)
• Port interfaces: /src/services/ports/project-health.port.ts (8 SOLID interfaces)
• ProjectDiscoveryService: /src/services/domain/project-health/ProjectDiscoveryService.ts (360 lines, fully implemented)

❌ Remaining Work

Services (6 implementations needed)

1. StructureAnalyzerService - Analyze project directory structures
2. ScriptAuditorService - Audit shell scripts (candidates for TS conversion)
3. MarkdownAuditorService - Audit markdown files (find auto-generated docs)
4. ComponentAnalyzerService - Analyze component distribution
5. HealthScoringService - Calculate overall project health scores
6. CleanupService - Execute automated cleanup operations
7. WorkspaceAuditorService - Orchestrate workspace-wide audits

Integration

• Fastify API routes (15 endpoints)
• CLI commands (`buildkit health audit`, `buildkit health recommend`)
• Service aggregation (ProjectHealthService class)
• Dependency injection wiring

Testing

• Unit tests for all services
• Integration tests for API
• E2E tests for CLI
• Test fixtures and mocks

Architecture

SOLID Principles Applied

• Single Responsibility: Each service has ONE job
• Open/Closed: Extensible via constructor injection
• Liskov Substitution: Services implement port contracts
• Interface Segregation: Ports have focused interfaces
• Dependency Inversion: Services depend on abstractions (IFileSystemPort)

Hexagonal Architecture (Ports & Adapters)

• Ports: Define contracts in `/src/services/ports/`
• Domain Services: Implement business logic in `/src/services/domain/project-health/`
• Adapters: Filesystem, API, CLI adapters

Type Safety

• OpenAPI-first: Single source of truth
• Zod schemas: Runtime validation + TypeScript inference
• No `any` types: Full type coverage

Goals

1. Eliminate bash scripts → TypeScript services
2. Automated audits → Identify anti-patterns across workspace
3. Actionable insights → Generate cleanup recommendations
4. CLI integration → `buildkit health audit` command
5. API access → REST endpoints for programmatic access

Deliverables

• All 7 services implemented and tested
• API routes with request validation
• CLI commands with progress indicators
• Comprehensive test suite (>80% coverage)
• Documentation and usage examples

Estimated Effort

Total: 85-110 hours (~2-3 weeks for one developer)

• Services: 40-60 hours
• API/CLI: 12 hours
• Tests: 20 hours
• Integration: 5 hours
• Documentation: 8 hours

Dependencies

All child issues depend on existing foundation:

• OpenAPI spec (completed)
• Zod schemas (completed)
• Port interfaces (completed)
• ProjectDiscoveryService (reference implementation)

References

• OpenAPI Spec: `/openapi/project-health.openapi.yml`
• Port Interfaces: `/src/services/ports/project-health.port.ts`
• Reference Implementation: `/src/services/domain/project-health/ProjectDiscoveryService.ts`
• Type Definitions: `/src/types/dto/project-health.schemas.ts`

Labels

`enhancement`, `epic`, `architecture`, `health-monitoring`, `high-priority`