@vibecodeqa/cli 0.42.0 → 0.44.0

package/dist/commands/explain.d.ts

@@ -0,0 +1,2 @@
+/** vcqa explain — deep-dive explanation of a check. */
+export declare function runExplain(checkName?: string): Promise<void>;

package/dist/commands/explain.js

@@ -0,0 +1,33 @@
+/** vcqa explain — deep-dive explanation of a check. */
+import { getCheckMeta } from "../check-meta.js";
+export async function runExplain(checkName) {
+    if (!checkName) {
+        console.log("\n  \x1b[1mUsage:\x1b[0m vcqa explain <check>\n");
+        console.log("  Available checks:");
+        const { CHECK_META } = await import("../check-meta.js");
+        for (const [name, meta] of Object.entries(CHECK_META)) {
+            console.log(`    \x1b[1m${name.padEnd(16)}\x1b[0m ${meta.label} (${meta.category}, ${meta.weight}%)`);
+        }
+        console.log("");
+        return;
+    }
+    const meta = getCheckMeta(checkName);
+    if (!meta.description || meta.description.length < 20) {
+        console.log(`\n  \x1b[31mUnknown check: ${checkName}\x1b[0m`);
+        console.log("  Run \x1b[1mvcqa explain\x1b[0m to see available checks.\n");
+        return;
+    }
+    console.log("");
+    console.log(`  \x1b[1m\x1b[38;5;141m${meta.label}\x1b[0m  \x1b[2m${meta.category} · ${meta.priority} priority · ${meta.weight}% weight\x1b[0m`);
+    console.log("");
+    console.log(`  \x1b[1mWhat:\x1b[0m ${meta.description}`);
+    console.log("");
+    console.log(`  \x1b[1mRisk:\x1b[0m ${meta.risk}`);
+    console.log("");
+    console.log(`  \x1b[1mFix:\x1b[0m ${meta.recommendation}`);
+    if (meta.deeperTools?.length) {
+        console.log("");
+        console.log(`  \x1b[1mGo deeper:\x1b[0m ${meta.deeperTools.join(", ")}`);
+    }
+    console.log("");
+}

package/dist/commands/fix.d.ts

@@ -0,0 +1,6 @@
+/** vcqa fix — auto-fix + AI-powered fixing with delta report. */
+export declare function runFix(cwd: string, opts?: {
+    ai?: boolean;
+    dryRun?: boolean;
+    checkFilter?: string;
+}): Promise<void>;

package/dist/commands/fix.js

