@qulib/core 0.8.2 → 0.10.0

package/dist/baseline/baseline.schema.d.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+/**
+ * A snapshot of a single gap found during a scan, stored in a baseline.
+ * Intentionally lighter than the full GapSchema: only the fields needed to
+ * detect meaningful drift between scans are captured.
+ */
+export declare const BaselineGapSchema: z.ZodObject<{
+    path: z.ZodString;
+    severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+    reason: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}, {
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}>;
+export type BaselineGap = z.infer<typeof BaselineGapSchema>;
+/**
+ * A persisted baseline snapshot for a given URL, saved by `qulib baseline save`.
+ */
+export declare const BaselineSnapshotSchema: z.ZodObject<{
+    /** Monotonic slug used as the on-disk filename stem: <url-slug>__<timestamp> */
+    id: z.ZodString;
+    url: z.ZodString;
+    savedAt: z.ZodString;
+    releaseConfidence: z.ZodNumber;
+    gapCount: z.ZodNumber;
+    gaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        reason: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    label: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    url: string;
+    releaseConfidence: number;
+    gaps: {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    gapCount: number;
+    savedAt: string;
+    label?: string | undefined;
+}, {
+    id: string;
+    url: string;
+    releaseConfidence: number;
+    gaps: {
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    gapCount: number;
+    savedAt: string;
+    label?: string | undefined;
+}>;
+export type BaselineSnapshot = z.infer<typeof BaselineSnapshotSchema>;
+/**
+ * A single change in gap status between two baselines.
+ */
+export declare const BaselineDeltaItemSchema: z.ZodObject<{
+    path: z.ZodString;
+    category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+    severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+    reason: z.ZodString;
+    status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+}, "strip", z.ZodTypeAny, {
+    status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}, {
+    status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+    path: string;
+    severity: "critical" | "high" | "medium" | "low";
+    reason: string;
+    category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+}>;
+export type BaselineDeltaItem = z.infer<typeof BaselineDeltaItemSchema>;
+/**
+ * The result of comparing two snapshots.
+ */
+export declare const BaselineDeltaSchema: z.ZodObject<{
+    fromId: z.ZodString;
+    toId: z.ZodString;
+    fromSavedAt: z.ZodString;
+    toSavedAt: z.ZodString;
+    fromReleaseConfidence: z.ZodNumber;
+    toReleaseConfidence: z.ZodNumber;
+    confidenceDelta: z.ZodNumber;
+    newGaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    resolvedGaps: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    severityChanges: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        category: z.ZodEnum<["untested-route", "a11y", "console-error", "broken-link", "auth-surface", "coverage", "untested-api-endpoint"]>;
+        severity: z.ZodEnum<["critical", "high", "medium", "low"]>;
+        reason: z.ZodString;
+        status: z.ZodEnum<["new", "resolved", "severity-increased", "severity-decreased"]>;
+    }, "strip", z.ZodTypeAny, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }, {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }>, "many">;
+    summary: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    summary: string;
+    fromId: string;
+    toId: string;
+    fromSavedAt: string;
+    toSavedAt: string;
+    fromReleaseConfidence: number;
+    toReleaseConfidence: number;
+    confidenceDelta: number;
+    newGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    resolvedGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    severityChanges: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+}, {
+    summary: string;
+    fromId: string;
+    toId: string;
+    fromSavedAt: string;
+    toSavedAt: string;
+    fromReleaseConfidence: number;
+    toReleaseConfidence: number;
+    confidenceDelta: number;
+    newGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    resolvedGaps: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+    severityChanges: {
+        status: "new" | "resolved" | "severity-increased" | "severity-decreased";
+        path: string;
+        severity: "critical" | "high" | "medium" | "low";
+        reason: string;
+        category: "untested-route" | "a11y" | "console-error" | "broken-link" | "auth-surface" | "coverage" | "untested-api-endpoint";
+    }[];
+}>;
+export type BaselineDelta = z.infer<typeof BaselineDeltaSchema>;
+//# sourceMappingURL=baseline.schema.d.ts.map

package/dist/baseline/baseline.schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseline.schema.d.ts","sourceRoot":"","sources":["../../src/baseline/baseline.schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;EAa5B,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,sBAAsB;IACjC,gFAAgF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQhF,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;EAMlC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAY9B,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/baseline/baseline.schema.js

