@boshu2/vibe-check 2.3.0 → 2.4.0

package/.agents/research/2025-12-29-complexity-driver-architecture.md

@@ -0,0 +1,392 @@
+---
+date: 2025-12-29
+type: Research
+topic: "Complexity Driver Architecture - Language-Agnostic Tool Integration"
+tags: [research, architecture, complexity]
+status: COMPLETE
+---
+
+# Research: Complexity Driver Architecture
+
+**Created:** 2025-12-29
+**Goal:** Design a plugin/driver system for language-specific complexity tools
+
+---
+
+## Executive Summary
+
+vibe-check should remain language-agnostic while being able to incorporate complexity metrics from language-specific tools. This research proposes a "driver" architecture (similar to Linux device drivers) where thin wrapper scripts normalize output from various tools into a standard JSON schema.
+
+---
+
+## Problem Statement
+
+The modularity analyzer (`src/analyzers/modularity.ts`) currently uses heuristics like line count and pattern detection. Testing on a real codebase revealed:
+
+| File | Lines | vibe-check Says | Actual Complexity (radon) |
+|------|-------|-----------------|---------------------------|
+| neo4j_store.py | 1,366 | "Too large" | Grade A (2.4) - FINE |
+| sync.py | 1,117 | "Too large" | Grade C (17.7) - PROBLEM |
+
+**Line count is a poor proxy.** A 1,000-line file of simple methods is fine; a 200-line file with nested conditionals is a nightmare.
+
+---
+
+## Existing Complexity Tools by Language
+
+| Language | Tool | Output Format | Installation |
+|----------|------|---------------|--------------|
+| **Python** | `radon` | JSON (`-j`) | `pip install radon` |
+| **Python** | `xenon` | Exit codes + text | `pip install xenon` |
+| **JS/TS** | `complexity-report` | JSON | `npm install complexity-report` |
+| **JS/TS** | `es6-plato` | HTML/JSON | `npm install es6-plato` |
+| **Go** | `gocyclo` | JSON (`-json`) | `go install github.com/fzipp/gocyclo` |
+| **Go** | `gocognit` | Text | `go install github.com/uudashr/gocognit` |
+| **Java** | `pmd` | XML/JSON | Download from PMD site |
+| **C/C++** | `lizard` | JSON/CSV | `pip install lizard` |
+| **Rust** | `cargo clippy` | Text (lint) | Built into Cargo |
+| **Ruby** | `flog` | Text | `gem install flog` |
+
+---
+
+## Proposed Architecture
+
+### Mental Model: Linux Driver Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  vibe-check (kernel)                                        │
+│  ───────────────────                                        │
+│  • Git pattern analysis (existing)                          │
+│  • Session detection (existing)                             │
+│  • AI failure patterns (existing)                           │
+│  • Modularity scoring (existing)                            │
+│  • NEW: Reads .vibe-check/complexity.json if present        │
+│  • NEW: Merges complexity into modularity score             │
+└─────────────────────────────────────────────────────────────┘
+                              ▲
+                              │ Standard JSON schema
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌───────────────┐   ┌───────────────┐   ┌───────────────┐
+│ driver-python │   │ driver-js     │   │ driver-go     │
+│ ───────────── │   │ ───────────── │   │ ───────────── │
+│ Wraps: radon  │   │ Wraps:        │   │ Wraps:        │
+│ Output: JSON  │   │ complexity-   │   │ gocyclo       │
+│               │   │ report        │   │               │
+└───────────────┘   └───────────────┘   └───────────────┘
+```
+
+### Standard Complexity Schema
+
+```typescript
+interface ComplexityReport {
+  // Metadata
+  tool: string;           // "radon", "complexity-report", "gocyclo"
+  language: string;       // "python", "javascript", "go"
+  generatedAt: string;    // ISO timestamp
+
+  // Per-file metrics
+  files: {
+    [filepath: string]: {
+      functions: FunctionComplexity[];
+      avgComplexity: number;
+      maxComplexity: number;
+      grade: 'A' | 'B' | 'C' | 'D' | 'E' | 'F';
+    };
+  };
+
+  // Summary
+  summary: {
+    totalFiles: number;
+    totalFunctions: number;
+    avgComplexity: number;
+    gradeDistribution: Record<string, number>;
+  };
+}
+
+interface FunctionComplexity {
+  name: string;
+  complexity: number;
+  grade: 'A' | 'B' | 'C' | 'D' | 'E' | 'F';
+  line: number;
+  endLine?: number;
+  isMethod?: boolean;
+  className?: string;
+}
+```
+
+### Grade Thresholds (Standardized)
+
+All drivers should normalize to these grades:
+
+| Grade | Complexity | Meaning |
+|-------|------------|---------|
+| A | 1-5 | Simple, low risk |
+| B | 6-10 | Slightly complex, acceptable |
+| C | 11-20 | Complex, consider refactoring |
+| D | 21-30 | Very complex, refactor |
+| E | 31-40 | Extremely complex, high risk |
+| F | 41+ | Unmaintainable, must refactor |
+
+---
+
+## Driver Implementation
+
+### Driver Contract
+
+Each driver is a script that:
+1. Takes a directory path as input
+2. Runs the language-specific tool
+3. Outputs JSON conforming to the standard schema
+4. Exits 0 on success, non-zero on failure
+
+### Example: Python Driver
+
+```bash
+#!/bin/bash
+# drivers/python.sh
+# Wraps radon to produce standard complexity JSON
+
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+
+# Check radon is installed
+if ! command -v radon &> /dev/null; then
+    echo '{"error": "radon not installed. Run: pip install radon"}' >&2
+    exit 1
+fi
+
+# Run radon and transform output
+radon cc "$TARGET_DIR" -j --total-average | jq '
+{
+  tool: "radon",
+  language: "python",
+  generatedAt: (now | todate),
+  files: (to_entries | map({
+    key: .key,
+    value: {
+      functions: (.value | map({
+        name: .name,
+        complexity: .complexity,
+        grade: .rank,
+        line: .lineno,
+        endLine: .endline,
+        isMethod: .is_method,
+        className: .classname
+      })),
+      avgComplexity: ((.value | map(.complexity) | add) / (.value | length)),
+      maxComplexity: (.value | map(.complexity) | max),
+      grade: (
+        ((.value | map(.complexity) | add) / (.value | length)) |
+        if . <= 5 then "A"
+        elif . <= 10 then "B"
+        elif . <= 20 then "C"
+        elif . <= 30 then "D"
+        elif . <= 40 then "E"
+        else "F"
+        end
+      )
+    }
+  }) | from_entries),
+  summary: {
+    totalFiles: (keys | length),
+    totalFunctions: ([.[]] | map(.functions | length) | add),
+    avgComplexity: ([.[]] | map(.avgComplexity) | add / length)
+  }
+}
+'
+```
+
+### Example: JavaScript Driver
+
+```bash
+#!/bin/bash
+# drivers/javascript.sh
+# Wraps complexity-report to produce standard complexity JSON
+
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+
+# Check tool is installed
+if ! npx complexity-report --version &> /dev/null; then
+    echo '{"error": "complexity-report not installed"}' >&2
+    exit 1
+fi
+
+# Run and transform
+npx complexity-report --format json "$TARGET_DIR" | jq '
+{
+  tool: "complexity-report",
+  language: "javascript",
+  generatedAt: (now | todate),
+  files: # ... transform logic
+}
+'
+```
+
+---
+
+## Integration with vibe-check
+
+### Reading Complexity Data
+
+```typescript
+// src/analyzers/complexity.ts
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+const COMPLEXITY_FILE = '.vibe-check/complexity.json';
+
+export interface ComplexityData {
+  // ... schema from above
+}
+
+export function loadComplexityData(rootDir: string): ComplexityData | null {
+  const filePath = path.join(rootDir, COMPLEXITY_FILE);
+
+  if (!fs.existsSync(filePath)) {
+    return null; // No complexity data available
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.warn(`Failed to parse ${COMPLEXITY_FILE}:`, e);
+    return null;
+  }
+}
+
+export function getFileComplexity(
+  data: ComplexityData,
+  file: string
+): { avgComplexity: number; grade: string } | null {
+  return data.files[file] || null;
+}
+```
+
+### Enhancing Modularity Score
+
+```typescript
+// In src/analyzers/modularity.ts, modify calculateScore()
+
+function calculateScore(
+  lines: number,
+  pattern: FilePattern | null,
+  details: ModularityDetails,
+  content: string,
+  file: string,
+  complexityData?: ComplexityData  // NEW parameter
+): { score: number; flags: ModularityFlag[] } {
+  let score = 10;
+  const flags: ModularityFlag[] = [];
+
+  // ... existing logic ...
+
+  // NEW: Complexity-based scoring (if data available)
+  if (complexityData) {
+    const fileComplexity = getFileComplexity(complexityData, file);
+    if (fileComplexity) {
+      switch (fileComplexity.grade) {
+        case 'A':
+        case 'B':
+          score += 2;  // Bonus for low complexity
+          break;
+        case 'C':
+          score -= 1;
+          flags.push('moderate-complexity');
+          break;
+        case 'D':
+        case 'E':
+          score -= 2;
+          flags.push('high-complexity');
+          break;
+        case 'F':
+          score -= 4;
+          flags.push('extreme-complexity');
+          break;
+      }
+    }
+  }
+
+  return { score: Math.max(0, Math.min(10, score)), flags };
+}
+```
+
+---
+
+## User Workflow
+
+### CI Integration
+
+```yaml
+# .gitlab-ci.yml or .github/workflows/ci.yml
+
+complexity-analysis:
+  script:
+    # Run appropriate driver for your language
+    - ./node_modules/.bin/vibe-check-driver-python services/ > .vibe-check/complexity.json
+
+    # Or if multi-language:
+    - vibe-check-driver-python backend/ >> .vibe-check/complexity.json
+    - vibe-check-driver-js frontend/ >> .vibe-check/complexity.json
+
+    # Then run vibe-check (will read complexity.json)
+    - vibe-check --format json > reports/vibe-report.json
+```
+
+### Local Development
+
+```bash
+# Generate complexity data
+vibe-check driver python ./src
+
+# Run full analysis (reads complexity data automatically)
+vibe-check
+
+# Or one-liner
+vibe-check --with-complexity python
+```
+
+---
+
+## File Locations
+
+| File | Purpose |
+|------|---------|
+| `.vibe-check/complexity.json` | Driver output (gitignored) |
+| `drivers/python.sh` | Python driver script |
+| `drivers/javascript.sh` | JavaScript driver script |
+| `src/analyzers/complexity.ts` | Schema + loader |
+| `src/analyzers/modularity.ts` | Enhanced scoring |
+
+---
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Tool not installed | HIGH | LOW | Graceful degradation, clear error messages |
+| Schema mismatch | MEDIUM | MEDIUM | Validate JSON against schema before use |
+| Performance (large codebases) | MEDIUM | LOW | Cache results, run incrementally |
+| Multiple languages | MEDIUM | LOW | Merge multiple driver outputs |
+
+---
+
+## Next Steps
+
+1. Implement `src/analyzers/complexity.ts` (schema + loader)
+2. Create `drivers/python.sh` wrapper
+3. Modify `analyzeModularity()` to accept complexity data
+4. Add `--with-complexity <lang>` CLI flag
+5. Document in README.md
+
+---
+
+**Output:** .agents/research/2025-12-29-complexity-driver-architecture.md

package/.agents/research/2025-12-29-complexity-drivers.md

@@ -0,0 +1,227 @@
+---
+date: 2025-12-29
+type: Research
+topic: "What complexity drivers should vibe-check support?"
+tags: [research, drivers, complexity, languages, tooling]
+status: COMPLETE
+---
+
+# Research: Complexity Drivers for vibe-check
+
+**Created:** 2025-12-29
+**Goal:** Determine which programming language drivers we should support for complexity analysis
+
+---
+
+## Executive Summary
+
+vibe-check currently supports **Python, JavaScript/TypeScript, and Go** complexity drivers. Based on developer survey data and tool availability, we should prioritize adding **Rust**, **Java**, and **PHP** drivers. Ruby and C# are lower priority due to tooling complexity or enterprise focus.
+
+---
+
+## Current State
+
+### What Exists
+
+Three drivers currently implemented:
+
+| Driver | Tool | Status |
+|--------|------|--------|
+| `python.sh` | [radon](https://radon.readthedocs.io/) | ✅ Complete |
+| `javascript.sh` | [cyclomatic-complexity](https://github.com/pilotpirxie/cyclomatic-complexity) | ✅ Complete |
+| `go.sh` | [gocyclo](https://github.com/fzipp/gocyclo) | ✅ Complete |
+
+### Key Files
+
+| File | Purpose | Relevance |
+|------|---------|-----------|
+| `drivers/README.md` | Driver architecture docs | Template for new drivers |
+| `src/analyzers/complexity.ts` | ComplexityReport schema | Must match output |
+| `src/commands/driver.ts` | Driver execution | Hardcoded available list |
+| `src/commands/modularity.ts` | Integration point | Uses driver output |
+
+### Driver Contract
+
+All drivers must output JSON matching `ComplexityReport` schema:
+- Accept directory path as first argument
+- Check tool availability, exit 1 with JSON error if missing
+- Output valid JSON to stdout
+- Exit 0 on success
+- Handle empty directories gracefully
+
+---
+
+## Findings
+
+### Finding 1: Language Popularity (2025 Data)
+
+Based on [Stack Overflow 2025](https://survey.stackoverflow.co/2025/technology) and [TIOBE Index](https://www.techrepublic.com/article/news-tiobe-index-language-rankings/):
+
+| Language | Stack Overflow 2025 | TIOBE Dec 2025 | Current Driver |
+|----------|---------------------|----------------|----------------|
+| JavaScript/TS | 66% usage | #6 | ✅ javascript.sh |
+| Python | +7% growth | #1 (25.98%) | ✅ python.sh |
+| Go | Growing | #8 | ✅ go.sh |
+| **Rust** | 72% admired | #13 (rising) | ❌ None |
+| **Java** | Enterprise staple | #4 | ❌ None |
+| **C#** | Enterprise | #5 | ❌ None |
+| **PHP** | Web backend | #16 | ❌ None |
+| **Ruby** | Web (Rails) | #18 | ❌ None |
+
+**Key insight:** We cover the top 3 general-purpose languages. Rust is the most admired language and rising fast.
+
+### Finding 2: Available Complexity Tools
+
+| Language | Tool | CLI | JSON Output | Install |
+|----------|------|-----|-------------|---------|
+| **Rust** | [rust-code-analysis](https://mozilla.github.io/rust-code-analysis/metrics.html) | ✅ | ✅ Native | `cargo install rust-code-analysis-cli` |
+| **Java** | [PMD](https://pmd.github.io/pmd/pmd_rules_java_design.html) | ✅ | ✅ `-f json` | Download JAR |
+| **C#** | [CCM](https://github.com/jonasblunck/ccm) | ✅ | XML only | NuGet |
+| **PHP** | [PHPMD](https://phpmd.org/rules/codesize.html) | ✅ | ✅ Native | Composer |
+| **Ruby** | [Saikuro](https://metricfu.github.io/Saikuro/) | ✅ | Text only | Gem |
+
+### Finding 3: Implementation Complexity
+
+| Language | Tool Quality | Output Parsing | Dependencies | Priority |
+|----------|--------------|----------------|--------------|----------|
+| **Rust** | Excellent (Mozilla) | Native JSON | Cargo | **P1** |
+| **Java** | Good (PMD) | JSON via flag | JRE + JAR | P2 |
+| **PHP** | Good (PHPMD) | Native JSON | PHP + Composer | P2 |
+| **Ruby** | Fair (Saikuro) | Text → parse | Ruby + Gem | P3 |
+| **C#** | Fair (CCM) | XML → parse | .NET SDK | P3 |
+
+### Finding 4: Rust Tool Deep Dive
+
+**rust-code-analysis** by Mozilla is ideal:
+- Calculates Cyclomatic (CC) and Cognitive complexity
+- Includes Halstead metrics
+- Native JSON output
+- Actively maintained
+
+```bash
+# Installation
+cargo install rust-code-analysis-cli
+
+# Usage with JSON output
+rust-code-analysis-cli -m -O json -p /path/to/src
+```
+
+### Finding 5: Java Tool Options
+
+**PMD** is the industry standard:
+- Measures cyclomatic complexity
+- JSON output with `-f json`
+- Requires JRE (widely available)
+- Well-documented
+
+```bash
+# Usage
+pmd check -d /path/to/src -R category/java/design.xml -f json
+```
+
+**Alternative:** Checkstyle has complexity checks but XML output only.
+
+### Finding 6: PHP Tool Options
+
+**PHPMD** (PHP Mess Detector) is the go-to:
+- Direct cyclomatic complexity support
+- JSON output built-in
+- Easy to install via Composer
+
+```bash
+# Usage
+phpmd /path/to/src json codesize
+```
+
+---
+
+## Constraints
+
+| Constraint | Impact | Mitigation |
+|------------|--------|------------|
+| Tool availability | Users must install language tools | Document requirements clearly |
+| JRE dependency (Java) | Heavy requirement | Note in docs, suggest alternatives |
+| Output format variance | Different JSON structures | Transform in driver (like Go uses awk) |
+| Platform compatibility | Some tools Unix-only | Test on macOS/Linux, note Windows limitations |
+
+---
+
+## Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| Tool discontinued | Low | High | Choose well-maintained tools (Mozilla, PMD) |
+| Breaking changes in tool output | Medium | Medium | Pin tool versions in docs |
+| Installation friction | Medium | Medium | Provide clear install instructions |
+| Windows compatibility | Low | Low | Focus on Unix first (developer primary platform) |
+
+---
+
+## Recommendation
+
+### Immediate (P1)
+
+**Add Rust driver** using `rust-code-analysis`:
+- Most admired language, fastest growing
+- Excellent Mozilla-backed tool
+- Native JSON output (simplest implementation)
+- Aligns with systems programming audience
+
+### Near-term (P2)
+
+**Add PHP driver** using PHPMD:
+- Large web developer audience
+- Native JSON output
+- Easy Composer install
+
+**Add Java driver** using PMD:
+- Enterprise relevance
+- JSON output via flag
+- Well-documented
+
+### Later (P3)
+
+**Ruby** via Saikuro or Fukuzatsu - text parsing required
+**C#** via CCM - XML output, .NET dependency
+
+### Not Recommended
+
+**Swift/Kotlin/Scala** - Niche audiences, tooling gaps
+
+---
+
+## Tool Comparison Matrix
+
+| Language | Tool | JSON Native | Install Friction | Priority |
+|----------|------|-------------|------------------|----------|
+| Rust | rust-code-analysis | ✅ | Low (cargo) | **P1** |
+| PHP | PHPMD | ✅ | Low (composer) | **P2** |
+| Java | PMD | ✅ (flag) | Medium (JRE) | **P2** |
+| Ruby | Saikuro | ❌ | Low (gem) | P3 |
+| C# | CCM | ❌ | Medium (.NET) | P3 |
+
+---
+
+## Next Steps
+
+1. Run `/plan` to create implementation plan for P1/P2 drivers
+2. Start with Rust (simplest: native JSON, cargo install)
+3. Add PHP and Java as follow-up work
+
+---
+
+## Sources
+
+- [Stack Overflow Developer Survey 2025](https://survey.stackoverflow.co/2025/technology)
+- [TIOBE Index December 2025](https://www.techrepublic.com/article/news-tiobe-index-language-rankings/)
+- [rust-code-analysis metrics](https://mozilla.github.io/rust-code-analysis/metrics.html)
+- [PMD Java Design Rules](https://pmd.github.io/pmd/pmd_rules_java_design.html)
+- [PHPMD Code Size Rules](https://phpmd.org/rules/codesize.html)
+- [gocyclo GitHub](https://github.com/fzipp/gocyclo)
+- [cyclomatic-complexity npm](https://github.com/pilotpirxie/cyclomatic-complexity)
+- [Checkstyle Cyclomatic Complexity](https://checkstyle.sourceforge.io/checks/metrics/cyclomaticcomplexity.html)
+- [Saikuro Ruby Complexity](https://metricfu.github.io/Saikuro/)
+
+---
+
+**Output:** .agents/research/2025-12-29-complexity-drivers.md