@@ -0,0 +1,157 @@
+/** vcqa fix — auto-fix + AI-powered fixing with delta report. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { aiFixIssues, collectFixableIssues } from "../ai-fix.js";
+import { scan } from "../core.js";
+import { computeDelta, formatDeltaMarkdown } from "../delta.js";
+import { detectStack } from "../detect.js";
+import { suggestFix, validateCwd } from "./shared.js";
+export async function runFix(cwd, opts = {}) {
+    console.log("");
+    console.log(`  \x1b[1m\x1b[38;5;141mvcqa fix${opts.ai ? " --ai" : ""}${opts.dryRun ? " --dry-run" : ""}${opts.checkFilter ? ` --check ${opts.checkFilter}` : ""}\x1b[0m`);
+    console.log(`  \x1b[2m${cwd}\x1b[0m`);
+    console.log("");
+    validateCwd(cwd);
+    // 0. Baseline scan (before fixes)
+    console.log("  \x1b[1mBaseline scan...\x1b[0m");
+    const beforeReport = await scan(cwd, { skipTests: true });
+    console.log(`  \x1b[2mBaseline: ${beforeReport.grade} ${beforeReport.score}/100\x1b[0m`);
+    console.log("");
+    const stack = detectStack(cwd);
+    let fixed = 0;
+    // 1. Auto-fix structure issues (missing files)
+    if (!existsSync(join(cwd, ".gitignore"))) {
+        writeFileSync(join(cwd, ".gitignore"), "node_modules\ndist\n.vibe-check\ncoverage\n.env\n.env.local\n");
+        console.log("  \x1b[32m\u2713 Created .gitignore\x1b[0m");
+        fixed++;
+    }
+    if (existsSync(join(cwd, ".gitignore"))) {
+        const gi = readFileSync(join(cwd, ".gitignore"), "utf-8");
+        if (!gi.includes(".vibe-check")) {
+            writeFileSync(join(cwd, ".gitignore"), gi.trimEnd() + "\n.vibe-check/\n");
+            console.log("  \x1b[32m\u2713 Added .vibe-check/ to .gitignore\x1b[0m");
+            fixed++;
+        }
+    }
+    const tsconfigPath = join(cwd, "tsconfig.json");
+    if (existsSync(tsconfigPath)) {
+        try {
+            const raw = readFileSync(tsconfigPath, "utf-8");
+            const tsconfig = JSON.parse(raw);
+            if (!tsconfig.compilerOptions?.strict) {
+                tsconfig.compilerOptions = { ...tsconfig.compilerOptions, strict: true };
+                writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
+                console.log('  \x1b[32m\u2713 Enabled "strict": true in tsconfig.json\x1b[0m');
+                fixed++;
+            }
+        }
+        catch { /* can't parse tsconfig */ }
+    }
+    // 2. Run linter auto-fix
+    if (stack.linter === "biome") {
+        console.log("  \x1b[1mFormatting with Biome...\x1b[0m");
+        const { execSync } = await import("node:child_process");
+        try {
+            execSync("npx biome check --write .", { cwd, stdio: "inherit", timeout: 30_000 });
+            fixed++;
+        }
+        catch {
+            console.log("  \x1b[33mBiome had issues (some may be unfixable)\x1b[0m");
+        }
+    }
+    else if (stack.linter === "eslint") {
+        console.log("  \x1b[1mFixing with ESLint...\x1b[0m");
+        const { execSync } = await import("node:child_process");
+        try {
+            execSync("npx eslint --fix src/", { cwd, stdio: "inherit", timeout: 30_000 });
+            fixed++;
+        }
+        catch {
+            console.log("  \x1b[33mESLint had issues (some may be unfixable)\x1b[0m");
+        }
+    }
+    // 3. AI-powered fix mode
+    if (opts.ai) {
+        console.log("");
+        console.log("  \x1b[1mScanning for AI-fixable issues...\x1b[0m");
+        const midReport = await scan(cwd, { skipTests: true });
+        const aiIssues = collectFixableIssues(midReport.checks, suggestFix, opts.checkFilter);
+        if (aiIssues.length === 0) {
+            console.log("  \x1b[2mNo fixable issues found.\x1b[0m");
+        }
+        else {
+            console.log(`  \x1b[1mAI fixing ${Math.min(aiIssues.length, 10)} issues${opts.dryRun ? " (dry run)" : ""}...\x1b[0m`);
+            console.log("");
+            await aiFixIssues(cwd, aiIssues, { dryRun: opts.dryRun || false });
+        }
+    }
+    // 4. Final scan + delta report
+    console.log("");
+    console.log("  \x1b[1mFinal scan...\x1b[0m");
+    const afterReport = await scan(cwd, { skipTests: true });
+    const delta = computeDelta(beforeReport, afterReport);
+    // Print delta summary
+    const scoreColor = delta.scoreDelta > 0 ? "32" : delta.scoreDelta < 0 ? "31" : "2";
+    const arrow = delta.scoreDelta > 0 ? "\u2191" : delta.scoreDelta < 0 ? "\u2193" : "=";
+    console.log("");
+    console.log(`  \x1b[1mScore:\x1b[0m \x1b[2m${beforeReport.grade} ${beforeReport.score}\x1b[0m \u2192 \x1b[${afterReport.score >= 75 ? "32" : afterReport.score >= 60 ? "33" : "31"}m${afterReport.grade} ${afterReport.score}\x1b[0m \x1b[${scoreColor}m(${arrow}${Math.abs(delta.scoreDelta)})\x1b[0m`);
+    if (delta.fixed.length > 0) {
+        console.log(`  \x1b[32m${delta.fixed.length} issues fixed\x1b[0m`);
+        // Show top fixed by check
+        const byCheck = new Map();
+        for (const f of delta.fixed)
+            byCheck.set(f.check, (byCheck.get(f.check) || 0) + 1);
+        for (const [check, count] of [...byCheck.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5)) {
+            console.log(`    \x1b[32m\u2713\x1b[0m ${check}: ${count} fixed`);
+        }
+    }
+    if (delta.introduced.length > 0) {
+        console.log(`  \x1b[31m${delta.introduced.length} new issues\x1b[0m`);
+    }
+    // Show per-check score changes
+    const changed = delta.checks.filter((c) => c.delta !== 0).sort((a, b) => b.delta - a.delta);
+    if (changed.length > 0) {
+        console.log("");
+        for (const c of changed.slice(0, 5)) {
+            const color = c.delta > 0 ? "32" : "31";
+            console.log(`  \x1b[${color}m${c.delta > 0 ? "+" : ""}${c.delta}\x1b[0m ${c.name} (${c.before} \u2192 ${c.after})`);
+        }
+    }
+    // Save delta markdown
+    if (!opts.dryRun) {
+        const outDir = join(cwd, ".vibe-check");
+        mkdirSync(outDir, { recursive: true });
+        const md = formatDeltaMarkdown(delta);
+        writeFileSync(join(outDir, "delta.md"), md);
+        console.log("");
+        console.log(`  \x1b[2mDelta report: .vibe-check/delta.md\x1b[0m`);
+    }
+    else {
+        console.log("");
+        console.log("  \x1b[2mDry run — no files modified. Remove --dry-run to apply.\x1b[0m");
+    }
+    // Non-AI mode: show remaining fix suggestions
+    if (!opts.ai) {
+        const fixable = [];
+        for (const c of afterReport.checks) {
+            for (const iss of c.issues) {
+                if (!iss.file || typeof iss.file !== "string" || !iss.line)
+                    continue;
+                const fix = suggestFix(c.name, iss.rule || "", iss.message);
+                if (fix)
+                    fixable.push({ check: c.name, file: iss.file, line: iss.line, message: iss.message, fix });
+            }
+        }
+        const top = fixable.slice(0, 5);
+        if (top.length > 0) {
+            console.log("");
+            console.log(`  \x1b[1mRemaining fixes available:\x1b[0m \x1b[2mrun \x1b[0m\x1b[1mvcqa fix --ai\x1b[0m`);
+            for (const f of top) {
+                console.log(`    \x1b[2m${f.file}:${f.line}\x1b[0m ${f.fix}`);
+            }
+            if (fixable.length > 5)
+                console.log(`    \x1b[2m+${fixable.length - 5} more\x1b[0m`);
+        }
+    }
+    console.log("");
+}