@@ -0,0 +1,59 @@
+import { z } from 'zod';
+/**
+ * A snapshot of a single gap found during a scan, stored in a baseline.
+ * Intentionally lighter than the full GapSchema: only the fields needed to
+ * detect meaningful drift between scans are captured.
+ */
+export const BaselineGapSchema = z.object({
+    path: z.string(),
+    severity: z.enum(['critical', 'high', 'medium', 'low']),
+    category: z.enum([
+        'untested-route',
+        'a11y',
+        'console-error',
+        'broken-link',
+        'auth-surface',
+        'coverage',
+        'untested-api-endpoint',
+    ]),
+    reason: z.string(),
+});
+/**
+ * A persisted baseline snapshot for a given URL, saved by `qulib baseline save`.
+ */
+export const BaselineSnapshotSchema = z.object({
+    /** Monotonic slug used as the on-disk filename stem: <url-slug>__<timestamp> */
+    id: z.string(),
+    url: z.string(),
+    savedAt: z.string().datetime(),
+    releaseConfidence: z.number().min(0).max(100),
+    gapCount: z.number().int().min(0),
+    gaps: z.array(BaselineGapSchema),
+    label: z.string().optional(),
+});
+/**
+ * A single change in gap status between two baselines.
+ */
+export const BaselineDeltaItemSchema = z.object({
+    path: z.string(),
+    category: BaselineGapSchema.shape.category,
+    severity: BaselineGapSchema.shape.severity,
+    reason: z.string(),
+    status: z.enum(['new', 'resolved', 'severity-increased', 'severity-decreased']),
+});
+/**
+ * The result of comparing two snapshots.
+ */
+export const BaselineDeltaSchema = z.object({
+    fromId: z.string(),
+    toId: z.string(),
+    fromSavedAt: z.string().datetime(),
+    toSavedAt: z.string().datetime(),
+    fromReleaseConfidence: z.number().min(0).max(100),
+    toReleaseConfidence: z.number().min(0).max(100),
+    confidenceDelta: z.number(),
+    newGaps: z.array(BaselineDeltaItemSchema),
+    resolvedGaps: z.array(BaselineDeltaItemSchema),
+    severityChanges: z.array(BaselineDeltaItemSchema),
+    summary: z.string(),
+});

package/dist/cli/analyze-diff-run.d.ts

@@ -0,0 +1,77 @@
+import type { Command } from 'commander';
+import type { GapAnalysis } from '../schemas/gap-analysis.schema.js';
+import type { BaselineDeltaItem } from '../baseline/baseline.schema.js';
+/**
+ * The structured result of diffing two analyze_app outputs.
+ * Wraps `BaselineDelta` with source provenance (file labels, timestamps).
+ */
+export interface AnalyzeDiffResult {
+    /** Human label for the "before" report (path by default). */
+    fromLabel: string;
+    /** Human label for the "after" report (path by default). */
+    toLabel: string;
+    /** ISO timestamp from the "before" report's analyzedAt field. */
+    fromAnalyzedAt: string;
+    /** ISO timestamp from the "after" report's analyzedAt field. */
+    toAnalyzedAt: string;
+    /** Release confidence from the "before" report (0–100, or null). */
+    fromReleaseConfidence: number | null;
+    /** Release confidence from the "after" report (0–100, or null). */
+    toReleaseConfidence: number | null;
+    /** Numeric delta: toReleaseConfidence − fromReleaseConfidence. Null if either is null. */
+    confidenceDelta: number | null;
+    /** Direction of the confidence delta. */
+    direction: 'improved' | 'regressed' | 'unchanged' | 'unknown';
+    /** Findings present in "to" that were absent in "from" (new regressions). */
+    added: BaselineDeltaItem[];
+    /** Findings present in "from" that are absent in "to" (resolved issues). */
+    removed: BaselineDeltaItem[];
+    /** Same finding (path + category) with a changed severity between the two reports. */
+    changed: BaselineDeltaItem[];
+    /** One-line human summary. */
+    summary: string;
+}
+/**
+ * Pure function: diff two GapAnalysis objects.
+ *
+ * Does NOT read files, make network requests, or touch disk. Both inputs must
+ * already be validated GapAnalysis objects.
+ *
+ * @param from  The "before" (baseline) analysis.
+ * @param to    The "after" (current) analysis.
+ * @param opts  Optional labels for provenance metadata.
+ */
+export declare function analyzeRunDiff(from: GapAnalysis, to: GapAnalysis, opts?: {
+    fromLabel?: string;
+    toLabel?: string;
+}): AnalyzeDiffResult;
+/**
+ * Read and validate a GapAnalysis from a report.json file path.
+ * Fails loudly on a missing/malformed/foreign file rather than diffing garbage.
+ */
+export declare function loadGapAnalysisFile(filePath: string, cwd?: string): Promise<GapAnalysis>;
+export interface AnalyzeDiffOptions {
+    from: string;
+    to: string;
+    labelFrom?: string;
+    labelTo?: string;
+    json?: boolean;
+}
+/**
+ * Core of `analyze diff`, factored out for direct testing.
+ * Loads both files, validates them, diffs them, and emits the result.
+ */
+export declare function runAnalyzeDiff(options: AnalyzeDiffOptions, out?: (line: string) => void): Promise<AnalyzeDiffResult>;
+/**
+ * Render an AnalyzeDiffResult as a human-readable Markdown report.
+ *
+ * The report is structured for readability in CI logs, GitHub PR comments, and
+ * terminal output. It covers:
+ *   - Header with report labels and timestamps
+ *   - Confidence score delta with direction indicator
+ *   - Added / Removed / Changed findings as tables
+ *   - One-line summary
+ */
+export declare function formatAnalyzeDiffMarkdown(result: AnalyzeDiffResult): string;
+export declare function registerAnalyzeDiffCommand(program: Command): void;
+//# sourceMappingURL=analyze-diff-run.d.ts.map

