@workerstack/testing 0.0.0-stage → 0.31.0

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

@@ -0,0 +1,12 @@
+/**
+ * Report rendering.
+ *
+ * The previous generation of this tool produced 88 failures that a human then spent days sorting
+ * into five root causes by hand, and the artifact that team actually used was a set of
+ * hand-written curl scripts. So: group by root cause, lead with severity, and generate the
+ * reproducers.
+ */
+import type { ReportInput } from "./input.ts";
+/** The markdown report: the run in summary, then every finding grouped by severity. */
+export declare function renderMarkdown(input: ReportInput): string;
+//# sourceMappingURL=markdown.d.ts.map

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

@@ -0,0 +1,38 @@
+/**
+ * Report rendering.
+ *
+ * The previous generation of this tool produced 88 failures that a human then spent days sorting
+ * into five root causes by hand, and the artifact that team actually used was a set of
+ * hand-written curl scripts. So: group by root cause, lead with severity, and generate the
+ * reproducers.
+ */
+import { runVerdict } from "../../runtime/exit.js";
+import { isFailingRootCause } from "../../runtime/finding.js";
+import { coverageByCheck } from "./coverage.js";
+import { headLines } from "./markdown-head.js";
+import { findingSections } from "./markdown-findings.js";
+import { coverageSections, fencedSection, fixedSection, isKnown, knownSection, leftoverSections, observedSection, outcomeSection, } from "./markdown-sections.js";
+import { scopeSections } from "./scope.js";
+/** The markdown report: the run in summary, then every finding grouped by severity. */
+export function renderMarkdown(input) {
+    const redactor = input.client.redactor;
+    /* Known findings have a section of their own; everything else reads as it always has. */
+    const findings = input.findings.filter((finding) => finding.known === undefined);
+    const known = input.findings.filter(isKnown);
+    const coverage = coverageByCheck(input);
+    const verdict = runVerdict(input);
+    const lines = [
+        ...headLines(input, verdict, coverage),
+        ...leftoverSections(input, redactor),
+        ...fencedSection(input, redactor),
+        ...observedSection(input),
+        ...outcomeSection(input, findings, { defects: findings.filter(isFailingRootCause).length, verdict }),
+        ...(input.scope === undefined ? [] : scopeSections(input.scope)),
+        ...knownSection(known),
+        ...fixedSection(input),
+        ...findingSections(findings, redactor),
+        ...coverageSections(coverage),
+    ];
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=markdown.js.map

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

@@ -0,0 +1,13 @@
+import type { Finding } from "../../runtime/finding.ts";
+import type { Redactor } from "../../security/redact.ts";
+export interface ReproScript {
+    filename: string;
+    content: string;
+}
+/** Directory for curl scripts that replay a finding. Absent when the run is clean. */
+export declare const ISSUE_REPRO_DIR = "issue-repro";
+/** The file stem a finding's script is saved under, before any numbering. */
+export declare function reproStem(finding: Finding): string;
+/** One runnable script per finding — the artifact a backend developer actually opens. */
+export declare function renderRepros(findings: Finding[], baseUrl: string, redactor: Redactor): ReproScript[];
+//# sourceMappingURL=repro.d.ts.map

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

@@ -0,0 +1,47 @@
+import { toCurl } from "../../client/curl.js";
+import { slug, wrap } from "./text.js";
+/** Directory for curl scripts that replay a finding. Absent when the run is clean. */
+export const ISSUE_REPRO_DIR = "issue-repro";
+/** The file stem a finding's script is saved under, before any numbering. */
+export function reproStem(finding) {
+    return slug(`${finding.entity}-${finding.check}`);
+}
+/** The script that replays one finding's evidence, step by step, against `base`. */
+function reproContent(finding, base, redactor) {
+    const lines = [];
+    lines.push("#!/usr/bin/env bash");
+    lines.push("# Generated by the API tester. Set TOKEN to a valid credential before running.");
+    lines.push("#");
+    lines.push(`# ${finding.entity} — ${finding.summary}`);
+    for (const chunk of wrap(finding.detail, 88))
+        lines.push(`# ${chunk}`);
+    lines.push("");
+    lines.push("set -u");
+    lines.push(`BASE="\${BASE:-${base}}"`);
+    lines.push('TOKEN="${TOKEN:?set TOKEN to a valid credential}"');
+    lines.push("");
+    finding.evidence.forEach((exchange, index) => {
+        lines.push(`# step ${index + 1} — observed ${exchange.status}`);
+        lines.push(toCurl(exchange, { origin: base, redactor }));
+        lines.push("");
+    });
+    return `${lines.join("\n")}\n`;
+}
+/** One runnable script per finding — the artifact a backend developer actually opens. */
+export function renderRepros(findings, baseUrl, redactor) {
+    /* `BASE` stands for the whole base URL, path prefix and all, so it replaces exactly that. */
+    const base = baseUrl.replace(/\/+$/, "");
+    const taken = new Set();
+    return findings
+        .filter((finding) => finding.evidence.length > 0)
+        .map((finding) => {
+        /* One check can report more than once on an entity; each finding keeps its own file. */
+        const stem = reproStem(finding);
+        let filename = `${stem}.sh`;
+        for (let n = 2; taken.has(filename); n++)
+            filename = `${stem}-${n}.sh`;
+        taken.add(filename);
+        return { content: reproContent(finding, base, redactor), filename };
+    });
+}
+//# sourceMappingURL=repro.js.map

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

@@ -0,0 +1,8 @@
+import { type ScopeReport } from "../../runtime/scope/types.ts";
+/** One line naming the scope: what was asked for, or that the run was full. */
+export declare function scopeLine(scope: ScopeReport, dash: string): string;
+/** The markdown report's confidence summary and operation table. */
+export declare function scopeSections(scope: ScopeReport): string[];
+/** The console summary's scope line, and on a targeted run one line per target. */
+export declare function scopeConsole(scope: ScopeReport): string[];
+//# sourceMappingURL=scope.d.ts.map

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

@@ -0,0 +1,98 @@
+import { renderConfidenceMarkdown } from "../confidence.js";
+import { describeRequested } from "../../runtime/scope/plan.js";
+import {} from "../../runtime/scope/types.js";
+const STATUS_MARK = {
+    blocked: "○",
+    failed: "✗",
+    passed: "✓",
+    inconclusive: "?",
+    untested: "○",
+};
+/** An operation by id, under its origin when it is not the primary's. */
+function operationLabel(op) {
+    return op.origin === undefined ? op.operationId : `${op.origin}:${op.operationId}`;
+}
+/** One line naming the scope: what was asked for, or that the run was full. */
+export function scopeLine(scope, dash) {
+    if (scope.mode === "full") {
+        const graded = scope.operations.filter((op) => op.status !== "untested").length;
+        return `full${dash}${graded} of ${scope.operations.length} operations graded`;
+    }
+    const n = scope.operations.length;
+    return `targeted${dash}${n} operation${n === 1 ? "" : "s"} (${describeRequested(scope.requested)})`;
+}
+function operationRow(op) {
+    const failed = op.checks.failed.length === 0 ? "0" : `${op.checks.failed.length} (${op.checks.failed.join(", ")})`;
+    return (`| ${operationLabel(op)} | ${op.entity ?? "—"} | ${op.status} | ${op.sufficiency ?? ""} | ${op.checks.passed.length} | ${failed} | ` +
+        `${op.checks.suppressed.length} | ${op.checks.inconclusive.length} | ${(op.why ?? op.reason ?? "").replace(/\|/g, "\\|")} |`);
+}
+function supportRow(use) {
+    const first = use.firstFailure === undefined
+        ? ""
+        : `${use.firstFailure.status}${use.firstFailure.requestId === "" ? "" : ` (${use.firstFailure.requestId})`}`;
+    return `| ${operationLabel(use)} | ${use.calls} | ${use.non2xx} | ${first} |`;
+}
+/** What a targeted run called without grading it. */
+function supportSection(scope) {
+    const lines = [
+        "## Support operations",
+        "",
+        "> Called to reach or observe a target. Not graded: a defect here is out of this run's scope.",
+        "",
+    ];
+    if (scope.support.length === 0) {
+        lines.push("None.");
+    }
+    else {
+        lines.push("| operation | calls | non-2xx | first failure |");
+        lines.push("| --- | --- | --- | --- |");
+        for (const use of scope.support)
+            lines.push(supportRow(use));
+    }
+    lines.push("");
+    return lines;
+}
+/** The markdown report's confidence summary and operation table. */
+export function scopeSections(scope) {
+    const lines = [renderConfidenceMarkdown(scope), "## Operations", ""];
+    lines.push(scope.mode === "full"
+        ? "> Every operation in the document and whether any check graded it. `untested` names why not."
+        : "> The targets of this run. Everything else the API tester called is listed under support: called, never graded.");
+    lines.push("");
+    lines.push("| operation | entity | status | proof | passed | failed | suppressed | inconclusive | why |");
+    lines.push("| --- | --- | --- | --- | --- | --- | --- | --- | --- |");
+    for (const op of scope.operations)
+        lines.push(operationRow(op));
+    lines.push("");
+    if (scope.originsSkipped.length > 0) {
+        lines.push(`Origins not run — no target named them: ${scope.originsSkipped.join(", ")}.`);
+        lines.push("");
+    }
+    if (scope.excluded.length > 0) {
+        lines.push(`Excluded by the profile: ${scope.excluded.map((e) => `${e.operationId} (${e.reason})`).join(", ")}.`);
+        lines.push("");
+    }
+    if (scope.mode === "targeted")
+        lines.push(...supportSection(scope));
+    return lines;
+}
+function operationDetail(op) {
+    const graded = op.checks.passed.length + op.checks.failed.length + op.checks.inconclusive.length;
+    if (op.status === "failed")
+        return `${graded} checks · ${op.findings} finding(s) (${op.checks.failed.join(", ")})`;
+    if (op.status === "passed" || op.status === "inconclusive")
+        return `${graded} checks`;
+    return op.reason ?? "";
+}
+/** The console summary's scope line, and on a targeted run one line per target. */
+export function scopeConsole(scope) {
+    if (scope.mode === "full")
+        return [`  scope: ${scopeLine(scope, " · ")}`];
+    const lines = [`  scope: ${scopeLine(scope, " · ")} · ${scope.support.length} support op(s)`];
+    const width = Math.max(16, ...scope.operations.map((op) => operationLabel(op).length)) + 2;
+    for (const op of scope.operations) {
+        lines.push(`    ${STATUS_MARK[op.status]} ${operationLabel(op).padEnd(width)}${op.status.padEnd(14)}${operationDetail(op)}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=scope.js.map

package/dist/api/report/render/step-summary.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The run as a GitHub Actions job summary, in GitHub-flavored Markdown: the verdict and its exit
+ * code, the operations by status, the root causes, and what went untested, collapsed. The CLI
+ * appends it to the file `GITHUB_STEP_SUMMARY` names; this module never reads the environment.
+ *
+ * GitHub refuses a step's summary over 1 MiB, and other steps in a job write there too, so this one
+ * stays within 64 KiB: rows are dropped from the end of the untested list, then of the findings,
+ * each list saying how many it left out, and only then is the rest cut at a line boundary.
+ */
+import type { ReportInput } from "./input.ts";
+/** The most this summary writes, in UTF-8 bytes. */
+export declare const STEP_SUMMARY_LIMIT = 65536;
+/** The run's job summary, at most {@link STEP_SUMMARY_LIMIT} bytes. */
+export declare function renderStepSummary(input: ReportInput, where: {
+    runDir: string;
+}): string;
+//# sourceMappingURL=step-summary.d.ts.map

package/dist/api/report/render/step-summary.js

@@ -0,0 +1,153 @@
+/**
+ * The run as a GitHub Actions job summary, in GitHub-flavored Markdown: the verdict and its exit
+ * code, the operations by status, the root causes, and what went untested, collapsed. The CLI
+ * appends it to the file `GITHUB_STEP_SUMMARY` names; this module never reads the environment.
+ *
+ * GitHub refuses a step's summary over 1 MiB, and other steps in a job write there too, so this one
+ * stays within 64 KiB: rows are dropped from the end of the untested list, then of the findings,
+ * each list saying how many it left out, and only then is the rest cut at a line boundary.
+ */
+import { EXIT, runVerdict } from "../../runtime/exit.js";
+import { isFailingRootCause, isRootCause } from "../../runtime/finding.js";
+import { coverageByCheck } from "./coverage.js";
+import { byVerdict, findingSubject } from "./verdicts.js";
+/** The most this summary writes, in UTF-8 bytes. */
+export const STEP_SUMMARY_LIMIT = 65_536;
+const STATUSES = ["passed", "failed", "inconclusive", "blocked", "untested"];
+function bytes(value) {
+    return Buffer.byteLength(value, "utf8");
+}
+/* One line of Markdown from text a backend or a check wrote: no secret, no raw markup, no line break. */
+function inline(value, redactor) {
+    return redactor
+        .text(value)
+        .replace(/\r\n|\r|\n/g, " ")
+        .replaceAll("<", "&lt;");
+}
+/* A table cell: one line, and a pipe that does not end the cell. */
+function cell(value, redactor) {
+    return inline(value, redactor).replaceAll("|", "\\|");
+}
+function headOf(input) {
+    const { outcome, reason } = runVerdict(input);
+    const redactor = input.client.redactor;
+    const lines = [
+        `## testing api: ${outcome} (exit ${EXIT[outcome]})`,
+        "",
+        `\`${inline(input.baseUrl, redactor)}\` · profile ${input.profile ?? "full"} · ` +
+            `${input.checksRun.length} checks · ${input.entitiesTested.length} entities · ` +
+            `${input.client.transcript.length} requests · ${(input.durationMs / 1000).toFixed(1)}s`,
+        "",
+        `**${inline(reason, redactor)}**`,
+    ];
+    const known = input.findings.filter((finding) => finding.known !== undefined).length;
+    const fixed = input.baseline?.fixed.length ?? 0;
+    if (known > 0 || fixed > 0)
+        lines.push("", `Baseline: ${known} known · ${fixed} fixed`);
+    if (input.interrupted === true)
+        lines.push("", "Interrupted by a signal: what ran before it is reported.");
+    const operations = input.scope?.operations ?? [];
+    const counts = STATUSES.map((status) => operations.filter((op) => op.status === status).length);
+    lines.push("", `| operations | ${STATUSES.join(" | ")} |`, `|${" ---: |".repeat(STATUSES.length + 1)}`, `| ${operations.length} | ${counts.join(" | ")} |`, "");
+    return lines;
+}
+/* Failing root causes, most severe first, then the known ones. */
+function findingRows(input) {
+    const redactor = input.client.redactor;
+    const roots = input.findings.filter(isRootCause);
+    const ordered = [
+        ...byVerdict(roots.filter(isFailingRootCause)),
+        ...byVerdict(roots.filter((finding) => !isFailingRootCause(finding))),
+    ].flatMap(([, group]) => group);
+    return ordered.map((finding) => `| ${finding.verdict}${finding.known === undefined ? "" : " (known)"} | ${cell(findingSubject(finding), redactor)}` +
+        ` | \`${cell(finding.check, redactor)}\` | ${cell(finding.summary, redactor)} |`);
+}
+/* Checks blocked by an earlier failure, then those that could not conclude, as the console groups them. */
+function untestedRows(input) {
+    const redactor = input.client.redactor;
+    const suppressed = input.checksSuppressed ?? [];
+    /* Every blocked row came from a suppression, so one is there. */
+    const waiting = (check) => inline(suppressed.find((s) => s.check === check).because, redactor);
+    const rows = coverageByCheck(input).blocked.map((row) => row.ran === 0
+        ? `- \`${row.check}\`: blocked by an earlier failure, waiting on ${waiting(row.check)}`
+        : `- \`${row.check}\`: blocked on ${row.blocked} of ${input.entitiesTested.length} entities, waiting on ${waiting(row.check)}`);
+    const byCheck = new Map();
+    for (const entry of input.inconclusive ?? [])
+        byCheck.set(entry.check, entry.reason);
+    for (const [check, reason] of [...byCheck].sort())
+        rows.push(`- \`${check}\`: could not conclude: ${inline(reason, redactor)}`);
+    return rows;
+}
+function rendered(parts, shownFindings, shownUntested) {
+    const { findings, untested, runDir } = parts;
+    const more = (n) => `… and ${n} more, truncated, see ${runDir}`;
+    const lines = [...parts.head, "### Findings", ""];
+    if (findings.length === 0)
+        lines.push("No defects found.", "");
+    else {
+        lines.push("| verdict | subject | check | summary |", "| --- | --- | --- | --- |", ...findings.slice(0, shownFindings), "");
+        if (shownFindings < findings.length)
+            lines.push(more(findings.length - shownFindings), "");
+    }
+    if (parts.gapLine !== null)
+        lines.push(parts.gapLine, "");
+    if (untested.length > 0) {
+        lines.push(`<details><summary>Untested (${untested.length})</summary>`, "");
+        if (shownUntested < untested.length)
+            lines.push(`- ${more(untested.length - shownUntested)}`);
+        lines.push(...untested.slice(0, shownUntested), "", "</details>", "");
+    }
+    lines.push(`Full report: \`${runDir}/report.md\``);
+    return `${lines.join("\n")}\n`;
+}
+function fits(text) {
+    return bytes(text) <= STEP_SUMMARY_LIMIT;
+}
+/* The largest count in [0, max] for which `holds` holds, given that it holds at 0. */
+function largest(max, holds) {
+    let low = 0;
+    let high = max;
+    while (low < high) {
+        const mid = Math.ceil((low + high) / 2);
+        if (holds(mid))
+            low = mid;
+        else
+            high = mid - 1;
+    }
+    return low;
+}
+/* The first lines that fit, then a line that says where the rest is. */
+function cut(text, runDir) {
+    const tail = `… truncated, see ${runDir}\n`;
+    let budget = STEP_SUMMARY_LIMIT - bytes(tail);
+    const kept = [];
+    for (const line of text.split("\n")) {
+        budget -= bytes(line) + 1;
+        if (budget < 0)
+            break;
+        kept.push(line);
+    }
+    return `${kept.join("\n")}\n${tail}`;
+}
+/** The run's job summary, at most {@link STEP_SUMMARY_LIMIT} bytes. */
+export function renderStepSummary(input, where) {
+    const gaps = input.findings.filter((finding) => finding.verdict === "COVERAGE_GAP").length;
+    const blocked = input.findings.filter((finding) => finding.verdict === "BLOCKED").length;
+    const parts = {
+        findings: findingRows(input),
+        gapLine: gaps + blocked === 0 ? null : `${gaps} coverage gaps · ${blocked} blocked, listed in report.md`,
+        head: headOf(input),
+        runDir: where.runDir,
+        untested: untestedRows(input),
+    };
+    const whole = rendered(parts, parts.findings.length, parts.untested.length);
+    if (fits(whole))
+        return whole;
+    const untested = largest(parts.untested.length, (n) => fits(rendered(parts, parts.findings.length, n)));
+    if (untested > 0)
+        return rendered(parts, parts.findings.length, untested);
+    const findings = largest(parts.findings.length, (n) => fits(rendered(parts, n, 0)));
+    const shortest = rendered(parts, findings, 0);
+    return fits(shortest) ? shortest : cut(shortest, where.runDir);
+}
+//# sourceMappingURL=step-summary.js.map

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

@@ -0,0 +1,3 @@
+import type { ReportInput } from "./input.ts";
+export declare function renderConsole(input: ReportInput): string;
+//# sourceMappingURL=summary.d.ts.map

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

@@ -0,0 +1,143 @@
+import { runVerdict } from "../../runtime/exit.js";
+import { coverageByCheck, profileExclusionSummary } from "./coverage.js";
+import { scopeConsole } from "./scope.js";
+import { formatBytes, named } from "./text.js";
+import { latency, utf8Total } from "./traffic.js";
+import { byVerdict, findingSubject, VERDICT_LABEL } from "./verdicts.js";
+/** The first line: how much ran, how long it took, and what did not apply. */
+function headline(input, coverage) {
+    const transcript = input.client.transcript;
+    const timing = latency(transcript);
+    return (`  ${input.checksRun.length} checks · ${input.entitiesTested.length} entities · ` +
+        `${transcript.length} requests · ${(input.durationMs / 1000).toFixed(1)}s` +
+        (timing === null ? "" : ` · p95 ${timing.p95}ms`) +
+        ` · ${formatBytes(utf8Total(transcript, "request"))} req · ${formatBytes(utf8Total(transcript, "response"))} res` +
+        (coverage.never.length > 0 ? ` · ${coverage.never.length} checks did not apply` : "") +
+        (coverage.partialSkip.length > 0 ? ` · ${coverage.partialSkip.length} only on some entities` : ""));
+}
+/** Checks that did not apply anywhere, and those that applied only on some entities. */
+function skippedLines(coverage) {
+    const lines = [];
+    if (coverage.never.length > 0) {
+        lines.push("  DID NOT APPLY — no entity had what these need");
+        for (const row of coverage.never) {
+            lines.push(`    ${row.check.padEnd(40)} needs ${row.needs}`);
+        }
+        lines.push("");
+    }
+    if (coverage.partialSkip.length > 0) {
+        lines.push("  APPLIED ONLY ON SOME ENTITIES");
+        for (const row of coverage.partialSkip) {
+            lines.push(`    ${row.check.padEnd(40)} ran ${row.ran > 0 ? `on ${row.ran}` : "per operation"} · skipped on ${row.skipped} (${named(row.skippedEntities)})`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+/** What a blocked check waited on. Every blocked row came from a suppression, so one is there. */
+function blockedBy(input, check) {
+    const suppressed = input.checksSuppressed;
+    return suppressed.find((s) => s.check === check).because;
+}
+/** Checks never run because an earlier check had already failed. */
+function blockedLines(input, coverage) {
+    const lines = [];
+    const blockedAll = coverage.blocked.filter((row) => row.ran === 0);
+    const blockedSome = coverage.blocked.filter((row) => row.ran > 0);
+    if (blockedAll.length > 0) {
+        lines.push("  BLOCKED BY AN EARLIER FAILURE — re-run once the cause is fixed");
+        for (const row of blockedAll)
+            lines.push(`    ${row.check.padEnd(40)} waiting on ${blockedBy(input, row.check)}`);
+        lines.push("");
+    }
+    if (blockedSome.length > 0) {
+        lines.push("  BLOCKED ON SOME ENTITIES");
+        for (const row of blockedSome) {
+            lines.push(`    ${row.check.padEnd(40)} ran on ${row.ran} · blocked on ${row.blocked} (${named(row.blockedEntities)})` +
+                ` · waiting on ${blockedBy(input, row.check)}`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+/** Checks that ran and could not decide, each with the reason it stopped. */
+function inconclusiveLines(input) {
+    const unresolved = input.inconclusive ?? [];
+    if (unresolved.length === 0)
+        return [];
+    const lines = ["  COULD NOT CONCLUDE"];
+    const byCheck = new Map();
+    for (const entry of unresolved)
+        byCheck.set(entry.check, entry.reason);
+    for (const [check, reason] of [...byCheck].sort()) {
+        lines.push(`    ${check}`);
+        lines.push(`      ${reason}`);
+    }
+    lines.push("");
+    return lines;
+}
+/*
+ * Neither of these is a pass, and both were previously invisible.
+ *
+ * A suppressed check was never run: its premise was already broken, so running it would have
+ * reported the same root cause a second time. An inconclusive one ran and could not decide.
+ * Either way the property is *untested*, and a report that shows only findings invites the
+ * reader to assume everything else was verified.
+ */
+function untestedLines(input, coverage) {
+    return [...blockedLines(input, coverage), ...inconclusiveLines(input)];
+}
+/** A section per severity, each finding's subject and summary over its check id. */
+function findingLines(findings) {
+    const lines = [];
+    for (const [findingVerdict, group] of byVerdict(findings)) {
+        lines.push(`  ${VERDICT_LABEL[findingVerdict].toUpperCase()} (${group.length})`);
+        for (const finding of group) {
+            lines.push(`    ${findingSubject(finding).padEnd(16)} ${finding.summary}`);
+            lines.push(`    ${"".padEnd(16)} ${finding.check}`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+/** Console summary — what shows up in CI logs. */
+/*
+ * What seeding noted about an entity's records: ones no read showed stored stand checks down,
+ * and a run that says nothing of it reads as a clean pass.
+ */
+function seedNoteLines(input) {
+    return (input.checkNotes ?? [])
+        .filter((note) => note.check === "world.seed")
+        .map((note) => `  note: ${note.entity} — ${note.note}`);
+}
+export function renderConsole(input) {
+    const { findings } = input;
+    const coverage = coverageByCheck(input);
+    const lines = ["", headline(input, coverage)];
+    const profileLine = profileExclusionSummary(input);
+    if (profileLine !== null)
+        lines.push(`  ${profileLine}`);
+    if (input.scope !== undefined)
+        lines.push(...scopeConsole(input.scope));
+    const verdict = runVerdict(input);
+    lines.push(`  result: ${verdict.outcome} — ${verdict.reason}`);
+    const knownCount = findings.filter((finding) => finding.known !== undefined).length;
+    const fixedCount = input.baseline?.fixed.length ?? 0;
+    if (knownCount > 0 || fixedCount > 0)
+        lines.push(`  baseline: ${knownCount} known · ${fixedCount} fixed`);
+    lines.push(...seedNoteLines(input));
+    lines.push("");
+    /* With no findings at all there is no root cause either. */
+    if (findings.length === 0) {
+        lines.push(verdict.outcome === "failed" ? `  run failed — ${verdict.reason}` : "  no defects found");
+        lines.push("");
+        /* Printed even on a clean run — especially on a clean run. "Nothing found" and "nothing
+         * was looked for" read identically without it. */
+    }
+    else {
+        lines.push(...findingLines(findings));
+    }
+    lines.push(...untestedLines(input, coverage), ...skippedLines(coverage));
+    return lines.join("\n");
+}
+//# sourceMappingURL=summary.js.map

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

@@ -0,0 +1,13 @@
+/** Small text helpers the reports share. */
+/** A file-name-safe stem: lowercase words joined by dashes, at most 60 characters. */
+export declare function slug(text: string): string;
+/** A body as a reader can take it in: text as is, anything else as JSON, cut at `max` characters. */
+export declare function truncate(value: unknown, max?: number): string;
+/** `text` broken into lines of at most `width` characters, at whitespace. */
+export declare function wrap(text: string, width: number): string[];
+/** The entities a run tested, by name while there are few enough to read. */
+export declare function entityList(names: readonly string[]): string;
+/** The first `keep` names, and how many more there are. */
+export declare function named(names: readonly string[], keep?: number): string;
+export declare function formatBytes(n: number): string;
+//# sourceMappingURL=text.d.ts.map

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

@@ -0,0 +1,54 @@
+/** Small text helpers the reports share. */
+/** A file-name-safe stem: lowercase words joined by dashes, at most 60 characters. */
+export function slug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 60);
+}
+/** A body as a reader can take it in: text as is, anything else as JSON, cut at `max` characters. */
+export function truncate(value, max = 600) {
+    const text = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    return text.length > max ? `${text.slice(0, max)}\n… ${text.length - max} more characters` : text;
+}
+/** `text` broken into lines of at most `width` characters, at whitespace. */
+export function wrap(text, width) {
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = "";
+    for (const word of words) {
+        if (current.length + word.length + 1 > width) {
+            lines.push(current);
+            current = word;
+        }
+        else {
+            current = current === "" ? word : `${current} ${word}`;
+        }
+    }
+    if (current !== "")
+        lines.push(current);
+    return lines;
+}
+/** The entities a run tested, by name while there are few enough to read. */
+export function entityList(names) {
+    if (names.length === 0)
+        return "none";
+    if (names.length <= 12)
+        return names.join(", ");
+    return `${names.length} entities`;
+}
+/** The first `keep` names, and how many more there are. */
+export function named(names, keep = 6) {
+    if (names.length <= keep)
+        return names.join(", ");
+    return `${names.slice(0, keep).join(", ")} +${names.length - keep} more`;
+}
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} bytes`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+//# sourceMappingURL=text.js.map

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

@@ -0,0 +1,37 @@
+import type { Exchange } from "../../runtime/exchange.ts";
+import type { ReportInput } from "./input.ts";
+/** Checks named in the summary's cost line. */
+export declare const COST_ROWS = 5;
+/** One check's share of the run: the requests it sent and its wall time. */
+export interface CheckCost {
+    check: string;
+    requests: number;
+    ms: number;
+}
+/** Latency percentiles over the run, and where the slowest request went. */
+export interface Latency {
+    p50: number;
+    p95: number;
+    max: number;
+    slowest: {
+        method: string;
+        path: string;
+    };
+}
+/** Bytes sent, or received, over the whole transcript. */
+export declare function utf8Total(transcript: readonly Exchange[], side: "request" | "response"): number;
+/**
+ * Latency percentiles over the run, and the single slowest request.
+ *
+ * A run is a few hundred requests against every read path an API has, which makes it a usable
+ * sample of where time actually goes — and the slowest exchange is very often a route with a
+ * missing index rather than a slow network. Reported, not asserted: the API tester has no baseline to judge
+ * "too slow" against, and inventing a threshold would produce a finding nobody can act on.
+ */
+export declare function latency(transcript: readonly Exchange[]): Latency | null;
+/**
+ * What each check cost: the requests it sent, counted from the transcript, and its wall time
+ * summed over entities. Costliest first, by requests.
+ */
+export declare function costByCheck(input: ReportInput): CheckCost[];
+//# sourceMappingURL=traffic.d.ts.map