@ecoma-io/archkeep 0.13.0 → 0.15.0

package/src/report/sarif.mjs

@@ -680,6 +680,31 @@ export function sarifCoverageGapNotification(gap) {
       },
     };
   }
+  // The accepted counterpart: the same bounded sample, saying the state is a
+  // recorded acceptance (`coverage.unowned`) rather than an open question —
+  // still a warning, because an accepted hole is still a hole, and this face
+  // must not be the one that stops saying so.
+  if (gap.kind === "accepted-unowned-files") {
+    const files = gap.files ?? [];
+    const languages = gap.languages ?? [];
+    const spans = languages.length > 0 ? ` (${languages.join(", ")})` : "";
+    const shown = files.slice(0, UNOWNED_SAMPLE_LIMIT);
+    const remaining = files.length - shown.length;
+    const listed =
+      shown.length > 0
+        ? `: ${shown.join(", ")}${remaining > 0 ? `, and ${remaining} more` : ""}`
+        : "";
+    return {
+      level: "warning",
+      message: {
+        text:
+          `${files.length} tracked analyzable file${files.length === 1 ? "" : "s"}${spans} ` +
+          `owned by no project — accepted as coverage holes by the policy's coverage.unowned, ` +
+          `so no boundary verdict in this run covers ` +
+          `${files.length === 1 ? "it" : "them"}${listed}`,
+      },
+    };
+  }
   return {
     level: "warning",
     message: {
@@ -931,6 +956,261 @@ export function buildSarifLog({
   };
 }
 
+/**
+ * One introduced boundary-violation entry, at one of its head sites, as a
+ * SARIF result — the `delta` verb's rendering of the same rule catalogue
+ * `sarifResult` resolves into.
+ *
+ * `ruleId` is the entry's `messageId`, spelled exactly, so a delta upload and
+ * a `check` upload name the same rule for the same law — no new descriptors,
+ * and no second catalogue. The classifier's entry carries no rendered upstream
+ * message (`../commands/delta-classify.mjs` keeps identity and evidence, not
+ * prose), so the message is composed here from the facts the entry does carry:
+ * the classification, both sides' occurrence counts, the edge, and the
+ * constraint row — never empty, because GitHub rejects a result whose
+ * `message.text` is.
+ *
+ * One result per HEAD site: an introduced violation exists at head by
+ * construction (`headCount > 0`), and the head sites are the lines a reviewer
+ * of the change can act on — a base site names code the checkout under review
+ * may no longer contain.
+ *
+ * A waived-introduced entry is still a result (reported, not gating —
+ * `../commands/delta.mjs`'s fold), tagged with the same `accepted` vocabulary
+ * `sarifResult` uses for a waived violation, so one consumer query covers both
+ * verbs' uploads.
+ *
+ * @param {{messageId: string, sourceProject: string|null, target: string,
+ *   targetIsSpecifier: boolean, constraint: object|null, baseCount: number,
+ *   headCount: number, reason?: string, waived?: boolean,
+ *   waivedBy?: {expiresAt?: string, reason?: string}}} entry One `introduced`
+ *   entry from `classifyViolations` (`../commands/delta-classify.mjs`).
+ * @param {{file: string, line: number, column: number, specifier?: string,
+ *   kind?: string}} site One of the entry's head sites — 1-based, as the
+ *   analysis records carry them.
+ * @returns {object}
+ */
+export function sarifDeltaResult(entry, site) {
+  const target = entry.targetIsSpecifier
+    ? `specifier ${JSON.stringify(entry.target)}`
+    : entry.target;
+  const text =
+    `Introduced by this change: ${entry.messageId} — ` +
+    `from ${entry.sourceProject ?? "(no project)"} to ${target} ` +
+    `(${entry.baseCount} occurrence${entry.baseCount === 1 ? "" : "s"} at base, ` +
+    `${entry.headCount} at head)` +
+    `${entry.reason ? ` — ${entry.reason}` : ""}. ` +
+    `Constraint: ${formatConstraint(entry.constraint)}`;
+  return {
+    ruleId: entry.messageId,
+    ruleIndex: MESSAGE_IDS.indexOf(entry.messageId),
+    level: "error",
+    message: { text },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: { uri: toUriReference(site.file) },
+          region: { startLine: site.line, startColumn: site.column },
+        },
+      },
+    ],
+    properties: {
+      delta: "introduced",
+      baseCount: entry.baseCount,
+      headCount: entry.headCount,
+      sourceProject: entry.sourceProject,
+      target: entry.target,
+      // The same vocabulary `sarifResult` uses for a waived violation: the
+      // result is still an error (an accepted violation is still a violation),
+      // and the properties say why it does not gate.
+      ...(entry.waived === true
+        ? {
+            accepted: true,
+            acceptedUntil: entry.waivedBy?.expiresAt,
+            acceptedReason: entry.waivedBy?.reason,
+          }
+        : {}),
+    },
+  };
+}
+
+/**
+ * The `delta` verb's SARIF log: the INTRODUCED buckets as results, everything
+ * the classification could not answer as tool-execution notifications.
+ *
+ * Results are introduced entries only — the classified boundary violations
+ * (`sarifDeltaResult`, waived ones included and tagged) and the introduced
+ * custom-rule findings, the latter through the same `sarifCustomRuleResult`
+ * and end-of-catalogue descriptors `check`'s log uses, so a custom finding
+ * resolves in `sarifRules(customCatalogue)` here exactly as it does there.
+ * Resolved and unchanged entries are deliberately NOT results: this log is
+ * uploaded against the head checkout, and an annotation for a violation the
+ * change resolved would mark code that no longer contains it.
+ *
+ * The notification lane is the load-bearing half. `delta` exits 3 on any
+ * `unknown` entry (`../commands/delta.mjs`'s fold), and every one of those
+ * rides here — a violation, unresolvable-record, or custom-rule item whose
+ * identity could not be stated — so an exit-3 delta can never upload a log
+ * byte-identical to a clean run's, the same guarantee `buildSarifLog` keeps
+ * for `check`'s no-verdict lanes. Coverage notes (policy drift, dirty trees,
+ * skipped or removed custom rules) and introduced unresolvable records ride
+ * the same lane: none is a verdict, and dropping any of them is the silent
+ * direction (`../../../../AGENTS.md`).
+ *
+ * `executionSuccessful` stays `true` on every status — the run completed and
+ * classified; the findings are results, not tool errors — and `columnKind`
+ * states the analyzers' real UTF-16 convention, both for the reasons the
+ * module header gives.
+ *
+ * @param {{delta: {violations: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]},
+ *   unresolvable: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]},
+ *   customRules?: {findings: {introduced: object[], resolved?: object[],
+ *     unchanged?: object[], unknown: object[]}}},
+ *   coverage: {notes?: string[]},
+ *   customCatalogue?: {ruleId: string, rule: string, findingId: string,
+ *     message: string}[]}} run The `deltaCommand` result's `delta` and
+ *   `coverage`, plus the head-declared custom-rule catalogue
+ *   (`../commands/custom-rules.mjs`'s `customRulesForDelta`) — passed
+ *   separately because the envelope deliberately does not carry it.
+ * @returns {object} A SARIF 2.1.0 log, ready to `JSON.stringify`.
+ */
+export function buildDeltaSarifLog({ delta, coverage, customCatalogue = [] }) {
+  const customRuleIndex = new Map(
+    customCatalogue.map((entry, index) => [entry.ruleId, CUSTOM_RULE_INDEX_BASE + index]),
+  );
+  const customIntroduced = delta.customRules?.findings.introduced ?? [];
+  const results = [
+    ...delta.violations.introduced.flatMap((entry) =>
+      entry.headSites.map((site) => sarifDeltaResult(entry, site)),
+    ),
+    ...customIntroduced.flatMap((entry) =>
+      entry.headSites.map((site) => {
+        const rendered = sarifCustomRuleResult(
+          {
+            id: entry.ruleId,
+            message:
+              `Introduced by this change: custom rule finding ${entry.ruleId} ` +
+              `(${entry.baseCount} occurrence${entry.baseCount === 1 ? "" : "s"} at base, ` +
+              `${entry.headCount} at head)` +
+              `${entry.reason ? ` — ${entry.reason}` : ""}` +
+              `${typeof entry.message === "string" && entry.message !== "" ? `: ${entry.message}` : ""}`,
+            ...(typeof site.file === "string" ? { sourceFile: site.file } : {}),
+            ...(typeof site.line === "number" ? { line: site.line } : {}),
+            ...(typeof site.column === "number" ? { column: site.column } : {}),
+            ...(entry.project === null ? {} : { project: entry.project }),
+          },
+          // `?? -1` for the same reason `buildSarifLog` gives: an introduced
+          // finding whose id its own head catalogue does not declare cannot
+          // arrive here, and a regression in that guarantee must be a visibly
+          // broken index rather than an `undefined` GitHub ignores.
+          customRuleIndex.get(entry.ruleId) ?? -1,
+        );
+        return {
+          ...rendered,
+          properties: {
+            ...(rendered.properties ?? {}),
+            delta: "introduced",
+            baseCount: entry.baseCount,
+            headCount: entry.headCount,
+          },
+        };
+      }),
+    ),
+  ];
+  const toolExecutionNotifications = [
+    ...delta.violations.unknown.map((entry) => ({
+      level: "warning",
+      message: {
+        text: `delta could not classify a violation — ${entry.reason}. The run reaches no verdict.`,
+      },
+    })),
+    ...delta.unresolvable.unknown.map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `delta could not classify an unresolvable import site — ${entry.reason}. ` +
+          `The run reaches no verdict.`,
+      },
+    })),
+    ...(delta.customRules?.findings.unknown ?? []).map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `delta could not classify a custom-rule item` +
+          `${typeof entry.rule === "string" ? ` (rule "${entry.rule}")` : ""} — ` +
+          `${entry.reason}. The run reaches no verdict.`,
+      },
+    })),
+    // Introduced unresolvable records: sites the change added whose target
+    // analysis could not resolve. Never results — no rule reached a verdict
+    // about them — but a change that adds them must not upload the log a
+    // change that adds nothing would.
+    ...delta.unresolvable.introduced.map((entry) => ({
+      level: "warning",
+      message: {
+        text:
+          `This change introduces ${entry.headCount - entry.baseCount} unresolvable import ` +
+          `site${entry.headCount - entry.baseCount === 1 ? "" : "s"} for specifier ` +
+          `${JSON.stringify(entry.specifier)} (${entry.kind || "unknown kind"})` +
+          `${entry.sourceProject === null ? "" : ` in ${entry.sourceProject}`} — ` +
+          `no rule reached a verdict about ${entry.headCount - entry.baseCount === 1 ? "it" : "them"}`,
+      },
+      locations: (entry.headSites ?? [])
+        .filter((site) => typeof site.file === "string")
+        .map((site) => ({
+          physicalLocation: {
+            artifactLocation: { uri: toUriReference(site.file) },
+            ...(typeof site.line === "number"
+              ? {
+                  region: {
+                    startLine: site.line,
+                    ...(typeof site.column === "number" ? { startColumn: site.column } : {}),
+                  },
+                }
+              : {}),
+          },
+        })),
+    })),
+    ...(coverage.notes ?? []).map((note) => ({
+      level: "warning",
+      message: { text: `Coverage note: ${note}` },
+    })),
+  ];
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: { driver: { name: "archkeep", rules: sarifRules(customCatalogue) } },
+        columnKind: "utf16CodeUnits",
+        results,
+        invocations: [
+          {
+            // True even on exit 1 or 3: the classification completed and said
+            // what it could not answer — the same reasoning `buildSarifLog`
+            // states for `check`.
+            executionSuccessful: true,
+            toolExecutionNotifications,
+          },
+        ],
+      },
+    ],
+  };
+}
+
+/**
+ * The delta SARIF log as the bytes to write — pretty-printed with a trailing
+ * newline, the same presentation `formatSarif` gives `check`'s log.
+ *
+ * @param {Parameters<typeof buildDeltaSarifLog>[0]} run
+ * @returns {string}
+ */
+export function formatDeltaSarif(run) {
+  return `${JSON.stringify(buildDeltaSarifLog(run), null, 2)}\n`;
+}
+
 /**
  * The SARIF log as the bytes to write — pretty-printed with a trailing newline,
  * so a file that lands in a diff or a log stays readable.

package/src/report/snapshot-text.mjs

@@ -0,0 +1,123 @@
+/**
+ * Formatters two snapshot-transition reports share — `history-text.mjs` and
+ * `evolution-text.mjs` render the same transition shape (a graph diff, notes,
+ * and a short kind label), and a second copy of these helpers is where the
+ * two renders would drift: one day "code drift" means one thing in `history`
+ * and another in `evolution`, and no gate compares rendered prose.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences in a name or value before
+ * it is printed, so a crafted project/tag/edge name cannot inject escape
+ * sequences into a consumer's terminal (`SECURITY.md`). Real project names are
+ * ordinary characters and pass through untouched; only C0 control characters
+ * (which includes the ESC byte) and DEL become visible escapes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * One project as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{name: string, root: string, tags: string[]}} project
+ * @returns {string}
+ */
+export function formatProject(project) {
+  const tags =
+    project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
+  return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
+}
+
+/**
+ * One edge as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function formatEdge(edge) {
+  return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
+}
+
+/**
+ * One metadata change as a line, same shape as `diff-text.mjs`.
+ *
+ * @param {{field: string, baseline: *, head: *}} change
+ * @returns {string}
+ */
+export function formatChange(change) {
+  const formatValue = (v) => {
+    if (Array.isArray(v)) return v.length > 0 ? v.map((x) => sanitize(x)).join(", ") : "(none)";
+    if (v === null || v === undefined) return "(none)";
+    return sanitize(String(v));
+  };
+  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
+}
+
+/**
+ * How the architecture actually changed between two snapshots: the added and
+ * removed projects and edges rendered as one line each. Changed projects
+ * render their changed fields beneath the project line, like `diff`.
+ *
+ * @param {object} changes The `computeDiff` payload.
+ * @returns {string[]}
+ */
+export function formatChanges(changes) {
+  const lines = [];
+  if (changes.addedProjects.length > 0) {
+    const word = changes.addedProjects.length === 1 ? "project" : "projects";
+    lines.push(`+ ${changes.addedProjects.length} added ${word}`);
+    for (const project of changes.addedProjects) lines.push(formatProject(project));
+  }
+  if (changes.removedProjects.length > 0) {
+    const word = changes.removedProjects.length === 1 ? "project" : "projects";
+    lines.push(`- ${changes.removedProjects.length} removed ${word}`);
+    for (const project of changes.removedProjects) lines.push(formatProject(project));
+  }
+  if (changes.changedProjects.length > 0) {
+    const word = changes.changedProjects.length === 1 ? "project" : "projects";
+    lines.push(`~ ${changes.changedProjects.length} changed ${word}`);
+    for (const project of changes.changedProjects) {
+      lines.push(`  ${project.name}`);
+      for (const change of project.changes) lines.push(formatChange(change));
+    }
+  }
+  if (changes.addedEdges.length > 0) {
+    const word = changes.addedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`+ ${changes.addedEdges.length} added ${word}`);
+    for (const edge of changes.addedEdges) lines.push(formatEdge(edge));
+  }
+  if (changes.removedEdges.length > 0) {
+    const word = changes.removedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`- ${changes.removedEdges.length} removed ${word}`);
+    for (const edge of changes.removedEdges) lines.push(formatEdge(edge));
+  }
+  return lines;
+}
+
+/**
+ * Classifies one transition into the short "kind" a reader skims for.
+ *
+ * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
+ *   providerChanged: boolean}} transition
+ * @returns {string}
+ */
+export function transitionKind(transition) {
+  if (transition.architectureChanged) return "architecture";
+  if (transition.providerChanged) return "provider";
+  if (transition.policyChanged === true) return "policy";
+  if (transition.codeDrift) return "code drift";
+  return "unchanged";
+}

