kibi-cli 0.19.0 → 2.0.0

package/dist/commands/prove.js

@@ -0,0 +1,470 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { executeIngestProof } from "../operations/proof/ingest-proof.js";
+import { PROOF_RUNS_DIR, loadProofIntegrations, resolveIntegration, } from "../proof/integrations.js";
+import { convertJUnitXml } from "../proof/producers/junit-adapter.js";
+import { convertTap } from "../proof/producers/tap-adapter.js";
+import { loadEntities } from "../public/operations/discovery-entities.js";
+import { ingestProofSpec } from "../public/operations/specs/proof.js";
+import { readWorkspaceSnapshot } from "../public/operations/workspace-snapshot.js";
+import { PROOF_RUN_VERSION, proofBindingsErrors, proofRunArtifactErrors, } from "../public/proof-protocol.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+/**
+ * Describe which paths moved when a proof snapshot refusal fires, so
+ * consumers can see what kibi thinks changed instead of diffing by hand.
+ * Snapshot-relevant changes come first (receipt-only and ignored edits do
+ * not affect the hash), and the list is capped to keep the error readable.
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function describeWorkspaceDrift(snapshot) {
+    if (!snapshot.available)
+        return " (workspace snapshot unavailable)";
+    const changes = snapshot.snapshot.changes ?? [];
+    const relevant = changes.filter((change) => change.snapshotRelevant);
+    const pool = relevant.length > 0
+        ? relevant
+        : changes.filter((change) => !change.snapshotRelevant);
+    if (pool.length === 0) {
+        return " (git reported no workspace changes; the hash drift may come from file content that git treats as unchanged)";
+    }
+    const maxPaths = 10;
+    const listed = pool
+        .slice(0, maxPaths)
+        .map((change) => `${change.status.trim() || "M"} ${change.path}`);
+    const more = pool.length - listed.length;
+    return `; changed: ${listed.join(", ")}${more > 0 ? ` (+${more} more)` : ""}`;
+}
+/**
+ * Parse a comma-separated integration selector ("a", "a,b,c") into a set of
+ * trimmed, non-empty ids. Empty selectors yield an empty set; blank items
+ * fail fast instead of silently narrowing the selection.
+ */
+// implements REQ-kibi-proof-evidence-protocol
+export function parseIntegrationSelector(value, flagName) {
+    if (value === undefined || value.trim() === "")
+        return new Set();
+    const ids = new Set();
+    for (const raw of value.split(",")) {
+        const id = raw.trim();
+        if (id === "")
+            throw new Error(`prove: ${flagName} contains an empty integration id`);
+        ids.add(id);
+    }
+    return ids;
+}
+function withId(entity) {
+    if (typeof entity.id !== "string" || entity.id === "")
+        throw new Error("prove: loaded test entity is missing an id");
+    return entity;
+}
+export function testId(test) {
+    return String(test.id);
+}
+function parseContract(test) {
+    const contract = test.proof_contract;
+    if (contract === null ||
+        typeof contract !== "object" ||
+        Array.isArray(contract))
+        return null;
+    return contract;
+}
+async function runChild(commandArgv, cwd, env) {
+    const [command, ...args] = commandArgv;
+    if (!command)
+        throw new Error("prove: integration command argv must be non-empty");
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            cwd,
+            env,
+            shell: false,
+            stdio: "inherit",
+        });
+        child.once("error", reject);
+        child.once("close", (code) => resolve(code ?? 1));
+    });
+}
+// implements REQ-kibi-proof-evidence-protocol
+export function commandEnvironment(integration, commandArgv, snapshot, workspaceRoot, testIds, outputPath) {
+    return {
+        ...process.env,
+        KIBI_PROOF_RUN: "1",
+        KIBI_PROOF_OUTPUT: outputPath,
+        KIBI_PROOF_SNAPSHOT: snapshot,
+        KIBI_PROOF_COMMAND_ARGV: JSON.stringify(commandArgv),
+        KIBI_PROOF_INTEGRATION: integration.id,
+        KIBI_PROOF_WORKSPACE: workspaceRoot,
+        KIBI_PROOF_TEST_IDS: JSON.stringify(testIds),
+    };
+}
+function collectBindings(tests) {
+    const bindings = [];
+    for (const test of tests) {
+        const raw = test.proof_bindings;
+        if (raw === undefined || raw === null)
+            continue;
+        if (!Array.isArray(raw))
+            continue;
+        const errors = proofBindingsErrors(raw);
+        if (errors.length > 0)
+            throw new Error(`prove: test ${test.id} has invalid proof_bindings: ${errors.join("; ")}`);
+        for (const entry of raw) {
+            const row = entry;
+            bindings.push({
+                symbol_id: String(row.symbol_id),
+                target: String(row.target),
+                ...(row.native_id !== undefined
+                    ? { native_id: String(row.native_id) }
+                    : {}),
+                ...(row.aliases !== undefined
+                    ? { aliases: row.aliases.map(String) }
+                    : {}),
+            });
+        }
+    }
+    return bindings;
+}
+function dedupeObligations(tests) {
+    const seen = new Set();
+    const results = [];
+    for (const test of tests) {
+        const contract = parseContract(test);
+        if (!contract)
+            continue;
+        for (const obligation of contract.required_proofs) {
+            const key = `${obligation.target}\0${obligation.symbol_id}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            results.push({
+                symbol_id: obligation.symbol_id,
+                target: obligation.target,
+                outcome: "passed",
+                binding: "aggregate_run",
+                attempts: { status: "unavailable" },
+            });
+        }
+    }
+    return results;
+}
+function markAggregateFailure(results) {
+    return results.map((result) => ({ ...result, outcome: "failed" }));
+}
+async function selectTests(context, options) {
+    // Paginated: loading every test entity with full props in one query can
+    // exceed the Prolog output buffer once receipt histories grow.
+    const loadAll = async () => {
+        const pageSize = 25;
+        const all = [];
+        for (let offset = 0;; offset += pageSize) {
+            const page = await loadEntities(context.prolog, {
+                type: "test",
+                limit: pageSize,
+                offset,
+            });
+            all.push(...page);
+            if (page.length < pageSize)
+                return all;
+        }
+    };
+    let candidates = [];
+    if (options.testId) {
+        const found = await loadEntities(context.prolog, {
+            id: options.testId,
+            type: "test",
+        });
+        candidates = found.map(withId);
+    }
+    else if (options.requirement) {
+        const requirementId = options.requirement;
+        const scenarioResult = await context.prolog?.query(`findall([S,T], (kb_relationship(specified_by, '${requirementId}', S), (kb_relationship(verified_by, S, T) ; kb_relationship(validates, T, S)), kb_entity(T, test, _)), Rows)`);
+        const rowsRaw = scenarioResult?.success
+            ? scenarioResult.bindings.Rows
+            : undefined;
+        const ids = new Set();
+        if (typeof rowsRaw === "string") {
+            for (const match of rowsRaw.matchAll(/\[['"]?([^,\]]+)['"]?,['"]?([^,\]]+)['"]?\]/g)) {
+                const test = match[2];
+                if (test)
+                    ids.add(test.trim());
+            }
+        }
+        const directResult = await context.prolog?.query(`findall(T, (kb_relationship(validates, T, '${requirementId}'), kb_entity(T, test, _)), Rows)`);
+        const directRaw = directResult?.success
+            ? directResult.bindings.Rows
+            : undefined;
+        if (typeof directRaw === "string") {
+            for (const match of directRaw.matchAll(/\[?['"]?([A-Za-z0-9_-]+)['"]?\]?/g)) {
+                const candidate = match[1];
+                if (candidate?.startsWith("TEST-"))
+                    ids.add(candidate);
+            }
+        }
+        const all = await loadAll();
+        candidates = all.filter((entity) => ids.has(String(entity.id))).map(withId);
+    }
+    else {
+        candidates = (await loadAll()).map(withId);
+    }
+    const selected = candidates.filter((entity) => parseContract(entity) !== null);
+    const includeIds = parseIntegrationSelector(options.integration, "--integration");
+    const excludeIds = parseIntegrationSelector(options.integrationExcept, "--integration-except");
+    if (includeIds.size === 0 && excludeIds.size === 0)
+        return selected;
+    const filtered = selected.filter((entity) => {
+        const contract = parseContract(entity);
+        if (!contract)
+            return false;
+        if (includeIds.size > 0 && !includeIds.has(contract.integration))
+            return false;
+        if (excludeIds.size > 0 && excludeIds.has(contract.integration))
+            return false;
+        return true;
+    });
+    if (filtered.length === 0 && includeIds.size + excludeIds.size > 0) {
+        const requested = [
+            ...(includeIds.size > 0
+                ? [`integrations: ${[...includeIds].sort().join(", ")}`]
+                : []),
+            ...(excludeIds.size > 0
+                ? [`excluding: ${[...excludeIds].sort().join(", ")}`]
+                : []),
+        ].join("; ");
+        throw new Error(`prove: no proof-bearing tests match the integration selector (${requested})`);
+    }
+    return filtered;
+}
+function summarize(result) {
+    const parts = [`passed ${result.passed}`, `failed ${result.failed}`];
+    if (result.unchanged > 0)
+        parts.push(`unchanged ${result.unchanged}`);
+    return parts.join(", ");
+}
+// implements REQ-kibi-proof-evidence-protocol
+export async function proveCommand(options, deps = {}) {
+    const workspaceRoot = options.workspaceRoot ?? process.cwd();
+    const ingestProof = deps.ingestProof ?? executeIngestProof;
+    const runtime = deps.runtime ??
+        createCliRuntime(options.workspaceRoot === undefined ? {} : { workspaceRoot });
+    const context = await runtime.open(ingestProofSpec, {
+        ...(options.workspaceRoot === undefined ? {} : { workspaceRoot }),
+    });
+    let completed = false;
+    try {
+        const integrations = loadProofIntegrations(context.workspaceRoot);
+        if (!integrations.available)
+            throw new Error(`prove: ${integrations.error}`);
+        const selected = await selectTests(context, options);
+        if (selected.length === 0) {
+            process.stdout.write(`${JSON.stringify({ proved: 0, failed: 0, message: "no proof-bearing tests selected" })}\n`);
+            completed = true;
+            return { exitCode: 0 };
+        }
+        const before = await readWorkspaceSnapshot(context);
+        if (!before.available)
+            throw new Error(`prove: ${before.error}`);
+        const snapshot = before.snapshot.hash;
+        // Packed contracts run in separate processes; one shared packed-tarball
+        // cache area per campaign snapshot replaces dozens of repeated packs and
+        // installs with a single population. The snapshot hash is the provenance
+        // key: different workspace state never sees another campaign's artifacts.
+        process.env.KIBI_E2E_PACK_CACHE_KEY ??= snapshot;
+        const groups = new Map();
+        for (const test of selected) {
+            const contract = parseContract(test);
+            if (!contract)
+                continue;
+            const list = groups.get(contract.integration) ?? [];
+            list.push(test);
+            groups.set(contract.integration, list);
+        }
+        const runsDir = path.join(context.workspaceRoot, PROOF_RUNS_DIR);
+        await mkdir(runsDir, { recursive: true });
+        const ingestResults = [];
+        const failures = [];
+        for (const [integrationId, tests] of groups) {
+            const integration = resolveIntegration(integrations.integrations, integrationId);
+            if (!integration) {
+                failures.push(`integration '${integrationId}' (required by ${tests.map((t) => t.id).join(", ")}) is not configured in .kb/proof/integrations.json`);
+                continue;
+            }
+            const commandArgv = [...integration.command];
+            const artifactPath = path.resolve(context.workspaceRoot, integration.artifact ??
+                path.join(PROOF_RUNS_DIR, `${integrationId}.json`));
+            await mkdir(path.dirname(artifactPath), { recursive: true });
+            await rm(artifactPath, { force: true });
+            const env = commandEnvironment(integration, commandArgv, snapshot, context.workspaceRoot, tests.map((test) => String(test.id)), artifactPath);
+            const startedAt = new Date().toISOString();
+            let exitCode;
+            try {
+                exitCode = await runChild(commandArgv, context.workspaceRoot, env);
+            }
+            catch (error) {
+                failures.push(`integration '${integrationId}' failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const finishedAt = new Date().toISOString();
+            let artifact;
+            try {
+                artifact = await buildArtifact({
+                    integration,
+                    commandArgv,
+                    exitCode,
+                    startedAt,
+                    finishedAt,
+                    artifactPath,
+                    snapshot,
+                    tests,
+                });
+            }
+            catch (error) {
+                failures.push(`integration '${integrationId}': ${error instanceof Error ? error.message : String(error)}`);
+                continue;
+            }
+            const artifactErrors = proofRunArtifactErrors(artifact);
+            if (artifactErrors.length > 0) {
+                failures.push(`integration '${integrationId}' produced an invalid kibi.proof-run.v1 artifact: ${artifactErrors.join("; ")}`);
+                continue;
+            }
+            await mkdir(path.dirname(artifactPath), { recursive: true });
+            await writeFile(artifactPath, `${JSON.stringify(artifact, null, 2)}\n`, "utf8");
+            const afterRun = await readWorkspaceSnapshot(context);
+            if (!afterRun.available || afterRun.snapshot.hash !== snapshot) {
+                failures.push(`integration '${integrationId}' changed the tracked workspace during proof execution; proof is bound to snapshot ${snapshot}${describeWorkspaceDrift(afterRun)}`);
+                continue;
+            }
+            const ingested = await ingestProof({
+                snapshot,
+                artifact: artifact,
+                testIds: tests.map((test) => String(test.id)),
+            }, context);
+            ingestResults.push(ingested.structuredContent);
+            const afterIngest = await readWorkspaceSnapshot(context);
+            if (!afterIngest.available || afterIngest.snapshot.hash !== snapshot) {
+                failures.push(`the tracked workspace changed while receipts were applied; re-run kibi prove${describeWorkspaceDrift(afterIngest)}`);
+            }
+        }
+        const passed = ingestResults.reduce((sum, result) => sum + result.passed, 0);
+        const failed = ingestResults.reduce((sum, result) => sum + result.failed, 0);
+        const unchanged = ingestResults.reduce((sum, result) => sum + result.unchanged, 0);
+        const summary = {
+            proved: passed,
+            failed,
+            unchanged,
+            runs: ingestResults.map((result) => ({
+                integration: result.integration,
+                summary: summarize(result),
+                results: result.results,
+            })),
+            ...(failures.length > 0 ? { failures } : {}),
+        };
+        process.stdout.write(`${JSON.stringify(summary)}\n`);
+        completed = true;
+        await runtime.afterSuccess(ingestProofSpec, context);
+        return { exitCode: failures.length > 0 || failed > 0 ? 1 : 0 };
+    }
+    finally {
+        await runtime.close(context, completed
+            ? { status: "success", result: 0 }
+            : { status: "error", error: 1 });
+    }
+}
+async function buildArtifact(input) {
+    const { integration, commandArgv, exitCode, startedAt, finishedAt, artifactPath, snapshot, tests, } = input;
+    const run = (outcome) => ({
+        outcome,
+        exit_code: exitCode,
+        started_at: startedAt,
+        finished_at: finishedAt,
+    });
+    if (integration.producer === "command") {
+        const results = dedupeObligations(tests);
+        return {
+            version: PROOF_RUN_VERSION,
+            producer: {
+                name: "kibi-command-producer",
+                ...(integration.producer_version !== undefined
+                    ? { version: integration.producer_version }
+                    : {}),
+            },
+            integration: integration.id,
+            command_argv: [...commandArgv],
+            code_snapshot: snapshot,
+            environment: {
+                os: process.platform,
+                arch: process.arch,
+                runtime: { name: "node", version: process.version },
+            },
+            run: run(exitCode === 0 ? "passed" : "failed"),
+            proof_results: exitCode === 0 ? results : markAggregateFailure(results),
+        };
+    }
+    if (integration.producer === "junit" || integration.producer === "tap") {
+        const nativePath = integration.artifact;
+        if (!nativePath)
+            throw new Error(`producer '${integration.producer}' requires an artifact path in .kb/proof/integrations.json`);
+        let native;
+        try {
+            native = await readFile(path.resolve(context_path(nativePath)), "utf8");
+        }
+        catch {
+            throw new Error(`producer '${integration.producer}' did not produce its native report at ${nativePath}`);
+        }
+        const bindings = collectBindings(tests);
+        const conversion = integration.producer === "junit"
+            ? convertJUnitXml(native, bindings)
+            : convertTap(native, bindings);
+        if (conversion.fatal) {
+            throw new Error(`producer '${integration.producer}' rejected its native report${conversion.diagnostics.length > 0 ? `: ${conversion.diagnostics.join("; ")}` : ""}`);
+        }
+        if (conversion.results.length === 0)
+            throw new Error(`producer '${integration.producer}' produced no bound proof results${conversion.diagnostics.length > 0 ? `: ${conversion.diagnostics.join("; ")}` : ""}`);
+        return {
+            version: PROOF_RUN_VERSION,
+            producer: {
+                name: `kibi-${integration.producer}-adapter`,
+                ...(integration.producer_version !== undefined
+                    ? { version: integration.producer_version }
+                    : {}),
+            },
+            integration: integration.id,
+            command_argv: [...commandArgv],
+            code_snapshot: snapshot,
+            environment: {
+                os: process.platform,
+                arch: process.arch,
+                runtime: { name: "node", version: process.version },
+            },
+            run: run(conversion.results.every((result) => result.outcome === "passed")
+                ? "passed"
+                : "failed"),
+            proof_results: conversion.results,
+            ...(conversion.diagnostics.length > 0
+                ? { diagnostics: conversion.diagnostics }
+                : {}),
+        };
+    }
+    // Self-emitting producers (playwright and custom): read the emitted
+    // kibi.proof-run.v1 artifact and enforce the process outcome.
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(artifactPath, "utf8"));
+    }
+    catch {
+        throw new Error(`producer '${integration.producer}' did not emit a readable kibi.proof-run.v1 artifact at ${artifactPath}`);
+    }
+    const artifact = parsed;
+    const runRecord = parsed.run;
+    const reportedOutcome = runRecord?.outcome;
+    if (exitCode !== 0) {
+        if (reportedOutcome === "passed") {
+            throw new Error(`producer '${integration.producer}' reported run.outcome 'passed' but the process exited with code ${exitCode}`);
+        }
+    }
+    return artifact;
+}
+function context_path(nativePath) {
+    return path.isAbsolute(nativePath)
+        ? nativePath
+        : path.join(process.cwd(), nativePath);
+}

