@boshu2/vibe-check 2.2.1 → 2.4.0

package/drivers/README.md

@@ -0,0 +1,327 @@
+# Complexity Drivers
+
+Drivers wrap language-specific complexity tools to produce standard JSON output conforming to vibe-check's `ComplexityReport` schema.
+
+## Architecture
+
+```
+vibe-check (kernel) ← reads .vibe-check/complexity.json
+    ↑
+    │ Standard JSON schema
+    │
+Drivers (python.sh, javascript.sh, etc.)
+    ↑
+    │ Tool-specific format
+    │
+Language tools (radon, complexity-report, gocyclo, etc.)
+```
+
+## Standard Schema
+
+All drivers must output JSON matching this schema:
+
+```typescript
+{
+  tool: string;           // "radon", "complexity-report", etc.
+  language: string;       // "python", "javascript", etc.
+  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
+
+All drivers normalize complexity scores 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 |
+
+## Available Drivers
+
+### Python (`python.sh`)
+
+Wraps [radon](https://radon.readthedocs.io/) for Python cyclomatic complexity.
+
+**Requirements:**
+```bash
+pip install radon
+```
+
+**Usage:**
+```bash
+./drivers/python.sh ./src
+./drivers/python.sh ./src > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "radon",
+  "language": "python",
+  "files": {
+    "src/main.py": {
+      "functions": [
+        {"name": "process", "complexity": 7, "grade": "B", "line": 10, "endLine": 25}
+      ],
+      "avgComplexity": 7,
+      "maxComplexity": 7,
+      "grade": "B"
+    }
+  }
+}
+```
+
+### JavaScript/TypeScript (`javascript.sh`)
+
+Wraps [cyclomatic-complexity](https://github.com/pilotpirxie/cyclomatic-complexity) for JavaScript and TypeScript.
+
+**Requirements:**
+```bash
+# npx automatically installs on first run
+# No manual installation needed
+```
+
+**Usage:**
+```bash
+./drivers/javascript.sh ./src
+./drivers/javascript.sh ./src > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "cyclomatic-complexity",
+  "language": "javascript",
+  "files": {
+    "src/app.ts": {
+      "functions": [
+        {"name": "handleRequest", "complexity": 12, "grade": "C", "line": 15, "endLine": null}
+      ],
+      "avgComplexity": 12,
+      "maxComplexity": 12,
+      "grade": "C"
+    }
+  }
+}
+```
+
+### Go (`go.sh`)
+
+Wraps [gocyclo](https://github.com/fzipp/gocyclo) for Go cyclomatic complexity.
+
+**Requirements:**
+```bash
+go install github.com/fzipp/gocyclo/cmd/gocyclo@latest
+```
+
+**Usage:**
+```bash
+./drivers/go.sh ./src
+./drivers/go.sh ./cmd > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "gocyclo",
+  "language": "go",
+  "files": {
+    "cmd/main.go": {
+      "functions": [
+        {"name": "handleRequest", "complexity": 8, "grade": "B", "line": 25, "endLine": null}
+      ],
+      "avgComplexity": 8,
+      "maxComplexity": 8,
+      "grade": "B"
+    }
+  }
+}
+```
+
+### Rust (`rust.sh`)
+
+Wraps [rust-code-analysis](https://mozilla.github.io/rust-code-analysis/) for Rust cyclomatic complexity.
+
+**Requirements:**
+```bash
+cargo install rust-code-analysis-cli
+```
+
+**Usage:**
+```bash
+./drivers/rust.sh ./src
+./drivers/rust.sh ./src > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "rust-code-analysis",
+  "language": "rust",
+  "files": {
+    "src/main.rs": {
+      "functions": [
+        {"name": "process_data", "complexity": 6, "grade": "B", "line": 12, "endLine": 45}
+      ],
+      "avgComplexity": 6,
+      "maxComplexity": 6,
+      "grade": "B"
+    }
+  }
+}
+```
+
+### PHP (`php.sh`)
+
+Wraps [PHPMD](https://phpmd.org/) (PHP Mess Detector) for PHP cyclomatic complexity.
+
+**Requirements:**
+```bash
+composer global require phpmd/phpmd
+```
+
+**Usage:**
+```bash
+./drivers/php.sh ./src
+./drivers/php.sh ./src > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "phpmd",
+  "language": "php",
+  "files": {
+    "src/Controller.php": {
+      "functions": [
+        {"name": "handleRequest", "complexity": 15, "grade": "C", "line": 23, "endLine": 67}
+      ],
+      "avgComplexity": 15,
+      "maxComplexity": 15,
+      "grade": "C"
+    }
+  }
+}
+```
+
+### Java (`java.sh`)
+
+Wraps [PMD](https://pmd.github.io/) for Java cyclomatic complexity.
+
+**Requirements:**
+```bash
+# Download PMD from https://pmd.github.io/
+# Requires JRE (Java Runtime Environment)
+```
+
+**Usage:**
+```bash
+./drivers/java.sh ./src
+./drivers/java.sh ./src > .vibe-check/complexity.json
+```
+
+**Example Output:**
+```json
+{
+  "tool": "pmd",
+  "language": "java",
+  "files": {
+    "src/main/java/Service.java": {
+      "functions": [
+        {"name": "processRequest", "complexity": 18, "grade": "C", "line": 42, "endLine": 89}
+      ],
+      "avgComplexity": 18,
+      "maxComplexity": 18,
+      "grade": "C"
+    }
+  }
+}
+```
+
+## Driver Contract
+
+Each driver script must:
+
+1. **Accept directory path** as first argument (default: current directory)
+2. **Check tool availability** and exit 1 with JSON error if missing
+3. **Output valid JSON** to stdout conforming to schema
+4. **Exit 0 on success**, non-zero on failure
+5. **Handle empty directories** gracefully (empty `files` object)
+
+## Error Format
+
+On error, write JSON to stderr and exit non-zero:
+
+```json
+{"error": "radon not installed. Run: pip install radon"}
+```
+
+## Writing a New Driver
+
+Example template:
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+
+# Check tool is installed
+if ! command -v your-tool &> /dev/null; then
+    echo '{"error": "your-tool not installed"}' >&2
+    exit 1
+fi
+
+# Run tool and transform to standard schema
+your-tool "$TARGET_DIR" --json | jq '{
+  tool: "your-tool",
+  language: "your-language",
+  generatedAt: (now | todate),
+  files: ...,
+  summary: ...
+}'
+```
+
+See `python.sh` for a complete example with jq transformation.
+
+## Integration with vibe-check
+
+Drivers are used via CLI:
+
+```bash
+# Run driver before analysis
+vibe-check --with-complexity python
+
+# Use existing complexity data
+vibe-check --complexity-file .vibe-check/complexity.json
+
+# Driver-only mode (outputs to stdout)
+vibe-check driver python ./src > complexity.json
+```
+
+See main README for usage details.

