@jevitate/cli 0.7.0 → 0.9.0

package/dist/journey-review-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey-review-store.js","sourceRoot":"","sources":["../src/journey-review-store.ts"],"names":[],"mappings":"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"}

package/dist/journey-review.d.ts

@@ -0,0 +1,54 @@
+import type { JourneyProposal } from "@jevitate/journey";
+import { type Journey, type JourneyReview, type JourneyCatalogLinks, type Finding } from "@jevitate/journey";
+import { type SafetyConfig } from "@jevitate/explore";
+/**
+ * #432: the content hash a review sheet shows and an approval binds to — `contentHash` (the same
+ * function annotation drafts are bound with) of the Journey WITHOUT its approval bookkeeping
+ * (`promoted`, `approval`, `acceptedWeak`), so promoting does not itself change what was approved.
+ */
+export declare function journeyReviewHash(journey: Journey): string;
+/** #432: the last `journey verify --mutate` verdict, as recorded beside the Journey. */
+export interface JourneyVerifyRecord {
+    readonly journeyId: string;
+    /** `journeyReviewHash` of the Journey the proof ran on. */
+    readonly contentHash: string;
+    readonly verdict: string;
+    readonly reason?: string;
+    readonly summary: Readonly<Record<string, number>>;
+    readonly at: string;
+}
+export interface JourneyReviewContext {
+    /** The site's safety config (targets.json `safety` for the Journey's origin): `deny` / `paid` / `allowControl`. */
+    readonly safety?: Pick<SafetyConfig, "deny" | "paid" | "allowControl">;
+    /** The Journey as last approved (`.approved/<id>.json`), or null when there is none. */
+    readonly approvedSnapshot?: Journey | null;
+    /** The last recorded mutation-proof verdict, or null when there is none. */
+    readonly lastVerify?: JourneyVerifyRecord | null;
+    /** #433: the Journey's catalog links and its pre-approval findings (the CLI loads the catalog). */
+    readonly catalog?: {
+        readonly links: JourneyCatalogLinks;
+        readonly findings: readonly Finding[];
+    };
+    /** #453: the pending self-heal proposal, with whether it is stale and why it cannot be accepted. */
+    readonly proposal?: {
+        readonly proposal: JourneyProposal;
+        readonly stale: boolean;
+        readonly problem?: string;
+    };
+}
+/** #432: the review sheet of one Journey — pure. */
+export declare function buildJourneyReview(journey: Journey, ctx?: JourneyReviewContext): JourneyReview;
+/** #432: the review sheet as Markdown (`journey review --markdown`). */
+export declare function renderReviewMarkdown(review: JourneyReview): string;
+/** #432: the review sheet as plain text (`journey review`, and `journey promote` in human mode). */
+export declare function renderReviewText(review: JourneyReview): string;
+/** #432: a review sheet file's content hash refused (none, or two different ones). */
+export declare class ReviewSheetError extends Error {
+    readonly code = "E_JOURNEY_REVIEW_ARGS";
+}
+/**
+ * #432: the content hash a review sheet file names — the `contentHash` of a JSON sheet
+ * (`journey review --json --out`, its envelope or the bare sheet), or the `Content hash:` line of a
+ * Markdown / text one. A sheet naming no hash, or two different ones, is refused.
+ */
+export declare function reviewSheetHash(text: string): string;

package/dist/journey-review.js

