@workerstack/testing 0.0.0-stage → 0.31.0

package/dist/api/report/matrix/graph.js

@@ -0,0 +1,108 @@
+/**
+ * The machine graph of a run's matrix: every entity's slice, the `x-invalidate` links between
+ * entities, the check edges, and how to read them.
+ */
+import { REPORT_SCHEMA_VERSION } from "../render/json.js";
+import { checkCatalog } from "./catalog.js";
+import { invalidateLinks } from "./invalidate.js";
+import { mermaidFromGraph } from "./mermaid.js";
+import { reportRows, rowsOfReport } from "./rows.js";
+import { entitySlice } from "./slice.js";
+import { summaryLine, thesisFor, totalCounts } from "./summary.js";
+import { unique } from "./text.js";
+const READ = {
+    edges: {
+        dependsOn: "if `from` failed, `to` is blocked. Do not treat blocked as a second defect.",
+        invalidate: "a write on `fromEntity` is declared to change `toRoute` on `toEntity`. `cross` is the case the invalidation check probes.",
+        uses: "`to` is a composition check (e.g. query.axes-compose) built from the single-axis check `from`.",
+    },
+    purpose: "How the API tester crossed the entities in this run. Each entity's checks are tracked independently. " +
+        "`invalidate` edges are x-invalidate claims. failed = two projections of the same fact " +
+        "disagreed. blocked = a dependsOn check already failed — not a second defect.",
+    status: {
+        blocked: "not evaluated; a dependsOn check already failed",
+        failed: "two projections of the same fact disagreed — a finding",
+        passed: "tested, and the projections agreed",
+        "out-of-scope": "a targeted run (--ops) did not grade it; it could apply",
+        skipped: "the document does not support this check",
+    },
+};
+/** One entity's graph, given piece by piece. */
+export function buildMatrixGraph(parts) {
+    const catalog = checkCatalog();
+    const entity = { identity: null, name: parts.entity, readSurface: parts.readSurface };
+    return assembleGraph(parts, { entities: [entitySlice(entity, catalog, reportRows(parts))], invalidate: [] }, catalog);
+}
+/** Every entity the run tested; a report that tested none draws one placeholder `entity`. */
+export function buildMatrixGraphFromReport(input) {
+    const catalog = checkCatalog();
+    const rows = reportRows(rowsOfReport(input));
+    const names = input.entitiesTested.length > 0 ? input.entitiesTested : ["entity"];
+    const entities = names.map((name) => entitySlice(sliceEntity(input.model, name), catalog, rows));
+    const origin = { baseUrl: input.baseUrl, generatedAt: input.startedAt.toISOString() };
+    return assembleGraph(origin, { entities, invalidate: invalidateLinks(input.model) }, catalog);
+}
+function sliceEntity(model, name) {
+    const modelEntity = model.entities.get(name);
+    return { identity: modelEntity?.identity ?? null, name, readSurface: modelEntity?.readSurface ?? [] };
+}
+function assembleGraph(origin, { entities, invalidate }, catalog) {
+    const counts = totalCounts(entities);
+    const cross = invalidate.filter((invalidation) => invalidation.cross);
+    const inbound = {};
+    for (const invalidation of cross)
+        inbound[invalidation.toEntity] = (inbound[invalidation.toEntity] ?? 0) + 1;
+    return {
+        kind: "testing.api.matrix",
+        schemaVersion: REPORT_SCHEMA_VERSION,
+        read: READ,
+        summary: summaryLine(entities, counts, cross),
+        thesis: thesisFor(entities, cross),
+        index: {
+            crossClaims: cross.length,
+            entityCount: entities.length,
+            failed: entities.filter((e) => e.counts.failed > 0).map((e) => e.name),
+            inbound,
+            parents: unique(cross.map((l) => l.toEntity)),
+        },
+        baseUrl: origin.baseUrl,
+        generatedAt: origin.generatedAt,
+        counts,
+        entities,
+        invalidate,
+        edges: catalog.edges,
+        mermaid: mermaidFromGraph(entities, invalidate),
+    };
+}
+/** Drop per-check nodes for clean entities so a 2k-entity graph stays loadable. */
+export function compactMatrixGraph(graph) {
+    if (graph.entities.length <= 80)
+        return graph;
+    const cross = graph.invalidate.filter((l) => l.cross);
+    return {
+        ...graph,
+        edges: graph.edges.filter((e) => e.kind === "uses"),
+        entities: graph.entities.map((entity) => entity.counts.failed === 0 && entity.counts.blocked === 0 ? { ...entity, nodes: [] } : entity),
+        invalidate: unique(cross.map((l) => `${l.fromEntity}\0${l.toEntity}`)).map((key) => {
+            const [fromEntity, toEntity] = key.split("\0");
+            return {
+                cross: true,
+                fromEntity,
+                fromOp: `${fromEntity}.create`,
+                toEntity,
+                toRoute: `GET …/${toEntity}`,
+            };
+        }),
+    };
+}
+/** The graph as the run folder's `matrix.json`: compacted, two-space indented, newline-terminated. */
+export function graphJson(graph) {
+    return `${JSON.stringify(compactMatrixGraph(graph), null, 2)}\n`;
+}
+export function renderMatrixGraph(input) {
+    return graphJson(buildMatrixGraphFromReport(input));
+}
+export function renderMatrixGraphFromParts(parts) {
+    return graphJson(buildMatrixGraph(parts));
+}
+//# sourceMappingURL=graph.js.map