package/drivers/go.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+# drivers/go.sh
+# Wraps gocyclo to produce standard complexity JSON
+#
+# Usage: ./drivers/go.sh [directory]
+#        directory: Path to Go code to analyze (default: current directory)
+#
+# Output: JSON conforming to ComplexityReport schema
+# Exit codes: 0 = success, 1 = error (gocyclo not installed or other failure)
+
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+
+# Check gocyclo is installed
+if ! command -v gocyclo &> /dev/null; then
+    echo '{"error": "gocyclo not installed. Run: go install github.com/fzipp/gocyclo/cmd/gocyclo@latest"}' >&2
+    exit 1
+fi
+
+# Check if target directory exists
+if [ ! -d "$TARGET_DIR" ]; then
+    echo "{\"error\": \"Directory not found: $TARGET_DIR\"}" >&2
+    exit 1
+fi
+
+# Check if there are any Go files
+if ! find "$TARGET_DIR" -name "*.go" ! -path "*/vendor/*" -print -quit 2>/dev/null | grep -q .; then
+    # No Go files found, output empty result
+    echo '{"tool":"gocyclo","language":"go","generatedAt":"'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'","files":{},"summary":{"totalFiles":0,"totalFunctions":0,"avgComplexity":0,"gradeDistribution":{"A":0,"B":0,"C":0,"D":0,"E":0,"F":0}}}'
+    exit 0
+fi
+
+# Run gocyclo and transform output
+# gocyclo outputs lines like:
+#   8 main complex /tmp/go-test/main.go:16:1
+#   <complexity> <package> <function> <file:row:column>
+
+gocyclo "$TARGET_DIR" 2>/dev/null | awk -v target_dir="$TARGET_DIR" '
+BEGIN {
+    # Initialize
+    file_count = 0
+    func_count = 0
+    total_complexity = 0
+    grade_a = 0; grade_b = 0; grade_c = 0; grade_d = 0; grade_e = 0; grade_f = 0
+}
+
+function complexity_to_grade(c) {
+    if (c <= 5) return "A"
+    else if (c <= 10) return "B"
+    else if (c <= 20) return "C"
+    else if (c <= 30) return "D"
+    else if (c <= 40) return "E"
+    else return "F"
+}
+
+function increment_grade(g) {
+    if (g == "A") grade_a++
+    else if (g == "B") grade_b++
+    else if (g == "C") grade_c++
+    else if (g == "D") grade_d++
+    else if (g == "E") grade_e++
+    else grade_f++
+}
+
+{
+    # Parse: complexity package function file:line:col
+    complexity = $1
+    pkg = $2
+    func_name = $3
+    file_line = $4
+
+    # Split file:line:col
+    split(file_line, parts, ":")
+    file = parts[1]
+    line = parts[2]
+
+    # Track functions per file
+    if (!(file in files)) {
+        files[file] = 1
+        file_count++
+        file_functions[file] = ""
+        file_complexities[file] = ""
+        file_total[file] = 0
+        file_max[file] = 0
+        file_func_count[file] = 0
+    }
+
+    func_count++
+    total_complexity += complexity
+
+    grade = complexity_to_grade(complexity)
+
+    # Append function data (JSON format)
+    sep = (file_functions[file] == "") ? "" : ","
+    file_functions[file] = file_functions[file] sep sprintf("{\"name\":\"%s\",\"complexity\":%d,\"grade\":\"%s\",\"line\":%d,\"endLine\":null}", func_name, complexity, grade, line)
+
+    # Track file stats
+    file_total[file] += complexity
+    file_func_count[file]++
+    if (complexity > file_max[file]) {
+        file_max[file] = complexity
+    }
+}
+
+END {
+    # Output JSON
+    printf "{\"tool\":\"gocyclo\",\"language\":\"go\",\"generatedAt\":\""
+    # Get current timestamp
+    cmd = "date -u +\"%Y-%m-%dT%H:%M:%SZ\""
+    cmd | getline timestamp
+    close(cmd)
+    printf "%s\",\"files\":{", timestamp
+
+    first_file = 1
+    for (file in files) {
+        if (!first_file) printf ","
+        first_file = 0
+
+        avg = (file_func_count[file] > 0) ? file_total[file] / file_func_count[file] : 0
+        file_grade = complexity_to_grade(avg)
+        increment_grade(file_grade)
+
+        printf "\"%s\":{\"functions\":[%s],\"avgComplexity\":%.2f,\"maxComplexity\":%d,\"grade\":\"%s\"}", file, file_functions[file], avg, file_max[file], file_grade
+    }
+
+    avg_complexity = (func_count > 0) ? total_complexity / func_count : 0
+
+    printf "},\"summary\":{\"totalFiles\":%d,\"totalFunctions\":%d,\"avgComplexity\":%.2f,\"gradeDistribution\":{\"A\":%d,\"B\":%d,\"C\":%d,\"D\":%d,\"E\":%d,\"F\":%d}}}", file_count, func_count, avg_complexity, grade_a, grade_b, grade_c, grade_d, grade_e, grade_f
+}
+'