package/dist/cli/analyze-diff-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-diff-run.d.ts","sourceRoot":"","sources":["../../src/cli/analyze-diff-run.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAGrE,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAOvF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,mEAAmE;IACnE,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,0FAA0F;IAC1F,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,yCAAyC;IACzC,SAAS,EAAE,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;IAC9D,6EAA6E;IAC7E,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,sFAAsF;IACtF,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAqCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,WAAW,EACjB,EAAE,EAAE,WAAW,EACf,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,iBAAiB,CA6CnB;AAMD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAsB,GAC1B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAMD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,kBAAkB,EAC3B,GAAG,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkC,GACxD,OAAO,CAAC,iBAAiB,CAAC,CAgB5B;AA8BD;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAgD3E;AAMD,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAiCjE"}

package/dist/cli/analyze-diff-run.js

@@ -0,0 +1,266 @@
+/**
+ * `qulib analyze diff` — structured diff between two analyze_app outputs.
+ *
+ * Produces a structured report (JSON + Markdown) that compares two GapAnalysis
+ * objects (the serialized output of `qulib analyze`): added findings, removed
+ * findings, severity changes, and a confidence score delta.
+ *
+ * The diff is a PURE function of two GapAnalysis objects — no disk state, no
+ * network, no LLM. Callers supply paths to report.json files; this module reads
+ * them, validates them, and produces the diff.
+ *
+ * Subcommand:
+ *   qulib analyze diff --from <path> --to <path>
+ *
+ * Flags:
+ *   --from <path>   Path to the baseline report.json (the "before" state).
+ *   --to <path>     Path to the current report.json (the "after" state).
+ *   --json          Emit the AnalyzeDiffResult as JSON to stdout (default: Markdown).
+ *   --label-from    Optional human label for the baseline report.
+ *   --label-to      Optional human label for the current report.
+ *
+ * Design rationale:
+ *   - Reuses the existing `BaselineDelta` shape and `compareBaselines` logic by
+ *     converting GapAnalysis objects to transient BaselineSnapshot objects.
+ *     No second format is introduced; the schema is the same.
+ *   - The result type `AnalyzeDiffResult` wraps `BaselineDelta` with the source
+ *     report metadata (analyzedAt, path labels) for full provenance.
+ *   - `analyzeRunDiff` is factored out as a pure function so it is testable and
+ *     importable without the CLI layer (follows the baseline-run.ts convention).
+ *
+ * Registered from cli/index.ts via `registerAnalyzeDiffCommand(program)` so this
+ * command never edits index.ts beyond a single additive registration line.
+ */
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { GapAnalysisSchema } from '../schemas/gap-analysis.schema.js';
+import { compareBaselines } from '../baseline/baseline.js';
+// ---------------------------------------------------------------------------
+// Pure diff function
+// ---------------------------------------------------------------------------
+/**
+ * Stable key used to match gaps between two reports.
+ * Same key as compareBaselines: path + category identifies the same problem.
+ */
+function gapKey(path, category) {
+    return `${path}|||${category}`;
+}
+/**
+ * Convert a GapAnalysis to a minimal BaselineSnapshot shape for reuse with
+ * compareBaselines. The `id` and `savedAt` fields are synthetic — we use
+ * `analyzedAt` for temporal ordering. `url` is left as an empty string since
+ * this path does not require URL-keyed baseline storage.
+ */
+function toTransientSnapshot(analysis, id) {
+    const confidence = analysis.releaseConfidence ?? 0;
+    return {
+        id,
+        url: '',
+        savedAt: analysis.analyzedAt,
+        releaseConfidence: confidence,
+        gapCount: analysis.gaps.length,
+        gaps: analysis.gaps.map((g) => ({
+            path: g.path,
+            severity: g.severity,
+            category: g.category,
+            reason: g.reason,
+        })),
+    };
+}
+/**
+ * Pure function: diff two GapAnalysis objects.
+ *
+ * Does NOT read files, make network requests, or touch disk. Both inputs must
+ * already be validated GapAnalysis objects.
+ *
+ * @param from  The "before" (baseline) analysis.
+ * @param to    The "after" (current) analysis.
+ * @param opts  Optional labels for provenance metadata.
+ */
+export function analyzeRunDiff(from, to, opts = {}) {
+    const fromLabel = opts.fromLabel ?? 'from';
+    const toLabel = opts.toLabel ?? 'to';
+    const priorSnap = toTransientSnapshot(from, 'from');
+    const currentSnap = toTransientSnapshot(to, 'to');
+    const delta = compareBaselines(priorSnap, currentSnap);
+    const fromConf = from.releaseConfidence;
+    const toConf = to.releaseConfidence;
+    const confidenceDelta = fromConf !== null && toConf !== null ? toConf - fromConf : null;
+    let direction = 'unknown';
+    if (confidenceDelta !== null) {
+        direction = confidenceDelta > 0 ? 'improved' : confidenceDelta < 0 ? 'regressed' : 'unchanged';
+    }
+    // Build a richer summary that covers the null-confidence case.
+    const confLine = fromConf !== null && toConf !== null
+        ? `Confidence ${direction} (${fromConf} → ${toConf})`
+        : 'Confidence unavailable in one or both reports';
+    const summaryParts = [
+        confLine,
+        delta.newGaps.length > 0 ? `${delta.newGaps.length} added finding(s)` : '',
+        delta.resolvedGaps.length > 0 ? `${delta.resolvedGaps.length} removed finding(s)` : '',
+        delta.severityChanges.length > 0 ? `${delta.severityChanges.length} severity change(s)` : '',
+    ].filter(Boolean);
+    return {
+        fromLabel,
+        toLabel,
+        fromAnalyzedAt: from.analyzedAt,
+        toAnalyzedAt: to.analyzedAt,
+        fromReleaseConfidence: fromConf,
+        toReleaseConfidence: toConf,
+        confidenceDelta,
+        direction,
+        added: delta.newGaps,
+        removed: delta.resolvedGaps,
+        changed: delta.severityChanges,
+        summary: summaryParts.join(', '),
+    };
+}
+// ---------------------------------------------------------------------------
+// File loader
+// ---------------------------------------------------------------------------
+/**
+ * Read and validate a GapAnalysis from a report.json file path.
+ * Fails loudly on a missing/malformed/foreign file rather than diffing garbage.
+ */
+export async function loadGapAnalysisFile(filePath, cwd = process.cwd()) {
+    const abs = resolve(cwd, filePath);
+    let raw;
+    try {
+        raw = await readFile(abs, 'utf8');
+    }
+    catch {
+        throw new Error(`analyze diff: could not read file: ${abs}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`analyze diff: file is not valid JSON: ${abs}`);
+    }
+    const result = GapAnalysisSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error(`analyze diff: file is not a valid qulib report.json (GapAnalysis): ${abs}\n` +
+            result.error.issues.map((i) => `  • ${i.path.join('.')}: ${i.message}`).join('\n'));
+    }
+    return result.data;
+}
+/**
+ * Core of `analyze diff`, factored out for direct testing.
+ * Loads both files, validates them, diffs them, and emits the result.
+ */
+export async function runAnalyzeDiff(options, out = (line) => console.log(line)) {
+    const fromAnalysis = await loadGapAnalysisFile(options.from);
+    const toAnalysis = await loadGapAnalysisFile(options.to);
+    const result = analyzeRunDiff(fromAnalysis, toAnalysis, {
+        fromLabel: options.labelFrom ?? options.from,
+        toLabel: options.labelTo ?? options.to,
+    });
+    if (options.json) {
+        out(JSON.stringify(result, null, 2));
+    }
+    else {
+        out(formatAnalyzeDiffMarkdown(result));
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+const SEVERITY_EMOJI = {
+    critical: '🔴',
+    high: '🟠',
+    medium: '🟡',
+    low: '🔵',
+};
+function severityTag(severity) {
+    return `${SEVERITY_EMOJI[severity] ?? ''} **${severity}**`.trim();
+}
+function renderDeltaTable(items) {
+    if (items.length === 0)
+        return '_none_';
+    const rows = items.map((i) => `| ${i.path} | ${i.category} | ${severityTag(i.severity)} | ${i.reason} |`);
+    return [
+        '| Path | Category | Severity | Reason |',
+        '|------|----------|----------|--------|',
+        ...rows,
+    ].join('\n');
+}
+/**
+ * Render an AnalyzeDiffResult as a human-readable Markdown report.
+ *
+ * The report is structured for readability in CI logs, GitHub PR comments, and
+ * terminal output. It covers:
+ *   - Header with report labels and timestamps
+ *   - Confidence score delta with direction indicator
+ *   - Added / Removed / Changed findings as tables
+ *   - One-line summary
+ */
+export function formatAnalyzeDiffMarkdown(result) {
+    const lines = [];
+    lines.push('## qulib analyze diff');
+    lines.push('');
+    lines.push(`| | Report |`);
+    lines.push(`|---|---|`);
+    lines.push(`| **From** | ${result.fromLabel} (${result.fromAnalyzedAt}) |`);
+    lines.push(`| **To** | ${result.toLabel} (${result.toAnalyzedAt}) |`);
+    lines.push('');
+    // Confidence delta
+    lines.push('### Release Confidence');
+    if (result.fromReleaseConfidence !== null && result.toReleaseConfidence !== null) {
+        const delta = result.confidenceDelta;
+        const arrow = delta > 0 ? '↑' : delta < 0 ? '↓' : '→';
+        const sign = delta > 0 ? '+' : '';
+        lines.push(`${result.fromReleaseConfidence}/100 ${arrow} ${result.toReleaseConfidence}/100 ` +
+            `(${sign}${delta}) — **${result.direction}**`);
+    }
+    else {
+        lines.push('_Confidence unavailable in one or both reports._');
+    }
+    lines.push('');
+    // Added findings
+    lines.push(`### Added Findings (${result.added.length})`);
+    lines.push('');
+    lines.push(renderDeltaTable(result.added));
+    lines.push('');
+    // Removed findings
+    lines.push(`### Removed Findings (${result.removed.length})`);
+    lines.push('');
+    lines.push(renderDeltaTable(result.removed));
+    lines.push('');
+    // Changed severity
+    lines.push(`### Severity Changes (${result.changed.length})`);
+    lines.push('');
+    lines.push(renderDeltaTable(result.changed));
+    lines.push('');
+    lines.push(`---`);
+    lines.push(`_${result.summary}_`);
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// CLI registration
+// ---------------------------------------------------------------------------
+export function registerAnalyzeDiffCommand(program) {
+    // Nest `diff` under the existing (or new) `analyze` group.
+    // Commander allows a subcommand under a top-level command; the analyze command
+    // already exists in index.ts as a `program.command('analyze')` — we add a peer
+    // group `analyze-diff` to avoid colliding with the top-level `analyze` action.
+    // The user-facing name is `qulib analyze-diff` to keep wiring simple.
+    program
+        .command('analyze-diff')
+        .description('Diff two analyze_app report.json outputs — surface added / removed / changed findings and confidence delta')
+        .requiredOption('--from <path>', 'Path to the baseline report.json ("before")')
+        .requiredOption('--to <path>', 'Path to the current report.json ("after")')
+        .option('--label-from <label>', 'Human label for the baseline report (default: the file path)')
+        .option('--label-to <label>', 'Human label for the current report (default: the file path)')
+        .option('--json', 'Emit the AnalyzeDiffResult as JSON to stdout (default: Markdown)', false)
+        .action(async (options) => {
+        await runAnalyzeDiff({
+            from: options.from,
+            to: options.to,
+            labelFrom: options.labelFrom,
+            labelTo: options.labelTo,
+            json: Boolean(options.json),
+        });
+    });
+}