package/dist/api/report/matrix/invalidate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The document's `x-invalidate` claims as links between entities: a write on one entity declared to
+ * change a read route, and the entity that route belongs to.
+ */
+import type { InvalidateLink, MatrixModel } from "./types.ts";
+export declare function invalidateLinks(model: MatrixModel): InvalidateLink[];
+//# sourceMappingURL=invalidate.d.ts.map

package/dist/api/report/matrix/invalidate.js

@@ -0,0 +1,30 @@
+/**
+ * The document's `x-invalidate` claims as links between entities: a write on one entity declared to
+ * change a read route, and the entity that route belongs to.
+ */
+export function invalidateLinks(model) {
+    const out = [];
+    for (const op of model.operations) {
+        if (op.entity === null)
+            continue;
+        for (const route of op.invalidates) {
+            const toEntity = model.byRoute.get(route)?.entity ?? owningEntityFromRoute(route, model) ?? op.entity;
+            out.push({
+                cross: toEntity !== op.entity,
+                fromEntity: op.entity,
+                fromOp: op.operationId,
+                toEntity,
+                toRoute: route,
+            });
+        }
+    }
+    return out;
+}
+function owningEntityFromRoute(route, model) {
+    for (const entity of model.entities.values()) {
+        if (entity.readSurface.includes(route))
+            return entity.name;
+    }
+    return null;
+}
+//# sourceMappingURL=invalidate.js.map

package/dist/api/report/matrix/loom.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The poster's loom: the focus entity's cohort as a pin, its reads and single axes as the warp,
+ * and the composition checks built from them as the weft.
+ */
+import type { EntityMatrix } from "./types.ts";
+export declare function loomSvg(focus: EntityMatrix): string;
+//# sourceMappingURL=loom.d.ts.map

package/dist/api/report/matrix/loom.js

