@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/report/render/json.js

@@ -0,0 +1,108 @@
+import { describeRequestBody } from "../../runtime/exchange.js";
+import { EXIT, runVerdict } from "../../runtime/exit.js";
+import { presentHeader } from "../../runtime/headers.js";
+import { coverageByCheck } from "./coverage.js";
+import { costByCheck, latency, utf8Total } from "./traffic.js";
+import { byVerdict } from "./verdicts.js";
+function evidenceJson(exchange, redactor) {
+    /* A secret the response issues may sit in the request or URL rendered first. */
+    redactor.learn(exchange.responseBody);
+    return {
+        at: new Date(exchange.at).toISOString(),
+        durationMs: exchange.durationMs,
+        method: exchange.method,
+        requestBody: redactor.body(describeRequestBody(exchange.requestBody), presentHeader(exchange.requestHeaders, "content-type") ?? ""),
+        requestBytes: exchange.requestBytes,
+        requestId: exchange.requestId,
+        responseBody: redactor.body(exchange.responseBody, presentHeader(exchange.responseHeaders, "content-type") ?? ""),
+        responseBytes: exchange.responseBytes,
+        status: exchange.status,
+        url: redactor.url(exchange.url),
+    };
+}
+function findingJson(finding, redactor) {
+    return {
+        check: finding.check,
+        detail: finding.detail,
+        entity: finding.entity,
+        ...(finding.origin === undefined ? {} : { origin: finding.origin }),
+        ...(finding.fixture === undefined ? {} : { fixture: finding.fixture }),
+        ...(finding.operations === undefined ? {} : { operations: finding.operations }),
+        ...(finding.known === undefined ? {} : { known: finding.known }),
+        evidence: finding.evidence.map((exchange) => evidenceJson(exchange, redactor)),
+        summary: finding.summary,
+        verdict: finding.verdict,
+    };
+}
+/** The verdict, and what the run did and did not check. */
+function runJson(input) {
+    const { outcome, reason } = runVerdict(input);
+    return {
+        backend: input.baseUrl,
+        /* The same verdict the process exit code states. */
+        outcome: { exitCode: EXIT[outcome], reason, result: outcome },
+        checksRun: input.checksRun,
+        checksSkipped: input.checksSkipped ?? [],
+        checksSuppressed: input.checksSuppressed ?? [],
+        inconclusive: input.inconclusive ?? [],
+        profile: input.profile ?? "full",
+        profileExclusions: input.profileExclusions ?? [],
+        ...(input.scope === undefined ? {} : { scope: input.scope }),
+        checksOutOfScope: input.checksOutOfScope ?? [],
+        durationMs: input.durationMs,
+        entitiesTested: input.entitiesTested,
+        ...(input.teardown === undefined || input.teardown === null ? {} : { teardown: input.teardown }),
+    };
+}
+/** When it ran, and the circumstances a reader needs to trust it: network, interruption, baseline, build, fence. */
+function contextJson(input, redactor) {
+    return {
+        generatedAt: input.startedAt.toISOString(),
+        requests: input.client.transcript.length,
+        ...(input.network === undefined ? {} : { network: input.network }),
+        ...(input.interrupted === true ? { interrupted: true } : {}),
+        ...(input.baseline === undefined ? {} : { baseline: input.baseline }),
+        ...(input.targetVersion === undefined ? {} : { targetVersion: input.targetVersion }),
+        ...(input.fenced === undefined
+            ? {}
+            : {
+                fenced: {
+                    failRun: input.fenced.failRun,
+                    requests: input.fenced.requests.map((request) => ({ ...request, url: redactor.url(request.url) })),
+                },
+            }),
+    };
+}
+/** What the run cost and observed, the findings per severity, and the coverage it fell short of. */
+function tallyJson(input) {
+    const coverage = coverageByCheck(input);
+    return {
+        requestBytes: utf8Total(input.client.transcript, "request"),
+        responseBytes: utf8Total(input.client.transcript, "response"),
+        latency: latency(input.client.transcript),
+        costByCheck: costByCheck(input),
+        observed: input.checkNotes ?? [],
+        summary: Object.fromEntries(byVerdict(input.findings).map(([verdict, group]) => [verdict, group.length])),
+        coverage: {
+            neverApplied: coverage.never.map((row) => row.check),
+            partial: coverage.partialSkip.map((row) => ({ check: row.check, ran: row.ran, skipped: row.skipped })),
+        },
+    };
+}
+/**
+ * The shape version of `report.json` and `matrix.json`. It rises only on a breaking change to a
+ * file's shape; an added field is not one.
+ */
+export const REPORT_SCHEMA_VERSION = 1;
+/** Machine-readable output for CI gating and diffing between runs. */
+export function renderJson(input) {
+    const redactor = input.client.redactor;
+    return `${JSON.stringify({
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        ...runJson(input),
+        findings: input.findings.map((finding) => findingJson(finding, redactor)),
+        ...contextJson(input, redactor),
+        ...tallyJson(input),
+    }, null, 2)}\n`;
+}
+//# sourceMappingURL=json.js.map

