@vibecodeqa/cli 0.9.0

package/dist/runners/architecture.js

@@ -0,0 +1,272 @@
+/** Architecture analysis — import graph, circular deps, coupling metrics, god modules.
+ *
+ * Produces:
+ *   1. Import graph (adjacency list)
+ *   2. Circular dependency detection
+ *   3. Fan-in / fan-out metrics per file (coupling)
+ *   4. God modules (imported by >50% of files)
+ *   5. Orphan files (not imported by anyone, not an entrypoint)
+ *   6. Layer violations (optional: detect cross-layer imports)
+ *   7. SVG architecture diagram
+ */
+import { basename, dirname, extname } from "node:path";
+import { gradeFromScore } from "../types.js";
+import { getProductionFiles } from "../fs-utils.js";
+export function runArchitecture(cwd) {
+    const start = Date.now();
+    const issues = [];
+    const files = getProductionFiles(cwd);
+    if (files.length < 2) {
+        return { name: "architecture", score: 100, grade: "A", details: { skipped: true, reason: "fewer than 2 source files" }, issues: [], duration: Date.now() - start };
+    }
+    const graph = buildGraph(files);
+    // ── Circular dependencies ──
+    const cycles = findCycles(graph.nodes);
+    for (const cycle of cycles.slice(0, 5)) {
+        issues.push({ severity: "error", message: `Circular: ${cycle.map(short).join(" → ")}`, rule: "circular-dep" });
+    }
+    if (cycles.length > 5) {
+        issues.push({ severity: "error", message: `...and ${cycles.length - 5} more cycles`, rule: "circular-dep" });
+    }
+    // ── God modules (imported by >50% of files) ──
+    const threshold = Math.max(3, Math.floor(files.length * 0.5));
+    const godModules = [];
+    for (const [path, node] of graph.nodes) {
+        if (node.importedBy.length >= threshold) {
+            godModules.push(path);
+            issues.push({ severity: "warning", message: `God module: imported by ${node.importedBy.length}/${files.length} files — consider splitting`, file: path, rule: "god-module" });
+        }
+    }
+    // ── Orphan files (not imported by anyone) ──
+    const entrypoints = new Set(["index.ts", "index.tsx", "main.ts", "main.tsx", "cli.ts", "App.tsx", "App.ts"]);
+    const orphans = [];
+    for (const [path, node] of graph.nodes) {
+        const isEntry = entrypoints.has(basename(path));
+        if (node.importedBy.length === 0 && !isEntry) {
+            orphans.push(path);
+            issues.push({ severity: "warning", message: `Orphan: not imported by any file (dead module?)`, file: path, rule: "orphan-module" });
+        }
+    }
+    // ── High fan-out (file imports too many modules) ──
+    let highFanOut = 0;
+    for (const [path, node] of graph.nodes) {
+        if (node.imports.length > 10) {
+            highFanOut++;
+            issues.push({ severity: "warning", message: `High fan-out: imports ${node.imports.length} modules — hard to test in isolation`, file: path, rule: "high-fan-out" });
+        }
+    }
+    // ── High fan-in + fan-out (connector files) ──
+    let connectors = 0;
+    for (const [path, node] of graph.nodes) {
+        if (node.imports.length > 5 && node.importedBy.length > 5) {
+            connectors++;
+            issues.push({ severity: "warning", message: `Connector: ${node.imports.length} imports, ${node.importedBy.length} importers — high coupling`, file: path, rule: "connector-module" });
+        }
+    }
+    // ── Score ──
+    const penalty = cycles.length * 15 + godModules.length * 5 + orphans.length * 2 + highFanOut * 3 + connectors * 4;
+    const score = Math.max(0, Math.min(100, 100 - penalty));
+    // ── Build details with graph data for visualization ──
+    const graphData = {};
+    for (const [path, node] of graph.nodes) {
+        graphData[path] = { imports: node.imports, importedBy: node.importedBy, dir: node.dir };
+    }
+    return {
+        name: "architecture",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            totalModules: graph.nodes.size,
+            circularDeps: cycles.length,
+            godModules: godModules.length,
+            orphans: orphans.length,
+            highFanOut,
+            connectors,
+            graph: graphData,
+        },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+// ── Graph building ──
+function buildGraph(files) {
+    const filePaths = new Set(files.map((f) => f.path));
+    const nodes = new Map();
+    // Initialize nodes
+    for (const f of files) {
+        nodes.set(f.path, {
+            path: f.path,
+            imports: [],
+            importedBy: [],
+            dir: dirname(f.path),
+            exports: (f.content.match(/\bexport\s+/g) || []).length,
+        });
+    }
+    // Parse imports and build edges
+    for (const f of files) {
+        const imports = parseImports(f.content);
+        const node = nodes.get(f.path);
+        for (const imp of imports) {
+            const resolved = resolveImport(f.path, imp, filePaths);
+            if (resolved && resolved !== f.path) {
+                node.imports.push(resolved);
+                const target = nodes.get(resolved);
+                if (target)
+                    target.importedBy.push(f.path);
+            }
+        }
+    }
+    return { nodes };
+}
+function parseImports(content) {
+    const imports = [];
+    const regex = /import\s+(?:[\s\S]*?)\s+from\s+['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        if (match[1].startsWith("."))
+            imports.push(match[1]);
+    }
+    return imports;
+}
+function resolveImport(fromPath, importPath, knownFiles) {
+    const fromDir = dirname(fromPath);
+    let resolved = importPath;
+    if (importPath.startsWith("./")) {
+        resolved = fromDir ? `${fromDir}/${importPath.slice(2)}` : importPath.slice(2);
+    }
+    else if (importPath.startsWith("../")) {
+        const parts = fromDir.split("/");
+        let imp = importPath;
+        while (imp.startsWith("../")) {
+            parts.pop();
+            imp = imp.slice(3);
+        }
+        resolved = [...parts, imp].filter(Boolean).join("/");
+    }
+    // Strip .js/.ts extension
+    resolved = resolved.replace(/\.(js|ts|tsx|jsx)$/, "");
+    // Try known extensions
+    for (const ext of [".ts", ".tsx", ".js", ".jsx"]) {
+        if (knownFiles.has(resolved + ext))
+            return resolved + ext;
+    }
+    // Try index
+    for (const ext of [".ts", ".tsx"]) {
+        if (knownFiles.has(resolved + "/index" + ext))
+            return resolved + "/index" + ext;
+    }
+    return null;
+}
+// ── Cycle detection (DFS with path tracking) ──
+function findCycles(nodes) {
+    const cycles = [];
+    const visited = new Set();
+    const inStack = new Set();
+    const path = [];
+    const seen = new Set(); // dedup cycles
+    function dfs(node) {
+        if (inStack.has(node)) {
+            const cycleStart = path.indexOf(node);
+            if (cycleStart >= 0) {
+                const cycle = path.slice(cycleStart).map(short);
+                const key = [...cycle].sort().join(",");
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    cycles.push([...cycle, short(node)]);
+                }
+            }
+            return;
+        }
+        if (visited.has(node))
+            return;
+        visited.add(node);
+        inStack.add(node);
+        path.push(node);
+        const n = nodes.get(node);
+        if (n) {
+            for (const dep of n.imports) {
+                dfs(dep);
+            }
+        }
+        path.pop();
+        inStack.delete(node);
+    }
+    for (const node of nodes.keys()) {
+        dfs(node);
+    }
+    return cycles;
+}
+function short(path) {
+    return basename(path, extname(path));
+}
+// ── SVG Architecture Diagram ──
+export function generateArchSVG(details) {
+    const graph = details.graph;
+    if (!graph || Object.keys(graph).length === 0)
+        return "";
+    const nodes = Object.entries(graph);
+    const nodeCount = nodes.length;
+    if (nodeCount > 40)
+        return ""; // too many nodes to render meaningfully
+    // Group by directory
+    const dirs = new Map();
+    for (const [path, info] of nodes) {
+        const dir = info.dir || ".";
+        const arr = dirs.get(dir) || [];
+        arr.push(path);
+        dirs.set(dir, arr);
+    }
+    const W = 800, padding = 40;
+    const dirEntries = [...dirs.entries()];
+    const dirWidth = (W - padding * 2) / Math.max(dirEntries.length, 1);
+    // Position nodes
+    const positions = new Map();
+    let dirIdx = 0;
+    for (const [_d, paths] of dirEntries) {
+        const x0 = padding + dirIdx * dirWidth + dirWidth / 2;
+        for (let i = 0; i < paths.length; i++) {
+            const y = padding + 50 + i * 35;
+            positions.set(paths[i], { x: x0, y });
+        }
+        dirIdx++;
+    }
+    const H = Math.max(300, padding * 2 + 50 + Math.max(...[...dirs.values()].map((p) => p.length)) * 35 + 20);
+    // Draw edges
+    let edges = "";
+    for (const [path, info] of nodes) {
+        const from = positions.get(path);
+        if (!from)
+            continue;
+        for (const imp of info.imports) {
+            const to = positions.get(imp);
+            if (!to)
+                continue;
+            const color = info.dir !== graph[imp]?.dir ? "#ef444440" : "#818cf825";
+            edges += `<line x1="${from.x}" y1="${from.y}" x2="${to.x}" y2="${to.y}" stroke="${color}" stroke-width="1.5"/>`;
+        }
+    }
+    // Draw directory groups
+    let groups = "";
+    dirIdx = 0;
+    for (const [dName, paths] of dirEntries) {
+        const x = padding + dirIdx * dirWidth;
+        const h = paths.length * 35 + 20;
+        groups += `<rect x="${x + 5}" y="${padding + 30}" width="${dirWidth - 10}" height="${h}" rx="8" fill="#14141a" stroke="#23232a"/>`;
+        groups += `<text x="${x + dirWidth / 2}" y="${padding + 22}" text-anchor="middle" fill="#6b7280" font-size="10" font-weight="600">${dName === "." ? "root" : dName.split("/").pop()}</text>`;
+        dirIdx++;
+    }
+    // Draw nodes
+    let nodesSvg = "";
+    for (const [path] of nodes) {
+        const pos = positions.get(path);
+        if (!pos)
+            continue;
+        const name = basename(path, extname(path));
+        const info = graph[path];
+        const fanIn = info.importedBy.length;
+        const size = Math.min(8, 3 + fanIn);
+        nodesSvg += `<circle cx="${pos.x}" cy="${pos.y}" r="${size}" fill="#818cf8"/>`;
+        nodesSvg += `<text x="${pos.x + size + 4}" y="${pos.y + 3}" fill="#e5e5e5" font-size="9">${name}</text>`;
+    }
+    return `<svg viewBox="0 0 ${W} ${H}" xmlns="http://www.w3.org/2000/svg" style="width:100%;max-width:${W}px;background:#09090b;border-radius:8px;border:1px solid #1e1e24">${groups}${edges}${nodesSvg}</svg>`;
+}

