@vibecodeqa/cli 0.9.0

package/dist/runners/context.js

@@ -0,0 +1,200 @@
+/** Context Locality — measures how self-contained code is for LLM consumption.
+ *
+ * Research backing:
+ * - "Lost in the Middle" (Liu et al. 2023): 30%+ accuracy drop for mid-context info
+ * - "Context Rot" (Chroma 2025): all frontier models degrade with input length
+ * - "Codified Context" (Vassilev 2025): 108K-line codebase needs 24.2% context overhead
+ *
+ * Sub-checks:
+ *   1. Import depth — how many files does each file transitively depend on?
+ *   2. Token density — estimated tokens per file (high = expensive for LLM context)
+ *   3. File self-containment — ratio of local symbols to imported symbols
+ *   4. Circular dependencies — import cycles that confuse navigation
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { gradeFromScore } from "../types.js";
+const MAX_FILE_TOKENS = 4000; // ~400 lines; beyond this LLMs lose mid-context info
+const MAX_IMPORTS = 15; // files importing >15 modules are hard to reason about
+const CHARS_PER_TOKEN = 3.5; // empirical average for code
+export function runContext(cwd) {
+    const start = Date.now();
+    const issues = [];
+    // Collect source files with imports
+    const files = [];
+    const dirs = ["src", "web/src"];
+    for (const dir of dirs) {
+        try {
+            collectFiles(join(cwd, dir), cwd, files);
+        }
+        catch { /* dir doesn't exist */ }
+    }
+    if (files.length === 0) {
+        return { name: "context", score: 100, grade: "A", details: { skipped: true, reason: "no source files" }, issues: [], duration: Date.now() - start };
+    }
+    let highTokenFiles = 0;
+    let heavyImportFiles = 0;
+    let circularDeps = 0;
+    let totalImports = 0;
+    let totalTokens = 0;
+    // ── 1. Token density per file ──
+    for (const f of files) {
+        totalTokens += f.tokens;
+        if (f.tokens > MAX_FILE_TOKENS) {
+            highTokenFiles++;
+            issues.push({ severity: "warning", message: `~${f.tokens} tokens (>${MAX_FILE_TOKENS}) — large context cost for LLMs`, file: f.path, rule: "high-token-count" });
+        }
+    }
+    // ── 2. Import count per file ──
+    for (const f of files) {
+        totalImports += f.imports.length;
+        if (f.imports.length > MAX_IMPORTS) {
+            heavyImportFiles++;
+            issues.push({ severity: "warning", message: `${f.imports.length} imports (>${MAX_IMPORTS}) — consider splitting or co-locating`, file: f.path, rule: "heavy-imports" });
+        }
+    }
+    // ── 3. Circular dependency detection ──
+    const importGraph = new Map();
+    for (const f of files) {
+        const deps = new Set();
+        for (const imp of f.imports) {
+            // Resolve relative import to file path
+            const resolved = resolveImport(f.path, imp);
+            if (resolved && files.some((ff) => ff.path === resolved)) {
+                deps.add(resolved);
+            }
+        }
+        importGraph.set(f.path, deps);
+    }
+    const cycles = findCycles(importGraph);
+    circularDeps = cycles.length;
+    for (const cycle of cycles.slice(0, 5)) {
+        issues.push({ severity: "error", message: `Circular dependency: ${cycle.join(" → ")}`, rule: "circular-dependency" });
+    }
+    if (cycles.length > 5) {
+        issues.push({ severity: "error", message: `...and ${cycles.length - 5} more circular dependencies`, rule: "circular-dependency" });
+    }
+    // ── 4. Self-containment heuristic ──
+    // Files with many imports and few exports are "context sinks" — hard to understand in isolation
+    let contextSinks = 0;
+    for (const f of files) {
+        const exportCount = (f.content.match(/\bexport\s+/g) || []).length;
+        if (f.imports.length > 8 && exportCount <= 1) {
+            contextSinks++;
+            issues.push({ severity: "warning", message: `${f.imports.length} imports but only ${exportCount} export — hard to understand in isolation`, file: f.path, rule: "context-sink" });
+        }
+    }
+    // ── Score ──
+    const avgImports = files.length > 0 ? totalImports / files.length : 0;
+    const avgTokens = files.length > 0 ? totalTokens / files.length : 0;
+    const penalty = highTokenFiles * 5 + heavyImportFiles * 3 + circularDeps * 15 + contextSinks * 2;
+    const score = Math.max(0, Math.min(100, 100 - penalty));
+    return {
+        name: "context",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            filesScanned: files.length,
+            totalTokens,
+            avgTokensPerFile: Math.round(avgTokens),
+            avgImportsPerFile: Math.round(avgImports * 10) / 10,
+            highTokenFiles,
+            heavyImportFiles,
+            circularDeps,
+            contextSinks,
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+// ── Import parsing ──
+function parseImports(content) {
+    const imports = [];
+    const regex = /import\s+(?:[\s\S]*?)\s+from\s+['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const path = match[1];
+        // Only count local imports (starting with . or /)
+        if (path.startsWith(".") || path.startsWith("/")) {
+            imports.push(path);
+        }
+    }
+    return imports;
+}
+function resolveImport(fromPath, importPath) {
+    // Simple resolution: join directory of fromPath with importPath
+    const dir = fromPath.includes("/") ? fromPath.replace(/\/[^/]+$/, "") : "";
+    let resolved = importPath;
+    if (importPath.startsWith("./")) {
+        resolved = dir ? `${dir}/${importPath.slice(2)}` : importPath.slice(2);
+    }
+    else if (importPath.startsWith("../")) {
+        const parts = dir.split("/");
+        parts.pop();
+        resolved = [...parts, importPath.slice(3)].join("/");
+    }
+    // Strip extension and try common ones
+    resolved = resolved.replace(/\.(js|ts|tsx|jsx)$/, "");
+    const extensions = [".ts", ".tsx", ".js", ".jsx"];
+    for (const ext of extensions) {
+        if (resolved.endsWith(ext.replace(".", "")))
+            return resolved;
+    }
+    // Return with .ts as default assumption
+    return resolved + ".ts";
+}
+// ── Cycle detection (DFS) ──
+function findCycles(graph) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const path = [];
+    function dfs(node) {
+        if (inStack.has(node)) {
+            // Found cycle — extract it
+            const cycleStart = path.indexOf(node);
+            if (cycleStart >= 0) {
+                cycles.push([...path.slice(cycleStart), node]);
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        inStack.add(node);
+        path.push(node);
+        const deps = graph.get(node);
+        if (deps) {
+            for (const dep of deps) {
+                dfs(dep);
+            }
+        }
+        path.pop();
+        inStack.delete(node);
+    }
+    for (const node of graph.keys()) {
+        dfs(node);
+    }
+    return cycles;
+}
+// ── File collection ──
+function collectFiles(dir, cwd, out) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === "node_modules" || entry === "dist" || entry === ".git")
+            continue;
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            collectFiles(full, cwd, out);
+        }
+        else {
+            const ext = extname(entry);
+            if ([".ts", ".tsx", ".js", ".jsx"].includes(ext) && !entry.includes(".test.") && !entry.includes(".spec.")) {
+                const content = readFileSync(full, "utf-8");
+                const relPath = full.replace(cwd + "/", "");
+                const imports = parseImports(content);
+                const tokens = Math.round(content.length / CHARS_PER_TOKEN);
+                out.push({ path: relPath, content, imports, tokens });
+            }
+        }
+    }
+}