package/dist/commands/init.d.ts

@@ -0,0 +1,2 @@
+/** vcqa init — set up CI workflow + recommended configs. */
+export declare function runInit(cwd: string): Promise<void>;

package/dist/commands/init.js

@@ -0,0 +1,96 @@
+/** vcqa init — set up CI workflow + recommended configs. */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { detectStack } from "../detect.js";
+import { validateCwd } from "./shared.js";
+export async function runInit(cwd) {
+    console.log("");
+    console.log(`  \x1b[1m\x1b[38;5;141mvcqa init\x1b[0m`);
+    console.log(`  \x1b[2m${cwd}\x1b[0m`);
+    console.log("");
+    validateCwd(cwd);
+    const stack = detectStack(cwd);
+    let created = 0;
+    // 1. GitHub Actions workflow
+    const workflowDir = join(cwd, ".github", "workflows");
+    const workflowPath = join(workflowDir, "vibecodeqa.yml");
+    if (!existsSync(workflowPath)) {
+        try {
+            mkdirSync(workflowDir, { recursive: true });
+            writeFileSync(workflowPath, `name: VibeCode QA
+on: [pull_request]
+permissions: { contents: read }
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npx @vibecodeqa/cli --ci --fail-under 70 --sarif --badge
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: .vibe-check/report.sarif
+`);
+            console.log(`  \x1b[32m+\x1b[0m .github/workflows/vibecodeqa.yml`);
+            created++;
+        }
+        catch {
+            console.log(`  \x1b[31m!\x1b[0m .github/workflows/vibecodeqa.yml (write failed — check permissions)`);
+        }
+    }
+    else {
+        console.log(`  \x1b[2m=\x1b[0m .github/workflows/vibecodeqa.yml (exists)`);
+    }
+    // 2. Biome config (if biome is a dep but no config exists)
+    if ((stack.linter === "biome" || existsSync(join(cwd, "node_modules", "@biomejs", "biome"))) &&
+        !existsSync(join(cwd, "biome.json")) &&
+        !existsSync(join(cwd, "biome.jsonc"))) {
+        writeFileSync(join(cwd, "biome.json"), JSON.stringify({
+            $schema: "https://biomejs.dev/schemas/2.0.0/schema.json",
+            formatter: { indentStyle: "tab", lineWidth: 120 },
+            linter: { enabled: true, rules: { recommended: true } },
+            organizeImports: { enabled: true },
+        }, null, "\t") + "\n");
+        console.log(`  \x1b[32m+\x1b[0m biome.json`);
+        created++;
+    }
+    // 3. Create .vcqa.json if not present
+    const vcqaConfigPath = join(cwd, ".vcqa.json");
+    if (!existsSync(vcqaConfigPath)) {
+        const { CHECK_META } = await import("../check-meta.js");
+        const checksConfig = {};
+        for (const name of Object.keys(CHECK_META)) {
+            checksConfig[name] = {};
+        }
+        const config = {
+            _comment: "vcqa config — docs: https://vibecodeqa.online/skills",
+            checks: checksConfig,
+            _checks_help: "Set { \"enabled\": false } to disable. Add \"ignore\": [\"generated/**\"] to skip files per-check.",
+            ignore: [],
+            _ignore_help: "Global file patterns to skip: [\"vendor/**\", \"*.generated.ts\", \"proto/**\"]",
+            failUnder: 60,
+            _failUnder_help: "Exit with code 1 if score below this. Overridden by --fail-under flag.",
+        };
+        writeFileSync(vcqaConfigPath, JSON.stringify(config, null, 2) + "\n");
+        console.log(`  \x1b[32m+\x1b[0m .vcqa.json`);
+        created++;
+    }
+    // 4. Add .vibe-check to .gitignore
+    const gitignorePath = join(cwd, ".gitignore");
+    if (existsSync(gitignorePath)) {
+        const content = readFileSync(gitignorePath, "utf-8");
+        if (!content.includes(".vibe-check")) {
+            writeFileSync(gitignorePath, content.trimEnd() + "\n.vibe-check/\n");
+            console.log(`  \x1b[32m+\x1b[0m .gitignore (added .vibe-check/)`);
+            created++;
+        }
+    }
+    console.log("");
+    if (created > 0) {
+        console.log(`  \x1b[32mCreated ${created} file(s).\x1b[0m Run \x1b[1mnpx @vibecodeqa/cli\x1b[0m to scan.`);
+    }
+    else {
+        console.log(`  \x1b[2mAlready set up. Run npx @vibecodeqa/cli to scan.\x1b[0m`);
+    }
+    console.log("");
+}