package/drivers/java.sh

@@ -0,0 +1,137 @@
+#!/bin/bash
+# drivers/java.sh
+# Wraps PMD to produce standard complexity JSON
+#
+# Usage: ./drivers/java.sh [directory]
+#        directory: Path to Java code to analyze (default: current directory)
+#
+# Output: JSON conforming to ComplexityReport schema
+# Exit codes: 0 = success, 1 = error (pmd not installed or other failure)
+
+set -euo pipefail
+
+TARGET_DIR="${1:-.}"
+
+# Check pmd is installed
+if ! command -v pmd &> /dev/null; then
+    echo '{"error": "pmd not installed. Download from: https://pmd.github.io/"}' >&2
+    exit 1
+fi
+
+# Check if target directory exists
+if [ ! -d "$TARGET_DIR" ]; then
+    echo "{\"error\": \"Directory not found: $TARGET_DIR\"}" >&2
+    exit 1
+fi
+
+# Check if there are any Java files
+if ! find "$TARGET_DIR" -name "*.java" ! -path "*/target/*" ! -path "*/build/*" -print -quit 2>/dev/null | grep -q .; then
+    # No Java files found, output empty result
+    echo '{"tool":"pmd","language":"java","generatedAt":"'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'","files":{},"summary":{"totalFiles":0,"totalFunctions":0,"avgComplexity":0,"gradeDistribution":{"A":0,"B":0,"C":0,"D":0,"E":0,"F":0}}}'
+    exit 0
+fi
+
+# Run PMD and transform output
+# PMD outputs JSON with violations grouped by file
+# We filter for CyclomaticComplexity rule violations
+# Using --no-cache to avoid caching issues
+# --ignore-violations to ensure exit 0 even with violations found
+
+pmd check -d "$TARGET_DIR" \
+  -R category/java/design.xml/CyclomaticComplexity \
+  -f json \
+  --no-cache \
+  --ignore-violations-on-exit 2>/dev/null | jq -c '
+# Helper function for complexity to grade conversion
+def complexity_to_grade:
+  if . <= 5 then "A"
+  elif . <= 10 then "B"
+  elif . <= 20 then "C"
+  elif . <= 30 then "D"
+  elif . <= 40 then "E"
+  else "F"
+  end;
+
+# Process PMD violations format
+# PMD JSON format has .files array with violations
+(.files // []) |
+map(
+  select(.violations | length > 0) |
+  {
+    path: .filename,
+    violations: [
+      .violations[] |
+      # PMD description format: "The {class|method} {name} has a {Cyclomatic|Standard} Complexity of {X}."
+      # or "The {class|method} '{name}' has a {Cyclomatic|Standard} cyclomatic complexity of {X}."
+      {
+        description: .description,
+        method: (.description | capture("method .(?<name>[^']+).") | .name),
+        beginLine: .beginLine,
+        endLine: .endLine,
+        # Extract complexity number from description
+        complexity: (
+          .description |
+          capture("complexity of (?<num>[0-9]+)") |
+          .num | tonumber
+        )
+      }
+    ]
+  } |
+  select(.violations | length > 0)
+) |
+
+# Group by file and calculate metrics
+map({
+  key: .path,
+  value: {
+    functions: (
+      .violations | map({
+        name: .method,
+        complexity: .complexity,
+        grade: (.complexity | complexity_to_grade),
+        line: .beginLine,
+        endLine: .endLine
+      })
+    ),
+    avgComplexity: (
+      if (.violations | length) > 0 then
+        ((.violations | map(.complexity) | add) / (.violations | length))
+      else 0 end
+    ),
+    maxComplexity: (
+      if (.violations | length) > 0 then
+        (.violations | map(.complexity) | max)
+      else 0 end
+    ),
+    grade: (
+      if (.violations | length) > 0 then
+        (((.violations | map(.complexity) | add) / (.violations | length)) | complexity_to_grade)
+      else "A" end
+    )
+  }
+}) |
+from_entries as $files |
+
+# Build final output
+{
+  tool: "pmd",
+  language: "java",
+  generatedAt: (now | todate),
+  files: $files,
+  summary: {
+    totalFiles: ($files | to_entries | length),
+    totalFunctions: ([$files | to_entries[].value.functions | length] | add // 0),
+    avgComplexity: (
+      [$files | to_entries[].value.avgComplexity] |
+      if length > 0 then (add / length) else 0 end
+    ),
+    gradeDistribution: (
+      [$files | to_entries[].value.grade] |
+      reduce .[] as $grade (
+        {A: 0, B: 0, C: 0, D: 0, E: 0, F: 0};
+        .[$grade] += 1
+      )
+    )
+  }
+}
+'