package/dist/commands/report.d.ts

@@ -0,0 +1,24 @@
+import { type HtmlReportCoverage } from "../report/html-report.js";
+import { type ReportRepository } from "../report/repository.js";
+export type ReportOptions = Readonly<{
+    output?: string;
+    open?: boolean;
+    tag?: string;
+    limit?: string;
+}>;
+type ReportCoverage = Readonly<{
+    requirements: HtmlReportCoverage;
+    symbols: HtmlReportCoverage;
+    branch: string;
+}>;
+export type ReportCommandDeps = Readonly<{
+    loadCoverage?: (tags: readonly string[], limit: number) => Promise<ReportCoverage>;
+    openReport?: (filePath: string) => Promise<void>;
+    now?: () => Date;
+    cwd?: () => string;
+    repository?: ReportRepository;
+}>;
+export declare function openReport(filePath: string): Promise<void>;
+export declare function reportCommand(options: ReportOptions, deps?: ReportCommandDeps): Promise<string>;
+export {};
+//# sourceMappingURL=report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report.d.ts","sourceRoot":"","sources":["../../src/commands/report.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,kBAAkB,EAExB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAC;AAIjC,MAAM,MAAM,aAAa,GAAG,QAAQ,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,KAAK,cAAc,GAAG,QAAQ,CAAC;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,YAAY,CAAC,EAAE,CACb,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7B,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,gBAAgB,CAAC;CAC/B,CAAC,CAAC;AA4HH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAoBhE;AAeD,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,MAAM,CAAC,CAyEjB"}

