---
type: spec
feature_id: qa
feature_name: Quality Assurance Commands System
related_brd: ../brds/qa-brd.md
related_prd: ../prds/qa-prd.md
version: 1.0
status: Ready for Implementation
created: 2025-10-29
---

# Quality Assurance Commands - Technical Specification

## 1. Requirements → Spec Mapping

| PRD Requirement | Spec Section | Implementation |
|-----------------|-------------|-----------------|
| R1: Security Scanning | 2.2 | `scripts/audit-security.ts` |
| R2: Complexity Analysis | 2.4 | `scripts/audit-complexity.ts` |
| R3: Performance Detection | 2.3 | `scripts/audit-performance.ts` |
| R4: Code Review | 2.1 | `scripts/review-code.ts` |
| R5: Coverage Analysis | 2.5 | `scripts/analyze-test-coverage.ts` |
| R6: Code Cleanup | 2.6 | `scripts/code-cleanup.ts` |

---

## 2. Individual Command Specifications

### 2.1 review-code

**Type**: Orchestrator  
**File**: `scripts/review-code.ts`  
**Input**: GitHub issue number  
**Output**: Comprehensive code review report (Markdown + JSON)

**Responsibilities**:
1. Fetch issue details from GitHub
2. Validate requirements compliance against acceptance criteria
3. Check coding standards (from .cursorrules.md)
4. Analyze quota/rate limits
5. Run security + complexity audits
6. Provide functional testing checklist
7. Generate APPROVE/FIX/REJECT recommendation

**Implementation**:
- Read issue body, extract acceptance criteria
- Get changed files from git
- Load `.cursorrules.md` for standards
- Run `audit-security` and `audit-complexity` in parallel
- Parse `config/runtime.template.json` for API limits
- Generate markdown report with all findings

**Output Format**:
```markdown
### Review Result
- Issue: #N - [Title]
- Overall: ✅/⚠️/❌
- Requirements: X/Y passing
- Standards: X violations
- Recommendation: APPROVE/FIX/REJECT
```

---

### 2.2 audit-security

**Type**: Atomic Command  
**File**: `scripts/audit-security.ts`  
**Input**: Optional flags (--severity, --create-issues)  
**Output**: Security findings report (Markdown + JSON + SARIF)

**Responsibilities**:
1. Run ESLint with security plugins
2. Run npm audit for dependencies
3. Analyze authentication patterns
4. Analyze data handling practices
5. Categorize findings (AUTH, DATA, INJECTION, DEPENDENCY, CONFIG)
6. Prioritize by severity (CRITICAL > HIGH > MEDIUM > LOW)
7. Generate SARIF report for GitHub Security tab
8. Optional: Create GitHub issues for critical findings

**Detection Categories**:
- 🔴 **CRITICAL**: RCE, SQL injection, auth bypass, exposed secrets
- 🟠 **HIGH**: XSS, CSRF, unencrypted PII, weak auth
- 🟡 **MEDIUM**: Insecure defaults, missing rate limiting
- 🟢 **LOW**: Best practices, code hygiene

**Implementation**:
```bash
# Run ESLint
eslint scripts/ --format json --plugin security

# Run npm audit
npm audit --json

# Pattern matching for auth/data issues
grep -r "password\|token\|secret" src/ | classify
```

**Output Format**:
```markdown
# Security Audit Report

## Summary
- 🔴 Critical: N
- 🟠 High: N
- 🟡 Medium: N
- 🟢 Low: N

## Findings by Category
[List each finding with severity, location, risk, remediation, CWE, OWASP ref]
```

---

### 2.3 audit-performance

**Type**: Atomic Command  
**File**: `scripts/audit-performance.ts`  
**Input**: Optional flags (--threshold, --compare)  
**Output**: Performance analysis report (Markdown + JSON)

**Responsibilities**:
1. Identify slow-running functions
2. Detect algorithmic inefficiencies (O(n²) loops, nesting)
3. Analyze memory patterns
4. Compare against baseline from previous scan
5. Estimate improvement potential