@@ -0,0 +1,538 @@
+import { contentHash } from "@jevitate/domain";
+import { describeProvenance } from "./approval-provenance.js";
+import { SECRET_PARAM_NAME_RE, describeStep, flatJourneySteps, isNoClaimExpect, isOwnTargetVisible, journeyAssertions, journeyEndState, journeyRunParams, journeyWriteSteps, lintJourney, secretParamNames, } from "@jevitate/journey";
+import { renderFindings } from "./catalog-review.js";
+import { SafetyPolicy, describeCheck } from "@jevitate/explore";
+import { navigateUrlParams, writeClassifier } from "@jevitate/recording";
+/**
+ * #432 — `jevitate journey review <id>`: one human-readable review sheet for promotion sign-off.
+ * `buildJourneyReview` is PURE (no I/O, no clock): the CLI loads what it needs (the targets.json
+ * safety config, the approved snapshot, the last mutation-proof verdict) into the context.
+ *
+ * Secrets: the sheet is built from the Journey alone, which never carries a secret parameter's value
+ * (values only arrive as `--param`). Defense in depth: a literal typed into a field whose name reads
+ * as a credential is shown «redacted», and a secret reference is listed by field and manager only.
+ */
+/** The approval bookkeeping a review hash leaves out: promoting writes them, so they cannot be part of what was reviewed. */
+const BOOKKEEPING = ["promoted", "approval", "acceptedWeak"];
+/**
+ * #432: the content hash a review sheet shows and an approval binds to — `contentHash` (the same
+ * function annotation drafts are bound with) of the Journey WITHOUT its approval bookkeeping
+ * (`promoted`, `approval`, `acceptedWeak`), so promoting does not itself change what was approved.
+ */
+export function journeyReviewHash(journey) {
+    const metadata = { ...journey.metadata };
+    for (const k of BOOKKEEPING)
+        delete metadata[k];
+    return contentHash({ metadata, recording: journey.recording });
+}
+function targetOf(step) {
+    if (step.kind === "forEach")
+        return step.items;
+    return "target" in step ? step.target : undefined;
+}
+function controlName(t) {
+    return (t.name ?? t.label ?? t.text ?? "").replace(/\s+/g, " ").trim();
+}
+function reviewTarget(t) {
+    if (t === undefined)
+        return undefined;
+    const name = controlName(t);
+    const out = { ...(t.role === undefined ? {} : { role: t.role }), ...(name === "" ? {} : { name }) };
+    return Object.keys(out).length === 0 ? undefined : out;
+}
+/** Does the field read as a credential (its name, label or test id)? Its literal value is then never shown. */
+function secretLooking(t) {
+    return [t.name, t.label, t.testId, t.text].some((s) => s !== undefined && SECRET_PARAM_NAME_RE.test(s));
+}
+function hideValue(v) {
+    return "var" in v || v.redacted ? v : { redacted: true, length: 0 };
+}
+/** The step with any credential-looking literal value hidden — what `describeStep` may show. */
+function sanitized(step) {
+    if ((step.kind === "fill" || step.kind === "select") && secretLooking(step.target))
+        return { ...step, value: hideValue(step.value) };
+    if (step.kind === "editText" && step.value !== undefined && secretLooking(step.target))
+        return { ...step, value: hideValue(step.value) };
+    return step;
+}
+function varName(v) {
+    return v !== undefined && "var" in v ? [v.var] : [];
+}
+/** The parameters (by name) a step uses, its `forEach` children included. */
+function paramsOf(step) {
+    switch (step.kind) {
+        case "navigate":
+            return navigateUrlParams(step.url);
+        case "fill":
+        case "select":
+            return varName(step.value);
+        case "editText":
+            return varName(step.value);
+        case "upload":
+            return varName(step.file);
+        case "forEach":
+            return step.steps.flatMap(paramsOf);
+        default:
+            return [];
+    }
+}
+function ownAssertion(step) {
+    if (step.kind === "assert")
+        return describeCheck({ kind: "page", assertion: step.check });
+    if (step.kind === "handback")
+        return describeCheck({ kind: "page", assertion: step.resume });
+    return "expect" in step ? describeCheck({ kind: "page", assertion: step.expect }) : undefined;
+}
+function evidenceLine(e) {
+    const change = e.before !== undefined || e.after !== undefined ? ` '${e.before ?? ""}' → '${e.after ?? ""}'` : "";
+    const where = e.file === undefined ? "" : ` (${e.file}${e.line === undefined ? "" : `:${e.line}`})`;
+    return `${e.kind}${change}${where}`;
+}
+function buildProposal(ctx, journeyId) {
+    const p = ctx.proposal;
+    return {
+        proposalId: p.proposalId,
+        baseHash: p.baseHash,
+        proposedHash: p.proposedHash,
+        createdAt: p.createdAt,
+        stale: ctx.stale,
+        ...(ctx.problem === undefined ? {} : { problem: ctx.problem }),
+        changes: { ...(p.changes.range === undefined ? {} : { range: p.changes.range }), ...(p.changes.baseSha === undefined ? {} : { baseSha: p.changes.baseSha }), ...(p.changes.headSha === undefined ? {} : { headSha: p.changes.headSha }), notes: [...p.changes.notes] },
+        steps: p.steps.map((s) => ({
+            number: s.index + 1,
+            before: describeStep(s.before),
+            after: describeStep(s.after),
+            hypothesis: s.justification.hypothesis + (s.justification.anchorNotInChange === true ? " (the new anchor is not named by any change evidence)" : ""),
+            evidence: s.justification.evidence.map(evidenceLine),
+            screenshots: [...(s.screenshots ?? [])],
+        })),
+        attempts: { total: p.attempts.length, rejected: p.attempts.filter((a) => a.result === "rejected").length },
+        acceptCommand: `jevitate journey promote ${journeyId} --proposal ${p.proposalId} --reviewed-hash ${p.proposedHash}`,
+    };
+}
+function buildSteps(journey) {
+    return flatJourneySteps(journey).map(({ index, recorded }) => {
+        const step = recorded.step;
+        const target = reviewTarget(targetOf(step));
+        const assertion = ownAssertion(step);
+        return {
+            number: index + 1,
+            kind: step.kind,
+            action: describeStep(sanitized(step)),
+            ...(target === undefined ? {} : { target }),
+            ...(recorded.objective === undefined || recorded.objective.trim() === "" ? {} : { objective: recorded.objective }),
+            ...(recorded.expectedResult === undefined || recorded.expectedResult.trim() === "" ? {} : { expectedResult: recorded.expectedResult }),
+            ...(assertion === undefined ? {} : { assertion }),
+            params: [...new Set(paramsOf(step))],
+        };
+    });
+}
+const REQUEST_LINE = /^(\S+)\s+(\S+)/;
+function buildWriteRequests(journey) {
+    const classify = writeClassifier();
+    const out = [];
+    const seen = new Set();
+    const add = (w) => {
+        const key = `${w.source}|${w.step ?? ""}|${w.method.toUpperCase()}|${w.endpoint}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push(w);
+    };
+    for (const w of journeyWriteSteps(journey)) {
+        for (const line of w.requests) {
+            const m = REQUEST_LINE.exec(line.trim());
+            if (m !== null)
+                add({ method: m[1].toUpperCase(), endpoint: m[2], source: "recorded", step: w.step });
+        }
+    }
+    flatJourneySteps(journey).forEach(({ index, recorded }) => {
+        for (const check of recorded.expectRequests ?? []) {
+            if (classify({ method: check.method, path: check.pathGlob }))
+                add({ method: check.method.toUpperCase(), endpoint: check.pathGlob, source: "expect-request", step: index + 1 });
+        }
+    });
+    for (const check of journeyEndState(journey)) {
+        if (check.kind !== "requestMade" && check.kind !== "responseStatus")
+            continue;
+        if (classify({ method: check.method, path: check.pathGlob }))
+            add({ method: check.method.toUpperCase(), endpoint: check.pathGlob, source: "end-state" });
+    }
+    return out;
+}
+/** Every click (a `forEach` child's too, under its parent's number) whose control a safety rule matches. */
+function buildRiskyControls(journey, safety) {
+    const policy = new SafetyPolicy({
+        ...(safety?.deny === undefined ? {} : { deny: safety.deny }),
+        ...(safety?.paid === undefined ? {} : { paid: safety.paid }),
+        ...(safety?.allowControl === undefined ? {} : { allowControl: safety.allowControl }),
+    });
+    const out = [];
+    const visit = (step, number) => {
+        if (step.kind === "forEach") {
+            for (const child of step.steps)
+                visit(child, number);
+            return;
+        }
+        if (step.kind !== "click")
+            return;
+        const name = controlName(step.target);
+        // A nameless control cannot be matched against a name rule: the sheet lists only named ones.
+        if (name === "")
+            return;
+        const control = { name, role: step.target.role ?? "", descriptor: step.target };
+        const role = step.target.role === undefined ? {} : { role: step.target.role };
+        const refused = policy.refuses(control);
+        if (refused !== null) {
+            out.push({ step: number, control: name, ...role, risk: refused.risk, ruleId: refused.refusal.ruleId });
+            return;
+        }
+        const waiver = policy.waiver(control);
+        if (waiver !== null)
+            out.push({ step: number, control: name, ...role, risk: policy.riskOf(control) ?? "paid", ruleId: waiver.ruleId, waivedBy: waiver.regex });
+    };
+    for (const { index, recorded } of flatJourneySteps(journey))
+        visit(recorded.step, index + 1);
+    return out;
+}
+function originOf(url, base) {
+    try {
+        const u = new URL(url, base);
+        return u.protocol === "http:" || u.protocol === "https:" ? u.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+function buildOrigins(journey) {
+    const site = journey.recording.site;
+    const origins = new Set();
+    const add = (url) => {
+        const o = originOf(url, site);
+        if (o !== null)
+            origins.add(o);
+    };
+    add(site);
+    for (const page of journey.recording.pages) {
+        add(page.url);
+        for (const { step, delta } of page.steps) {
+            if (step.kind === "navigate")
+                add(step.url);
+            for (const line of delta?.requests ?? []) {
+                const m = REQUEST_LINE.exec(line.trim());
+                if (m !== null && /^https?:\/\//i.test(m[2]))
+                    add(m[2]);
+            }
+        }
+    }
+    return [...origins];
+}
+function buildChange(journey, hash, snapshot) {
+    const approval = journey.metadata.approval;
+    if (snapshot === null || snapshot === undefined) {
+        if (approval !== undefined) {
+            return { kind: "snapshot-missing", approvedHash: approval.contentHash, approvedAt: approval.at, changed: approval.contentHash !== hash };
+        }
+        return journey.metadata.promoted ? { kind: "no-record" } : { kind: "first-approval" };
+    }
+    const approvedHash = journeyReviewHash(snapshot);
+    const approvedAt = approval?.at ?? snapshot.metadata.approval?.at;
+    return {
+        kind: "diff",
+        approvedHash,
+        ...(approvedAt === undefined ? {} : { approvedAt }),
+        changed: approvedHash !== hash,
+        steps: multisetDiff(stepLines(snapshot), stepLines(journey)),
+        assertions: multisetDiff(assertionLines(snapshot), assertionLines(journey)),
+        sideEffects: multisetDiff(sideEffectLines(snapshot), sideEffectLines(journey)),
+    };
+}
+/** Step lines for a diff: the action and its check, without the number (an inserted step shifts every number). */
+function stepLines(j) {
+    return buildSteps(j).map((s) => `${s.action}${s.assertion === undefined ? "" : ` — expect ${s.assertion}`}`);
+}
+function assertionLines(j) {
+    return [
+        ...journeyEndState(j).map((c) => `end state: ${describeCheck(c)}`),
+        ...journeyAssertions(j)
+            .filter((s) => s.where === "step-request")
+            .map((s) => `step request: ${describeCheck(s.check)}`),
+    ];
+}
+function sideEffectLines(j) {
+    return [
+        ...[...new Set(buildWriteRequests(j).map((w) => `write ${w.method} ${w.endpoint}`))],
+        ...buildRiskyControls(j, undefined).map((c) => `control "${c.control}" [${c.ruleId}]`),
+        ...buildOrigins(j).map((o) => `origin ${o}`),
+    ];
+}
+function multisetDiff(before, after) {
+    const left = new Map();
+    for (const l of before)
+        left.set(l, (left.get(l) ?? 0) + 1);
+    const added = [];
+    for (const l of after) {
+        const n = left.get(l) ?? 0;
+        if (n > 0)
+            left.set(l, n - 1);
+        else
+            added.push(l);
+    }
+    const removed = [];
+    for (const l of before) {
+        const n = left.get(l) ?? 0;
+        if (n > 0) {
+            removed.push(l);
+            left.set(l, n - 1);
+        }
+    }
+    return { added, removed };
+}
+function buildVerify(journey, hash, rec) {
+    if (rec === null || rec === undefined) {
+        return { status: "not-verified", hint: `run \`jevitate journey verify ${journey.metadata.id} --mutate\` to prove each assertion can fail` };
+    }
+    return {
+        status: "recorded",
+        verdict: rec.verdict,
+        at: rec.at,
+        stale: rec.contentHash !== hash,
+        ...(rec.reason === undefined ? {} : { reason: rec.reason }),
+        summary: { ...rec.summary },
+    };
+}
+/** #432: the review sheet of one Journey — pure. */
+export function buildJourneyReview(journey, ctx = {}) {
+    const m = journey.metadata;
+    const hash = journeyReviewHash(journey);
+    const steps = buildSteps(journey);
+    const flat = flatJourneySteps(journey);
+    const missingIntent = [];
+    const annotate = `draft it with \`jevitate journey annotate ${m.id}\``;
+    if ((m.goal ?? "").trim() === "")
+        missingIntent.push(`no goal — ${annotate}`);
+    if ((m.successCriteria ?? []).length === 0)
+        missingIntent.push(`no success criteria — ${annotate}`);
+    const withoutObjective = steps.filter((s) => s.objective === undefined).length;
+    if (withoutObjective > 0)
+        missingIntent.push(`${withoutObjective} of ${steps.length} step(s) have no objective — ${annotate}`);
+    const secret = new Set(secretParamNames(journey));
+    const described = new Map((m.parameters ?? []).map((p) => [p.name, p.description]));
+    const paramNames = [...new Set([...journeyRunParams(journey), ...(m.parameters ?? []).map((p) => p.name)])];
+    const findings = lintJourney(journey);
+    const stepAssertions = journeyAssertions(journey).flatMap((site) => {
+        if (site.where === "end-state")
+            return [];
+        if (site.where === "step-request")
+            return [{ step: site.step, check: describeCheck(site.check), weak: false }];
+        const step = flat[site.step - 1]?.recorded.step;
+        const weak = site.check.assertion.kind === "visible" || (site.field === "expect" && step !== undefined && (isOwnTargetVisible(step) || isNoClaimExpect(step)));
+        return [{ step: site.step, check: describeCheck(site.check), weak }];
+    });
+    return {
+        id: m.id,
+        name: m.name,
+        promoted: m.promoted,
+        summary: {
+            ...(m.description === undefined ? {} : { description: m.description }),
+            ...(m.goal === undefined ? {} : { goal: m.goal }),
+            ...(m.persona === undefined ? {} : { persona: m.persona }),
+            ...(m.role === undefined ? {} : { role: m.role }),
+            requiresAuth: m.requiresAuth === true,
+            preconditions: (m.preconditions ?? []).map((p) => p.description),
+            successCriteria: (m.successCriteria ?? []).map((c) => ({
+                description: c.description,
+                ...(c.check === undefined ? {} : { check: describeCheck({ kind: "page", assertion: c.check }) }),
+            })),
+            missingIntent,
+        },
+        steps,
+        sideEffects: { writeRequests: buildWriteRequests(journey), riskyControls: buildRiskyControls(journey, ctx.safety), origins: buildOrigins(journey) },
+        inputs: {
+            params: paramNames.map((name) => {
+                const description = described.get(name);
+                return { name, ...(description === undefined ? {} : { description }), secret: secret.has(name) };
+            }),
+            secrets: (m.secretRefs ?? []).map((r) => ({ field: r.field, manager: r.manager, origin: r.origin })),
+        },
+        proof: {
+            endState: journeyEndState(journey).map(describeCheck),
+            stepAssertions,
+            lint: {
+                errors: findings.filter((f) => f.level === "error").length,
+                warnings: findings.filter((f) => f.level === "warning").length,
+                findings: findings.map((f) => ({ rule: f.rule, level: f.level, ...(f.step === undefined ? {} : { step: f.step }), message: f.message })),
+            },
+            ...(m.acceptedWeak === undefined ? {} : { acceptedWeak: { reason: m.acceptedWeak.reason, rules: [...m.acceptedWeak.rules] } }),
+            verify: buildVerify(journey, hash, ctx.lastVerify),
+        },
+        changeSinceApproval: buildChange(journey, hash, ctx.approvedSnapshot),
+        ...(m.approval === undefined
+            ? {}
+            : {
+                approval: {
+                    contentHash: m.approval.contentHash,
+                    at: m.approval.at,
+                    ...(m.approval.provenance === undefined ? {} : { provenance: copyProvenance(m.approval.provenance) }),
+                    ...(m.approval.acceptedWeak === undefined
+                        ? {}
+                        : { acceptedWeak: { reason: m.approval.acceptedWeak.reason, rules: [...m.approval.acceptedWeak.rules], ...provenanceField(m.approval.acceptedWeak.provenance) } }),
+                    ...(m.approval.waivers === undefined ? {} : { waivers: m.approval.waivers.map((w) => ({ kind: w.kind, reason: w.reason, items: [...w.items], ...provenanceField(w.provenance) })) }),
+                    ...(m.approval.acceptedFindings === undefined
+                        ? {}
+                        : { acceptedFindings: { reason: m.approval.acceptedFindings.reason, findings: [...m.approval.acceptedFindings.findings], ...provenanceField(m.approval.acceptedFindings.provenance) } }),
+                },
+            }),
+        ...(ctx.catalog === undefined ? {} : { catalog: ctx.catalog.links, findings: [...ctx.catalog.findings] }),
+        ...(ctx.proposal === undefined ? {} : { proposal: buildProposal(ctx.proposal, m.id) }),
+        contentHash: hash,
+    };
+}
+/** #437: a copy of an approval's provenance (the sheet never shares the Journey's objects). */
+function copyProvenance(p) {
+    return { channel: p.channel, agentSignals: [...p.agentSignals], ...(p.user === undefined ? {} : { user: p.user }), ...(p.reason === undefined ? {} : { reason: p.reason }) };
+}
+function provenanceField(p) {
+    return p === undefined ? {} : { provenance: copyProvenance(p) };
+}
+function renderSheet(r, style) {
+    const md = style === "markdown";
+    const code = (s) => (md ? `\`${s.replace(/`/g, "'")}\`` : s);
+    const h1 = (s) => (md ? `# ${s}` : `${s}\n${"=".repeat(Math.min(s.length, 80))}`);
+    const h2 = (s) => (md ? `## ${s}` : `${s.toUpperCase()}`);
+    const h3 = (s) => (md ? `### ${s}` : `${s}:`);
+    const em = (s) => (md ? `_${s}_` : s);
+    const li = (s, depth = 0) => `${"  ".repeat(md ? depth : depth + 1)}- ${s}`;
+    const out = [];
+    const section = (...lines) => {
+        out.push(...lines, "");
+    };
+    const list = (items, none) => (items.length === 0 ? [li(em(none))] : items.map((i) => li(i)));
+    section(h1(`Journey review: ${r.name} (${r.id})`), "", `Content hash: ${code(r.contentHash)}`, `Status: ${r.promoted ? "promoted" : "not promoted"}${r.approval === undefined ? "" : ` · last approved ${r.approval.at} — ${describeProvenance(r.approval.provenance)}`}`);
+    const s = r.summary;
+    section(h2("Summary"), "", ...(s.description === undefined ? [] : [li(`Description: ${s.description}`)]), li(`Goal: ${s.goal ?? em("none")}`), ...(s.persona === undefined ? [] : [li(`Persona: ${s.persona}`)]), ...(s.role === undefined ? [] : [li(`Runs as: ${s.role}`)]), ...(s.requiresAuth ? [li("Needs an authenticated session")] : []), ...(s.preconditions.length === 0 ? [] : [li("Preconditions:"), ...s.preconditions.map((p) => li(p, 1))]), li("Success criteria:"), ...(s.successCriteria.length === 0
+        ? [li(em("none"), 1)]
+        : s.successCriteria.map((c) => li(`${c.description}${c.check === undefined ? "" : ` (checked by ${code(c.check)})`}`, 1))), ...(s.missingIntent.length === 0 ? [] : [li("Missing intent:"), ...s.missingIntent.map((w) => li(`⚠ ${w}`, 1))]));
+    const stepLinesOut = [];
+    for (const st of r.steps) {
+        const target = st.target === undefined ? "" : ` — target: ${[st.target.role, st.target.name === undefined ? undefined : `"${st.target.name}"`].filter((x) => x !== undefined).join(" ")}`;
+        stepLinesOut.push(`${md ? "" : "  "}${st.number}. ${md ? `**${st.action}**` : st.action}${target}`);
+        const sub = (t) => {
+            stepLinesOut.push(`${md ? "   " : "     "}- ${t}`);
+        };
+        sub(`Objective: ${st.objective ?? em("none")}`);
+        if (st.expectedResult !== undefined)
+            sub(`Expected result: ${st.expectedResult}`);
+        if (st.assertion !== undefined)
+            sub(`Checks: ${code(st.assertion)}`);
+        if (st.params.length > 0)
+            sub(`Params: ${st.params.map(code).join(", ")}`);
+    }
+    section(h2("Steps"), "", ...(stepLinesOut.length === 0 ? [li(em("no steps"))] : stepLinesOut));
+    const fx = r.sideEffects;
+    section(h2("Side effects"), "", h3("Write requests"), ...list(fx.writeRequests.map((w) => `${code(`${w.method} ${w.endpoint}`)} — ${w.source === "recorded" ? `recorded at step ${w.step}` : w.source === "expect-request" ? `expected at step ${w.step}` : "end-state check"}`), "none expected"), "", h3("Controls matching safety rules"), ...list(fx.riskyControls.map((c) => `step ${c.step}: ${c.role === undefined ? "" : `${c.role} `}"${c.control}" — ${c.risk} [${code(c.ruleId)}]${c.waivedBy === undefined ? "" : ` (exempted by allowControl ${code(c.waivedBy)})`}`), "none"), "", h3("Origins"), ...list(fx.origins.map(code), "none"));
+    section(h2("Inputs"), "", h3("Parameters"), ...list(r.inputs.params.map((p) => `${code(p.name)}${p.secret ? " (secret)" : ""}${p.description === undefined ? "" : ` — ${p.description}`}`), "none"), "", h3("Secret references"), ...list(r.inputs.secrets.map((x) => `${code(x.field)} from ${x.manager} on ${x.origin}`), "none"));
+    const p = r.proof;
+    const verify = p.verify.status === "not-verified"
+        ? `not verified — ${p.verify.hint}`
+        : `${p.verify.verdict} (${p.verify.at})${p.verify.stale ? " — STALE: the Journey changed after this proof ran" : ""}${p.verify.reason === undefined ? "" : ` — ${p.verify.reason}`}: ${Object.entries(p.verify.summary)
+            .map(([k, v]) => `${v} ${k}`)
+            .join(", ")}`;
+    section(h2("Proof"), "", h3("End-state checks"), ...list(p.endState.map(code), "none"), "", h3("Per-step assertions"), ...list(p.stepAssertions.map((a) => `step ${a.step}: ${code(a.check)}${a.weak ? " (weak: proves nothing about the step's effect)" : ""}`), "none"), "", h3(`Lint: ${p.lint.errors} error(s), ${p.lint.warnings} warning(s)`), ...list(p.lint.findings.map((f) => `${f.level} ${f.rule}${f.step === undefined ? "" : ` (step ${f.step})`}: ${f.message}`), "no findings"), ...(p.acceptedWeak === undefined ? [] : ["", `Accepted weak: "${p.acceptedWeak.reason}" (waived: ${p.acceptedWeak.rules.join(", ")})`]), "", `Mutation proof: ${verify}`);
+    const c = r.changeSinceApproval;
+    const change = [];
+    if (c.kind === "first-approval")
+        change.push(em("first approval — nothing approved before"));
+    else if (c.kind === "no-record")
+        change.push(em("promoted before approvals were recorded — no approved version to compare with"));
+    else if (c.kind === "snapshot-missing") {
+        change.push(`Approved${c.approvedAt === undefined ? "" : ` ${c.approvedAt}`} as ${code(c.approvedHash)}; its snapshot is missing — ${c.changed ? "the Journey CHANGED since" : "unchanged since"}`);
+    }
+    else {
+        change.push(`Approved${c.approvedAt === undefined ? "" : ` ${c.approvedAt}`} as ${code(c.approvedHash)} — ${c.changed ? "CHANGED since" : "unchanged since"}`);
+        for (const [label, d] of [
+            ["Steps", c.steps],
+            ["Assertions", c.assertions],
+            ["Side effects", c.sideEffects],
+        ]) {
+            if (d.added.length === 0 && d.removed.length === 0)
+                continue;
+            change.push("", h3(label), ...d.removed.map((l) => li(`− ${l}`)), ...d.added.map((l) => li(`+ ${l}`)));
+        }
+    }
+    section(h2("Change since last approval"), "", ...change);
+    // #433: the catalog links (job, persona), then the pre-approval findings — before the approval line.
+    if (r.catalog !== undefined) {
+        const k = r.catalog;
+        const status = (st) => (st === "stale" ? "STALE — needs re-review" : st === "unknown" ? "UNKNOWN — not declared in the catalog" : st);
+        section(h2("Catalog"), "", ...(k.linked
+            ? [
+                li(k.job === undefined ? `Job: ${em("none")}` : `Job: ${code(k.job.id)} (${status(k.job.status)})${k.job.story === undefined ? "" : ` — ${k.job.story}`}`),
+                li(k.persona === undefined ? `Persona: ${em("none")}` : `Persona: ${code(k.persona.id)} (${status(k.persona.status)})`),
+                ...(k.unvetted.length === 0 ? [] : [li(`Unvetted: ${k.unvetted.join(", ")} — promote needs them approved, or --accept-unvetted "<reason>"`)]),
+                ...(k.needsReReview.length === 0 ? [] : [li(`NEEDS RE-REVIEW: ${k.needsReReview.join("; ")}`)]),
+            ]
+            : [li(em("not linked to a job/persona"))]));
+    }
+    if (r.findings !== undefined)
+        section(...renderFindings(r.findings, style));
+    if (r.approval?.waivers !== undefined || r.approval?.acceptedFindings !== undefined) {
+        section(h3("Recorded with the last approval"), ...(r.approval.waivers ?? []).map((w) => li(`waived (${w.kind}): "${w.reason}" — ${w.items.join(", ")}`)), ...(r.approval.acceptedFindings === undefined ? [] : [li(`acknowledged findings: "${r.approval.acceptedFindings.reason}" — ${r.approval.acceptedFindings.findings.join(", ")}`)]));
+    }
+    if (r.proposal !== undefined) {
+        const pr = r.proposal;
+        const scope = pr.changes.range ?? (pr.changes.notes.length > 0 ? "change notes" : "no change context");
+        section(h2("Proposed revision (self-heal)"), "", li(`Proposal ${code(pr.proposalId)} from ${pr.createdAt}, made against ${code(pr.baseHash)}; accepting it makes the content hash ${code(pr.proposedHash)}`), li(`Change context: ${scope}${pr.changes.baseSha === undefined ? "" : ` (${pr.changes.baseSha.slice(0, 8)}..${(pr.changes.headSha ?? "").slice(0, 8)})`}`), ...pr.changes.notes.map((n) => li(`note: ${n}`, 1)), li(`Heal attempts: ${pr.attempts.total} (${pr.attempts.rejected} rejected)`), ...(pr.stale ? [li(`STALE — the Journey changed after this proposal was made; it cannot be accepted. Re-run: jevitate journey run ${r.id} --self-heal`)] : []), ...(pr.problem !== undefined && !pr.stale ? [li(`REFUSED — ${pr.problem}`)] : []), "", ...pr.steps.flatMap((st) => [
+            `${md ? "" : "  "}${st.number}. ${md ? `**${st.hypothesis}**` : st.hypothesis}`,
+            `${md ? "   " : "     "}- Before: ${code(st.before)}`,
+            `${md ? "   " : "     "}- After: ${code(st.after)}`,
+            ...st.evidence.map((e) => `${md ? "   " : "     "}- Evidence: ${e}`),
+            ...st.screenshots.map((sh) => `${md ? "   " : "     "}- Screenshot: ${sh}`),
+        ]), "", pr.stale || pr.problem !== undefined ? em("not acceptable as it stands") : `Accept exactly this revision: ${code(pr.acceptCommand)}`, `Reject it: ${code(`jevitate journey promote ${r.id} --reject-proposal ${pr.proposalId} --reason "<why>"`)}`);
+    }
+    section(h2("Content hash"), "", `Content hash: ${code(r.contentHash)}`, "", `Approve exactly this version: ${code(`jevitate journey promote ${r.id} --reviewed-hash ${r.contentHash}`)}`);
+    return `${out.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+/** #432: the review sheet as Markdown (`journey review --markdown`). */
+export function renderReviewMarkdown(review) {
+    return renderSheet(review, "markdown");
+}
+/** #432: the review sheet as plain text (`journey review`, and `journey promote` in human mode). */
+export function renderReviewText(review) {
+    return renderSheet(review, "text");
+}
+/** #432: a review sheet file's content hash refused (none, or two different ones). */
+export class ReviewSheetError extends Error {
+    code = "E_JOURNEY_REVIEW_ARGS";
+}
+const HASH_LINE = /Content hash:\s*`?([0-9a-f]{64})`?/gi;
+/**
+ * #432: the content hash a review sheet file names — the `contentHash` of a JSON sheet
+ * (`journey review --json --out`, its envelope or the bare sheet), or the `Content hash:` line of a
+ * Markdown / text one. A sheet naming no hash, or two different ones, is refused.
+ */
+export function reviewSheetHash(text) {
+    const trimmed = text.trim();
+    if (trimmed.startsWith("{")) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new ReviewSheetError("the review sheet is not valid JSON");
+        }
+        const o = parsed;
+        const hash = o.contentHash ?? o.data?.contentHash;
+        if (typeof hash !== "string" || !/^[0-9a-f]{64}$/.test(hash))
+            throw new ReviewSheetError("the review sheet names no contentHash");
+        return hash;
+    }
+    const hashes = new Set([...text.matchAll(HASH_LINE)].map((m) => m[1].toLowerCase()));
+    if (hashes.size === 0)
+        throw new ReviewSheetError("the review sheet names no content hash (a `Content hash:` line)");
+    if (hashes.size > 1)
+        throw new ReviewSheetError("the review sheet names more than one content hash");
+    return [...hashes][0];
+}
+//# sourceMappingURL=journey-review.js.map