package/dist/commands/report.js

@@ -0,0 +1,191 @@
+import { execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { coverageSpec } from "../public/operations/specs/reporting.js";
+import { KIBI_BRAND, renderKibiBadge } from "../report/brand.js";
+import { renderHtmlReport, } from "../report/html-report.js";
+import { resolveReportRepository, } from "../report/repository.js";
+import { createCliRuntime } from "../runtime/cli-runtime.js";
+import { listGitRemotes } from "./github-init.js";
+function gitCommitSha(cwd) {
+    try {
+        const sha = execFileSync("git", ["-C", cwd, "rev-parse", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        return /^[0-9a-f]{7,64}$/i.test(sha) ? sha : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function loadReportRepository(cwd, branch) {
+    const commitSha = gitCommitSha(cwd);
+    return resolveReportRepository({
+        remotes: listGitRemotes(cwd),
+        ...(commitSha ? { commitSha } : {}),
+        branch,
+    });
+}
+function parseTags(value) {
+    return (value ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean);
+}
+function parseLimit(value) {
+    const raw = (value ?? "10000").trim();
+    const limit = /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100_000) {
+        throw new Error("Report limit must be an integer between 1 and 100000");
+    }
+    return limit;
+}
+function reportTarget(root, output) {
+    const requested = output?.trim() || "kibi-report";
+    const absolute = path.resolve(root, requested);
+    return [".html", ".htm"].includes(path.extname(absolute).toLowerCase())
+        ? absolute
+        : path.join(absolute, "index.html");
+}
+async function executeCoverageInContext(context, tags, limit) {
+    const requirements = await coverageSpec.execute({
+        by: "req",
+        tags,
+        includePassing: true,
+        includeTransitive: true,
+        limit,
+        offset: 0,
+    }, context);
+    const symbols = await coverageSpec.execute({
+        by: "symbol",
+        tags,
+        includePassing: false,
+        includeTransitive: true,
+        // Only the complete summary is needed for the unowned-code metric.
+        limit: 0,
+        offset: 0,
+    }, context);
+    if (!requirements.structuredContent || !symbols.structuredContent) {
+        throw new Error("Coverage did not return structured report data");
+    }
+    return {
+        requirements: requirements.structuredContent,
+        symbols: symbols.structuredContent,
+        branch: context.branchAttachment?.gitBranch ??
+            String(requirements.structuredContent.meta?.branch ?? "unknown"),
+    };
+}
+async function loadCoverage(tags, limit) {
+    const runtime = createCliRuntime();
+    const runtimeSpec = coverageSpec;
+    const context = await runtime.open(runtimeSpec);
+    let result;
+    try {
+        result = await executeCoverageInContext(context, tags, limit);
+    }
+    catch (error) {
+        await runtime.close(context, { status: "error", error });
+        throw error;
+    }
+    await runtime.close(context, { status: "success", result });
+    return result;
+}
+async function writeAtomically(filePath, contents) {
+    const directory = path.dirname(filePath);
+    const temporaryPath = path.join(directory, `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    await mkdir(directory, { recursive: true });
+    try {
+        await writeFile(temporaryPath, contents, "utf8");
+        await rename(temporaryPath, filePath);
+    }
+    catch (error) {
+        await rm(temporaryPath, { force: true });
+        throw error;
+    }
+}
+export async function openReport(filePath) {
+    const fileUrl = pathToFileURL(filePath).href;
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [fileUrl]]
+        : process.platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", fileUrl]]
+            : ["xdg-open", [fileUrl]];
+    await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+function assertCompleteRequirementRows(coverage, limit) {
+    const total = Number(coverage.summary.total ?? 0);
+    if (Number.isFinite(total) && coverage.rows.length < total) {
+        throw new Error(`Report requires complete requirement rows, but ${coverage.rows.length} of ${total} were returned. Increase --limit above ${limit}.`);
+    }
+}
+// implements REQ-kibi-html-health-report
+export async function reportCommand(options, deps = {}) {
+    const limit = parseLimit(options.limit);
+    const tags = parseTags(options.tag);
+    const coverage = await (deps.loadCoverage ?? loadCoverage)(tags, limit);
+    assertCompleteRequirementRows(coverage.requirements, limit);
+    const now = (deps.now ?? (() => new Date()))();
+    const workspace = (deps.cwd ?? (() => process.cwd()))();
+    const html = renderHtmlReport({
+        requirements: coverage.requirements,
+        symbols: coverage.symbols,
+        branch: coverage.branch,
+        generatedAt: now,
+        repository: deps.repository ?? loadReportRepository(workspace, coverage.branch),
+    });
+    const outputPath = reportTarget(workspace, options.output);
+    const requestedOutput = options.output?.trim() || "kibi-report";
+    const outputIsHtmlFile = [".html", ".htm"].includes(path.extname(requestedOutput).toLowerCase());
+    const badgePath = outputIsHtmlFile
+        ? path.join(path.dirname(outputPath), `${path.basename(outputPath, path.extname(outputPath))}.badge.svg`)
+        : path.join(path.dirname(outputPath), "badge.svg");
+    const summary = coverage.requirements.summary;
+    const total = Number(summary.total ?? 0);
+    const notApplicable = Number(summary.proofNotApplicable ?? 0);
+    const proven = Number(summary.proofProven ?? 0);
+    const currentRequirements = Math.max(0, total - notApplicable);
+    const proofPercent = currentRequirements === 0
+        ? 0
+        : Math.round((proven / currentRequirements) * 100);
+    const hasContradiction = coverage.requirements.rows.some((row) => Array.isArray(row.proofGaps) &&
+        row.proofGaps.includes("blocking_contradiction"));
+    const snapshotStale = coverage.requirements.meta?.dirty === true ||
+        coverage.requirements.meta?.proofSnapshotDirty === true;
+    const badgeMessage = currentRequirements === 0 ? "no requirements" : `${proofPercent}% proven`;
+    const badgeColor = currentRequirements === 0
+        ? KIBI_BRAND.rail
+        : hasContradiction
+            ? KIBI_BRAND.danger
+            : snapshotStale
+                ? KIBI_BRAND.warning
+                : proofPercent === 100
+                    ? KIBI_BRAND.success
+                    : proofPercent >= 90
+                        ? KIBI_BRAND.signal
+                        : proofPercent >= 70
+                            ? KIBI_BRAND.warning
+                            : KIBI_BRAND.danger;
+    const badge = renderKibiBadge(badgeMessage, badgeColor);
+    await writeAtomically(outputPath, html);
+    await writeAtomically(badgePath, badge);
+    console.log(`Kibi report written to ${outputPath}`);
+    console.log(`Kibi badge written to ${badgePath}`);
+    if (options.open === true) {
+        await (deps.openReport ?? openReport)(outputPath);
+        console.log("Opened Kibi report in the default browser");
+    }
+    return outputPath;
+}