**Detection Methods**:
- **AST Analysis**: Parse TypeScript/JavaScript
- **Pattern Matching**: Find nested loops, unbounded structures
- **Baseline Comparison**: Load previous metrics, calculate delta
- **Estimation**: Rank by impact (requests affected)

**Performance Categories**:
- 🔴 **Critical**: Blocks scalability (O(n²), memory leaks)
- 🟠 **High**: 10%+ slower than baseline
- 🟡 **Medium**: 5-10% slower
- 🟢 **Low**: Optimization suggestions

**Implementation**:
- Parse AST to find function signatures
- Detect nested loops and recursion depth
- Load baseline from `config/reports/performance-baseline.json`
- Calculate execution time estimates
- Suggest specific optimizations

**Output Format**:
```markdown
# Performance Audit Report

## Summary
- Slow Functions: N
- Memory Issues: N
- Algorithmic Issues: N

## Critical Issues
[Each issue: location, current perf, target perf, problem, recommendation, effort]
```

---

### 2.4 audit-complexity

**Type**: Atomic Command  
**File**: `scripts/audit-complexity.ts`  
**Input**: Optional flags (--max-complexity, --sort)  
**Output**: Complexity metrics report (Markdown + JSON)

**Responsibilities**:
1. Calculate cyclomatic complexity per function
2. Measure function size (LOC)
3. Measure nesting depth
4. Calculate maintainability index
5. Rank functions by complexity level
6. Provide refactoring recommendations

**Complexity Thresholds**:
- Cyclomatic: 1-3 ✅, 4-7 🟡, 8-10 ⚠️, 11+ 🔴
- Function Size: 1-20 LOC ✅, 21-50 🟡, 51-100 ⚠️, 100+ 🔴
- Nesting: 1-2 ✅, 3-4 🟡, 5+ 🔴

**Implementation**:
- Parse TypeScript to build AST
- Count decision nodes + 1 for cyclomatic complexity
- Count lines for function size
- Track indent level for nesting depth
- Calculate maintainability index: 171 - 5.2*ln(Halstead) - 0.23*CC - 50*sin(sqrt(2.4*LOC))

**Output Format**:
```markdown
# Code Complexity Audit Report

## Summary
- Functions Exceeding Threshold: N
- Average Cyclomatic Complexity: X
- Maintainability Index: Y/100

## Critical Functions (>15)
[Each: name, location, complexity, size, nesting, recommendation]

## Refactoring Strategies
[Extract conditions, guard clauses, polymorphism, etc.]
```

---

### 2.5 analyze-test-coverage

**Type**: Atomic Command  
**File**: `scripts/analyze-test-coverage.ts`  
**Input**: Optional flags (--min-coverage, --show-dead-code)  
**Output**: Coverage analysis report (Markdown + JSON)

**Responsibilities**:
1. Parse `coverage/lcov.info` (Jest coverage)
2. Calculate overall coverage percentage
3. Identify untested functions (0% coverage)
4. Find partially tested branches
5. Detect dead code
6. Rank gaps by impact
7. Estimate effort to improve coverage

**Coverage Types**:
- **Lines**: % of executable lines tested
- **Branches**: % of conditional branches tested
- **Functions**: % of functions called during tests
- **Statements**: % of statements executed

**Implementation**:
- Parse LCOV format (line-by-line coverage)
- Extract file/function/branch info
- Calculate percentages for each type
- Identify 0% coverage items (untested)
- Rank by files affected, frequency changed, criticality

**Output Format**:
```markdown
# Test Coverage Analysis Report

## Summary
- Overall: 62% (Target: 80%)
- Lines: 77% | Branches: 46% | Functions: 70% | Statements: 78%

## Untested Functions (0%)
[Each file: function names, line ranges, estimated effort to test]

## Improvement Roadmap
Phase 1: Critical (0% coverage)
Phase 2: High (Branch coverage <50%)
Phase 3: Medium (File coverage <70%)
```

---

### 2.6 code-cleanup

**Type**: Maintenance Command  
**File**: `scripts/code-cleanup.ts`  
**Input**: Context-dependent (run after new implementation confirmed working)  
**Output**: Cleanup execution log (Markdown + git operations)

