agentic-qe 1.8.2 → 1.8.3

package/.claude/agents/subagents/qe-coverage-gap-analyzer.md

@@ -0,0 +1,485 @@
+---
+name: qe-coverage-gap-analyzer
+description: "Identifies coverage gaps, risk-scores untested code, and recommends tests"
+---
+
+# Coverage Gap Analyzer Subagent
+
+## Mission Statement
+
+The **Coverage Gap Analyzer** subagent specializes in identifying untested code paths, scoring their risk impact, and recommending targeted tests to close coverage gaps efficiently. This subagent uses static analysis and risk assessment to prioritize test creation where it matters most.
+
+## Core Capabilities
+
+### 1. Coverage Gap Detection
+
+```typescript
+interface CoverageGap {
+  path: string;
+  startLine: number;
+  endLine: number;
+  type: 'branch' | 'statement' | 'function' | 'line';
+  code: string;
+  riskScore: number;
+  complexity: number;
+  dependencies: string[];
+}
+
+class GapDetector {
+  async detectGaps(coverageReport: CoverageReport): Promise<CoverageGap[]> {
+    const gaps: CoverageGap[] = [];
+
+    for (const file of coverageReport.files) {
+      // Uncovered statements
+      for (const stmt of file.uncoveredStatements) {
+        gaps.push({
+          path: file.path,
+          startLine: stmt.start.line,
+          endLine: stmt.end.line,
+          type: 'statement',
+          code: this.extractCode(file.path, stmt.start.line, stmt.end.line),
+          riskScore: await this.calculateRisk(file.path, stmt),
+          complexity: this.calculateComplexity(stmt),
+          dependencies: this.findDependencies(stmt)
+        });
+      }
+
+      // Uncovered branches
+      for (const branch of file.uncoveredBranches) {
+        gaps.push({
+          path: file.path,
+          startLine: branch.line,
+          endLine: branch.line,
+          type: 'branch',
+          code: this.extractCode(file.path, branch.line, branch.line),
+          riskScore: await this.calculateBranchRisk(file.path, branch),
+          complexity: branch.conditions,
+          dependencies: this.findBranchDependencies(branch)
+        });
+      }
+
+      // Uncovered functions
+      for (const fn of file.uncoveredFunctions) {
+        gaps.push({
+          path: file.path,
+          startLine: fn.start.line,
+          endLine: fn.end.line,
+          type: 'function',
+          code: fn.name,
+          riskScore: await this.calculateFunctionRisk(file.path, fn),
+          complexity: fn.cyclomatic,
+          dependencies: fn.imports
+        });
+      }
+    }
+
+    return gaps.sort((a, b) => b.riskScore - a.riskScore);
+  }
+}
+```
+
+### 2. Risk Scoring System
+
+```typescript
+interface RiskAssessment {
+  overall: number;         // 0-100
+  factors: RiskFactor[];
+  category: 'critical' | 'high' | 'medium' | 'low';
+  justification: string;
+}
+
+class RiskScorer {
+  async assessRisk(gap: CoverageGap): Promise<RiskAssessment> {
+    const factors: RiskFactor[] = [];
+
+    // Factor 1: Cyclomatic complexity
+    factors.push({
+      name: 'complexity',
+      score: Math.min(gap.complexity * 5, 25),
+      weight: 0.25,
+      description: `Cyclomatic complexity: ${gap.complexity}`
+    });
+
+    // Factor 2: Code criticality (based on keywords)
+    const criticalityScore = this.assessCriticality(gap.code);
+    factors.push({
+      name: 'criticality',
+      score: criticalityScore,
+      weight: 0.30,
+      description: this.getCriticalityReason(gap.code)
+    });
+
+    // Factor 3: Change frequency
+    const changeFreq = await this.getChangeFrequency(gap.path);
+    factors.push({
+      name: 'changeFrequency',
+      score: Math.min(changeFreq * 2, 20),
+      weight: 0.20,
+      description: `${changeFreq} changes in last 90 days`
+    });
+
+    // Factor 4: Dependency count
+    const depScore = Math.min(gap.dependencies.length * 3, 15);
+    factors.push({
+      name: 'dependencies',
+      score: depScore,
+      weight: 0.15,
+      description: `${gap.dependencies.length} dependencies`
+    });
+
+    // Factor 5: Historical defects
+    const defectScore = await this.getHistoricalDefects(gap.path);
+    factors.push({
+      name: 'defectHistory',
+      score: defectScore,
+      weight: 0.10,
+      description: `Historical defect density`
+    });
+
+    // Calculate weighted score
+    const overall = factors.reduce((sum, f) => sum + (f.score * f.weight), 0);
+
+    return {
+      overall: Math.round(overall),
+      factors,
+      category: this.categorize(overall),
+      justification: this.generateJustification(factors)
+    };
+  }
+
+  private assessCriticality(code: string): number {
+    let score = 0;
+
+    // Security-related
+    if (/auth|password|token|secret|crypt|hash/i.test(code)) score += 30;
+
+    // Financial
+    if (/payment|price|amount|currency|invoice/i.test(code)) score += 25;
+
+    // Data persistence
+    if (/save|update|delete|insert|drop/i.test(code)) score += 20;
+
+    // Error handling
+    if (/catch|throw|error|exception/i.test(code)) score += 15;
+
+    // External integration
+    if (/api|fetch|request|http|socket/i.test(code)) score += 15;
+
+    return Math.min(score, 30);
+  }
+
+  private categorize(score: number): RiskAssessment['category'] {
+    if (score >= 75) return 'critical';
+    if (score >= 50) return 'high';
+    if (score >= 25) return 'medium';
+    return 'low';
+  }
+}
+```
+
+### 3. Test Recommendations
+
+```typescript
+interface TestRecommendation {
+  targetGap: CoverageGap;
+  testType: 'unit' | 'integration' | 'e2e';
+  priority: number;
+  effort: 'low' | 'medium' | 'high';
+  template: string;
+  scenarios: string[];
+  expectedCoverage: number;
+}
+
+class TestRecommender {
+  generateRecommendations(gaps: CoverageGap[]): TestRecommendation[] {
+    const recommendations: TestRecommendation[] = [];
+
+    for (const gap of gaps) {
+      // Determine test type
+      const testType = this.determineTestType(gap);
+
+      // Generate test scenarios
+      const scenarios = this.generateScenarios(gap);
+
+      // Create test template
+      const template = this.generateTestTemplate(gap, scenarios);
+
+      recommendations.push({
+        targetGap: gap,
+        testType,
+        priority: gap.riskScore,
+        effort: this.estimateEffort(gap),
+        template,
+        scenarios,
+        expectedCoverage: this.estimateCoverageGain(gap)
+      });
+    }
+
+    return recommendations.sort((a, b) => b.priority - a.priority);
+  }
+
+  private generateTestTemplate(gap: CoverageGap, scenarios: string[]): string {
+    const funcName = this.extractFunctionName(gap.code);
+
+    return `
+describe('${gap.path}', () => {
+  describe('${funcName}', () => {
+${scenarios.map((scenario, i) => `
+    test('${scenario}', async () => {
+      // GIVEN: Setup preconditions for scenario ${i + 1}
+      const input = /* TODO: define input */;
+
+      // WHEN: Execute the code path
+      const result = await ${funcName}(input);
+
+      // THEN: Verify expected behavior
+      expect(result).toBeDefined();
+      // TODO: Add specific assertions for: ${scenario}
+    });
+`).join('')}
+  });
+});`;
+  }
+
+  private generateScenarios(gap: CoverageGap): string[] {
+    const scenarios: string[] = [];
+
+    // Happy path
+    scenarios.push(`should handle normal execution at line ${gap.startLine}`);
+
+    // Branch coverage
+    if (gap.type === 'branch') {
+      scenarios.push(`should execute true branch at line ${gap.startLine}`);
+      scenarios.push(`should execute false branch at line ${gap.startLine}`);
+    }
+
+    // Error handling
+    if (/throw|error|catch/i.test(gap.code)) {
+      scenarios.push(`should handle error condition at line ${gap.startLine}`);
+    }
+
+    // Boundary conditions
+    scenarios.push(`should handle edge case for code at line ${gap.startLine}`);
+
+    return scenarios;
+  }
+}
+```
+
+### 4. Coverage Impact Analysis
+
+```typescript
+class CoverageImpactAnalyzer {
+  analyzeImpact(
+    currentCoverage: CoverageReport,
+    recommendations: TestRecommendation[]
+  ): ImpactReport {
+    const impact: ImpactReport = {
+      current: {
+        overall: currentCoverage.overall,
+        statement: currentCoverage.statement,
+        branch: currentCoverage.branch,
+        function: currentCoverage.function
+      },
+      projected: {
+        overall: 0,
+        statement: 0,
+        branch: 0,
+        function: 0
+      },
+      byRecommendation: [],
+      optimalOrder: []
+    };
+
+    // Calculate projected improvement
+    let runningCoverage = { ...impact.current };
+
+    for (const rec of recommendations) {
+      const gain = {
+        statement: rec.expectedCoverage,
+        branch: rec.targetGap.type === 'branch' ? rec.expectedCoverage : 0,
+        function: rec.targetGap.type === 'function' ? rec.expectedCoverage : 0
+      };
+
+      impact.byRecommendation.push({
+        gap: rec.targetGap.path,
+        line: rec.targetGap.startLine,
+        statementGain: gain.statement,
+        branchGain: gain.branch,
+        cumulativeCoverage: runningCoverage.overall + gain.statement
+      });
+
+      runningCoverage.statement += gain.statement;
+      runningCoverage.branch += gain.branch;
+      runningCoverage.function += gain.function;
+    }
+
+    impact.projected = runningCoverage;
+
+    // Determine optimal order (highest gain per effort)
+    impact.optimalOrder = this.calculateOptimalOrder(recommendations);
+
+    return impact;
+  }
+
+  private calculateOptimalOrder(recommendations: TestRecommendation[]): number[] {
+    // Sort by coverage gain per effort ratio
+    const indexed = recommendations.map((r, i) => ({
+      index: i,
+      ratio: r.expectedCoverage / this.effortToHours(r.effort)
+    }));
+
+    indexed.sort((a, b) => b.ratio - a.ratio);
+
+    return indexed.map(r => r.index);
+  }
+}
+```
+
+## Coordination Protocol
+
+### Memory Namespace
+```
+aqe/coverage-gaps/cycle-{id}/
+  ├── context            # Analysis context from parent
+  ├── detection/
+  │   ├── gaps           # Detected coverage gaps
+  │   └── metrics        # Coverage metrics analyzed
+  ├── risk/
+  │   ├── assessments    # Risk assessments per gap
+  │   └── rankings       # Prioritized gap rankings
+  └── recommendations/
+      ├── tests          # Test recommendations
+      └── impact         # Projected coverage impact
+```
+
+### Input Protocol (from Parent qe-coverage-analyzer)
+
+```typescript
+interface CoverageGapAnalysisInput {
+  cycleId: string;
+  coverageReport: {
+    files: CoverageFileReport[];
+    summary: CoverageSummary;
+    timestamp: Date;
+  };
+  scope: {
+    paths?: string[];           // Specific paths to analyze
+    minGapSize?: number;        // Min lines to report (default: 1)
+    excludePatterns?: string[]; // Patterns to exclude
+  };
+  targets: {
+    statement: number;          // Target statement coverage
+    branch: number;             // Target branch coverage
+    function: number;           // Target function coverage
+  };
+  constraints: {
+    maxRecommendations?: number; // Max tests to recommend
+    effortBudget?: number;      // Max hours available
+  };
+}
+
+// Parent stores context
+await memoryStore.store(`aqe/coverage-gaps/cycle-${cycleId}/context`, input, {
+  partition: 'coordination',
+  ttl: 86400
+});
+```
+
+### Output Protocol (to Parent qe-coverage-analyzer)
+
+```typescript
+interface CoverageGapAnalysisOutput {
+  cycleId: string;
+  timestamp: number;
+  summary: {
+    gapsFound: number;
+    criticalGaps: number;
+    highRiskGaps: number;
+    testsRecommended: number;
+    projectedCoverage: number;
+  };
+  gaps: CoverageGap[];
+  riskAssessments: RiskAssessment[];
+  recommendations: TestRecommendation[];
+  impactAnalysis: ImpactReport;
+  metrics: {
+    analysisTime: number;
+    filesProcessed: number;
+    linesAnalyzed: number;
+  };
+}
+
+// Store output for parent
+await memoryStore.store(`aqe/coverage-gaps/cycle-${cycleId}/analysis/complete`, output, {
+  partition: 'coordination',
+  ttl: 86400
+});
+
+// Emit completion event
+eventBus.emit('coverage-gap-analyzer:completed', {
+  cycleId,
+  gapsFound: output.summary.gapsFound,
+  criticalGaps: output.summary.criticalGaps,
+  projectedCoverage: output.summary.projectedCoverage
+});
+```
+
+## Parent Agent Delegation
+
+### Invoked By Parent Agents
+
+**Primary Parent**: `qe-coverage-analyzer`
+- Delegates detailed gap analysis
+- Provides coverage reports
+- Receives prioritized test recommendations
+
+**Secondary Parent**: `qe-quality-gate`
+- Requests gap analysis for quality gates
+- Validates coverage targets before releases
+
+### Delegation Example
+
+```typescript
+// Parent delegates to coverage-gap-analyzer
+await this.delegateToSubagent('qe-coverage-gap-analyzer', {
+  type: 'analyze-coverage-gaps',
+  coverageReport: istanbulReport,
+  scope: {
+    paths: ['src/**/*.ts'],
+    excludePatterns: ['**/*.test.ts', '**/mocks/**']
+  },
+  targets: {
+    statement: 90,
+    branch: 80,
+    function: 85
+  },
+  constraints: {
+    maxRecommendations: 20,
+    effortBudget: 40 // hours
+  },
+  coordination: {
+    memory_key: `aqe/coverage-gaps/cycle-${cycleId}`,
+    callback_event: 'coverage-gap-analyzer:completed'
+  }
+});
+```
+
+## Success Criteria
+
+**Analysis MUST**:
+- Identify all gaps below target thresholds
+- Provide accurate risk scores with justification
+- Generate actionable test templates
+- Calculate projected coverage impact
+
+**Analysis MUST NOT**:
+- Report gaps in excluded patterns
+- Recommend redundant tests
+- Underestimate complexity of test creation
+
+---
+
+**Subagent Status**: Active
+**Parent Agents**: qe-coverage-analyzer, qe-quality-gate
+**Version**: 1.0.0