package/dist/commands/shared.d.ts

@@ -0,0 +1,4 @@
+/** Shared utilities for CLI commands. */
+export declare function validateCwd(cwd: string): void;
+/** Map common issue rules to actionable fix suggestions. */
+export declare function suggestFix(check: string, rule: string, message: string): string | null;

package/dist/commands/shared.js

@@ -0,0 +1,80 @@
+/** Shared utilities for CLI commands. */
+import { existsSync, statSync } from "node:fs";
+export function validateCwd(cwd) {
+    if (!existsSync(cwd)) {
+        console.error(`  \x1b[31mError: path does not exist: ${cwd}\x1b[0m`);
+        process.exit(1);
+    }
+    try {
+        if (!statSync(cwd).isDirectory()) {
+            console.error(`  \x1b[31mError: not a directory: ${cwd}\x1b[0m`);
+            process.exit(1);
+        }
+    }
+    catch {
+        console.error(`  \x1b[31mError: cannot access: ${cwd}\x1b[0m`);
+        process.exit(1);
+    }
+}
+/** Map common issue rules to actionable fix suggestions. */
+export function suggestFix(check, rule, message) {
+    if (rule === "empty-catch")
+        return "Add error logging: catch(e) { console.error(e); }";
+    if (rule === "throw-string")
+        return 'Replace throw "msg" with throw new Error("msg")';
+    if (rule === "swallowed-promise")
+        return "Add logging: .catch((e) => { console.error(e); })";
+    if (rule === "floating-promise")
+        return "Add await or .catch() to handle the promise";
+    if (rule === "unsafe-json-parse")
+        return "Wrap in try-catch: try { JSON.parse(x) } catch { /* handle */ }";
+    if (rule === "no-error-boundary")
+        return "Add <ErrorBoundary> wrapper in your React app root";
+    if (rule === "img-alt")
+        return 'Add alt attribute: <img alt="description" ...>';
+    if (rule === "click-events")
+        return 'Add role="button" and onKeyDown handler';
+    if (rule === "vue-v-for-key")
+        return 'Add :key="item.id" to the v-for element';
+    if (rule === "missing-key")
+        return "Add key={item.id} to the JSX element in .map()";
+    if (rule === "index-key")
+        return "Use a stable unique ID instead of array index for key";
+    if (rule === "conditional-hook")
+        return "Move the hook call before any conditional (if/switch)";
+    if (rule === "no-tests")
+        return "Create a test file: src/__tests__/example.test.ts";
+    if (rule === "no-readme")
+        return "Create README.md with: project description, install, usage";
+    if (rule === "no-changelog")
+        return "Create CHANGELOG.md or use changesets: npx changeset init";
+    if (rule === "env-not-ignored")
+        return "Add .env to .gitignore";
+    if (rule === "secret-detected")
+        return "Move to environment variable, rotate the exposed secret";
+    if (rule === "no-ci")
+        return "Run: npx @vibecodeqa/cli init";
+    if (rule === "missing-lockfile")
+        return "Run: pnpm install (or npm install) to generate lockfile";
+    if (rule === "missing-file" && message.includes("LICENSE"))
+        return "Add LICENSE file: https://choosealicense.com/";
+    if (rule === "long-function")
+        return "Extract logic into smaller helper functions";
+    if (rule === "high-complexity")
+        return "Reduce nesting: use early returns, extract conditions";
+    if (rule === "duplicate-code")
+        return "Extract shared logic into a helper function";
+    if (rule === "circular-dep")
+        return "Extract shared types to a separate file both modules import";
+    if (rule === "god-module")
+        return "Split into focused interfaces — one responsibility per module";
+    if (rule === "process-exit")
+        return "Replace process.exit() with throw new Error()";
+    if (check === "security" && message.includes("innerHTML"))
+        return "Use textContent or DOM APIs instead";
+    if (check === "security" && message.includes("ev" + "al"))
+        return `Remove ${"ev" + "al"}() — use a safer alternative`;
+    if (check === "security" && message.includes("v-html"))
+        return 'Sanitize with DOMPurify: v-html="DOMPurify.sanitize(input)"';
+    return null;
+}