package/dist/api/report/render/junit.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The run as JUnit XML, for CI tools that gate on test results. There is no official schema; this
+ * writes the common denominator of Jenkins' xunit `junit-10.xsd`, GitLab and Testmo:
+ * - a suite per entity (`operations` for one with none, `<origin>:<entity>` on a secondary origin);
+ * - a case per (operation, check): passed, a failure for a failing root cause, or skipped for a
+ *   known finding, a coverage gap, an inconclusive check or a blocked one, each check once;
+ * - an `testing.api.run` suite for findings no operation case holds, and for a run that failed or may have
+ *   left records behind, so the JUnit outcome agrees with the exit code.
+ * Every text and attribute goes through the run's redactor, then XML escaping. No CDATA is used.
+ */
+import type { ReportInput } from "./input.ts";
+/** The run as `junit.xml`. */
+export declare function renderJunit(input: ReportInput): string;
+//# sourceMappingURL=junit.d.ts.map

package/dist/api/report/render/junit.js

@@ -0,0 +1,218 @@
+/**
+ * The run as JUnit XML, for CI tools that gate on test results. There is no official schema; this
+ * writes the common denominator of Jenkins' xunit `junit-10.xsd`, GitLab and Testmo:
+ * - a suite per entity (`operations` for one with none, `<origin>:<entity>` on a secondary origin);
+ * - a case per (operation, check): passed, a failure for a failing root cause, or skipped for a
+ *   known finding, a coverage gap, an inconclusive check or a blocked one, each check once;
+ * - an `testing.api.run` suite for findings no operation case holds, and for a run that failed or may have
+ *   left records behind, so the JUnit outcome agrees with the exit code.
+ * Every text and attribute goes through the run's redactor, then XML escaping. No CDATA is used.
+ */
+import { runVerdict } from "../../runtime/exit.js";
+import { isFailingRootCause, isRootCause } from "../../runtime/finding.js";
+const RUN_SUITE = "testing.api.run";
+const RUN_CLASS = "run";
+const EVIDENCE_LINES = 5;
+/* An operation's checks, the first kind a check appears under winning: GitLab keeps only the first duplicate. */
+const PRECEDENCE = ["failed", "gaps", "inconclusive", "suppressed", "passed"];
+/*
+ * What XML 1.0 forbids anywhere, escaped or not: C0 controls other than tab, newline and carriage
+ * return, U+FFFE, U+FFFF, and a surrogate half with no partner.
+ */
+// oxlint-disable-next-line no-control-regex -- these are the characters XML forbids
+const XML_INVALID = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u{FFFE}\u{FFFF}]|\p{Cs}/gu;
+const ESCAPES = {
+    "\t": "&#9;",
+    "\n": "&#10;",
+    "\r": "&#13;",
+    '"': "&quot;",
+    "&": "&amp;",
+    "'": "&apos;",
+    "<": "&lt;",
+    ">": "&gt;",
+};
+/* Text content keeps its tabs and newlines; a carriage return is escaped so a parser does not fold it. */
+function text(value) {
+    return value.replace(XML_INVALID, "").replace(/[&<>"'\r]/g, (c) => ESCAPES[c]);
+}
+/* An attribute value keeps every whitespace character a parser would otherwise normalize to a space. */
+function attr(value) {
+    return value.replace(XML_INVALID, "").replace(/[&<>"'\t\n\r]/g, (c) => ESCAPES[c]);
+}
+function suiteName(op) {
+    const entity = op.entity ?? "operations";
+    return op.origin === undefined ? entity : `${op.origin}:${entity}`;
+}
+function className(op) {
+    return op.origin === undefined ? op.operationId : `${op.origin}:${op.operationId}`;
+}
+function evidenceLine(exchange, redactor) {
+    return `${exchange.method} ${redactor.url(exchange.url)} → ${exchange.status}`;
+}
+/* A finding's detail, then the first exchanges that prove it. */
+function bodyOf(finding, redactor) {
+    const lines = [finding.detail, ...finding.evidence.slice(0, EVIDENCE_LINES).map((e) => evidenceLine(e, redactor))];
+    const more = finding.evidence.length - EVIDENCE_LINES;
+    if (more > 0)
+        lines.push(`… ${more} more exchanges in report.json`);
+    return lines.join("\n");
+}
+/* Why a finding that does not fail the run is still worth a line. */
+function excuse(finding) {
+    if (finding.known !== undefined)
+        return `known (baseline): ${finding.known.reason}`;
+    return finding.verdict === "COVERAGE_GAP" ? `coverage gap: ${finding.summary}` : `blocked: ${finding.summary}`;
+}
+/*
+ * One case standing for `findings`: a failure when any fails the run, else skipped with every excuse
+ * once. A failure is only ever a finding the exit code counts: the scope report grades a check failed
+ * from the same findings (junit.test.ts pins it), so a failed check with none on record is a report
+ * out of step with itself, shown as skipped rather than as a failure the run did not count.
+ */
+function judged(findings, redactor) {
+    const failing = findings.filter(isFailingRootCause);
+    const first = failing[0];
+    if (first !== undefined) {
+        const body = failing.map((finding) => bodyOf(finding, redactor)).join("\n\n");
+        return { body, kind: "failure", message: first.summary, type: first.verdict };
+    }
+    if (findings.length === 0)
+        return { kind: "skipped", message: "graded failed, but no finding on record names it" };
+    return { kind: "skipped", message: [...new Set(findings.map(excuse))].join("; ") };
+}
+/** Builds the cases, remembering which findings a case already holds. */
+class Cases {
+    suites = new Map();
+    placed = new Set();
+    #input;
+    constructor(input) {
+        this.#input = input;
+    }
+    add(suite, entry) {
+        const list = this.suites.get(suite) ?? [];
+        list.push(entry);
+        this.suites.set(suite, list);
+    }
+    /* The findings an operation's case for `check` stands for: that check, on that operation, from that origin. */
+    #findingsOn(op, check) {
+        return this.#input.findings.filter((f) => f.check === check && f.origin === op.origin && f.operations?.includes(op.operationId) === true);
+    }
+    #result(op, kind, check) {
+        const input = this.#input;
+        const suite = suiteName(op);
+        if (kind === "passed")
+            return { kind: "passed" };
+        if (kind === "failed") {
+            const causes = this.#findingsOn(op, check).filter(isRootCause);
+            for (const cause of causes)
+                this.placed.add(cause);
+            return judged(causes, input.client.redactor);
+        }
+        if (kind === "gaps") {
+            const gap = this.#findingsOn(op, check).find((f) => f.verdict === "COVERAGE_GAP");
+            return { kind: "skipped", message: gap === undefined ? "coverage gap" : `coverage gap: ${gap.summary}` };
+        }
+        if (kind === "inconclusive") {
+            /* A secondary origin's entries come back under its prefixed entity, not by operation. */
+            const entries = input.inconclusive ?? [];
+            const entry = entries.find((i) => i.check === check &&
+                (op.origin === undefined ? i.operations?.includes(op.operationId) === true : i.entity === suite));
+            return { kind: "skipped", message: entry === undefined ? "inconclusive" : `inconclusive: ${entry.reason}` };
+        }
+        const waiting = (input.checksSuppressed ?? []).find((s) => s.check === check && s.entity === suite);
+        return { kind: "skipped", message: `blocked: waiting on ${waiting?.because ?? "an earlier failure"}` };
+    }
+    operation(op) {
+        const seen = new Set();
+        const classname = className(op);
+        for (const kind of PRECEDENCE) {
+            for (const check of op.checks[kind]) {
+                if (seen.has(check))
+                    continue;
+                seen.add(check);
+                this.add(suiteName(op), { classname, name: check, result: this.#result(op, kind, check) });
+            }
+        }
+        if (seen.size === 0)
+            this.add(suiteName(op), {
+                classname,
+                name: "graded",
+                result: { kind: "skipped", message: op.reason ?? op.status },
+            });
+    }
+    standDowns() {
+        const seen = new Set();
+        for (const { check, entity, needs } of this.#input.checksSkipped ?? []) {
+            const key = `${entity}\0${check}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            this.add(entity, { classname: entity, name: check, result: { kind: "skipped", message: `stood down: ${needs}` } });
+        }
+    }
+    /* Run-level findings, and root causes no operation case holds: the exit code counts them all. */
+    run() {
+        const byCheck = new Map();
+        for (const finding of this.#input.findings) {
+            if (this.placed.has(finding))
+                continue;
+            if (finding.operations !== undefined && !isRootCause(finding))
+                continue;
+            byCheck.set(finding.check, [...(byCheck.get(finding.check) ?? []), finding]);
+        }
+        const redactor = this.#input.client.redactor;
+        for (const [check, findings] of byCheck)
+            this.add(RUN_SUITE, { classname: RUN_CLASS, name: check, result: judged(findings, redactor) });
+        const { outcome, reason } = runVerdict(this.#input);
+        if (outcome === "failed" || outcome === "leftovers")
+            this.add(RUN_SUITE, {
+                classname: RUN_CLASS,
+                name: "outcome",
+                result: { kind: "error", message: reason, type: outcome },
+            });
+    }
+}
+function count(cases, kind) {
+    return cases.filter((c) => c.result.kind === kind).length;
+}
+function caseXml(entry, redactor) {
+    const said = (value) => attr(redactor.text(value));
+    const head = `    <testcase classname="${said(entry.classname)}" name="${said(entry.name)}"`;
+    const { result } = entry;
+    switch (result.kind) {
+        case "passed":
+            return `${head}/>`;
+        case "skipped":
+            return `${head}><skipped message="${said(result.message)}"/></testcase>`;
+        case "error":
+            return `${head}><error type="${said(result.type)}" message="${said(result.message)}"/></testcase>`;
+        case "failure":
+            return (`${head}><failure type="${said(result.type)}" message="${said(result.message)}">` +
+                `${text(redactor.text(result.body))}</failure></testcase>`);
+    }
+}
+/** The run as `junit.xml`. */
+export function renderJunit(input) {
+    const cases = new Cases(input);
+    for (const op of input.scope?.operations ?? [])
+        cases.operation(op);
+    cases.standDowns();
+    cases.run();
+    const redactor = input.client.redactor;
+    const timestamp = input.startedAt.toISOString().replace(/\.\d{3}Z$/, "Z");
+    const suites = [...cases.suites].sort(([a], [b]) => a.localeCompare(b));
+    const all = suites.flatMap(([, list]) => list);
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        `<testsuites name="testing api" tests="${all.length}" failures="${count(all, "failure")}" errors="${count(all, "error")}"` +
+            ` time="${(input.durationMs / 1000).toFixed(3)}">`,
+    ];
+    for (const [name, list] of suites) {
+        list.sort((a, b) => a.classname.localeCompare(b.classname) || a.name.localeCompare(b.name));
+        lines.push(`  <testsuite name="${attr(redactor.text(name))}" tests="${list.length}" failures="${count(list, "failure")}"` +
+            ` errors="${count(list, "error")}" skipped="${count(list, "skipped")}" timestamp="${timestamp}">`, ...list.map((entry) => caseXml(entry, redactor)), "  </testsuite>");
+    }
+    lines.push("</testsuites>");
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=junit.js.map

package/dist/api/report/render/markdown-findings.d.ts

@@ -0,0 +1,8 @@
+import { type Exchange } from "../../runtime/exchange.ts";
+import type { Finding } from "../../runtime/finding.ts";
+import type { Redactor } from "../../security/redact.ts";
+/** One exchange: its request line and timing, then its bodies, collapsed. */
+export declare function exchangeBlock(exchange: Exchange, redactor: Redactor): string[];
+/** A section per severity, most severe first: each finding with its evidence and its repro script. */
+export declare function findingSections(findings: readonly Finding[], redactor: Redactor): string[];
+//# sourceMappingURL=markdown-findings.d.ts.map

package/dist/api/report/render/markdown-findings.js

@@ -0,0 +1,53 @@
+import { describeRequestBody } from "../../runtime/exchange.js";
+import { presentHeader } from "../../runtime/headers.js";
+import { ISSUE_REPRO_DIR, reproStem } from "./repro.js";
+import { formatBytes, truncate } from "./text.js";
+import { byVerdict, findingSubject, VERDICT_LABEL, VERDICT_NOTE } from "./verdicts.js";
+/** Evidence shown per finding; the repro script carries all of it. */
+const EVIDENCE_SHOWN = 3;
+/** A collapsed body, in a fenced JSON block. */
+function bodyBlock(summary, body) {
+    return ["", `<details><summary>${summary}</summary>`, "", "```json", truncate(body), "```", "", "</details>"];
+}
+/** One exchange: its request line and timing, then its bodies, collapsed. */
+export function exchangeBlock(exchange, redactor) {
+    /* A secret the response issues may sit in the request or URL rendered first. */
+    redactor.learn(exchange.responseBody);
+    const url = new URL(redactor.url(exchange.url));
+    const lines = [
+        "",
+        `\`${exchange.method} ${url.pathname}${url.search}\` → **${exchange.status}** (${new Date(exchange.at).toISOString()} · ${exchange.durationMs}ms · ${formatBytes(exchange.requestBytes)} → ${formatBytes(exchange.responseBytes)}${exchange.requestId === "" ? "" : ` · ${exchange.requestId}`})`,
+    ];
+    if (exchange.requestBody !== undefined) {
+        lines.push(...bodyBlock("request body", redactor.body(describeRequestBody(exchange.requestBody), presentHeader(exchange.requestHeaders, "content-type") ?? "")));
+    }
+    if (exchange.responseBody !== null && exchange.responseBody !== undefined) {
+        lines.push(...bodyBlock("response body", redactor.body(exchange.responseBody, presentHeader(exchange.responseHeaders, "content-type") ?? "")));
+    }
+    return lines;
+}
+function findingSection(finding, redactor) {
+    const lines = [`### ${findingSubject(finding)} — ${finding.summary}`, "", `\`${finding.check}\``, "", finding.detail];
+    for (const exchange of finding.evidence.slice(0, EVIDENCE_SHOWN))
+        lines.push(...exchangeBlock(exchange, redactor));
+    if (finding.evidence.length > 0) {
+        lines.push("");
+        lines.push(`Reproduce: \`${ISSUE_REPRO_DIR}/${reproStem(finding)}.sh\``);
+    }
+    lines.push("");
+    return lines;
+}
+/** A section per severity, most severe first: each finding with its evidence and its repro script. */
+export function findingSections(findings, redactor) {
+    const lines = [];
+    for (const [findingVerdict, group] of byVerdict(findings)) {
+        lines.push(`## ${VERDICT_LABEL[findingVerdict]}`);
+        lines.push("");
+        lines.push(`> ${VERDICT_NOTE[findingVerdict]}`);
+        lines.push("");
+        for (const finding of group)
+            lines.push(...findingSection(finding, redactor));
+    }
+    return lines;
+}
+//# sourceMappingURL=markdown-findings.js.map

package/dist/api/report/render/markdown-head.d.ts

@@ -0,0 +1,8 @@
+import type { runVerdict } from "../../runtime/exit.ts";
+import { type Coverage } from "./coverage.ts";
+import type { ReportInput } from "./input.ts";
+type RunVerdict = ReturnType<typeof runVerdict>;
+/** The report's title and its bullet summary of the run, ending in a blank line. */
+export declare function headLines(input: ReportInput, verdict: RunVerdict, coverage: Coverage): string[];
+export {};
+//# sourceMappingURL=markdown-head.d.ts.map

package/dist/api/report/render/markdown-head.js

@@ -0,0 +1,82 @@
+import { profileExclusionSummary } from "./coverage.js";
+import { scopeLine } from "./scope.js";
+import { entityList, formatBytes } from "./text.js";
+import { COST_ROWS, costByCheck, latency, utf8Total } from "./traffic.js";
+/** What was tested, when, and what came of it. */
+function runLines(input, verdict) {
+    const lines = [`- **Backend**: ${input.baseUrl}`];
+    if (input.targetVersion !== undefined) {
+        lines.push("value" in input.targetVersion
+            ? `- **Target version**: ${input.targetVersion.value}`
+            : `- **Target version**: unknown — ${input.targetVersion.error}`);
+    }
+    lines.push(`- **Result**: ${verdict.outcome} — ${verdict.reason}`);
+    if (input.interrupted === true)
+        lines.push("- **Interrupted**: stopped by a signal; teardown ran");
+    lines.push(`- **Generated**: ${input.startedAt.toISOString()} (${(input.durationMs / 1000).toFixed(1)}s)`);
+    if (input.scope !== undefined)
+        lines.push(`- **Scope**: ${scopeLine(input.scope, " — ")}`);
+    lines.push(`- **Entities tested**: ${entityList(input.entitiesTested)}`);
+    lines.push(`- **Checks run**: ${input.checksRun.length}`);
+    return lines;
+}
+/** How many checks fell short of running everywhere, and what the profile left out. */
+function coverageLines(input, coverage) {
+    const lines = [];
+    if (coverage.never.length > 0) {
+        lines.push(`- **Checks that did not apply anywhere**: ${coverage.never.length}`);
+    }
+    if (coverage.partialSkip.length > 0) {
+        lines.push(`- **Checks that applied only on some entities**: ${coverage.partialSkip.length}`);
+    }
+    const suppressedEverywhere = coverage.blocked.filter((row) => row.ran === 0);
+    if (suppressedEverywhere.length > 0) {
+        lines.push(`- **Checks blocked by an earlier failure**: ${suppressedEverywhere.length}`);
+    }
+    const unresolvedCount = new Set((input.inconclusive ?? []).map((s) => s.check)).size;
+    if (unresolvedCount > 0)
+        lines.push(`- **Checks that could not conclude**: ${unresolvedCount}`);
+    const profileLine = profileExclusionSummary(input);
+    if (profileLine !== null)
+        lines.push(`- **Profile**: ${profileLine}`);
+    return lines;
+}
+/** What the run sent, how the network held up, and where the time went. */
+function trafficLines(input) {
+    const transcript = input.client.transcript;
+    const lines = [
+        `- **Requests**: ${transcript.length}` +
+            ` (${formatBytes(utf8Total(transcript, "request"))} req · ${formatBytes(utf8Total(transcript, "response"))} res)`,
+    ];
+    if (input.exchanges !== undefined) {
+        lines.push(`- **Exchanges**: ${input.exchanges.count} → [exchanges/](./exchanges/)`);
+    }
+    if (input.network !== undefined) {
+        const wait = input.network.waitedMs > 0 ? ` · waited ${Math.round(input.network.waitedMs / 1000)}s` : "";
+        lines.push(`- **Network**: ${input.network.kind} after ${input.network.attempts} attempt(s)${wait}` +
+            (input.network.incomplete ? " — run incomplete, not a backend defect" : ""));
+    }
+    lines.push("- **Matrix**: [matrix.html](./matrix.html) · [matrix.json](./matrix.json)");
+    const timing = latency(transcript);
+    if (timing !== null) {
+        lines.push(`- **Latency**: p50 ${timing.p50}ms · p95 ${timing.p95}ms · max ${timing.max}ms ` +
+            `(${timing.slowest.method} ${timing.slowest.path})`);
+    }
+    const cost = costByCheck(input).slice(0, COST_ROWS);
+    if (cost.length > 0) {
+        lines.push(`- **Costliest checks**: ${cost.map((row) => `${row.check} ${row.requests} req · ${(row.ms / 1000).toFixed(1)}s`).join(", ")}`);
+    }
+    return lines;
+}
+/** The report's title and its bullet summary of the run, ending in a blank line. */
+export function headLines(input, verdict, coverage) {
+    return [
+        "# The API tester report",
+        "",
+        ...runLines(input, verdict),
+        ...coverageLines(input, coverage),
+        ...trafficLines(input),
+        "",
+    ];
+}
+//# sourceMappingURL=markdown-head.js.map

package/dist/api/report/render/markdown-sections.d.ts

@@ -0,0 +1,35 @@
+import type { runVerdict } from "../../runtime/exit.ts";
+import type { Finding } from "../../runtime/finding.ts";
+import type { Redactor } from "../../security/redact.ts";
+import type { Coverage } from "./coverage.ts";
+import type { ReportInput } from "./input.ts";
+/** A finding the baseline named. */
+type KnownFinding = Finding & {
+    known: NonNullable<Finding["known"]>;
+};
+/** Records the API tester made and cannot remove: first, since someone has to clean them up by hand. */
+export declare function leftoverSections(input: ReportInput, redactor: Redactor): string[];
+/** Requests the fence refused: never sent, so never judged — unknown, not passed. */
+export declare function fencedSection(input: ReportInput, redactor: Redactor): string[];
+/**
+ * Policies the document leaves open, as the backend showed them. One line per policy: the same
+ * observation on every entity is said once.
+ */
+export declare function observedSection(input: ReportInput): string[];
+/** How the run ended: its verdict, and how many defects it found. */
+export interface RunOutcome {
+    verdict: ReturnType<typeof runVerdict>;
+    defects: number;
+}
+/** No defects, said plainly, or the count of findings per severity. */
+export declare function outcomeSection(input: ReportInput, findings: readonly Finding[], { defects, verdict }: RunOutcome): string[];
+/** True for a finding the baseline named. */
+export declare function isKnown(finding: Finding): finding is KnownFinding;
+/** Findings the baseline named: reported, and not counted against the run. */
+export declare function knownSection(known: readonly KnownFinding[]): string[];
+/** Baseline entries no finding matched in this run. */
+export declare function fixedSection(input: ReportInput): string[];
+/** Checks that did not apply anywhere, and those that applied only on some entities. */
+export declare function coverageSections(coverage: Coverage): string[];
+export {};
+//# sourceMappingURL=markdown-sections.d.ts.map

package/dist/api/report/render/markdown-sections.js

@@ -0,0 +1,125 @@
+import { named } from "./text.js";
+import { byVerdict, VERDICT_LABEL } from "./verdicts.js";
+/** Records the API tester made and cannot remove: first, since someone has to clean them up by hand. */
+export function leftoverSections(input, redactor) {
+    const unidentified = input.teardown?.unidentified ?? [];
+    const unremoved = input.teardown?.failed ?? [];
+    const lines = [];
+    if (unidentified.length > 0 || unremoved.length > 0)
+        lines.push("## Leftovers", "");
+    if (unidentified.length > 0) {
+        lines.push("Each create answered 2xx, but no id could be read from its answer or confirmed by a read, so");
+        lines.push("teardown could not remove what it made. Declare `x-entity.createdIdFrom` where the id is.");
+        lines.push("");
+        for (const create of unidentified) {
+            lines.push(`- \`${create.method} ${redactor.url(create.url)}\` · ${create.operationId} · ${create.status} · exchange #${create.seq}`);
+        }
+        lines.push("");
+    }
+    if (unremoved.length > 0) {
+        lines.push("Records teardown could not show gone, each with the principal that created it:");
+        lines.push("");
+        for (const record of unremoved) {
+            lines.push(`- ${record.entity} \`${record.id}\` · as ${record.principal} · ${record.reason}`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+/** Requests the fence refused: never sent, so never judged — unknown, not passed. */
+export function fencedSection(input, redactor) {
+    const fenced = input.fenced?.requests ?? [];
+    if (fenced.length === 0)
+        return [];
+    const lines = ["## Fenced requests", ""];
+    for (const request of fenced) {
+        lines.push(`- \`${request.method} ${redactor.url(request.url)}\` · ${request.operationId ?? "—"} · ${request.phase} · ${request.reason}`);
+    }
+    lines.push("");
+    return lines;
+}
+/**
+ * Policies the document leaves open, as the backend showed them. One line per policy: the same
+ * observation on every entity is said once.
+ */
+export function observedSection(input) {
+    const observed = new Map();
+    for (const note of input.checkNotes ?? []) {
+        observed.set(note.note, [...(observed.get(note.note) ?? []), note.entity]);
+    }
+    if (observed.size === 0)
+        return [];
+    const lines = ["## Observed behavior", ""];
+    for (const [note, entities] of observed)
+        lines.push(`- ${note} (${entities.join(", ")})`);
+    lines.push("");
+    return lines;
+}
+/** No defects, said plainly, or the count of findings per severity. */
+export function outcomeSection(input, findings, { defects, verdict }) {
+    if (defects === 0) {
+        return [
+            verdict.outcome === "failed"
+                ? `No defects found, but the run failed: ${verdict.reason}.`
+                : `No defects found across ${input.checksRun.length} checks.`,
+            "",
+        ];
+    }
+    const lines = ["## Summary", "", "| severity | count |", "| --- | --- |"];
+    for (const [findingVerdict, group] of byVerdict(findings)) {
+        lines.push(`| ${VERDICT_LABEL[findingVerdict]} | ${group.length} |`);
+    }
+    lines.push("");
+    return lines;
+}
+/** True for a finding the baseline named. */
+export function isKnown(finding) {
+    return finding.known !== undefined;
+}
+/** Findings the baseline named: reported, and not counted against the run. */
+export function knownSection(known) {
+    if (known.length === 0)
+        return [];
+    const lines = ["## Known", "", "Named by the baseline: reported, and not counted against the run.", ""];
+    for (const finding of known) {
+        lines.push(`- **${finding.check}** on ${finding.entity} — ${finding.summary} _(known: ${finding.known.reason})_`);
+    }
+    lines.push("");
+    return lines;
+}
+/** Baseline entries no finding matched in this run. */
+export function fixedSection(input) {
+    const fixed = input.baseline?.fixed ?? [];
+    if (fixed.length === 0)
+        return [];
+    const lines = ["## Fixed", "", "Baseline entries no finding matched in this run:", ""];
+    for (const entry of fixed) {
+        const where = [entry.entity, entry.operationId].filter((part) => part !== undefined).join(" · ");
+        lines.push(`- **${entry.check}**${where === "" ? "" : ` (${where})`} — ${entry.reason}`);
+    }
+    lines.push("");
+    return lines;
+}
+/** Checks that did not apply anywhere, and those that applied only on some entities. */
+export function coverageSections(coverage) {
+    const lines = [];
+    if (coverage.never.length > 0) {
+        lines.push("## Did not apply anywhere");
+        lines.push("");
+        for (const row of coverage.never) {
+            lines.push(`- \`${row.check}\` — ${row.needs} (all ${row.skipped} entities)`);
+        }
+        lines.push("");
+    }
+    if (coverage.partialSkip.length > 0) {
+        lines.push("## Applied only on some entities");
+        lines.push("");
+        for (const row of coverage.partialSkip) {
+            const ran = row.ran > 0 ? `on ${row.ran}` : "per operation";
+            lines.push(`- \`${row.check}\` — ran ${ran}, skipped on ${row.skipped} (${named(row.skippedEntities)})`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+//# sourceMappingURL=markdown-sections.js.map