**Responsibilities**:
1. Identify old/deprecated files to remove
2. Verify new implementation is working
3. Find all references to old code
4. Delete files via `git rm`
5. Update references in all files
6. Create cleanup commit
7. Verify no broken imports

**Cleanup Categories**:
- **Immediate**: Old implementations, temporary helpers, dead code, duplicates
- **Delayed**: Backwards compatibility layers (keep 1 version)
- **Never Delete**: Working code with no replacement, code used externally

**Implementation**:
- List old files candidates
- Ask for confirmation with preview
- Use `git rm` for deletions
- Search/replace for reference updates
- Run `npm run build` to verify
- Create commit with clear message

**Output Format**:
```markdown
# Code Cleanup Report

## Summary
- Files Deleted: N
- Functions Removed: N
- References Updated: N

## Git Operations
[List of git rm/git add commands executed]

## Verification
✅ Build succeeds
✅ Tests pass
✅ No broken imports
```

---

## 2.7 CI/CD Integration

### GitHub Actions Workflows

**File**: `.github/workflows/qa-checks.yml`  
**Trigger**: PR, push to main, nightly (2 AM UTC)  
**Duration**: ~5 minutes  

**Steps**:
1. Checkout code
2. Install dependencies
3. Build TypeScript
4. Run audit-complexity
5. Run audit-security
6. Run audit-performance
7. Generate SARIF report
8. Upload to GitHub Security
9. Comment PR with results
10. Archive reports (30-day retention)

**File**: `.github/workflows/security-gate.yml`  
**Trigger**: Pull request to main  
**Fails if**: Any CRITICAL or 5+ HIGH findings

**File**: `.github/workflows/performance-gate.yml`  
**Trigger**: Pull request to main  
**Fails if**: 10%+ execution time regression or O(n²) patterns

### Gate Configuration

**File**: `.github/.roadcrew-ci.yml`
```yaml
gates:
  security:
    failOn: [CRITICAL]
    maxHigh: 5
  complexity:
    maxCyclomaticComplexity: 10
    maxFunctionSize: 100
  performance:
    maxRegressionPercentage: 10
  coverage:
    minOverall: 80
    minCriticalPath: 95
```

---

## 3. Shared Infrastructure

### Utilities (`scripts/utils/`)

**code-analyzer.ts**:
- `parseTSFile(path: string)` - Parse TypeScript to AST
- `calculateCyclomaticComplexity(ast)` - Count decision nodes
- `measureFunctionSize(node)` - Count LOC
- `measureNestingDepth(node)` - Track nesting level
- `detectPatterns(code, pattern)` - Find inefficiencies

**report-generator.ts**:
- `formatMarkdown(report)` - Convert to Markdown
- `formatJSON(report)` - Convert to JSON
- `formatSARIF(findings)` - Convert to SARIF
- `getColor(severity)` - Return emoji for severity

**baseline-manager.ts**:
- `loadBaseline(command)` - Load previous metrics
- `saveBaseline(command, metrics)` - Save current metrics
- `compareWithBaseline(current)` - Calculate delta
- `getTrend(history)` - 📈/📉/➡️

**git-integration.ts**:
- `getChangedFiles()` - Get git status
- `readFile(path)` - Read file content
- `deleteFile(path)` - Git rm operation
- `createCommit(message)` - Stage and commit

### Data Models (`scripts/core/qa-models.ts`)

```typescript
interface QAFinding {
  id: string;
  title: string;
  severity: 'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW';
  location: string;
  category: string;
  description: string;
  remediation: string;
  priority: number;
}

interface QAReport {
  commandName: string;
  scanDate: Date;
  summary: ScanSummary;
  findings: QAFinding[];
  metadata: ReportMetadata;
}

interface Baseline {
  date: Date;
  commandName: string;
  metrics: Record<string, number>;
  findings: QAFinding[];
}
```

---

## 4. Implementation Roadmap

### Phase 1: Foundation + CI/CD (Weeks 1-3)
**Goal**: Build shared infrastructure + deploy CI/CD pipeline

