@boshu2/vibe-check 2.3.0 → 2.4.0

package/.agents/plans/2025-12-29-complexity-driver-plan.md

@@ -0,0 +1,225 @@
+---
+date: 2025-12-29
+type: Plan
+topic: "Add Complexity Driver Architecture"
+research: ".agents/research/2025-12-29-complexity-driver-architecture.md"
+tags: [plan, architecture, complexity]
+status: READY_FOR_IMPLEMENTATION
+---
+
+# Plan: Complexity Driver Architecture
+
+**Created:** 2025-12-29
+**Research:** [Complexity Driver Architecture Research](.agents/research/2025-12-29-complexity-driver-architecture.md)
+
+---
+
+## Overview
+
+Add a "driver" system that allows language-specific complexity tools (radon, gocyclo, complexity-report) to feed metrics into vibe-check's modularity analyzer. vibe-check remains language-agnostic; drivers normalize tool output to a standard schema.
+
+---
+
+## Features
+
+### Feature 1: Define Complexity Schema and Loader
+
+**Priority:** P1
+**Type:** feature
+
+**Description:** Create TypeScript types for the standard complexity schema and a loader function.
+
+**Files to Create:**
+- `src/analyzers/complexity.ts`
+
+**Implementation:**
+```typescript
+// Types
+export interface ComplexityReport { ... }
+export interface FunctionComplexity { ... }
+
+// Loader
+export function loadComplexityData(rootDir: string): ComplexityReport | null
+
+// Helper
+export function getFileComplexity(data: ComplexityReport, file: string)
+```
+
+**Acceptance Criteria:**
+- [ ] Types exported and documented
+- [ ] Loader returns null if file doesn't exist
+- [ ] Loader handles malformed JSON gracefully
+- [ ] Helper returns null for unknown files
+
+---
+
+### Feature 2: Integrate Complexity into Modularity Scoring
+
+**Priority:** P1
+**Type:** feature
+**Depends On:** Feature 1
+
+**Description:** Modify `analyzeModularity()` to optionally accept complexity data and incorporate it into scoring.
+
+**Files to Modify:**
+- `src/analyzers/modularity.ts`
+
+**Changes:**
+1. Add optional `complexityData` parameter to `analyzeModularity()`
+2. Pass to `calculateScore()`
+3. Add scoring logic:
+   - Grade A/B: +2 bonus
+   - Grade C: -1, flag `moderate-complexity`
+   - Grade D/E: -2, flag `high-complexity`
+   - Grade F: -4, flag `extreme-complexity`
+4. Add new flags to `ModularityFlag` type
+
+**Acceptance Criteria:**
+- [ ] Backwards compatible (works without complexity data)
+- [ ] Flags appear in output when complexity issues detected
+- [ ] Score adjustments match spec
+
+---
+
+### Feature 3: Create Python Driver
+
+**Priority:** P1
+**Type:** feature
+
+**Description:** Shell script that wraps `radon` and outputs standard schema JSON.
+
+**Files to Create:**
+- `drivers/python.sh`
+
+**Implementation:**
+- Check radon installed
+- Run `radon cc <dir> -j`
+- Transform with `jq` to standard schema
+- Output to stdout
+
+**Acceptance Criteria:**
+- [ ] Exits 0 on success
+- [ ] Exits 1 with error JSON if radon not installed
+- [ ] Output validates against schema
+- [ ] Handles empty directories gracefully
+
+---
+
+### Feature 4: Create JavaScript/TypeScript Driver
+
+**Priority:** P2
+**Type:** feature
+
+**Description:** Shell script that wraps `complexity-report` for JS/TS analysis.
+
+**Files to Create:**
+- `drivers/javascript.sh`
+
+**Acceptance Criteria:**
+- [ ] Works with complexity-report npm package
+- [ ] Output validates against schema
+- [ ] Handles mixed .js/.ts codebases
+
+---
+
+### Feature 5: Add CLI Integration
+
+**Priority:** P2
+**Type:** feature
+**Depends On:** Features 1-3
+
+**Description:** Add CLI flags to run drivers and consume their output.
+
+**Files to Modify:**
+- `src/cli.ts`
+- `src/commands/analyze.ts`
+
+**New CLI Options:**
+```bash
+# Run driver before analysis
+vibe-check --with-complexity python
+
+# Use existing complexity file
+vibe-check --complexity-file .vibe-check/complexity.json
+
+# Driver subcommand
+vibe-check driver python ./src
+```
+
+**Acceptance Criteria:**
+- [ ] `--with-complexity` runs driver, saves to `.vibe-check/complexity.json`
+- [ ] `--complexity-file` uses existing file
+- [ ] `driver` subcommand outputs to stdout
+- [ ] Help text updated
+
+---
+
+### Feature 6: Documentation
+
+**Priority:** P2
+**Type:** docs
+**Depends On:** Features 1-5
+
+**Description:** Document the driver architecture in README and create driver authoring guide.
+
+**Files to Modify/Create:**
+- `README.md` - Add "Complexity Analysis" section
+- `docs/drivers.md` - Driver authoring guide
+
+**Acceptance Criteria:**
+- [ ] README shows basic usage
+- [ ] Driver guide explains schema and contract
+- [ ] Examples for Python and JS
+
+---
+
+## Implementation Order
+
+| Step | Feature | Validation |
+|------|---------|------------|
+| 1 | Schema + Loader | Unit tests pass |
+| 2 | Modularity Integration | `npm test` passes |
+| 3 | Python Driver | Manual test with radon |
+| 4 | CLI Integration | `vibe-check --with-complexity python` works |
+| 5 | JS Driver | Manual test with complexity-report |
+| 6 | Documentation | README updated |
+
+---
+
+## Beads Issues
+
+| ID | Title | Priority |
+|----|-------|----------|
+| TBD | Add complexity schema and loader | P1 |
+| TBD | Integrate complexity into modularity scoring | P1 |
+| TBD | Create Python driver (radon wrapper) | P1 |
+| TBD | Add CLI complexity flags | P2 |
+| TBD | Create JavaScript driver | P2 |
+| TBD | Document driver architecture | P2 |
+
+---
+
+## Test Strategy
+
+**Unit Tests:**
+- `tests/analyzers/complexity.test.ts` - Schema validation, loader edge cases
+- `tests/analyzers/modularity.test.ts` - Scoring with/without complexity data
+
+**Integration Tests:**
+- Run Python driver on known codebase, verify output
+- Run full vibe-check with complexity, verify report includes grades
+
+**Manual Testing:**
+- Test on ai-platform repo (known sync.py has F-grade functions)
+
+---
+
+## Next Steps
+
+1. `bd create` to create beads issues
+2. `/implement` to start with Feature 1
+3. Build incrementally, test each feature
+
+---
+
+**Output:** .agents/plans/2025-12-29-complexity-driver-plan.md

