@copperbox/why 1.0.0

package/dist/audit.js

@@ -0,0 +1,483 @@
+// `why audit` (DESIGN.md §5): constraints must be falsifiable, and expiry
+// must propagate downstream. The sweep covers every `active` constraint:
+// `verify.method: check` commands run in the enclosing repo directory with a
+// timeout and captured output; `method: ask` items are exported as an
+// agent-consumable questionnaire (the CLI never calls an LLM) and applied
+// back via `--answers`; overdue `review_by` dates are flagged. A failed
+// check — or an answer marking an ask no longer true — flips the constraint
+// to `status: expired` and walks `# Because of` edges backwards: every
+// `active` decision reached is reported as candidate scar tissue and gets a
+// generated `question` concept, unless an open question already links the
+// pair. That report is the tool's reason to exist.
+//
+// Nothing here asserts above its evidence: a check that cannot run (timeout,
+// spawn failure) is an error item, never an expiry, and an unanswered ask
+// stays open. Writes go through okf-mcp's updateConcept/writeConcept so
+// everything outside the touched spans survives byte-for-byte.
+import { exec } from "node:child_process";
+import { existsSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { promisify } from "node:util";
+import { extractSection, updateConcept, writeConcept } from "@copperbox/okf-mcp";
+import { isOneOf, isPlainMap } from "./bundle.js";
+import { plural } from "./dig.js";
+const execAsync = promisify(exec);
+/** An audit run that must stop cleanly (exit 1), not crash. */
+export class AuditError extends Error {
+}
+/** How long one `verify.check` command may run before it counts as an error. */
+export const DEFAULT_CHECK_TIMEOUT_MS = 30_000;
+/** Chars of captured check output kept — clipped with a marker, never silently. */
+export const CHECK_OUTPUT_LIMIT = 4_000;
+export const ASK_ANSWERS = ["still-true", "no-longer-true", "unknown"];
+// --- Questionnaire ---------------------------------------------------------
+export const EVIDENCE_PLACEHOLDER = "(replace this line with the evidence for your answer)";
+/** The agent-facing export of `method: ask` items; round-trips via `--answers`. */
+export function renderQuestionnaire(items) {
+    const lines = [
+        "# why audit questionnaire",
+        "",
+        "Active constraints verifying with `method: ask`, exported for an agent (or",
+        "human) to re-verify — `why audit` never calls an LLM itself. For each item,",
+        "investigate, set `answer:` to `still-true`, `no-longer-true`, or `unknown`,",
+        "and replace the placeholder with your evidence. Then apply the answers:",
+        "",
+        "    why audit --answers <this-file>",
+        "",
+    ];
+    if (items.length === 0) {
+        lines.push("No unanswered `method: ask` constraints — nothing to do.");
+    }
+    for (const item of items) {
+        lines.push(`## ${item.concept}`, "", item.ask, "", "answer: unknown", "", EVIDENCE_PLACEHOLDER, "");
+    }
+    return lines.join("\n").trimEnd() + "\n";
+}
+/**
+ * Parse a filled-in questionnaire: `## <concept-id>` starts an item, the first
+ * `answer:` line inside it is the verdict, and everything after that line
+ * (until the next item) is the evidence. Strict where it matters: an
+ * unrecognized answer or a `no-longer-true` without evidence is an error —
+ * the flip writes that evidence into `# Still true?`, so it cannot be empty.
+ */
+export function parseAnswers(text) {
+    const out = new Map();
+    let current;
+    let answer;
+    let evidence = [];
+    const flush = () => {
+        if (current === undefined)
+            return;
+        const value = answer ?? "unknown";
+        if (!isOneOf(ASK_ANSWERS, value)) {
+            throw new AuditError(`--answers: "${value}" is not an answer for ${current} — use ${ASK_ANSWERS.join(", ")}`);
+        }
+        const kept = evidence.join("\n").replaceAll(EVIDENCE_PLACEHOLDER, "").trim();
+        if (value === "no-longer-true" && kept === "") {
+            throw new AuditError(`--answers: ${current} is marked no-longer-true without evidence — the flip records that evidence in "# Still true?", so it cannot be empty`);
+        }
+        out.set(current, { answer: value, evidence: kept });
+    };
+    for (const line of text.split("\n")) {
+        const heading = /^##\s+(\S+)\s*$/.exec(line);
+        if (heading !== null) {
+            flush();
+            current = heading[1];
+            if (out.has(current)) {
+                throw new AuditError(`--answers: ${current} appears twice — keep one answer per constraint`);
+            }
+            answer = undefined;
+            evidence = [];
+            continue;
+        }
+        if (current === undefined)
+            continue;
+        if (answer === undefined) {
+            const m = /^answer:\s*(.*)$/.exec(line.trim());
+            if (m !== null)
+                answer = m[1].trim();
+            continue; // text between the heading and the answer line is the ask itself
+        }
+        evidence.push(line);
+    }
+    flush();
+    return out;
+}
+// --- Check execution -------------------------------------------------------
+function clipOutput(text) {
+    if (text.length <= CHECK_OUTPUT_LIMIT)
+        return text;
+    return `${text.slice(0, CHECK_OUTPUT_LIMIT)}\n[clipped: showing ${CHECK_OUTPUT_LIMIT} of ${text.length} chars]`;
+}
+/**
+ * Run one `verify.check` command, confined to the repo directory (cwd) with a
+ * timeout and captured output. Exit 0 = still true; a non-zero exit is the
+ * falsification; anything that prevents an exit code is an `error`.
+ */
+async function runCheck(concept, command, repoDir, timeoutMs) {
+    try {
+        const { stdout, stderr } = await execAsync(command, {
+            cwd: repoDir,
+            timeout: timeoutMs,
+            maxBuffer: 16 * 1024 * 1024,
+        });
+        return { concept, command, outcome: "passed", exitCode: 0, output: clipOutput((stdout + stderr).trimEnd()) };
+    }
+    catch (e) {
+        const err = e;
+        const output = clipOutput(`${err.stdout ?? ""}${err.stderr ?? ""}`.trimEnd());
+        if (err.killed === true) {
+            return { concept, command, outcome: "error", exitCode: null, output, detail: `timed out after ${timeoutMs}ms` };
+        }
+        if (typeof err.code === "number") {
+            return { concept, command, outcome: "failed", exitCode: err.code, output };
+        }
+        return { concept, command, outcome: "error", exitCode: null, output, detail: String(err.message ?? err.code) };
+    }
+}
+// --- Blast radius ----------------------------------------------------------
+/**
+ * Walk `# Because of` edges backwards from a constraint (DESIGN.md §5):
+ * concepts linking to it from a `# Because of` section exist because of it,
+ * transitively. Returns every `active` decision reached, sorted.
+ */
+export function blastRadius(bundle, constraintId) {
+    const inbound = new Map();
+    for (const concept of bundle.concepts.values()) {
+        for (const link of concept.links) {
+            if (link.section?.toLowerCase() !== "because of" || link.resolvedId === undefined)
+                continue;
+            const sources = inbound.get(link.resolvedId) ?? [];
+            sources.push(concept.id);
+            inbound.set(link.resolvedId, sources);
+        }
+    }
+    const visited = new Set([constraintId]);
+    const queue = [constraintId];
+    const decisions = [];
+    while (queue.length > 0) {
+        for (const source of inbound.get(queue.shift()) ?? []) {
+            if (visited.has(source))
+                continue;
+            visited.add(source);
+            queue.push(source);
+            const concept = bundle.concepts.get(source);
+            if (concept?.frontmatter.type === "decision" && concept.why.status === "active") {
+                decisions.push(source);
+            }
+        }
+    }
+    return decisions.sort();
+}
+/** An open question already linking both the constraint and the decision. */
+function existingQuestion(bundle, constraintId, decisionId) {
+    return [...bundle.concepts.values()].find((c) => c.frontmatter.type === "question" &&
+        c.why.status === "open" &&
+        c.links.some((l) => l.resolvedId === constraintId) &&
+        c.links.some((l) => l.resolvedId === decisionId));
+}
+// --- Writes ------------------------------------------------------------------
+function titleOf(concept) {
+    const title = concept.frontmatter.title;
+    return typeof title === "string" && title !== "" ? title : concept.id;
+}
+/**
+ * Flip one constraint: status/expired_on via the frontmatter patch, evidence
+ * appended to `# Still true?` via the section patch — the rest of the file
+ * survives byte-for-byte (okf-mcp updateConcept splices the document on disk).
+ */
+async function expireConstraint(bundle, constraint, expiredOn, evidence) {
+    const rawWhy = isPlainMap(constraint.frontmatter.why) ? constraint.frontmatter.why : {};
+    const frontmatter = { why: { ...rawWhy, status: "expired", expired_on: expiredOn } };
+    const existing = extractSection(constraint.body, "still true?");
+    if (existing !== undefined) {
+        const content = existing.content === "" ? evidence : `${existing.content}\n\n${evidence}`;
+        await updateConcept(bundle.okf, constraint.id, {
+            frontmatter,
+            section: { heading: "Still true?", content },
+        });
+        return;
+    }
+    // A constraint missing its required `# Still true?` section (lint W202)
+    // still flips — the falsification is real — and gains the section by a
+    // plain append, since the section patch has no heading to splice into.
+    await updateConcept(bundle.okf, constraint.id, { frontmatter });
+    const absolute = join(bundle.root, constraint.path);
+    const source = await readFile(absolute, "utf8");
+    const glue = source.endsWith("\n") ? "\n" : "\n\n";
+    await writeFile(absolute, `${source}${glue}# Still true?\n\n${evidence}\n`, "utf8");
+}
+/** File the "is this decision still needed?" question for one blast-radius pair. */
+async function writeQuestion(bundle, constraint, decision, expiredOn) {
+    const slug = `is-${basename(decision.path, ".md")}-still-needed`;
+    let relPath = `questions/${slug}.md`;
+    for (let n = 2; existsSync(join(bundle.root, relPath)); n++) {
+        relPath = `questions/${slug}-${n}.md`;
+    }
+    const constraintTitle = titleOf(constraint);
+    const decisionTitle = titleOf(decision);
+    const title = `Constraint "${constraintTitle}" expired — is "${decisionTitle}" still needed?`;
+    const body = [
+        `# ${title}`,
+        "",
+        `[${constraintTitle}](/${constraint.path}) expired on ${expiredOn}, but ` +
+            `[${decisionTitle}](/${decision.path}) — shaped by it via \`# Because of\` — is still \`active\`. ` +
+            "The decision's code shape may now be scar tissue: re-evaluate it, then either supersede it " +
+            "or record why it stands on its own merits.",
+        "",
+        "Filed by `why audit` (DESIGN.md §5).",
+        "",
+    ].join("\n");
+    await writeConcept(bundle.root, relPath, {
+        type: "question",
+        title,
+        description: `Generated by why audit: ${constraint.id} expired on ${expiredOn} while ${decision.id} is still active.`,
+        why: { status: "open", happened_on: expiredOn },
+    }, body, { failIfExists: true });
+    return relPath;
+}
+// --- The sweep ---------------------------------------------------------------
+function isoDate(now) {
+    return now.toISOString().slice(0, 10);
+}
+function indentBlock(text) {
+    const body = text === "" ? "(no output)" : text;
+    return body
+        .split("\n")
+        .map((line) => `    ${line}`)
+        .join("\n");
+}
+/** The evidence paragraph appended to `# Still true?` when a check fails. */
+function checkEvidence(check, expiredOn) {
+    return [
+        `**No — expired ${expiredOn}.** \`why audit\`: the verify check failed (exit ${check.exitCode}).`,
+        "",
+        indentBlock(`$ ${check.command}\n${check.output === "" ? "(no output)" : check.output}`),
+    ].join("\n");
+}
+/** The evidence paragraph appended to `# Still true?` for an answered ask. */
+function askEvidence(evidence, expiredOn) {
+    const quoted = evidence
+        .split("\n")
+        .map((line) => (line === "" ? ">" : `> ${line}`))
+        .join("\n");
+    return [
+        `**No — expired ${expiredOn}.** \`why audit --answers\`: marked no longer true.`,
+        "",
+        quoted,
+    ].join("\n");
+}
+/**
+ * The full audit: sweep, verify, flip, walk, file. Returns the report; exit
+ * semantics (1 when anything newly expired) belong to the CLI.
+ */
+export async function auditBundle(bundle, options = {}) {
+    const now = options.now ?? new Date();
+    const today = isoDate(now);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_CHECK_TIMEOUT_MS;
+    const answers = options.answers ?? new Map();
+    const repoDir = dirname(bundle.root);
+    const constraints = [...bundle.concepts.values()]
+        .filter((c) => c.frontmatter.type === "constraint")
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const active = constraints.filter((c) => c.why.status === "active");
+    const activeIds = new Set(active.map((c) => c.id));
+    // Answers must land on sweepable ask constraints — a typo or a stale
+    // questionnaire (the constraint expired since) errors loudly, never a no-op.
+    for (const id of answers.keys()) {
+        const target = bundle.concepts.get(id);
+        if (target === undefined || target.frontmatter.type !== "constraint") {
+            throw new AuditError(`--answers: ${id} is not a constraint in this bundle`);
+        }
+        if (!activeIds.has(id)) {
+            throw new AuditError(`--answers: ${id} is not an active constraint (status: ${target.why.status ?? "unset"}) — the answer no longer applies`);
+        }
+        if (target.why.verify?.method !== "ask") {
+            throw new AuditError(`--answers: ${id} does not verify with method "ask"`);
+        }
+    }
+    const checks = [];
+    const asks = [];
+    const reviewByPastDue = [];
+    const unverifiable = [];
+    const flips = [];
+    for (const constraint of active) {
+        const verify = constraint.why.verify;
+        if (verify === undefined) {
+            unverifiable.push({
+                concept: constraint.id,
+                reason: "no verify block — a constraint must be falsifiable (DESIGN.md §5)",
+            });
+            continue;
+        }
+        if (verify.method === "check") {
+            if (verify.check === undefined) {
+                unverifiable.push({ concept: constraint.id, reason: "verify.check is missing — run `why lint`" });
+                continue;
+            }
+            const result = await runCheck(constraint.id, verify.check, repoDir, timeoutMs);
+            checks.push(result);
+            if (result.outcome === "failed") {
+                flips.push({
+                    constraint,
+                    method: "check",
+                    detail: `verify check failed (exit ${result.exitCode})`,
+                    evidence: checkEvidence(result, today),
+                });
+            }
+        }
+        else if (verify.method === "ask") {
+            if (verify.ask === undefined) {
+                unverifiable.push({ concept: constraint.id, reason: "verify.ask is missing — run `why lint`" });
+                continue;
+            }
+            const entry = answers.get(constraint.id);
+            asks.push({ concept: constraint.id, ask: verify.ask, answer: entry?.answer ?? "unknown" });
+            if (entry?.answer === "no-longer-true") {
+                flips.push({
+                    constraint,
+                    method: "ask",
+                    detail: "marked no longer true via --answers",
+                    evidence: askEvidence(entry.evidence, today),
+                });
+            }
+        }
+        else {
+            const reviewBy = verify.review_by;
+            if (reviewBy === undefined) {
+                unverifiable.push({ concept: constraint.id, reason: "verify.review_by is missing — run `why lint`" });
+                continue;
+            }
+            // An unparseable date cannot be shown to lie in the future, so it counts
+            // as due — the check may not silently pass a claim it cannot evaluate.
+            if (!(Date.parse(reviewBy) > now.getTime())) {
+                reviewByPastDue.push({ concept: constraint.id, review_by: reviewBy });
+            }
+        }
+    }
+    // Flips and their blast radius. The question filing dedupes by link pair:
+    // an open question already linking both concepts makes a new one noise.
+    const expired = [];
+    const questionsWritten = [];
+    for (const flip of flips) {
+        await expireConstraint(bundle, flip.constraint, today, flip.evidence);
+        const entries = [];
+        for (const decisionId of blastRadius(bundle, flip.constraint.id)) {
+            const decision = bundle.concepts.get(decisionId);
+            const open = existingQuestion(bundle, flip.constraint.id, decisionId);
+            if (open !== undefined) {
+                entries.push({ decision: decisionId, question: open.id, written: false });
+            }
+            else {
+                const relPath = await writeQuestion(bundle, flip.constraint, decision, today);
+                questionsWritten.push(relPath);
+                entries.push({ decision: decisionId, question: relPath, written: true });
+            }
+        }
+        expired.push({
+            concept: flip.constraint.id,
+            method: flip.method,
+            expired_on: today,
+            detail: flip.detail,
+            blastRadius: entries,
+        });
+    }
+    // Constraints already expired before this run keep their candidacy visible
+    // (report-only — no re-flip, no new questions: that flagging already ran).
+    const alreadyExpired = [];
+    for (const constraint of constraints) {
+        if (constraint.why.status !== "expired")
+            continue;
+        const decisions = blastRadius(bundle, constraint.id);
+        if (decisions.length === 0)
+            continue;
+        alreadyExpired.push({ concept: constraint.id, expired_on: constraint.why.expired_on ?? null, decisions });
+    }
+    // The questionnaire exports what still needs answering; already-answered
+    // items would loop forever if re-exported.
+    let questionnaire = null;
+    if (options.questionsOut !== undefined) {
+        const unanswered = asks.filter((a) => a.answer === "unknown");
+        await writeFile(options.questionsOut, renderQuestionnaire(unanswered), "utf8");
+        questionnaire = options.questionsOut;
+    }
+    return {
+        root: bundle.root,
+        activeConstraints: active.length,
+        checks,
+        asks,
+        reviewByPastDue,
+        unverifiable,
+        expired,
+        alreadyExpired,
+        questionsWritten,
+        questionnaire,
+    };
+}
+// --- Rendering ---------------------------------------------------------------
+export function renderAuditReport(report) {
+    const lines = [];
+    lines.push(`why audit: ${plural(report.activeConstraints, "active constraint")} at ${report.root}`);
+    const swept = report.checks.length + report.asks.length + report.reviewByPastDue.length + report.unverifiable.length > 0;
+    if (swept)
+        lines.push("");
+    for (const check of report.checks) {
+        let label = check.outcome;
+        let suffix = "";
+        if (check.outcome === "failed") {
+            label = "FAILED";
+            suffix = ` (exit ${check.exitCode})`;
+        }
+        else if (check.outcome === "error") {
+            suffix = ` — ${check.detail}`;
+        }
+        lines.push(`  check     ${label.padEnd(8)} ${check.concept}  \`${check.command}\`${suffix}`);
+    }
+    for (const ask of report.asks) {
+        const note = ask.answer === "unknown"
+            ? "unanswered — export with --questions-out, apply with --answers"
+            : `answered ${ask.answer} via --answers`;
+        lines.push(`  ask       ${ask.answer.padEnd(8)} ${ask.concept}  ${note}`);
+    }
+    for (const item of report.reviewByPastDue) {
+        lines.push(`  review-by PAST DUE ${item.concept}  review_by ${item.review_by} — needs a human look`);
+    }
+    for (const item of report.unverifiable) {
+        lines.push(`  unverifiable       ${item.concept}  ${item.reason}`);
+    }
+    if (report.questionnaire !== null) {
+        const unanswered = report.asks.filter((a) => a.answer === "unknown").length;
+        lines.push("", `wrote questionnaire (${plural(unanswered, "unanswered ask")}) to ${report.questionnaire}`);
+    }
+    if (report.expired.length > 0) {
+        lines.push("", "expired this run:");
+        for (const item of report.expired) {
+            lines.push(`  ${item.concept} — expired_on ${item.expired_on} (${item.detail})`);
+            for (const entry of item.blastRadius) {
+                const action = entry.written ? `filed ${entry.question}` : `already tracked by ${entry.question}`;
+                lines.push(`    ${entry.decision} is active because of it — ${action}`);
+            }
+            if (item.blastRadius.length === 0) {
+                lines.push("    no active decisions downstream");
+            }
+        }
+    }
+    if (report.alreadyExpired.length > 0) {
+        lines.push("", "already expired (candidate scar tissue, report-only):");
+        for (const item of report.alreadyExpired) {
+            lines.push(`  ${item.concept}${item.expired_on === null ? "" : ` (expired_on ${item.expired_on})`}`);
+            for (const decision of item.decisions) {
+                lines.push(`    ${decision} is still active`);
+            }
+        }
+    }
+    lines.push("");
+    if (report.expired.length > 0) {
+        lines.push(`${plural(report.expired.length, "constraint")} expired this run — the archive learned something (exit 1)`);
+    }
+    else {
+        lines.push("nothing newly expired");
+    }
+    return lines;
+}

package/dist/blame.d.ts

@@ -0,0 +1,91 @@
+import { type AnchorIndex, type LineRange } from "./anchors.js";
+import type { Anchor, Confidence, WhyBundle } from "./bundle.js";
+export { parseLineRange } from "./anchors.js";
+export type { LineRange } from "./anchors.js";
+/** The target spec was malformed — a usage error, not an operational one. */
+export declare class BlameTargetError extends Error {
+}
+export interface BlameTarget {
+    path: string;
+    /** Absent = the whole file. */
+    lines?: LineRange;
+}
+/** Parse `<path>[:line[-line]]`; a non-numeric suffix is part of the path. */
+export declare function parseBlameTarget(spec: string): BlameTarget;
+export declare function normalizePath(path: string): string;
+export declare function formatTarget(target: BlameTarget): string;
+/** One edge endpoint or downstream note, resolved to its concept when possible. */
+export interface BlameEdge {
+    title: string;
+    id?: string;
+    type?: string;
+    status?: string;
+}
+/** Typed edges out of a story hit, grouped by relation (docs/ui-contract.md). */
+export interface BlameEdges {
+    becauseOf: BlameEdge[];
+    insteadOf: BlameEdge[];
+    supersededBy: BlameEdge[];
+}
+/** One `# Citations` entry: display label plus the link target. */
+export interface BlameCitation {
+    label: string;
+    url: string;
+}
+/** One concept in the story, fully resolved for rendering or `--json`. */
+export interface BlameBlock {
+    id: string;
+    title: string;
+    type: string;
+    status?: string;
+    happened_on?: string;
+    expired_on?: string;
+    confidence?: Confidence;
+    /** The one-line rationale as written; `renderedRationale` is the hedged form. */
+    description: string;
+    /** True when confidence sits below `corroborated` (questions never hedge). */
+    hedged: boolean;
+    /**
+     * The rationale with its mandatory hedge prefix baked in (DESIGN.md §2 made
+     * structural): renderers display this verbatim and must not re-derive
+     * hedging — a renderer that ignores `confidence` still cannot show
+     * unhedged speculation. Empty when there is no rationale to show.
+     */
+    renderedRationale: string;
+    /** Anchors of this concept that cover the target (empty on warning blocks). */
+    anchors: Anchor[];
+    edges: BlameEdges;
+    citations: BlameCitation[];
+    /** Short citation labels — the `evidence ▸` line. */
+    evidence: string[];
+    /** Expired constraints only: active decisions reachable via `# Led to`. */
+    downstream: BlameEdge[];
+}
+export interface NearbyConcept {
+    id: string;
+    title: string;
+    type: string;
+    status?: string;
+    anchor: Anchor;
+}
+/** Major version of the story payload — see docs/ui-contract.md for the policy. */
+export declare const STORY_SCHEMA_VERSION = 1;
+export interface BlameReport {
+    schemaVersion: typeof STORY_SCHEMA_VERSION;
+    target: BlameTarget;
+    /** Narrowest covering anchor span — the output header. */
+    span?: string;
+    /** Concepts anchored on the target, newest first. */
+    hits: BlameBlock[];
+    /** Expired constraints not already matched: never invisible (DESIGN.md §7). */
+    warnings: BlameBlock[];
+    /** When nothing matches: anchored concepts nearest the target's directory. */
+    nearby: NearbyConcept[];
+}
+export declare function buildBlameReport(bundle: WhyBundle, target: BlameTarget, index?: AnchorIndex): BlameReport;
+/** Status glyph vocabulary — shared with `why export ui-index` (docs/ui-contract.md). */
+export type Glyph = "●" | "⚠" | "?";
+export declare function glyphFor(type: string, status: string | undefined): Glyph;
+/** `path[:lines]` — also the span format `why anchor` and `why doctor` print. */
+export declare function anchorSpan(anchor: Pick<Anchor, "path" | "lines">): string;
+export declare function renderBlameReport(report: BlameReport): string[];