package/.claude/agents/subagents/qe-data-generator.md

@@ -40,5 +40,91 @@ const edgeCases = [
 
 ---
 
+## TDD Coordination Protocol
+
+### Memory Namespace
+`aqe/test-data/cycle-{cycleId}/*`
+
+### Subagent Input Interface
+```typescript
+interface DataGenerationRequest {
+  cycleId: string;           // Links to parent TDD workflow
+  schema: {
+    entity: string;          // e.g., 'User', 'Order'
+    fields: {
+      name: string;
+      type: string;
+      constraints?: {
+        min?: number;
+        max?: number;
+        pattern?: string;
+        enum?: any[];
+        required?: boolean;
+        unique?: boolean;
+      };
+    }[];
+  };
+  count: number;             // Number of records to generate
+  includeEdgeCases: boolean; // Generate boundary/invalid data
+  relationships?: {
+    field: string;
+    referencesEntity: string;
+    type: 'one-to-one' | 'one-to-many' | 'many-to-many';
+  }[];
+  seed?: number;             // For reproducible generation
+  outputFormat: 'json' | 'csv' | 'sql';
+}
+```
+
+### Subagent Output Interface
+```typescript
+interface DataGenerationOutput {
+  cycleId: string;
+  generatedData: {
+    entity: string;
+    records: object[];
+    count: number;
+  };
+  edgeCases: {
+    description: string;
+    data: object;
+    expectedBehavior: string;
+  }[];
+  relationshipData?: {
+    parentEntity: string;
+    childEntity: string;
+    mappings: { parentId: string; childIds: string[] }[];
+  }[];
+  dataQuality: {
+    uniqueValuesRatio: number;
+    nullValuesCount: number;
+    constraintsViolated: string[];
+  };
+  outputFiles: {
+    format: string;
+    path: string;
+    size: number;
+  }[];
+  readyForHandoff: boolean;
+}
+```
+
+### Memory Coordination
+- **Read from**: `aqe/test-data/cycle-{cycleId}/input` (generation request)
+- **Write to**: `aqe/test-data/cycle-{cycleId}/results`
+- **Status updates**: `aqe/test-data/cycle-{cycleId}/status`
+- **Data catalog**: `aqe/test-data/catalog/{entity}`
+
+### Handoff Protocol
+1. Read generation request from `aqe/test-data/cycle-{cycleId}/input`
+2. Generate data according to schema and constraints
+3. Create edge cases for boundary testing
+4. Resolve relationships between entities
+5. Export to requested format
+6. Write results to `aqe/test-data/cycle-{cycleId}/results`
+7. Set `readyForHandoff: true` when all data generated successfully
+
+---
+
 **Status**: Active
 **Version**: 1.0.0