package/.agents/plans/2025-12-29-complexity-drivers-plan.md

@@ -0,0 +1,253 @@
+---
+date: 2025-12-29
+type: Plan
+topic: "Add complexity drivers for Rust, PHP, and Java"
+research: ".agents/research/2025-12-29-complexity-drivers.md"
+tags: [plan, drivers, complexity, rust, php, java]
+status: COMPLETED
+---
+
+# Plan: Additional Complexity Drivers
+
+**Created:** 2025-12-29
+**Research:** .agents/research/2025-12-29-complexity-drivers.md
+**Vibe Level:** L4 (high confidence - following established driver pattern)
+
+---
+
+## Overview
+
+Add complexity drivers for **Rust**, **PHP**, and **Java** to expand vibe-check's language coverage. These are the highest-value additions based on language popularity (TIOBE/Stack Overflow 2025) and tool quality. All three have tools with JSON output, making implementation straightforward.
+
+---
+
+## Approach
+
+Follow existing driver pattern established by `python.sh`, `javascript.sh`, and `go.sh`:
+
+1. Shell script wrapper around language-specific tool
+2. Transform tool output to `ComplexityReport` JSON schema
+3. Update CLI error messages to include new driver
+4. Update documentation
+
+**Why this approach:**
+- Proven pattern (3 working drivers)
+- Language-agnostic kernel stays clean
+- Shell scripts are portable and don't add npm dependencies
+
+---
+
+## Features
+
+### Feature 1: Rust Driver
+
+**Priority:** P1
+**Type:** feature
+**Depends On:** None
+
+**Acceptance Criteria:**
+- [ ] `drivers/rust.sh` created wrapping `rust-code-analysis-cli`
+- [ ] Outputs valid `ComplexityReport` JSON
+- [ ] Handles missing tool with helpful error message
+- [ ] Handles empty directories gracefully
+- [ ] CLI updated to list `rust` as available driver
+- [ ] Documentation updated (drivers/README.md, README.md)
+
+**Files Affected:**
+- `drivers/rust.sh` - New driver script
+- `drivers/README.md` - Add Rust section
+- `README.md` - Add Rust to Available Drivers list
+- `src/commands/driver.ts` - Update available drivers message
+- `src/commands/modularity.ts` - Update available drivers message
+
+**Test Strategy:**
+1. Create test Rust file with known complexity
+2. Run `./drivers/rust.sh /path/to/test`
+3. Verify JSON output matches schema
+4. Run `vibe-check driver rust /path/to/test`
+5. Run `vibe-check modularity --with-complexity rust`
+
+**Tool Details:**
+```bash
+# Install
+cargo install rust-code-analysis-cli
+
+# Usage (native JSON)
+rust-code-analysis-cli -m -O json -p /path/to/src
+```
+
+---
+
+### Feature 2: PHP Driver
+
+**Priority:** P2
+**Type:** feature
+**Depends On:** None (can be done in parallel with Rust)
+
+**Acceptance Criteria:**
+- [ ] `drivers/php.sh` created wrapping `phpmd`
+- [ ] Outputs valid `ComplexityReport` JSON
+- [ ] Handles missing tool with helpful error message
+- [ ] Handles empty directories gracefully
+- [ ] CLI updated to list `php` as available driver
+- [ ] Documentation updated
+
+**Files Affected:**
+- `drivers/php.sh` - New driver script
+- `drivers/README.md` - Add PHP section
+- `README.md` - Add PHP to Available Drivers list
+- `src/commands/driver.ts` - Update available drivers message
+- `src/commands/modularity.ts` - Update available drivers message
+
+**Test Strategy:**
+1. Create test PHP file with known complexity
+2. Run `./drivers/php.sh /path/to/test`
+3. Verify JSON output matches schema
+4. Run `vibe-check driver php /path/to/test`
+
+**Tool Details:**
+```bash
+# Install
+composer global require phpmd/phpmd
+
+# Usage (native JSON)
+phpmd /path/to/src json codesize
+```
+
+---
+
+### Feature 3: Java Driver
+
+**Priority:** P2
+**Type:** feature
+**Depends On:** None (can be done in parallel)
+
+**Acceptance Criteria:**
+- [ ] `drivers/java.sh` created wrapping PMD
+- [ ] Outputs valid `ComplexityReport` JSON
+- [ ] Handles missing tool with helpful error message
+- [ ] Handles empty directories gracefully
+- [ ] CLI updated to list `java` as available driver
+- [ ] Documentation updated
+
+**Files Affected:**
+- `drivers/java.sh` - New driver script
+- `drivers/README.md` - Add Java section
+- `README.md` - Add Java to Available Drivers list
+- `src/commands/driver.ts` - Update available drivers message
+- `src/commands/modularity.ts` - Update available drivers message
+
+**Test Strategy:**
+1. Create test Java file with known complexity
+2. Run `./drivers/java.sh /path/to/test`
+3. Verify JSON output matches schema
+4. Run `vibe-check driver java /path/to/test`
+
+**Tool Details:**
+```bash
+# Install (download PMD)
+# https://pmd.github.io/
+
+# Usage (JSON via flag)
+pmd check -d /path/to/src -R category/java/design.xml -f json
+```
+
+**Note:** PMD requires JRE. Document this clearly.
+
+---
+
+## Implementation Order
+
+| Step | Feature | Depends On | Validation |
+|------|---------|------------|------------|
+| 1 | Rust Driver | - | `vibe-check driver rust ./test` produces valid JSON |
+| 2 | PHP Driver | - | `vibe-check driver php ./test` produces valid JSON |
+| 3 | Java Driver | - | `vibe-check driver java ./test` produces valid JSON |
+
+**Note:** All three can be implemented in parallel - no dependencies between them.
+
+---
+
+## Beads Issues to Create
+
+After approval, these issues will be created:
+
+| ID | Title | Type | Priority | Depends On |
+|----|-------|------|----------|------------|
+| TBD | Epic: Additional Complexity Drivers | epic | P1 | - |
+| TBD | Create Rust complexity driver | feature | P1 | Epic |
+| TBD | Create PHP complexity driver | feature | P2 | Epic |
+| TBD | Create Java complexity driver | feature | P2 | Epic |
+
+---
+
+## Output Format Reference
+
+All drivers must output JSON matching this schema:
+
+```typescript
+{
+  tool: string;           // "rust-code-analysis", "phpmd", "pmd"
+  language: string;       // "rust", "php", "java"
+  generatedAt: string;    // ISO timestamp
+  files: {
+    [filepath: string]: {
+      functions: Array<{
+        name: string;
+        complexity: number;
+        grade: 'A' | 'B' | 'C' | 'D' | 'E' | 'F';
+        line: number;
+        endLine?: number;
+      }>;
+      avgComplexity: number;
+      maxComplexity: number;
+      grade: 'A' | 'B' | 'C' | 'D' | 'E' | 'F';
+    };
+  };
+  summary: {
+    totalFiles: number;
+    totalFunctions: number;
+    avgComplexity: number;
+    gradeDistribution: Record<'A'|'B'|'C'|'D'|'E'|'F', number>;
+  };
+}
+```
+
+**Grade Thresholds:**
+- A: 1-5 (simple)
+- B: 6-10 (acceptable)
+- C: 11-20 (consider refactoring)
+- D: 21-30 (refactor)
+- E: 31-40 (high risk)
+- F: 41+ (unmaintainable)
+
+---
+
+## Rollback Procedure
+
+Each driver is independent. To rollback:
+1. `git revert <commit>` for the specific driver
+2. Remove the `drivers/<lang>.sh` file
+3. Update CLI error messages to remove language
+
+---
+
+## Not In Scope
+
+- Ruby driver (P3 - requires text parsing)
+- C# driver (P3 - requires XML parsing)
+- Automated tool installation
+- Windows-specific handling
+
+---
+
+## Next Steps
+
+1. Review and approve this plan
+2. Run beads issue creation (below)
+3. `bd ready` to see unblocked issues
+4. `/implement` to execute
+
+---
+
+**Output:** .agents/plans/2025-12-29-complexity-drivers-plan.md