@@ -0,0 +1,117 @@
+/**
+ * The poster's loom: the focus entity's cohort as a pin, its reads and single axes as the warp,
+ * and the composition checks built from them as the weft.
+ */
+import { NODE_ORDER } from "./catalog.js";
+import { nodeOf } from "./slice.js";
+import { esc } from "./text.js";
+const COHORT = { x: 130, y: 270 };
+/** Reads and single axes, each tied to the cohort. */
+const WARP = [
+    { id: "tenant.item-not-readable-cross-tenant", x: 130, y: 70 },
+    { id: "list.read-after-write", x: 130, y: 150 },
+    { id: "consistency.projections-agree", x: 130, y: 390 },
+    { id: "filter.equality-selects-exactly-one", x: 390, y: 90 },
+    { id: "sort.order-is-applied", x: 390, y: 180 },
+    { id: "select.projection-honored", x: 390, y: 270 },
+    { id: "search.q-narrows-result", x: 390, y: 360 },
+    { id: "pagination.page-walk-covers-set", x: 390, y: 450 },
+];
+/** Composition checks, each tied to the checks it is built from. */
+const WEFT = [
+    { from: ["filter.equality-selects-exactly-one", "sort.order-is-applied"], id: "query.axes-compose", x: 700, y: 110 },
+    {
+        from: ["filter.equality-selects-exactly-one", "select.projection-honored"],
+        id: "query.filter-and-select-compose",
+        x: 700,
+        y: 220,
+    },
+    {
+        from: ["filter.equality-selects-exactly-one", "search.q-narrows-result"],
+        id: "query.search-and-filter-compose",
+        x: 700,
+        y: 330,
+    },
+    {
+        from: ["filter.equality-selects-exactly-one", "pagination.page-walk-covers-set"],
+        id: "query.filter-selects-from-whole-set",
+        x: 700,
+        y: 450,
+    },
+    {
+        from: ["query.axes-compose", "query.filter-and-select-compose"],
+        id: "query.filter-sort-select-compose",
+        x: 980,
+        y: 160,
+    },
+    {
+        from: ["query.axes-compose", "query.search-and-filter-compose"],
+        id: "query.filter-search-sort-compose",
+        x: 980,
+        y: 270,
+    },
+    {
+        from: ["query.filter-and-select-compose", "query.search-and-filter-compose"],
+        id: "query.filter-search-select-compose",
+        x: 980,
+        y: 380,
+    },
+];
+const LABEL = 'fill="#9aa3b2" font-size="11" letter-spacing="2" font-family="IBM Plex Mono, monospace"';
+export function loomSvg(focus) {
+    const status = (id) => nodeOf(focus, id).status;
+    /* Every `from` names a warp or weft station. */
+    const at = (id) => [...WARP, ...WEFT].find((node) => node.id === id);
+    const lines = [
+        ...WARP.map((node) => link(COHORT, node, status(node.id))),
+        ...WEFT.flatMap((node) => node.from.map((src) => link(at(src), node, status(node.id)))),
+    ];
+    /* Every station is a poster cell. */
+    const stations = [...WARP, ...WEFT].map((pt) => box(pt, NODE_ORDER.find((s) => s.id === pt.id), status(pt.id)));
+    return `<svg viewBox="0 0 1120 540" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Query checks for ${esc(focus.name)}">
+    <text x="48" y="24" ${LABEL}>READS</text>
+    <text x="360" y="24" ${LABEL}>AXES</text>
+    <text x="650" y="24" ${LABEL}>PAIRS</text>
+    <text x="930" y="24" ${LABEL}>TRIPLES</text>
+    ${lines.join("\n")}
+    <circle cx="${COHORT.x}" cy="${COHORT.y}" r="18" fill="#f0c14b"/>
+    <circle cx="${COHORT.x}" cy="${COHORT.y}" r="7" fill="#243044"/>
+    <text x="${COHORT.x}" y="${COHORT.y + 38}" text-anchor="middle" fill="#f0c14b" font-size="13" font-family="Syne, sans-serif" font-weight="700">${esc(focus.name)}</text>
+    <text x="${COHORT.x}" y="${COHORT.y + 54}" text-anchor="middle" fill="#9aa3b2" font-size="10" font-family="IBM Plex Mono, monospace">one cohort</text>
+    ${stations.join("\n")}
+  </svg>`;
+}
+function strokeOf(status) {
+    return status === "failed"
+        ? "#ff6b3d"
+        : status === "passed"
+            ? "#7dcea0"
+            : status === "blocked"
+                ? "#6d7686"
+                : "#3d4758";
+}
+/** A check that did not run is drawn dashed. */
+function dashed(status) {
+    return status === "blocked" || status === "skipped" || status === "out-of-scope";
+}
+function link(from, to, status) {
+    const dash = dashed(status) ? 'stroke-dasharray="5 5"' : "";
+    return `<line x1="${from.x}" y1="${from.y}" x2="${to.x}" y2="${to.y}" stroke="${strokeOf(status)}" stroke-width="1.6" ${dash}/>`;
+}
+/** A station: the cell's label, and under it its hint, `disagreed`, or nothing while it stood down. */
+function box(pt, spec, status) {
+    const caption = status === "failed" ? "disagreed" : status === "blocked" ? "" : spec.hint;
+    const fill = status === "failed" ? "#ff6b3d" : "#1b2332";
+    const ink = status === "failed" ? "#243044" : status === "passed" ? "#7dcea0" : "#9aa3b2";
+    const dash = dashed(status) ? 'stroke-dasharray="3 3"' : "";
+    const w = Math.max(92, spec.label.length * 7.4 + 22);
+    const cap = caption === ""
+        ? ""
+        : `<text x="${pt.x}" y="${pt.y + 28}" text-anchor="middle" fill="#9aa3b2" font-size="10" font-family="IBM Plex Mono, monospace">${esc(caption)}</text>`;
+    return `<g>
+    <rect x="${pt.x - w / 2}" y="${pt.y - 15}" width="${w}" height="30" rx="2" fill="${fill}" stroke="${strokeOf(status)}" ${dash}/>
+    <text x="${pt.x}" y="${pt.y + 5}" text-anchor="middle" fill="${ink}" font-size="12" font-family="Syne, sans-serif" font-weight="700">${esc(spec.label)}</text>
+    ${cap}
+  </g>`;
+}
+//# sourceMappingURL=loom.js.map