package/dist/runners/complexity.d.ts

@@ -0,0 +1,3 @@
+/** Complexity analysis — counts lines, functions, and cognitive complexity via AST-free heuristics. */
+import type { CheckResult } from "../types.js";
+export declare function runComplexity(cwd: string): CheckResult;

package/dist/runners/complexity.js

@@ -0,0 +1,152 @@
+/** Complexity analysis — counts lines, functions, and cognitive complexity via AST-free heuristics. */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import { gradeFromScore } from "../types.js";
+const MAX_FUNCTION_LINES = 60;
+const MAX_COMPLEXITY = 15;
+export function runComplexity(cwd) {
+    const start = Date.now();
+    const issues = [];
+    const functions = [];
+    // Find all TS/JS source files (not tests, not node_modules)
+    const srcDirs = ["src", "web/src"];
+    const files = [];
+    for (const dir of srcDirs) {
+        try {
+            collectFiles(join(cwd, dir), files);
+        }
+        catch {
+            /* dir doesn't exist */
+        }
+    }
+    let totalLines = 0;
+    const totalFiles = files.length;
+    let longFunctions = 0;
+    let complexFunctions = 0;
+    for (const file of files) {
+        const content = readFileSync(file, "utf-8");
+        const lines = content.split("\n");
+        totalLines += lines.length;
+        // Simple heuristic: find function boundaries and measure complexity
+        const funcs = extractFunctions(content, file.replace(cwd + "/", ""));
+        for (const f of funcs) {
+            functions.push(f);
+            if (f.lines > MAX_FUNCTION_LINES) {
+                longFunctions++;
+                issues.push({
+                    severity: "warning",
+                    message: `${f.name}: ${f.lines} lines (max ${MAX_FUNCTION_LINES})`,
+                    file: f.file,
+                    rule: "long-function",
+                });
+            }
+            if (f.complexity > MAX_COMPLEXITY) {
+                complexFunctions++;
+                issues.push({
+                    severity: "warning",
+                    message: `${f.name}: complexity ${f.complexity} (max ${MAX_COMPLEXITY})`,
+                    file: f.file,
+                    rule: "high-complexity",
+                });
+            }
+        }
+    }
+    // Score: start at 100, -3 per long function, -5 per complex function
+    const score = Math.max(0, Math.min(100, 100 - longFunctions * 3 - complexFunctions * 5));
+    return {
+        name: "complexity",
+        score,
+        grade: gradeFromScore(score),
+        details: {
+            totalFiles,
+            totalLines,
+            longFunctions,
+            complexFunctions,
+            functionCount: functions.length,
+        },
+        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);
+        const stat = statSync(full);
+        if (stat.isDirectory()) {
+            collectFiles(full, out);
+        }
+        else {
+            const ext = extname(entry);
+            if ((ext === ".ts" || ext === ".tsx" || ext === ".js" || ext === ".jsx") &&
+                !entry.includes(".test.") &&
+                !entry.includes(".spec.")) {
+                out.push(full);
+            }
+        }
+    }
+}
+/** Simple heuristic function extraction — not a full AST parser but good enough for metrics. */
+function extractFunctions(content, filePath) {
+    const funcs = [];
+    const lines = content.split("\n");
+    // Track brace nesting
+    let funcStart = -1;
+    let funcName = "";
+    let braceCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        // Detect function start
+        if (funcStart === -1) {
+            const match = trimmed.match(/^(?:export\s+)?(?:async\s+)?function\s+(\w+)/) ||
+                trimmed.match(/^(?:export\s+)?(?:const|let)\s+(\w+)\s*=\s*(?:async\s*)?\(/) ||
+                trimmed.match(/^(?:private|public|protected)?\s*(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*\w[^{]*)?\{/) ||
+                trimmed.match(/^(?:async\s+)?(\w+)\s*\([^)]*\)\s*\{/);
+            if (match) {
+                funcStart = i;
+                funcName = match[1] || "anonymous";
+                braceCount = 0;
+            }
+        }
+        // Track brace depth
+        if (funcStart !== -1) {
+            for (const ch of line) {
+                if (ch === "{")
+                    braceCount++;
+                if (ch === "}")
+                    braceCount--;
+            }
+            if (braceCount <= 0 && i > funcStart) {
+                const funcLines = i - funcStart + 1;
+                const funcContent = lines.slice(funcStart, i + 1).join("\n");
+                funcs.push({
+                    file: filePath,
+                    name: funcName,
+                    lines: funcLines,
+                    complexity: measureComplexity(funcContent),
+                });
+                funcStart = -1;
+            }
+        }
+    }
+    return funcs;
+}
+/** Heuristic cognitive complexity — counts nesting and branching. */
+function measureComplexity(code) {
+    let complexity = 0;
+    const lines = code.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // +1 for each branch/loop keyword
+        if (/\b(if|else if|else|switch|for|while|do|catch|&&|\|\||[?]:)\b/.test(trimmed)) {
+            complexity++;
+        }
+        // +1 for ternary
+        if (/\?.*:/.test(trimmed) && !trimmed.startsWith("//")) {
+            complexity++;
+        }
+    }
+    return complexity;
+}

package/dist/runners/confusion.d.ts

@@ -0,0 +1,16 @@
+/** Confusion Index — measures naming ambiguity that causes LLMs to misunderstand or edit the wrong code.
+ *
+ * Research backing:
+ * - "When Names Disappear" (arXiv:2510.03178): GPT-4o drops 28.6 pts on summarization with obfuscated names
+ * - "How Does Naming Affect LLMs?" (Wang et al. 2024): LLMs heavily rely on well-defined names
+ * - Linguistic Antipatterns (Arnaoudova et al.): 17-pattern catalog, 69% devs perceive as harmful
+ * - "Variable Naming Impact" (2024): descriptive names = 0.874 semantic similarity vs 0.802 obfuscated
+ *
+ * Four sub-checks:
+ *   1. File name confusability (near-identical or synonym filenames)
+ *   2. Generic function/variable names (process, handle, data, result, etc.)
+ *   3. Export name collisions (same name exported from multiple files)
+ *   4. Ambiguous abbreviations (auth, config, ctx, etc. outside conventional scope)
+ */
+import type { CheckResult } from "../types.js";
+export declare function runConfusion(cwd: string): CheckResult;

package/dist/runners/confusion.js

@@ -0,0 +1,198 @@
+/** Confusion Index — measures naming ambiguity that causes LLMs to misunderstand or edit the wrong code.
+ *
+ * Research backing:
+ * - "When Names Disappear" (arXiv:2510.03178): GPT-4o drops 28.6 pts on summarization with obfuscated names
+ * - "How Does Naming Affect LLMs?" (Wang et al. 2024): LLMs heavily rely on well-defined names
+ * - Linguistic Antipatterns (Arnaoudova et al.): 17-pattern catalog, 69% devs perceive as harmful
+ * - "Variable Naming Impact" (2024): descriptive names = 0.874 semantic similarity vs 0.802 obfuscated
+ *
+ * Four sub-checks:
+ *   1. File name confusability (near-identical or synonym filenames)
+ *   2. Generic function/variable names (process, handle, data, result, etc.)
+ *   3. Export name collisions (same name exported from multiple files)
+ *   4. Ambiguous abbreviations (auth, config, ctx, etc. outside conventional scope)
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import { gradeFromScore } from "../types.js";
+// ── Pattern dictionaries ──
+const SYNONYM_PAIRS = [
+    ["utils", "helpers"], ["util", "helper"],
+    ["types", "interfaces"], ["types", "models"], ["interfaces", "models"],
+    ["constants", "config"], ["constants", "settings"], ["config", "settings"],
+    ["service", "controller"], ["service", "handler"], ["controller", "handler"],
+    ["store", "state"], ["context", "provider"],
+];
+const GENERIC_NAMES = new Set([
+    "process", "handle", "run", "execute", "do", "perform", "make",
+    "get", "set", "update", "create", "delete", "remove", "add",
+    "data", "result", "item", "value", "info", "temp", "obj",
+    "stuff", "thing", "ret", "val", "res", "output", "input",
+    "response", "request", "payload", "body", "args", "params",
+    "list", "arr", "map", "dict", "collection",
+    "callback", "cb", "fn", "func", "handler",
+]);
+const AMBIGUOUS_ABBREVS = {
+    auth: "authentication OR authorization",
+    config: "which configuration?",
+    env: "environment (runtime? deployment? variables?)",
+    db: "database (connection? schema? query builder?)",
+    msg: "message (type? content? handler?)",
+    ctx: "context (React? request? app?)",
+    err: "error (type? instance? handler?)",
+    mgr: "manager (of what?)",
+    svc: "service (which service?)",
+    srv: "server (HTTP? WebSocket? instance?)",
+    req: "request (HTTP? specific type?)",
+    res: "response or result?",
+    cmd: "command (CLI? pattern? string?)",
+    evt: "event (DOM? custom? type?)",
+    ref: "reference (React ref? DB ref? pointer?)",
+};
+export function runConfusion(cwd) {
+    const start = Date.now();
+    const issues = [];
+    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: "confusion", score: 100, grade: "A", details: { skipped: true, reason: "no source files" }, issues: [], duration: Date.now() - start };
+    }
+    let fileConfusability = 0;
+    let genericNames = 0;
+    let exportCollisions = 0;
+    let ambiguousAbbrevs = 0;
+    // ── 1. File name confusability ──
+    for (let i = 0; i < files.length; i++) {
+        for (let j = i + 1; j < files.length; j++) {
+            const a = files[i].base;
+            const b = files[j].base;
+            // Near-identical (Levenshtein ≤ 2)
+            if (a !== b && levenshtein(a, b) <= 2) {
+                fileConfusability++;
+                issues.push({ severity: "warning", message: `Similar filenames: ${a} ↔ ${b} (edit distance ${levenshtein(a, b)})`, file: files[i].path, rule: "similar-filename" });
+            }
+            // Synonym pairs
+            for (const [s1, s2] of SYNONYM_PAIRS) {
+                if ((a.includes(s1) && b.includes(s2)) || (a.includes(s2) && b.includes(s1))) {
+                    fileConfusability++;
+                    issues.push({ severity: "warning", message: `Synonym filenames: ${a} ↔ ${b} (${s1}/${s2} are interchangeable — pick one convention)`, file: files[i].path, rule: "synonym-filename" });
+                    break;
+                }
+            }
+        }
+    }
+    // ── 2. Generic function/variable names ──
+    for (const f of files) {
+        const lines = f.content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i].trim();
+            if (line.startsWith("//") || line.startsWith("*"))
+                continue;
+            // Match exported function names
+            const funcMatch = line.match(/^export\s+(?:async\s+)?function\s+(\w+)/);
+            if (funcMatch && GENERIC_NAMES.has(funcMatch[1].toLowerCase())) {
+                genericNames++;
+                issues.push({ severity: "warning", message: `Generic export name: ${funcMatch[1]}() — not descriptive enough for LLM comprehension`, file: f.path, line: i + 1, rule: "generic-name" });
+            }
+            // Match standalone variable assignments with generic names
+            const varMatch = line.match(/^(?:export\s+)?(?:const|let)\s+(\w+)\s*=/);
+            if (varMatch && GENERIC_NAMES.has(varMatch[1].toLowerCase()) && varMatch[1].length <= 6) {
+                genericNames++;
+                issues.push({ severity: "warning", message: `Generic variable: ${varMatch[1]} — use a descriptive name`, file: f.path, line: i + 1, rule: "generic-name" });
+            }
+        }
+    }
+    // ── 3. Export name collisions ──
+    const exportMap = new Map();
+    for (const f of files) {
+        for (const exp of f.exports) {
+            const arr = exportMap.get(exp) || [];
+            arr.push(f.path);
+            exportMap.set(exp, arr);
+        }
+    }
+    for (const [name, paths] of exportMap) {
+        if (paths.length > 1) {
+            exportCollisions++;
+            issues.push({ severity: "error", message: `Export collision: "${name}" exported from ${paths.length} files — LLMs may reference the wrong one`, file: paths.join(", "), rule: "export-collision" });
+        }
+    }
+    // ── 4. Ambiguous abbreviations in filenames and exports ──
+    for (const f of files) {
+        const nameParts = f.base.split(/[-_./]/).map((s) => s.toLowerCase());
+        for (const part of nameParts) {
+            if (AMBIGUOUS_ABBREVS[part]) {
+                ambiguousAbbrevs++;
+                issues.push({ severity: "warning", message: `Ambiguous abbreviation "${part}" in filename — could mean: ${AMBIGUOUS_ABBREVS[part]}`, file: f.path, rule: "ambiguous-abbreviation" });
+            }
+        }
+    }
+    // ── Score ──
+    const penalty = fileConfusability * 5 + genericNames * 1 + exportCollisions * 10 + ambiguousAbbrevs * 2;
+    const score = Math.max(0, Math.min(100, 100 - penalty));
+    return {
+        name: "confusion",
+        score,
+        grade: gradeFromScore(score),
+        details: { fileConfusability, genericNames, exportCollisions, ambiguousAbbrevs, filesScanned: files.length },
+        issues,
+        duration: Date.now() - start,
+    };
+}
+// ── Helpers ──
+function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+    for (let i = 0; i <= m; i++)
+        dp[i][0] = i;
+    for (let j = 0; j <= n; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+        for (let j = 1; j <= n; j++) {
+            dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+        }
+    }
+    return dp[m][n];
+}
+function extractExports(content) {
+    const exports = [];
+    const patterns = [
+        /export\s+(?:async\s+)?function\s+(\w+)/g,
+        /export\s+(?:const|let|var)\s+(\w+)/g,
+        /export\s+class\s+(\w+)/g,
+        /export\s+interface\s+(\w+)/g,
+        /export\s+type\s+(\w+)/g,
+    ];
+    for (const pat of patterns) {
+        let match;
+        while ((match = pat.exec(content)) !== null) {
+            exports.push(match[1]);
+        }
+    }
+    return exports;
+}
+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 base = basename(entry, ext);
+                out.push({ path: relPath, base, content, exports: extractExports(content) });
+            }
+        }
+    }
+}

package/dist/runners/context.d.ts

@@ -0,0 +1,15 @@
+/** 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 type { CheckResult } from "../types.js";
+export declare function runContext(cwd: string): CheckResult;