package/dist/runners/coverage.d.ts

@@ -0,0 +1,3 @@
+/** Coverage runner — runs tests with coverage and parses the summary. */
+import type { CheckResult, StackInfo } from "../types.js";
+export declare function runCoverage(cwd: string, stack: StackInfo): CheckResult;

package/dist/runners/coverage.js

@@ -0,0 +1,65 @@
+/** Coverage runner — runs tests with coverage and parses the summary. */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { gradeFromScore } from "../types.js";
+import { run } from "./exec.js";
+export function runCoverage(cwd, stack) {
+    const start = Date.now();
+    if (stack.testRunner === "none") {
+        return {
+            name: "coverage",
+            score: 0,
+            grade: "F",
+            details: { skipped: true, reason: "no test runner" },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    // Run tests with coverage
+    const cmd = stack.testRunner === "vitest"
+        ? "npx vitest run --coverage 2>/dev/null || true"
+        : "npx jest --coverage --coverageReporters=json-summary 2>/dev/null || true";
+    run(cmd, cwd, 120_000);
+    // Look for coverage summary
+    const searchPaths = [
+        "coverage/coverage-summary.json",
+        "test-results/coverage/coverage-summary.json",
+    ];
+    let summary = null;
+    for (const p of searchPaths) {
+        const full = join(cwd, p);
+        if (existsSync(full)) {
+            try {
+                summary = JSON.parse(readFileSync(full, "utf-8"));
+                break;
+            }
+            catch {
+                /* parse failed */
+            }
+        }
+    }
+    if (!summary?.total) {
+        return {
+            name: "coverage",
+            score: 0,
+            grade: "F",
+            details: { skipped: true, reason: "no coverage data generated" },
+            issues: [],
+            duration: Date.now() - start,
+        };
+    }
+    const stmts = summary.total.statements?.pct || 0;
+    const lines = summary.total.lines?.pct || 0;
+    const branches = summary.total.branches?.pct || 0;
+    const functions = summary.total.functions?.pct || 0;
+    // Score is the average of all four metrics
+    const score = Math.round((stmts + lines + branches + functions) / 4);
+    return {
+        name: "coverage",
+        score,
+        grade: gradeFromScore(score),
+        details: { statements: stmts, lines, branches, functions },
+        issues: [],
+        duration: Date.now() - start,
+    };
+}

package/dist/runners/dependencies.d.ts

@@ -0,0 +1,3 @@
+/** Dependency health — vulnerabilities, outdated packages. */
+import type { CheckResult, StackInfo } from "../types.js";
+export declare function runDependencies(cwd: string, stack: StackInfo): CheckResult;

package/dist/runners/dependencies.js

@@ -0,0 +1,106 @@
+/** Dependency health — vulnerabilities, outdated packages. */
+import { gradeFromScore } from "../types.js";
+import { run } from "./exec.js";
+export function runDependencies(cwd, stack) {
+    const start = Date.now();
+    const issues = [];
+    const pm = stack.packageManager;
+    // Vulnerability audit
+    const auditCmd = pm === "pnpm"
+        ? "pnpm audit --json"
+        : pm === "yarn"
+            ? "yarn audit --json"
+            : "npm audit --json";
+    const auditResult = run(auditCmd + " 2>/dev/null || true", cwd);
+    let vulnCritical = 0, vulnHigh = 0, vulnModerate = 0, vulnLow = 0;
+    try {
+        const audit = JSON.parse(auditResult.stdout);
+        // npm audit format
+        if (audit.metadata?.vulnerabilities) {
+            const v = audit.metadata.vulnerabilities;
+            vulnCritical = v.critical || 0;
+            vulnHigh = v.high || 0;
+            vulnModerate = v.moderate || 0;
+            vulnLow = v.low || 0;
+        }
+        // pnpm audit format
+        if (audit.advisories) {
+            for (const adv of Object.values(audit.advisories)) {
+                if (adv.severity === "critical")
+                    vulnCritical++;
+                else if (adv.severity === "high")
+                    vulnHigh++;
+                else if (adv.severity === "moderate")
+                    vulnModerate++;
+                else
+                    vulnLow++;
+            }
+        }
+    }
+    catch {
+        /* audit parse failed — might be clean */
+    }
+    if (vulnCritical > 0)
+        issues.push({
+            severity: "error",
+            message: `${vulnCritical} critical vulnerabilities`,
+        });
+    if (vulnHigh > 0)
+        issues.push({
+            severity: "error",
+            message: `${vulnHigh} high vulnerabilities`,
+        });
+    if (vulnModerate > 0)
+        issues.push({
+            severity: "warning",
+            message: `${vulnModerate} moderate vulnerabilities`,
+        });
+    // Outdated check
+    const outdatedCmd = pm === "pnpm" ? "pnpm outdated --json" : "npm outdated --json";
+    const outdatedResult = run(outdatedCmd + " 2>/dev/null || true", cwd);
+    let outdatedCount = 0;
+    let majorOutdated = 0;
+    try {
+        const outdated = JSON.parse(outdatedResult.stdout);
+        // npm/pnpm format: object keyed by package name
+        for (const [, info] of Object.entries(outdated)) {
+            outdatedCount++;
+            const current = info.current || info.version || "";
+            const latest = info.latest || "";
+            if (current && latest && current.split(".")[0] !== latest.split(".")[0]) {
+                majorOutdated++;
+            }
+        }
+    }
+    catch {
+        /* no outdated data */
+    }
+    if (majorOutdated > 0)
+        issues.push({
+            severity: "warning",
+            message: `${majorOutdated} packages behind by a major version`,
+        });
+    // Score: -25 per critical, -15 per high, -5 per moderate, -1 per major outdated
+    const score = Math.max(0, Math.min(100, 100 -
+        vulnCritical * 25 -
+        vulnHigh * 15 -
+        vulnModerate * 5 -
+        majorOutdated * 1));
+    return {
+        name: "dependencies",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            vulnerabilities: {
+                critical: vulnCritical,
+                high: vulnHigh,
+                moderate: vulnModerate,
+                low: vulnLow,
+            },
+            outdated: outdatedCount,
+            majorOutdated,
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}

package/dist/runners/docs.d.ts

@@ -0,0 +1,3 @@
+/** Documentation check — README, JSDoc, code comments. */
+import type { CheckResult } from "../types.js";
+export declare function runDocs(cwd: string): CheckResult;

package/dist/runners/docs.js

@@ -0,0 +1,97 @@
+/** Documentation check — README, JSDoc, code comments. */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { gradeFromScore } from "../types.js";
+export function runDocs(cwd) {
+    const start = Date.now();
+    const issues = [];
+    let readmeScore = 0;
+    let exportDocScore = 0;
+    // Check README
+    const readmePath = join(cwd, "README.md");
+    if (!existsSync(readmePath)) {
+        issues.push({ severity: "error", message: "No README.md — project has no documentation", rule: "no-readme" });
+    }
+    else {
+        const readme = readFileSync(readmePath, "utf-8");
+        const lines = readme.split("\n").length;
+        if (lines < 5) {
+            issues.push({ severity: "warning", message: `README.md is only ${lines} lines — minimal documentation`, rule: "short-readme" });
+            readmeScore = 30;
+        }
+        else if (lines < 20) {
+            readmeScore = 60;
+        }
+        else {
+            readmeScore = 100;
+        }
+        // Check README sections
+        const hasInstall = /install|getting started|setup|usage/i.test(readme);
+        const hasDescription = readme.length > 100;
+        if (!hasInstall)
+            issues.push({ severity: "info", message: "README missing install/usage section", rule: "readme-no-install" });
+        if (!hasDescription)
+            issues.push({ severity: "warning", message: "README has very little content", rule: "readme-sparse" });
+    }
+    // Check exported function documentation
+    const files = [];
+    const dirs = ["src", "web/src"];
+    for (const dir of dirs) {
+        try {
+            collectFiles(join(cwd, dir), files);
+        }
+        catch { /* dir doesn't exist */ }
+    }
+    let totalExports = 0;
+    let documentedExports = 0;
+    for (const file of files) {
+        const content = readFileSync(file, "utf-8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            if (line.startsWith("export function ") || line.startsWith("export async function ") || line.startsWith("export class ") || line.startsWith("export interface ")) {
+                totalExports++;
+                // Check if preceded by a JSDoc or // comment
+                const prevLine = i > 0 ? lines[i - 1].trim() : "";
+                if (prevLine.endsWith("*/") || prevLine.startsWith("//") || prevLine.startsWith("/**")) {
+                    documentedExports++;
+                }
+            }
+        }
+    }
+    if (totalExports > 0) {
+        const pct = Math.round((documentedExports / totalExports) * 100);
+        exportDocScore = pct;
+        if (pct < 30) {
+            issues.push({ severity: "warning", message: `Only ${pct}% of exports have documentation (${documentedExports}/${totalExports})`, rule: "undocumented-exports" });
+        }
+    }
+    else {
+        exportDocScore = 100; // no exports = nothing to document
+    }
+    const score = Math.round(readmeScore * 0.5 + exportDocScore * 0.5);
+    return {
+        name: "docs",
+        score,
+        grade: gradeFromScore(score),
+        details: { readmeLines: existsSync(readmePath) ? readFileSync(readmePath, "utf-8").split("\n").length : 0, totalExports, documentedExports, documentedPct: totalExports > 0 ? Math.round((documentedExports / totalExports) * 100) + "%" : "n/a" },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+function collectFiles(dir, out) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === "node_modules" || entry === "dist")
+            continue;
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            collectFiles(full, out);
+        }
+        else {
+            const ext = extname(entry);
+            if ((ext === ".ts" || ext === ".tsx") && !entry.includes(".test.") && !entry.includes(".spec.")) {
+                out.push(full);
+            }
+        }
+    }
+}