package/dist/api/report/matrix/mermaid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The graph as mermaid source: entities and their cross-entity invalidate edges, then the focus
+ * entity's query checks. A crowd of entities draws only the parents that receive writes.
+ */
+import type { EntityMatrix, InvalidateLink } from "./types.ts";
+export declare function mermaidFromGraph(entities: readonly EntityMatrix[], invalidate: readonly InvalidateLink[]): string;
+//# sourceMappingURL=mermaid.d.ts.map

package/dist/api/report/matrix/mermaid.js

@@ -0,0 +1,65 @@
+/**
+ * The graph as mermaid source: entities and their cross-entity invalidate edges, then the focus
+ * entity's query checks. A crowd of entities draws only the parents that receive writes.
+ */
+import { NODE_ORDER, USES } from "./catalog.js";
+import { focusOf, nodeOf } from "./slice.js";
+import { esc } from "./text.js";
+const CLASS_DEFS = [
+    "  classDef passed stroke:#7dcea0",
+    "  classDef failed stroke:#ff6b3d,color:#ff6b3d",
+    "  classDef blocked stroke:#6d7686,stroke-dasharray: 4 4",
+    "  classDef skipped stroke:#3d4758",
+    "  classDef out-of-scope stroke:#3d4758,stroke-dasharray: 2 4",
+];
+/** `id` as a mermaid node id. */
+function mid(id) {
+    return id.replaceAll(/[^A-Za-z0-9_]/g, "_");
+}
+export function mermaidFromGraph(entities, invalidate) {
+    if (entities.length > 24)
+        return crowdMermaid(entities.length, invalidate);
+    return [
+        "flowchart LR",
+        ...entities.map((entity) => `  ${mid(entity.name)}((${esc(entity.name)}))`),
+        ...invalidate.filter((l) => l.cross).map((l) => `  ${mid(l.fromEntity)} -->|invalidates| ${mid(l.toEntity)}`),
+        ...focusLines(focusOf(entities, invalidate)),
+        ...CLASS_DEFS,
+    ].join("\n");
+}
+/** The 24 parents that receive the most cross-entity claims, and a note of how many entities there are. */
+function crowdMermaid(count, invalidate) {
+    const inbound = new Map();
+    for (const invalidation of invalidate) {
+        if (invalidation.cross)
+            inbound.set(invalidation.toEntity, (inbound.get(invalidation.toEntity) ?? 0) + 1);
+    }
+    const parents = [...inbound.entries()].sort((a, b) => b[1] - a[1]).slice(0, 24);
+    return [
+        "flowchart LR",
+        ...parents.map(([parent, n]) => `  ${mid(parent)}(("${parent} ← ${n}"))`),
+        `  note["${count} entities, compact"]`,
+    ].join("\n");
+}
+/** The focus entity's query checks: reads and axes hang off the entity, compositions off their axes. */
+function focusLines(focus) {
+    const lines = [];
+    for (const spec of NODE_ORDER) {
+        const node = nodeOf(focus, spec.id);
+        const sid = mid(`${focus.name}__${spec.id}`);
+        lines.push(`  ${sid}["${spec.label}"]`);
+        if (node.layer === "axis" ||
+            spec.id === "list.read-after-write" ||
+            spec.id === "tenant.item-not-readable-cross-tenant") {
+            lines.push(`  ${mid(focus.name)} --> ${sid}`);
+        }
+        lines.push(`  class ${sid} ${node.status}`);
+    }
+    for (const edge of USES) {
+        const dest = nodeOf(focus, edge.to);
+        const arrow = dest.status === "blocked" || dest.status === "skipped" || dest.status === "out-of-scope" ? "-.->" : "-->";
+        lines.push(`  ${mid(`${focus.name}__${edge.from}`)} ${arrow} ${mid(`${focus.name}__${edge.to}`)}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=mermaid.js.map

package/dist/api/report/matrix/poster.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The run's matrix as a poster: the entities and their invalidate claims, the focus entity's checks
+ * as a loom, and its strips of chips.
+ */
+import type { MatrixGraph, MatrixParts, MatrixReport } from "./types.ts";
+export declare function renderMatrixFromParts(parts: MatrixParts): string;
+export declare function renderMatrixHtml(input: MatrixReport): string;
+/** The poster of a graph built here: one with at least one entity, never compacted. */
+export declare function renderPoster(graph: MatrixGraph): string;
+//# sourceMappingURL=poster.d.ts.map

package/dist/api/report/matrix/poster.js

@@ -0,0 +1,105 @@
+/**
+ * The run's matrix as a poster: the entities and their invalidate claims, the focus entity's checks
+ * as a loom, and its strips of chips.
+ */
+import { entityBand } from "./band.js";
+import { entityCards, forestSummary } from "./cards.js";
+import { buildMatrixGraph, buildMatrixGraphFromReport } from "./graph.js";
+import { loomSvg } from "./loom.js";
+import { focusOf } from "./slice.js";
+import { stripHtml } from "./strips.js";
+import { posterStyle } from "./style.js";
+import { esc } from "./text.js";
+export function renderMatrixFromParts(parts) {
+    return renderPoster(buildMatrixGraph(parts));
+}
+export function renderMatrixHtml(input) {
+    return renderPoster(buildMatrixGraphFromReport(input));
+}
+/** The poster of a graph built here: one with at least one entity, never compacted. */
+export function renderPoster(graph) {
+    return `${posterHead(graph)}${posterBody(graph)}`;
+}
+function posterHead(graph) {
+    const names = graph.entities.length <= 8 ? graph.entities.map((e) => e.name).join(", ") : `${graph.entities.length} entities`;
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>testing api matrix — ${esc(names)}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=Syne:wght@600;700;800&display=swap" rel="stylesheet">
+<style>
+${posterStyle(graph.entities.length)}</style>
+</head>
+`;
+}
+function posterBody(graph) {
+    const multi = graph.entities.length > 1;
+    const crowded = graph.entities.length > 24;
+    const focus = focusOf(graph.entities, graph.invalidate);
+    const surface = focus.readSurface.map((r) => `<code>${esc(r)}</code>`).join("<span> · </span>");
+    return `<body>
+<article class="poster">
+  ${headerHtml(graph, multi)}
+
+  <div class="band">
+    <div class="band-label">entities and x-invalidate</div>
+    ${entityBand(graph)}
+    <div class="legend">
+      <span><i class="swatch passed"></i>own read surface</span>
+      <span><i class="swatch failed"></i>cross-entity invalidate — the check that needs two entities</span>
+    </div>
+  </div>
+
+  ${multi && !crowded ? entityCards(graph) : ""}
+  ${crowded ? forestSummary(graph) : ""}
+
+  <div class="stage">
+    <div class="stage-label">checks — ${esc(focus.name)}</div>
+    ${loomSvg(focus)}
+    <div class="legend">
+      <span><i class="swatch passed"></i>passed</span>
+      <span><i class="swatch failed"></i>disagreed — a finding</span>
+      <span><i class="swatch blocked"></i>blocked — an earlier check it depends on already failed</span>
+      <span><i class="swatch skipped"></i>did not apply — the document has no support for this check</span>
+      ${graph.counts["out-of-scope"] > 0 ? '<span><i class="swatch out-of-scope"></i>out of scope — --ops did not target it</span>' : ""}
+    </div>
+  </div>
+
+  <div class="strips">${crowded ? "" : stripHtml(focus, multi)}</div>
+
+  <footer>
+    <div>${surface === "" ? "" : `read surface ${surface}`}</div>
+    <div>${esc(graph.baseUrl)} · ${esc(graph.generatedAt)}</div>
+  </footer>
+</article>
+</body>
+</html>
+`;
+}
+function headerHtml(graph, multi) {
+    return `<header>
+    <div>
+      <div class="kicker">${multi ? "many entities · invalidate is an edge" : "same fact · many checks"}</div>
+      <h1>${headerTitle(graph)}</h1>
+      <p class="thesis">${esc(graph.thesis)}</p>
+    </div>
+    <div class="counts">
+      <div class="failed"><b>${graph.counts.failed}</b><span>disagreed</span></div>
+      <div class="blocked"><b>${graph.counts.blocked}</b><span>blocked</span></div>
+      <div class="passed"><b>${graph.counts.passed}</b><span>passed</span></div>
+      <div class="skipped"><b>${graph.counts.skipped}</b><span>did not apply</span></div>
+      ${graph.counts["out-of-scope"] > 0 ? `<div class="skipped"><b>${graph.counts["out-of-scope"]}</b><span>out of scope</span></div>` : ""}
+    </div>
+  </header>`;
+}
+function headerTitle(graph) {
+    if (graph.entities.length <= 1)
+        return `${esc(graph.entities[0].name)} was asked<br>through independent projections`;
+    const cross = graph.invalidate.filter((l) => l.cross).length;
+    return `${graph.entities.length} entities, ${cross} cross-entity claim${cross === 1 ? "" : "s"}`;
+}
+//# sourceMappingURL=poster.js.map

package/dist/api/report/matrix/rows.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Report rows looked up per cell. Each list is indexed once per graph by check id, then by entity,
+ * rather than scanned for every cell of every entity.
+ */
+import type { CheckRow, MatrixFinding, MatrixReport, MatrixRows } from "./types.ts";
+/** A list's rows by check id, then by entity key; `*` holds rows that name no entity. */
+export type RowIndex<T> = ReadonlyMap<string, ReadonlyMap<string, ReadonlyArray<{
+    at: number;
+    row: T;
+}>>>;
+/** Every list of a report, indexed, and the set of checks that ran. */
+export interface ReportRows {
+    findings: RowIndex<MatrixFinding>;
+    suppressed: RowIndex<CheckRow & {
+        because: string;
+    }>;
+    skipped: RowIndex<CheckRow>;
+    outOfScope: RowIndex<CheckRow>;
+    ran: ReadonlySet<string>;
+}
+/** A report's lists as the matrix reads them: a list the report left out is empty. */
+export declare function rowsOfReport(report: MatrixReport): Required<MatrixRows>;
+export declare function reportRows(rows: MatrixRows): ReportRows;
+export declare function indexRows<T extends CheckRow>(rows: readonly T[]): RowIndex<T>;
+/** The rows about `check` on `entity`, in report order. A row naming no entity applies to every entity. */
+export declare function rowsFor<T extends CheckRow>(index: RowIndex<T>, check: string, entity: string): readonly T[];
+/**
+ * The matrix draws the primary document's entities. A secondary origin may have an entity of the
+ * same name, and its findings belong to it, not to the primary one.
+ */
+export declare function onPrimary(finding: {
+    origin?: string;
+}): boolean;
+//# sourceMappingURL=rows.d.ts.map

package/dist/api/report/matrix/rows.js

@@ -0,0 +1,68 @@
+/**
+ * Report rows looked up per cell. Each list is indexed once per graph by check id, then by entity,
+ * rather than scanned for every cell of every entity.
+ */
+/** A report's lists as the matrix reads them: a list the report left out is empty. */
+export function rowsOfReport(report) {
+    return {
+        checksOutOfScope: report.checksOutOfScope ?? [],
+        checksRun: report.checksRun,
+        checksSkipped: report.checksSkipped ?? [],
+        checksSuppressed: report.checksSuppressed ?? [],
+        findings: report.findings,
+    };
+}
+export function reportRows(rows) {
+    return {
+        findings: indexRows(rows.findings),
+        outOfScope: indexRows(rows.checksOutOfScope ?? []),
+        ran: new Set(rows.checksRun),
+        skipped: indexRows(rows.checksSkipped),
+        suppressed: indexRows(rows.checksSuppressed),
+    };
+}
+/** The text before the first `separator`, or all of it. */
+function head(value, separator) {
+    const at = value.indexOf(separator);
+    return at === -1 ? value : value.slice(0, at);
+}
+/** The entity a report row is about: `table`, `table · fixture` and `table.field` are all `table`. */
+function entityKey(value) {
+    return head(head(value, " · "), ".");
+}
+export function indexRows(rows) {
+    const index = new Map();
+    for (const [at, row] of rows.entries()) {
+        const byEntity = index.get(row.check) ?? new Map();
+        index.set(row.check, byEntity);
+        const key = row.entity === undefined ? "*" : entityKey(row.entity);
+        const list = byEntity.get(key) ?? [];
+        list.push({ at, row });
+        byEntity.set(key, list);
+    }
+    return index;
+}
+/** The rows about `check` on `entity`, in report order. A row naming no entity applies to every entity. */
+export function rowsFor(index, check, entity) {
+    const byEntity = index.get(check);
+    if (byEntity === undefined)
+        return [];
+    const own = byEntity.get(entityKey(entity)) ?? [];
+    const everyone = byEntity.get("*") ?? [];
+    const merged = everyone.length === 0 ? own : [...own, ...everyone].sort((a, b) => a.at - b.at);
+    return merged.map((entry) => entry.row).filter((row) => matchesEntity(row.entity, entity));
+}
+/**
+ * The matrix draws the primary document's entities. A secondary origin may have an entity of the
+ * same name, and its findings belong to it, not to the primary one.
+ */
+export function onPrimary(finding) {
+    return finding.origin === undefined || finding.origin === "";
+}
+function matchesEntity(value, entity) {
+    if (value === undefined || value === entity)
+        return true;
+    const lead = head(value, " · ");
+    return lead === entity || lead.startsWith(`${entity}.`);
+}
+//# sourceMappingURL=rows.js.map

package/dist/api/report/matrix/slice.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One entity's slice of the matrix: a node per cataloged check with the status the report gave
+ * it, the counts, and the failed checks no other failure explains.
+ */
+import type { CheckCatalog } from "./catalog.ts";
+import { type ReportRows } from "./rows.ts";
+import type { EntityMatrix, InvalidateLink, MatrixGraphNode } from "./types.ts";
+/** The entity a slice is cut for, as the document's model has it. */
+export interface SliceEntity {
+    name: string;
+    readSurface: string[];
+    identity: string | null;
+}
+export declare function entitySlice(entity: SliceEntity, catalog: CheckCatalog, rows: ReportRows): EntityMatrix;
+/**
+ * The node a slice holds for check `id`. Every slice carries a node for every cataloged check, and
+ * the poster and the mermaid source only ask for cataloged ones.
+ */
+export declare function nodeOf(entity: EntityMatrix, id: string): MatrixGraphNode;
+/**
+ * The slice the detail views draw: the first entity whose writes reach another entity, else the
+ * first entity. Every graph holds at least one entity.
+ */
+export declare function focusOf(entities: readonly EntityMatrix[], invalidate: readonly InvalidateLink[]): EntityMatrix;
+//# sourceMappingURL=slice.d.ts.map

package/dist/api/report/matrix/slice.js

@@ -0,0 +1,62 @@
+/**
+ * One entity's slice of the matrix: a node per cataloged check with the status the report gave
+ * it, the counts, and the failed checks no other failure explains.
+ */
+import { isRootCause } from "../../runtime/finding.js";
+import { onPrimary, rowsFor } from "./rows.js";
+export function entitySlice(entity, catalog, rows) {
+    const nodes = catalog.ids.map((id) => graphNode({ entity: entity.name, id }, catalog, rows));
+    const counts = { blocked: 0, failed: 0, passed: 0, "out-of-scope": 0, skipped: 0 };
+    for (const node of nodes)
+        counts[node.status] += 1;
+    const failedSet = new Set(nodes.filter((n) => n.status === "failed").map((n) => n.id));
+    const roots = [...failedSet].filter((id) => !catalog.edges.some((e) => e.kind === "dependsOn" && e.to === id && failedSet.has(e.from)));
+    return { counts, identity: entity.identity, name: entity.name, nodes, readSurface: entity.readSurface, roots };
+}
+function graphNode({ entity, id }, catalog, rows) {
+    /* The catalog's ids are the ids of its strips: every one has a strip. */
+    const strip = catalog.stripOf.get(id);
+    const node = { group: strip.title, id, layer: strip.layer, status: statusFor(entity, id, rows) };
+    const need = catalog.needs.get(id);
+    if (need !== undefined)
+        node.needs = need;
+    const suppressed = rowsFor(rows.suppressed, id, entity)[0];
+    if (suppressed !== undefined)
+        node.because = suppressed.because;
+    const finding = rowsFor(rows.findings, id, entity).find(onPrimary);
+    if (finding !== undefined) {
+        node.summary = finding.summary;
+        node.verdict = finding.verdict;
+    }
+    return node;
+}
+function statusFor(entity, id, rows) {
+    const finding = rowsFor(rows.findings, id, entity).find((f) => onPrimary(f) && isRootCause(f));
+    if (finding !== undefined)
+        return "failed";
+    if (rowsFor(rows.suppressed, id, entity).length > 0)
+        return "blocked";
+    if (rowsFor(rows.skipped, id, entity).length > 0)
+        return "skipped";
+    if (rowsFor(rows.outOfScope, id, entity).length > 0)
+        return "out-of-scope";
+    if (rows.ran.has(id))
+        return "passed";
+    return "skipped";
+}
+/**
+ * The node a slice holds for check `id`. Every slice carries a node for every cataloged check, and
+ * the poster and the mermaid source only ask for cataloged ones.
+ */
+export function nodeOf(entity, id) {
+    return entity.nodes.find((n) => n.id === id);
+}
+/**
+ * The slice the detail views draw: the first entity whose writes reach another entity, else the
+ * first entity. Every graph holds at least one entity.
+ */
+export function focusOf(entities, invalidate) {
+    const writer = entities.find((e) => invalidate.some((l) => l.cross && l.fromEntity === e.name));
+    return writer ?? entities[0];
+}
+//# sourceMappingURL=slice.js.map