citty-test-utils/docs/architecture/README.md

A comprehensive testing framework for CLI applications built with Citty, featuring Docker cleanroom support, fluent assertions, advanced scenario DSL, and noun-verb CLI structure with template generation.

# 🏗️ CTU Analysis Verbs Architecture Documentation

## 📋 **Overview**

This documentation provides comprehensive PlantUML architecture diagrams for the CTU Analysis Verbs system, showing the design, data flow, and system integration of the AST-based CLI coverage analysis framework.

## 📊 **Architecture Diagrams**

### 1. **System Architecture** (`analysis-verbs-architecture.puml`)
**High-level system overview showing all components and their relationships**

- **CLI Interface Layer**: Command routing and parameter processing
- **Analysis Engine Layer**: Core AST-based and legacy analyzers
- **AST Processing Layer**: JavaScript parsing and command extraction
- **Data Processing Layer**: Coverage calculation and report generation
- **Output Layer**: Format conversion and file writing

**Key Features:**
- Shows the dual analyzer approach (AST-based + legacy)
- Illustrates import tracking and subcommand resolution
- Demonstrates format-specific output handling

### 2. **Sequence Flow** (`analysis-verbs-sequence.puml`)
**Detailed interaction flow showing data movement through the system**

- **Command Execution Flow**: User input to command routing
- **AST-Based Analysis Flow**: CLI structure discovery and test pattern matching
- **Output Generation Flow**: Format conversion and output handling
- **Error Handling Flow**: Graceful failure management

**Key Features:**
- Step-by-step process flow
- Activation/deactivation of components
- Error handling and performance optimizations
- Parallel processing capabilities

### 3. **Component Architecture** (`analysis-verbs-components.puml`)
**Detailed internal structure of all system components**

- **Command Interface**: Individual command implementations
- **Core Analysis Engine**: Primary and legacy analyzers
- **AST Processing Core**: JavaScript parsing and command extraction
- **Test Analysis Engine**: Test file discovery and pattern extraction
- **Data Processing Layer**: Coverage calculation and report generation
- **Output Layer**: Console, file, and stream output handling

**Key Features:**
- Granular component breakdown
- Internal component relationships
- Data flow between components
- Performance and scalability annotations

### 4. **Data Flow Pipeline** (`analysis-verbs-dataflow.puml`)
**Activity diagram showing data transformation through the system**

- **AST-Based Analysis Pipeline**: CLI structure discovery
- **Test Pattern Discovery Pipeline**: Test usage extraction
- **Coverage Calculation Pipeline**: Statistics and metrics
- **Report Generation Pipeline**: Comprehensive report assembly
- **Output Formatting Pipeline**: Format-specific serialization

**Key Features:**
- Data transformation stages
- Pipeline branching logic
- Error handling flows
- Performance optimization notes

### 5. **Deployment Architecture** (`analysis-verbs-deployment.puml`)
**System integration and dependency relationships**

- **Citty Test Utils Ecosystem**: Internal system components
- **Target CLI Applications**: External CLI files and test suites
- **Output Destinations**: Console and file outputs
- **External Dependencies**: Node.js runtime and NPM packages

**Key Features:**
- System integration points
- External dependency management
- Runtime requirements
- Scalability considerations

## 🎯 **Architecture Principles**

### **1. Separation of Concerns**
- **Command Layer**: User interface and parameter handling
- **Analysis Layer**: Core business logic and processing
- **Data Layer**: Data models and transformations
- **Output Layer**: Format conversion and delivery

### **2. AST-First Design**
- **Primary Engine**: Enhanced AST CLI Analyzer for accuracy
- **Legacy Support**: Help-based analyzer for backward compatibility
- **Consistent Processing**: AST parsing throughout the pipeline

### **3. Extensibility**
- **Plugin Architecture**: Easy addition of new analysis methods
- **Format Support**: Extensible output format system
- **Command Extension**: Simple addition of new analysis verbs

### **4. Performance Optimization**
- **Parallel Processing**: Concurrent test file analysis
- **AST Caching**: Repeated analysis optimization
- **Memory Efficiency**: Optimized data structures
- **Configurable Limits**: Timeout and resource management