package/dist/core.d.ts

@@ -22,6 +22,7 @@ export interface ScanOptions {
 export declare function scan(cwd: string, options?: ScanOptions): Promise<VibeReport>;
 export { CHECK_META, getCheckMeta, type CheckMeta };
 export { computeScore } from "./score.js";
+export { computeDelta, formatDeltaMarkdown, type ScanDelta } from "./delta.js";
 export { loadConfig, type VcqaConfig } from "./config.js";
 export { detectStack, detectWorkspace } from "./detect.js";
 export { gradeFromScore } from "./types.js";

package/dist/core.js

@@ -23,7 +23,11 @@ import { runContainerHealth } from "./runners/container-health.js";
 import { runConfusion } from "./runners/confusion.js";
 import { runContext } from "./runners/context.js";
 import { runDependencies } from "./runners/dependencies.js";
+import { runDesignConsistency } from "./runners/design-consistency.js";
 import { runEnvValidation } from "./runners/env-validation.js";
+import { runFrontendHealth } from "./runners/frontend-health.js";
+import { runHtmlQuality } from "./runners/html-quality.js";
+import { runFileCohesion } from "./runners/file-cohesion.js";
 import { runGitHygiene } from "./runners/git-hygiene.js";
 import { runDocCoherence } from "./runners/doc-coherence.js";
 import { runDocs } from "./runners/docs.js";
@@ -32,6 +36,7 @@ import { runErrorHandling } from "./runners/error-handling.js";
 import { runLint } from "./runners/lint.js";
 import { runMemorySafety } from "./runners/memory-safety.js";
 import { runPerformance } from "./runners/performance.js";
+import { runStyling } from "./runners/styling.js";
 import { runReact } from "./runners/react.js";
 import { runSecrets } from "./runners/secrets.js";
 import { runSecurity } from "./runners/security.js";
@@ -61,7 +66,7 @@ export async function scan(cwd, options = {}) {
         { name: "lint", fn: () => runLint(resolvedCwd, stack, workspace) },
         { name: "types", fn: () => runTypeCheck(resolvedCwd, isDart, workspace) },
         { name: "type-safety", fn: () => runTypeSafety(resolvedCwd, isDart) },
-        { name: "standards", fn: () => runStandards(resolvedCwd, stack) },
+        { name: "standards", fn: () => runStandards(resolvedCwd, stack, workspace) },
         { name: "complexity", fn: () => runComplexity(resolvedCwd) },
         { name: "duplication", fn: () => runDuplication(resolvedCwd) },
         { name: "error-handling", fn: () => runErrorHandling(resolvedCwd, stack) },
@@ -84,8 +89,13 @@ export async function scan(cwd, options = {}) {
         { name: "doc-coherence", fn: () => runDocCoherence(resolvedCwd) },
         { name: "code-coherence", fn: () => runCodeCoherence(resolvedCwd) },
         { name: "comment-staleness", fn: () => runCommentStaleness(resolvedCwd) },
+        { name: "html-quality", fn: () => runHtmlQuality(resolvedCwd) },
+        { name: "frontend-health", fn: () => runFrontendHealth(resolvedCwd) },
+        { name: "styling", fn: () => runStyling(resolvedCwd) },
         { name: "dead-patterns", fn: () => runDeadPatterns(resolvedCwd) },
         { name: "test-audit", fn: () => runTestAudit(resolvedCwd) },
+        { name: "file-cohesion", fn: () => runFileCohesion(resolvedCwd) },
+        { name: "design-consistency", fn: () => runDesignConsistency(resolvedCwd) },
     ];
     // Filter checks if specified
     const checkFilter = options.checks ? new Set(options.checks) : null;
@@ -166,6 +176,7 @@ export async function scan(cwd, options = {}) {
 // ── Re-exports ──
 export { CHECK_META, getCheckMeta };
 export { computeScore } from "./score.js";
+export { computeDelta, formatDeltaMarkdown } from "./delta.js";
 export { loadConfig } from "./config.js";
 export { detectStack, detectWorkspace } from "./detect.js";
 export { gradeFromScore } from "./types.js";

package/dist/delta.d.ts

@@ -0,0 +1,45 @@
+/** Delta report — structured diff between two scans.
+ *
+ * Used by `vcqa fix` to show before/after, and by the Actions page
+ * to display "what changed since last scan."
+ */
+import type { Issue, VibeReport } from "./types.js";
+export interface DeltaIssue {
+    check: string;
+    severity: Issue["severity"];
+    message: string;
+    file?: string;
+    line?: number;
+    rule?: string;
+}
+export interface CheckDelta {
+    name: string;
+    label: string;
+    before: number;
+    after: number;
+    delta: number;
+    fixed: DeltaIssue[];
+    introduced: DeltaIssue[];
+}
+export interface ScanDelta {
+    before: {
+        score: number;
+        grade: string;
+        timestamp: string;
+        issueCount: number;
+    };
+    after: {
+        score: number;
+        grade: string;
+        timestamp: string;
+        issueCount: number;
+    };
+    scoreDelta: number;
+    checks: CheckDelta[];
+    fixed: DeltaIssue[];
+    introduced: DeltaIssue[];
+}
+/** Compute a structured delta between two scan reports. */
+export declare function computeDelta(before: VibeReport, after: VibeReport): ScanDelta;
+/** Format a delta as a markdown report. */
+export declare function formatDeltaMarkdown(delta: ScanDelta): string;

package/dist/delta.js

@@ -0,0 +1,158 @@
+/** Delta report — structured diff between two scans.
+ *
+ * Used by `vcqa fix` to show before/after, and by the Actions page
+ * to display "what changed since last scan."
+ */
+/** Fingerprint an issue for stable matching (ignores line numbers which shift after edits). */
+function issueKey(check, iss) {
+    const file = typeof iss.file === "string" ? iss.file.split(":")[0] : "";
+    return `${check}|${iss.rule || ""}|${file}|${iss.message}`;
+}
+/** Compute a structured delta between two scan reports. */
+export function computeDelta(before, after) {
+    const beforeIssueCount = before.checks.reduce((s, c) => s + c.issues.length, 0);
+    const afterIssueCount = after.checks.reduce((s, c) => s + c.issues.length, 0);
+    const checks = [];
+    const allFixed = [];
+    const allIntroduced = [];
+    for (const afterCheck of after.checks) {
+        const beforeCheck = before.checks.find((c) => c.name === afterCheck.name);
+        const beforeScore = beforeCheck?.score ?? 0;
+        // Build multiset of issue keys for before and after
+        const beforeKeys = new Map();
+        const afterKeys = new Map();
+        if (beforeCheck) {
+            for (const iss of beforeCheck.issues) {
+                const key = issueKey(afterCheck.name, iss);
+                const entry = beforeKeys.get(key);
+                if (entry)
+                    entry.count++;
+                else
+                    beforeKeys.set(key, { count: 1, issue: iss });
+            }
+        }
+        for (const iss of afterCheck.issues) {
+            const key = issueKey(afterCheck.name, iss);
+            const entry = afterKeys.get(key);
+            if (entry)
+                entry.count++;
+            else
+                afterKeys.set(key, { count: 1, issue: iss });
+        }
+        const fixed = [];
+        const introduced = [];
+        // Fixed: in before but not in after (or count decreased)
+        for (const [key, bEntry] of beforeKeys) {
+            const aEntry = afterKeys.get(key);
+            const aCount = aEntry?.count ?? 0;
+            const diff = bEntry.count - aCount;
+            for (let i = 0; i < diff; i++) {
+                const di = {
+                    check: afterCheck.name,
+                    severity: bEntry.issue.severity,
+                    message: bEntry.issue.message,
+                    file: typeof bEntry.issue.file === "string" ? bEntry.issue.file : undefined,
+                    line: bEntry.issue.line,
+                    rule: bEntry.issue.rule,
+                };
+                fixed.push(di);
+                allFixed.push(di);
+            }
+        }
+        // Introduced: in after but not in before (or count increased)
+        for (const [key, aEntry] of afterKeys) {
+            const bEntry = beforeKeys.get(key);
+            const bCount = bEntry?.count ?? 0;
+            const diff = aEntry.count - bCount;
+            for (let i = 0; i < diff; i++) {
+                const di = {
+                    check: afterCheck.name,
+                    severity: aEntry.issue.severity,
+                    message: aEntry.issue.message,
+                    file: typeof aEntry.issue.file === "string" ? aEntry.issue.file : undefined,
+                    line: aEntry.issue.line,
+                    rule: aEntry.issue.rule,
+                };
+                introduced.push(di);
+                allIntroduced.push(di);
+            }
+        }
+        checks.push({
+            name: afterCheck.name,
+            label: afterCheck.name,
+            before: beforeScore,
+            after: afterCheck.score,
+            delta: afterCheck.score - beforeScore,
+            fixed,
+            introduced,
+        });
+    }
+    return {
+        before: { score: before.score, grade: before.grade, timestamp: before.timestamp, issueCount: beforeIssueCount },
+        after: { score: after.score, grade: after.grade, timestamp: after.timestamp, issueCount: afterIssueCount },
+        scoreDelta: after.score - before.score,
+        checks: checks.filter((c) => c.delta !== 0 || c.fixed.length > 0 || c.introduced.length > 0),
+        fixed: allFixed,
+        introduced: allIntroduced,
+    };
+}
+/** Format a delta as a markdown report. */
+export function formatDeltaMarkdown(delta) {
+    const arrow = delta.scoreDelta > 0 ? "+" : "";
+    const emoji = delta.scoreDelta > 0 ? "improvement" : delta.scoreDelta < 0 ? "regression" : "no change";
+    let md = `# VibeCode QA — Delta Report\n\n`;
+    md += `| | Before | After | Delta |\n|---|---|---|---|\n`;
+    md += `| **Score** | ${delta.before.grade} ${delta.before.score} | ${delta.after.grade} ${delta.after.score} | ${arrow}${delta.scoreDelta} (${emoji}) |\n`;
+    md += `| **Issues** | ${delta.before.issueCount} | ${delta.after.issueCount} | ${delta.fixed.length} fixed, ${delta.introduced.length} new |\n\n`;
+    // Per-check changes
+    const changed = delta.checks.filter((c) => c.delta !== 0);
+    if (changed.length > 0) {
+        md += `## Check Changes\n\n`;
+        md += `| Check | Before | After | Delta |\n|---|---|---|---|\n`;
+        for (const c of changed.sort((a, b) => b.delta - a.delta)) {
+            const a = c.delta > 0 ? "+" : "";
+            md += `| ${c.name} | ${c.before} | ${c.after} | ${a}${c.delta} |\n`;
+        }
+        md += "\n";
+    }
+    // Fixed issues
+    if (delta.fixed.length > 0) {
+        md += `## Fixed (${delta.fixed.length})\n\n`;
+        // Group by check
+        const byCheck = new Map();
+        for (const f of delta.fixed) {
+            const arr = byCheck.get(f.check) || [];
+            arr.push(f);
+            byCheck.set(f.check, arr);
+        }
+        for (const [check, issues] of byCheck) {
+            md += `### ${check} (${issues.length} fixed)\n`;
+            for (const iss of issues.slice(0, 10)) {
+                md += `- ${iss.file ? `\`${iss.file}\`` : ""} ${iss.message}\n`;
+            }
+            if (issues.length > 10)
+                md += `- ...and ${issues.length - 10} more\n`;
+            md += "\n";
+        }
+    }
+    // New issues
+    if (delta.introduced.length > 0) {
+        md += `## New Issues (${delta.introduced.length})\n\n`;
+        const byCheck = new Map();
+        for (const f of delta.introduced) {
+            const arr = byCheck.get(f.check) || [];
+            arr.push(f);
+            byCheck.set(f.check, arr);
+        }
+        for (const [check, issues] of byCheck) {
+            md += `### ${check} (${issues.length} new)\n`;
+            for (const iss of issues.slice(0, 10)) {
+                md += `- ${iss.file ? `\`${iss.file}\`` : ""} ${iss.message}\n`;
+            }
+            if (issues.length > 10)
+                md += `- ...and ${issues.length - 10} more\n`;
+            md += "\n";
+        }
+    }
+    return md;
+}