package/src/report/text.mjs

@@ -588,6 +588,7 @@ const UNOWNED_SAMPLE_LIMIT = 10;
 function formatCoverageGap(gap) {
   if (gap.kind === "unregistered-plugin") return formatUnregisteredPluginGap(gap);
   if (gap.kind === "unowned-files") return formatUnownedFilesGap(gap);
+  if (gap.kind === "accepted-unowned-files") return formatAcceptedUnownedFilesGap(gap);
   return `⚠ coverage gap "${gap.kind}" — part of this workspace is outside what this run covered`;
 }
 
@@ -655,6 +656,41 @@ function formatUnownedFilesGap(gap) {
   );
 }
 
+/**
+ * The accepted counterpart of the gap above: unowned files the boundary
+ * policy's `coverage.unowned` rows accept (`../commands/check.mjs`,
+ * `../commands/coverage-acceptance.mjs`). An accepted hole is still a hole,
+ * so the section renders on every run the acceptance is in force, with the
+ * same bounded sample the warning uses — what it no longer does is ask the
+ * reader a question someone already answered, which is the warning's job.
+ * The reasons live on the accepting rows, and `archkeep waivers` is the
+ * surface that names each row with its reason and current coverage; this
+ * face points there rather than restating them.
+ *
+ * @param {{languages?: string[], files: string[]}} gap
+ * @returns {string}
+ */
+function formatAcceptedUnownedFilesGap(gap) {
+  const files = gap.files ?? [];
+  const count = files.length;
+  const languages = gap.languages ?? [];
+  const spans = languages.length > 0 ? ` (${languages.join(", ")})` : "";
+  const shown = files.slice(0, UNOWNED_SAMPLE_LIMIT);
+  const remaining = count - shown.length;
+  const lines = shown.map((file) => `${CONTINUED}${file}`);
+  if (remaining > 0) {
+    lines.push(`${CONTINUED}… and ${remaining} more — the full list is in --format json`);
+  }
+  const them = count === 1 ? "it" : "them";
+  return (
+    `⚠ ${count} tracked analyzable file${count === 1 ? "" : "s"}${spans} ` +
+    `owned by no project — accepted as coverage holes by the policy's coverage.unowned, ` +
+    `so no boundary verdict covers ${them}\n` +
+    `${lines.join("\n")}\n` +
+    `${DETAIL}each accepting row's reason: archkeep waivers`
+  );
+}
+
 /**
  * The policy-identity line — which law this run enforced — rendered FIRST,
  * ahead of every verdict below it: a reader has to know WHICH law produced a

package/src/report/trajectory-text.mjs

@@ -0,0 +1,143 @@
+/**
+ * The terminal report for the `trajectory` command: the aggregate signals
+ * across a snapshot history, with what each number is a claim about.
+ *
+ * Every line states counts, never judgments — the report has no "better", no
+ * score, no direction adjective. The header names the observation basis (one
+ * observation is one stored graph snapshot, not a commit or a day), an
+ * insufficient history says so instead of printing zeros, and the disclosures
+ * line prints even when every count is zero, so a reader can tell "nothing
+ * was incomparable" from "the report forgot to say".
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences before anything reaches
+ * the terminal (`SECURITY.md`) — the same sanitation every other renderer
+ * applies. Only paths and snapshot filenames are printed here; project and
+ * edge identities stay aggregated precisely so nothing name-shaped needs to.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * A delta with its sign, so +2 / -1 / 0 read as movement rather as bare
+ * magnitudes. Zero prints unsigned — it is the absence of movement, not a
+ * positive one.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function signed(value) {
+  if (value === null) return "n/a";
+  if (value > 0) return `+${value}`;
+  return `${value}`;
+}
+
+/**
+ * A count that is either established or explicitly unavailable. `null`
+ * renders as `n/a` beside the reason the header already stated — never as a
+ * zero that would claim a measurement.
+ *
+ * @param {number|null} value
+ * @returns {string}
+ */
+function counted(value) {
+  return value === null ? "n/a" : `${value}`;
+}
+
+/**
+ * One structural axis as one line: endpoints, then events, then persistence.
+ *
+ * @param {{first: number, current: number, delta: number|null,
+ *   addedEvents: number|null, removedEvents: number|null,
+ *   changedEvents: number|null, introduced: number|null, resolved: number|null,
+ *   persistent: number|null}} axis
+ * @param {boolean} withChanged Whether the axis carries a changed-event count
+ *   (projects do; edges do not — a type flip is remove+add under the triple
+ *   identity).
+ * @returns {string}
+ */
+function formatAxis(axis, withChanged) {
+  const parts = [
+    `first ${axis.first}`,
+    `current ${axis.current}`,
+    `delta ${signed(axis.delta)}`,
+    `added ${counted(axis.addedEvents)}`,
+    `removed ${counted(axis.removedEvents)}`,
+  ];
+  if (withChanged) parts.push(`changed ${counted(axis.changedEvents)}`);
+  parts.push(
+    `introduced ${counted(axis.introduced)}`,
+    `resolved ${counted(axis.resolved)}`,
+    `persistent ${counted(axis.persistent)}`,
+  );
+  return parts.join(" · ");
+}
+
+/**
+ * The whole trajectory report.
+ *
+ * @param {{trajectory: {dir: string, observations: {count: number, basis: string,
+ *   first: string|null, last: string|null, withProvenance: number,
+ *   dirtyProvenance: number}, available: boolean, unavailableReason: string|null,
+ *   transitions: {count: number, architecture: number, policy: number,
+ *     provider: number, codeDrift: number, incomparable: number, unchanged: number},
+ *   disclosures: {policyOneSided: number, provenanceOneSided: number, crossRepo: number},
+ *   projects: object, edges: object}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatTrajectoryReport({ trajectory, coverage }) {
+  const sections = [];
+
+  const observations = trajectory.observations;
+  sections.push(`trajectory  ${trajectory.dir}`);
+  sections.push(
+    `${observations.count} observation${observations.count === 1 ? "" : "s"} ` +
+      `(${observations.basis}), ${trajectory.transitions.count} transition${
+        trajectory.transitions.count === 1 ? "" : "s"
+      }`,
+  );
+
+  if (!trajectory.available) {
+    // Named, not implied: a one-snapshot history cannot show movement, and
+    // every derived number below stays n/a rather than reading as a zero.
+    sections.push(
+      `✖ ${trajectory.unavailableReason}: a trajectory needs at least two observations — ` +
+        "derived values are unavailable, not zero",
+    );
+  }
+
+  const t = trajectory.transitions;
+  sections.push(
+    `signals  architecture ${t.architecture} · policy ${t.policy} · provider ${t.provider} · ` +
+      `code drift ${t.codeDrift} · incomparable ${t.incomparable} · unchanged ${t.unchanged}`,
+  );
+  sections.push(`projects  ${formatAxis(trajectory.projects, true)}`);
+  sections.push(`edges     ${formatAxis(trajectory.edges, false)}`);
+
+  const d = trajectory.disclosures;
+  sections.push(
+    `disclosures  policy incomparable ${d.policyOneSided} · provenance incomparable ` +
+      `${d.provenanceOneSided} · cross-repo ${d.crossRepo} · ` +
+      `dirty captures ${observations.dirtyProvenance} · with provenance ${observations.withProvenance}`,
+  );
+
+  for (const note of coverage.notes) {
+    sections.push(sanitize(note));
+  }
+
+  return sections.join("\n");
+}

package/src/report/waivers-text.mjs

@@ -16,7 +16,11 @@
 
 /**
  * @param {{waivers: object[], covered: number, expired: number, stale: number,
- *   suppressions: object[], suppressed: number}} result
+ *   suppressions: object[], suppressed: number,
+ *   unownedAcceptances?: {path: string, reason: string, covered: number}[]}} result
+ *   `unownedAcceptances` is present exactly when the policy declares
+ *   `coverage.unowned` (`../commands/waivers.mjs`) — the third surface, and
+ *   the one the acceptances' reasons live on.
  * @returns {string}
  */
 export function formatWaiversReport({
@@ -26,10 +30,17 @@ export function formatWaiversReport({
   stale,
   suppressions,
   suppressed,
+  unownedAcceptances,
 }) {
   const sections = [];
+  const acceptances = unownedAcceptances ?? [];
 
-  if (waivers.length === 0 && suppressions.length === 0) {
+  if (waivers.length === 0 && suppressions.length === 0 && acceptances.length === 0) {
+    // The all-empty claim may only be made when all THREE surfaces were
+    // measured and found empty — a declared `coverage.unowned` row is an
+    // acceptance on the table exactly as a suppression is, and this line
+    // reading "nothing is accepted" over one would be the module header's
+    // defect on a third table.
     return `no waivers — every boundary is enforced, nothing is being accepted temporarily or permanently`;
   }
 
@@ -96,5 +107,27 @@ export function formatWaiversReport({
     }
   }
 
+  if (acceptances.length > 0) {
+    // The coverage half of the table: each row accepts unowned FILES rather
+    // than a verdict — `check` still states the files as an accepted
+    // coverage gap, and this section is where their reasons live
+    // (`../commands/coverage-acceptance.mjs`). A row covering nothing is
+    // named the way a stale waiver is; `check` refuses it outright.
+    const totalCovered = acceptances.reduce((sum, row) => sum + row.covered, 0);
+    sections.push(
+      `${acceptances.length} coverage acceptance${acceptances.length === 1 ? "" : "s"} ` +
+        `(coverage.unowned) on the table — currently accepting ${totalCovered} unowned ` +
+        `file${totalCovered === 1 ? "" : "s"} as recorded coverage holes`,
+    );
+
+    for (const row of acceptances) {
+      const coverage =
+        row.covered === 0
+          ? "covers no unowned file right now — the files it accepted may be owned by a project now"
+          : `currently covers ${row.covered} unowned file${row.covered === 1 ? "" : "s"}`;
+      sections.push([`- ${row.path}: ${coverage}`, `  reason: ${row.reason}`].join("\n"));
+    }
+  }
+
   return sections.join("\n\n");
 }