## 🔧 **Key Components**

### **Enhanced AST CLI Analyzer**
- **Purpose**: Primary analysis engine using AST parsing
- **Features**: Import tracking, subcommand resolution, precise coverage
- **Usage**: All commands except Turtle export

### **Legacy CLI Coverage Analyzer**
- **Purpose**: Backward compatibility for Turtle/RDF output
- **Features**: Help-based parsing, RDF generation
- **Usage**: Export command for Turtle format only

### **Import Resolution Engine**
- **Purpose**: Track and resolve command imports
- **Features**: Module path resolution, command mapping
- **Benefits**: Enables accurate subcommand discovery

### **Test Pattern Extractor**
- **Purpose**: Extract test usage patterns from test files
- **Features**: AST-based call extraction, argument parsing
- **Benefits**: Precise test coverage mapping

## 📈 **Performance Characteristics**

### **Time Complexity**
- **AST Parsing**: O(n) where n = file size
- **Test Discovery**: O(m) where m = number of test files
- **Coverage Calculation**: O(c×t) where c = commands, t = tests
- **Overall**: O(n + m + c×t) for complete analysis

### **Space Complexity**
- **AST Storage**: O(n + m) for parsed ASTs
- **Pattern Storage**: O(c + f + o) for commands, flags, options
- **Report Generation**: O(r) where r = report size
- **Overall**: O(n + m + c + f + o + r) for complete analysis

### **Optimization Strategies**
- **Parallel Processing**: Concurrent test file analysis
- **AST Caching**: Repeated analysis optimization
- **Memory Management**: Efficient data structures
- **Lazy Loading**: On-demand component initialization

## 🚀 **Usage Examples**

### **Generate Architecture Diagrams**
```bash
# Install PlantUML (if not already installed)
npm install -g plantuml

# Generate all diagrams
plantuml docs/architecture/*.puml

# Generate specific diagram
plantuml docs/architecture/analysis-verbs-architecture.puml
```

### **View Diagrams**
- **PNG**: `plantuml -tpng docs/architecture/*.puml`
- **SVG**: `plantuml -tsvg docs/architecture/*.puml`
- **PDF**: `plantuml -tpdf docs/architecture/*.puml`

## 🔍 **Architecture Benefits**

### **1. Maintainability**
- **Clear Separation**: Well-defined component boundaries
- **Modular Design**: Easy to modify and extend
- **Documentation**: Comprehensive architectural documentation

### **2. Scalability**
- **Parallel Processing**: Concurrent analysis capabilities
- **Memory Efficiency**: Optimized data structures
- **Configurable Limits**: Resource management controls

### **3. Reliability**
- **Error Handling**: Graceful failure management
- **Fallback Mechanisms**: AST parsing with regex fallback
- **Validation**: Comprehensive input validation

### **4. Extensibility**
- **Plugin Architecture**: Easy addition of new analyzers
- **Format Support**: Extensible output format system
- **Command Extension**: Simple addition of new verbs

## 📚 **Related Documentation**

- [Analysis Commands Review](./ANALYSIS-COMMANDS-REVIEW.md)
- [AST Innovation Summary](./AST-INNOVATION-SUMMARY.md)
- [CLI Coverage Analysis Guide](../guides/cli-coverage-analysis-guide.md)

## 🎯 **Future Enhancements**

### **Planned Improvements**
1. **Recursive Command Analysis**: Parse individual command files
2. **Dependency Analysis**: Track command dependencies
3. **Coverage Visualization**: Generate coverage charts and graphs
4. **CI/CD Integration**: Automated coverage tracking

### **Architecture Evolution**
1. **Microservice Architecture**: Distributed analysis capabilities
2. **Plugin System**: Third-party analyzer support
3. **Real-time Analysis**: Live coverage monitoring
4. **Cloud Integration**: Scalable analysis services

---

This architecture documentation provides a comprehensive view of the CTU Analysis Verbs system, enabling developers to understand, maintain, and extend the AST-based CLI coverage analysis framework.