**Deliverables**:
- `scripts/utils/code-analyzer.ts` (8-10 hrs)
- `scripts/utils/report-generator.ts` (6-8 hrs)
- `scripts/core/qa-models.ts` (4-5 hrs)
- `.github/workflows/qa-checks.yml` (10-12 hrs)
- `.github/workflows/security-gate.yml` (3-4 hrs)
- `.github/workflows/performance-gate.yml` (3-4 hrs)
- `.github/.roadcrew-ci.yml` (2-3 hrs)
- `config/reports/.gitkeep` (1 hr)

**Total**: 41-53 hours

### Phase 2: High-Priority Commands (Weeks 4-5)
**Goal**: Implement core commands ready for CI/CD integration

**Deliverables**:
- `scripts/audit-complexity.ts` (15-20 hrs)
- `scripts/audit-security.ts` (25-30 hrs)
- `scripts/review-code.ts` (20-25 hrs)

**Total**: 60-75 hours

### Phase 3: Supporting Commands (Week 6)
**Goal**: Complete command suite

**Deliverables**:
- `scripts/audit-performance.ts` (20-25 hrs)
- `scripts/analyze-test-coverage.ts` (18-22 hrs)
- `scripts/code-cleanup.ts` (12-16 hrs)

**Total**: 50-63 hours

### Phase 4: Testing & Validation (Week 7)
**Goal**: Full test coverage and production readiness

**Deliverables**:
- Unit tests for all 6 commands (8-10 hrs)
- Integration tests (10-12 hrs)
- CI/CD pipeline testing (6-8 hrs)
- Documentation updates (5-8 hrs)

**Total**: 29-38 hours

---

## 5. File Structure

```
scripts/
├── utils/
│   ├── code-analyzer.ts
│   ├── report-generator.ts
│   ├── baseline-manager.ts
│   ├── git-integration.ts
│   └── severity-calculator.ts
├── core/
│   ├── qa-models.ts
│   ├── qa-github-integration.ts
│   └── ci-cd-report-generator.ts
├── review-code.ts
├── audit-security.ts
├── audit-performance.ts
├── audit-complexity.ts
├── analyze-test-coverage.ts
├── code-cleanup.ts
└── __tests__/
    ├── audit-*.test.ts (6 files)
    └── integration/*.test.ts

.github/
├── workflows/
│   ├── qa-checks.yml
│   ├── security-gate.yml
│   └── performance-gate.yml
└── .roadcrew-ci.yml

config/
└── reports/
    └── .gitkeep

package.json (scripts added):
  "audit-complexity": "npm run ensure-built && node dist/scripts/audit-complexity.js"
  "audit-security": "npm run ensure-built && node dist/scripts/audit-security.js"
  "audit-performance": "npm run ensure-built && node dist/scripts/audit-performance.js"
  "review-code": "npm run ensure-built && node dist/scripts/review-code.js"
  "analyze-test-coverage": "npm run ensure-built && node dist/scripts/analyze-test-coverage.js"
  "code-cleanup": "npm run ensure-built && node dist/scripts/code-cleanup.js"
```

---

## 6. Success Criteria

- ✅ All 6 commands compile without errors
- ✅ Commands execute in <10 seconds
- ✅ 95%+ security vulnerability detection rate
- ✅ CI/CD workflows auto-run and post PR comments
- ✅ 80%+ test coverage for new code
- ✅ Build gates working (pass/fail status)
- ✅ SARIF reports in GitHub Security tab
- ✅ Baseline comparisons tracking trends

---

## 7. Dependencies

### Already Available ✅
- Node.js 18+
- TypeScript 5.0+
- @octokit/rest (GitHub API)
- ESLint + plugins
- Jest + coverage/lcov.info

### May Need Installation ⚠️
- @typescript-eslint/plugin-security (ESLint security)
- semgrep (optional advanced scanning)

---

## Related Documents

- **BRD**: `../brds/qa-brd.md` - Business context and goals
- **PRD**: `../prds/qa-prd.md` - Product requirements and user flows
- **Narratives**: `../narratives/qa/` - Detailed planning and background