@vertaaux/cli 0.2.2 → 0.3.0

package/dist/commands/drift.js

@@ -0,0 +1,309 @@
+/**
+ * Drift detection command for VertaaUX CLI.
+ *
+ * Compares current audit scores against a baseline and reports
+ * per-category regressions with delta magnitudes. Used in local
+ * workflows and CI pipelines to detect score regressions before merging.
+ *
+ * Implements DRIFT-01: CLI drift check command.
+ */
+import fs from "fs";
+import path from "path";
+import chalk from "chalk";
+import { computeDrift, DEFAULT_DRIFT_CONFIG, isPolicyV2, } from "@vertaaux/quality-control";
+import { loadBaseline } from "../baseline/manager.js";
+import { ExitCode } from "../utils/exit-codes.js";
+import { writeJsonOutput, writeOutput } from "../output/envelope.js";
+import { resolveCommandFormat } from "../output/formats.js";
+import { loadPolicy } from "../policy/index.js";
+/**
+ * Extract numeric scores from an audit result object.
+ *
+ * Audit results store scores as Record<string, unknown>; this extracts
+ * only the numeric entries.
+ */
+function extractNumericScores(scores) {
+    if (!scores)
+        return {};
+    const result = {};
+    for (const [key, value] of Object.entries(scores)) {
+        if (typeof value === "number" && Number.isFinite(value)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Format a signed delta value for display.
+ */
+function formatDelta(delta) {
+    if (delta > 0)
+        return `+${delta}`;
+    if (delta < 0)
+        return `${delta}`;
+    return "0";
+}
+/**
+ * Pad a string to the right to a given width.
+ */
+function padRight(str, width) {
+    return str.length >= width ? str : str + " ".repeat(width - str.length);
+}
+/**
+ * Pad a string to the left to a given width.
+ */
+function padLeft(str, width) {
+    return str.length >= width ? str : " ".repeat(width - str.length) + str;
+}
+/**
+ * Build drift config from policy file if available.
+ *
+ * If the policy is v2 and has a delta config, extracts max_regression
+ * and per_analyzer settings. Otherwise falls back to DEFAULT_DRIFT_CONFIG.
+ */
+function buildDriftConfigFromPolicy(policy) {
+    if (!policy)
+        return {};
+    // Only v2 policies have delta config
+    if (policy.version !== 2)
+        return {};
+    const v2 = policy;
+    if (!v2.delta)
+        return {};
+    const config = {};
+    if (v2.delta.max_regression !== undefined) {
+        config.max_regression = v2.delta.max_regression;
+    }
+    if (v2.delta.per_analyzer) {
+        config.per_analyzer = v2.delta.per_analyzer;
+    }
+    return config;
+}
+/**
+ * Format the human-readable drift report.
+ */
+function formatDriftReport(result) {
+    const lines = [];
+    lines.push("");
+    lines.push(chalk.bold(`Drift Detection: ${result.url}`));
+    lines.push("");
+    // Build table data from both regressions and improvements, plus stable categories
+    const allCategories = new Set();
+    const categoryData = {};
+    for (const r of result.regressions) {
+        allCategories.add(r.category);
+        categoryData[r.category] = {
+            previous: r.previous,
+            current: r.current,
+            delta: -(r.delta), // delta in regressions is positive (previous - current), display as negative
+            status: r.exceeded ? "REGRESSION (exceeded)" : "Within tolerance",
+        };
+    }
+    for (const imp of result.improvements) {
+        allCategories.add(imp.category);
+        categoryData[imp.category] = {
+            previous: imp.previous,
+            current: imp.current,
+            delta: -(imp.delta), // delta in improvements is negative (previous - current), display as positive
+            status: "Improved",
+        };
+    }
+    // Table header
+    const catWidth = 22;
+    const numWidth = 10;
+    const deltaWidth = 8;
+    const statusWidth = 26;
+    const header = padRight("Category", catWidth) +
+        padLeft("Previous", numWidth) +
+        padLeft("Current", numWidth) +
+        padLeft("Delta", deltaWidth) +
+        "  " +
+        padRight("Status", statusWidth);
+    lines.push(chalk.dim(header));
+    lines.push(chalk.dim("-".repeat(catWidth + numWidth * 2 + deltaWidth + 2 + statusWidth)));
+    // Sort categories alphabetically
+    const sortedCategories = [...allCategories].sort();
+    for (const category of sortedCategories) {
+        const data = categoryData[category];
+        if (!data)
+            continue;
+        const deltaStr = formatDelta(data.delta);
+        let statusStr;
+        let deltaDisplay;
+        if (data.status === "REGRESSION (exceeded)") {
+            statusStr = chalk.red(data.status);
+            deltaDisplay = chalk.red(deltaStr);
+        }
+        else if (data.status === "Within tolerance") {
+            statusStr = chalk.yellow(data.status);
+            deltaDisplay = chalk.yellow(deltaStr);
+        }
+        else {
+            statusStr = chalk.green(data.status);
+            deltaDisplay = chalk.green(deltaStr);
+        }
+        const row = padRight(category, catWidth) +
+            padLeft(String(data.previous), numWidth) +
+            padLeft(String(data.current), numWidth) +
+            padLeft(deltaDisplay, deltaWidth + 10) + // Extra for ANSI codes
+            "  " +
+            statusStr;
+        lines.push(row);
+    }
+    if (sortedCategories.length === 0) {
+        lines.push(chalk.dim("  No category changes detected."));
+    }
+    lines.push("");
+    // Overall summary
+    const directionLabel = result.overall.direction === "improving"
+        ? chalk.green("Improving")
+        : result.overall.direction === "regressing"
+            ? chalk.red("Regressing")
+            : chalk.dim("Stable");
+    lines.push(`Overall: ${directionLabel} (magnitude: ${result.overall.magnitude})`);
+    // Alerts summary
+    if (result.alerts.length > 0) {
+        const criticalCount = result.alerts.filter((a) => a.severity === "critical").length;
+        const warningCount = result.alerts.filter((a) => a.severity === "warning").length;
+        const parts = [];
+        if (criticalCount > 0)
+            parts.push(chalk.red(`${criticalCount} critical`));
+        if (warningCount > 0)
+            parts.push(chalk.yellow(`${warningCount} warning`));
+        lines.push(`Alerts: ${parts.join(", ")} regression${result.alerts.length !== 1 ? "s" : ""} exceeded tolerance`);
+    }
+    else {
+        lines.push(chalk.green("Alerts: None -- all categories within tolerance"));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Register the drift command with the Commander program.
+ */
+export function registerDriftCommand(program) {
+    const drift = program
+        .command("drift")
+        .description("Drift detection and regression analysis");
+    drift
+        .command("check <url>")
+        .description("Compare current audit against baseline and report regressions")
+        .option("--baseline <path>", "Path to baseline audit results JSON")
+        .option("--input <path>", "Path to current audit results JSON (default: .vertaaux/latest-audit.json)")
+        .option("--policy <file>", "Policy file with drift thresholds (vertaa.policy.yml)")
+        .option("--format <type>", "Output format: human|json")
+        .option("--json", "Alias for --format json")
+        .action(async (url, options) => {
+        try {
+            // a. Resolve output format (--json is alias for --format json)
+            const explicitFormat = options.json ? "json" : options.format;
+            const format = resolveCommandFormat("drift", explicitFormat, false);
+            // b. Load baseline
+            let baselineData;
+            if (options.baseline) {
+                baselineData = await loadBaseline(options.baseline);
+                if (!baselineData) {
+                    process.stderr.write(chalk.red(`Error: Baseline file not found: ${options.baseline}\n`));
+                    process.exit(ExitCode.ERROR);
+                }
+            }
+            else {
+                baselineData = await loadBaseline();
+            }
+            if (!baselineData) {
+                process.stderr.write(chalk.red("Error: No baseline found. Create one first:\n"));
+                process.stderr.write("  vertaa baseline save <url>\n\n");
+                process.stderr.write("Or provide a baseline file:\n");
+                process.stderr.write("  vertaa drift check <url> --baseline path/to/baseline.json\n");
+                process.exit(ExitCode.ERROR);
+            }
+            // c. Extract previous scores from baseline
+            // BaselineFile doesn't have scores directly -- we need audit results with scores.
+            // The baseline contains issues, not scores. We need a separate source for previous scores.
+            // Look for scores in the baseline file (it may have been extended with scores field).
+            const baselineAny = baselineData;
+            const previousScores = extractNumericScores(baselineAny.scores ??
+                baselineAny.metadata?.scores);
+            if (Object.keys(previousScores).length === 0) {
+                process.stderr.write(chalk.red("Error: Baseline does not contain score data.\n"));
+                process.stderr.write("Re-save the baseline from an audit that includes scores:\n");
+                process.stderr.write("  vertaa baseline save <url>\n");
+                process.exit(ExitCode.ERROR);
+            }
+            // d. Obtain current audit scores
+            const inputPath = options.input ?? ".vertaaux/latest-audit.json";
+            const resolvedInput = path.resolve(process.cwd(), inputPath);
+            if (!fs.existsSync(resolvedInput)) {
+                if (options.input) {
+                    process.stderr.write(chalk.red(`Error: Input file not found: ${resolvedInput}\n`));
+                }
+                else {
+                    process.stderr.write(chalk.red("Error: No current audit results found.\n\n"));
+                    process.stderr.write("Run an audit first:\n");
+                    process.stderr.write("  vertaa audit <url>\n\n");
+                    process.stderr.write("Or provide results explicitly:\n");
+                    process.stderr.write("  vertaa drift check <url> --input path/to/audit-results.json\n");
+                }
+                process.exit(ExitCode.ERROR);
+            }
+            let currentAuditData;
+            try {
+                const raw = fs.readFileSync(resolvedInput, "utf-8");
+                currentAuditData = JSON.parse(raw);
+            }
+            catch (err) {
+                process.stderr.write(chalk.red(`Error: Failed to parse audit results: ${err instanceof Error ? err.message : String(err)}\n`));
+                process.exit(ExitCode.ERROR);
+                return; // TypeScript flow control
+            }
+            // e. Extract current scores
+            const currentScores = extractNumericScores(currentAuditData.scores);
+            if (Object.keys(currentScores).length === 0) {
+                process.stderr.write(chalk.red("Error: Current audit results do not contain scores.\n"));
+                process.exit(ExitCode.ERROR);
+            }
+            // f. Load policy for drift thresholds (optional)
+            let driftConfig = {};
+            try {
+                if (options.policy) {
+                    const { loadPolicyFile } = await import("../policy/index.js");
+                    const policy = await loadPolicyFile(options.policy);
+                    if (isPolicyV2(policy)) {
+                        driftConfig = buildDriftConfigFromPolicy(policy);
+                    }
+                }
+                else {
+                    const policyResult = await loadPolicy();
+                    if (policyResult.policy && isPolicyV2(policyResult.policy)) {
+                        driftConfig = buildDriftConfigFromPolicy(policyResult.policy);
+                    }
+                }
+            }
+            catch {
+                // Policy loading is optional -- continue with defaults
+            }
+            // g. Compute drift
+            const driftResult = computeDrift(url, currentScores, previousScores, {
+                ...DEFAULT_DRIFT_CONFIG,
+                ...driftConfig,
+            });
+            // h. Output results
+            if (format === "json") {
+                writeJsonOutput(driftResult, "drift");
+            }
+            else {
+                const report = formatDriftReport(driftResult);
+                writeOutput(report);
+            }
+            // i. Exit codes
+            const hasExceededRegressions = driftResult.alerts.length > 0;
+            if (hasExceededRegressions) {
+                process.exitCode = ExitCode.ISSUES_FOUND;
+            }
+        }
+        catch (error) {
+            process.stderr.write(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}\n`));
+            process.exit(ExitCode.ERROR);
+        }
+    });
+}

package/dist/commands/explain.d.ts

@@ -1,17 +1,19 @@
 /**
  * Explain command for VertaaUX CLI.
  *
- * Shows full evidence bundle for a specific finding:
- * - Description
- * - Selector
- * - WCAG reference
- * - Recommendation
- * - Related artifacts (screenshots, DOM)
+ * Two modes:
+ * 1. **AI mode** (no finding-id): Accepts full audit JSON via stdin, --file,
+ *    or --job. Calls the LLM explain endpoint to produce a 3-bullet summary
+ *    and per-issue explanations. Use --verbose for full evidence per issue.
  *
- * Supports loading issues from:
- * - Active job via --job flag
- * - Local JSON file via --file flag
- * - Recent audits from .vertaaux/recent.json
+ * 2. **Evidence mode** (with finding-id): Shows the full evidence bundle for
+ *    a specific finding (backward compatible with existing usage).
+ *
+ * Examples:
+ *   vertaa audit https://example.com --json | vertaa explain
+ *   vertaa explain --job abc123
+ *   vertaa explain --file audit.json --verbose
+ *   vertaa explain color-contrast-001 --job abc123   (legacy mode)
  */
 import { Command } from "commander";
 import type { Issue } from "../baseline/hash.js";
@@ -19,44 +21,23 @@ import type { Issue } from "../baseline/hash.js";
  * Extended issue type with additional evidence fields.
  */
 export interface EvidenceIssue extends Issue {
-    /** DOM snippet showing the issue */
     html?: string;
-    /** Element HTML snippet */
     element?: string;
-    /** Screenshot path or URL */
     screenshot?: string;
-    /** Help URL for the rule */
     helpUrl?: string;
 }
 /**
  * Format a full evidence bundle for display.
- *
- * @param issue - Issue with evidence
- * @returns Formatted string for terminal display
  */
 export declare function formatEvidenceBundle(issue: EvidenceIssue): string;
-/**
- * Format evidence as JSON.
- */
 export declare function formatEvidenceJson(issue: EvidenceIssue): string;
-/**
- * Export for reuse in fix-wizard.
- *
- * @param issue - Issue to explain
- * @returns Formatted evidence string
- */
+/** Exported for reuse in fix-wizard. */
 export declare function explainIssue(issue: EvidenceIssue): string;
-/**
- * Command options for explain.
- */
 export interface ExplainCommandOptions {
     job?: string;
     file?: string;
-    format?: "json" | "human";
+    format?: string;
     base?: string;
 }
-/**
- * Register the explain command with the Commander program.
- */
 export declare function registerExplainCommand(program: Command): void;
 //# sourceMappingURL=explain.d.ts.map

package/dist/commands/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/commands/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,oCAAoC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAyED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAyDjE;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAgB/D;AAUD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzD;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgK7D"}
+{"version":3,"file":"explain.d.ts","sourceRoot":"","sources":["../../src/commands/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAYpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAMjD;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,KAAK;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAiFD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAyCjE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAmB/D;AAED,wCAAwC;AACxC,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAEzD;AAqRD,MAAM,WAAW,qBAAqB;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA+C7D"}