package/dist/runners/duplication.d.ts

@@ -0,0 +1,3 @@
+/** Code duplication detection — finds copy-pasted blocks. */
+import type { CheckResult } from "../types.js";
+export declare function runDuplication(cwd: string): CheckResult;

package/dist/runners/duplication.js

@@ -0,0 +1,100 @@
+/** Code duplication detection — finds copy-pasted blocks. */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { gradeFromScore } from "../types.js";
+const MIN_LINES = 6; // minimum duplicate block size
+const MIN_TOKENS = 50; // minimum token count for a duplicate
+export function runDuplication(cwd) {
+    const start = Date.now();
+    const issues = [];
+    const files = [];
+    const dirs = ["src", "web/src"];
+    for (const dir of dirs) {
+        try {
+            collectFiles(join(cwd, dir), files);
+        }
+        catch { /* dir doesn't exist */ }
+    }
+    if (files.length < 2) {
+        return { name: "duplication", score: 100, grade: "A", details: { filesScanned: files.length, duplicates: 0 }, issues: [], duration: Date.now() - start };
+    }
+    // Simple line-based duplicate detection
+    // Build a map of normalized line hashes → locations
+    const lineMap = new Map();
+    let totalSourceLines = 0;
+    for (const file of files) {
+        const content = readFileSync(file, "utf-8");
+        const relPath = file.replace(cwd + "/", "");
+        const lines = content.split("\n");
+        totalSourceLines += lines.length;
+        for (let i = 0; i <= lines.length - MIN_LINES; i++) {
+            const block = lines
+                .slice(i, i + MIN_LINES)
+                .map((l) => l.trim())
+                .filter((l) => l.length > 0 && !l.startsWith("//") && !l.startsWith("*") && l !== "{" && l !== "}" && l !== "");
+            if (block.length < MIN_LINES - 2)
+                continue; // too many empty/trivial lines
+            const key = block.join("\n");
+            if (key.length < MIN_TOKENS)
+                continue;
+            const locs = lineMap.get(key) || [];
+            locs.push({ file: relPath, line: i + 1 });
+            lineMap.set(key, locs);
+        }
+    }
+    // Find blocks that appear in 2+ locations
+    const duplicates = [];
+    const seen = new Set();
+    for (const [_key, locs] of lineMap) {
+        if (locs.length < 2)
+            continue;
+        // Deduplicate: same file, adjacent lines are the same block
+        const unique = locs.filter((l, i) => i === 0 || l.file !== locs[i - 1].file || l.line > locs[i - 1].line + MIN_LINES);
+        if (unique.length < 2)
+            continue;
+        // Only report each pair once
+        for (let i = 0; i < unique.length - 1; i++) {
+            const a = unique[i];
+            const b = unique[i + 1];
+            const pairKey = `${a.file}:${a.line}-${b.file}:${b.line}`;
+            if (seen.has(pairKey))
+                continue;
+            seen.add(pairKey);
+            duplicates.push({ fileA: a.file, lineA: a.line, fileB: b.file, lineB: b.line, lines: MIN_LINES });
+        }
+    }
+    for (const d of duplicates.slice(0, 20)) {
+        issues.push({
+            severity: "warning",
+            message: `${MIN_LINES}-line duplicate block`,
+            file: `${d.fileA}:${d.lineA} ↔ ${d.fileB}:${d.lineB}`,
+            rule: "duplicate-code",
+        });
+    }
+    const dupPct = totalSourceLines > 0 ? Math.round((duplicates.length * MIN_LINES * 100) / totalSourceLines) : 0;
+    const score = Math.max(0, Math.min(100, 100 - dupPct * 3 - duplicates.length));
+    return {
+        name: "duplication",
+        score,
+        grade: gradeFromScore(score),
+        details: { filesScanned: files.length, totalSourceLines, duplicateBlocks: duplicates.length, duplicationPct: dupPct + "%" },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+function collectFiles(dir, out) {
+    for (const entry of readdirSync(dir)) {
+        if (entry === "node_modules" || entry === "dist" || entry === ".git")
+            continue;
+        const full = join(dir, entry);
+        if (statSync(full).isDirectory()) {
+            collectFiles(full, out);
+        }
+        else {
+            const ext = extname(entry);
+            if ([".ts", ".tsx", ".js", ".jsx"].includes(ext) && !entry.includes(".test.") && !entry.includes(".spec.")) {
+                out.push(full);
+            }
+        }
+    }
+}

package/dist/runners/exec.d.ts

@@ -0,0 +1,6 @@
+/** Shared exec helper for runners. */
+export declare function run(cmd: string, cwd: string, timeout?: number): {
+    stdout: string;
+    ok: boolean;
+};
+export declare function runJSON<T>(cmd: string, cwd: string, timeout?: number): T | null;

package/dist/runners/exec.js

@@ -0,0 +1,25 @@
+/** Shared exec helper for runners. */
+import { execSync } from "node:child_process";
+export function run(cmd, cwd, timeout = 60_000) {
+    try {
+        const stdout = execSync(cmd, {
+            cwd,
+            timeout,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return { stdout, ok: true };
+    }
+    catch (e) {
+        return { stdout: e.stdout || e.stderr || String(e), ok: false };
+    }
+}
+export function runJSON(cmd, cwd, timeout = 60_000) {
+    const { stdout } = run(cmd, cwd, timeout);
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/runners/lint.d.ts

@@ -0,0 +1,3 @@
+/** Lint check — auto-detects biome or eslint. */
+import type { CheckResult, StackInfo } from "../types.js";
+export declare function runLint(cwd: string, stack: StackInfo): CheckResult;