@codyswann/lisa 2.352.0 → 3.0.0

package/expo/copy-overwrite/scripts/bdd/discover.mjs

@@ -0,0 +1,502 @@
+/**
+ * Test-file DISCOVERY for the BDD gate.
+ *
+ * Validating what a manifest DECLARES can only ever find defects in the
+ * declarations. A test file nobody declared is invisible to that check, which
+ * is precisely how undeclared end-to-end specs came to sit on default branches
+ * with a green gate above them. This module walks the project's own declared
+ * roots, extracts each test's evidence string, and hands the caller the specs
+ * that no mapping and no exclusion accounts for.
+ *
+ * Nothing here names a runner, a directory, or a file extension: roots,
+ * extensions and the evidence grammar are per-runner CONTRACT DATA
+ * (`testDiscovery` in the coverage map), and the runner→platform pairing is
+ * derived from `runnerPlatforms`. A gate with `e2e/` compiled into it cannot
+ * see a project that keeps its flows anywhere else — the exact reason a
+ * subflow directory was structurally invisible to the fork this replaces.
+ *
+ * @module scripts/bdd/discover
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { listFiles, posix, resolveInsideRepo } from "./parse.mjs";
+
+/**
+ * Build one defect record, always naming the entity it is about.
+ * @param {string} code - Stable machine-readable defect code.
+ * @param {string} message - Operator-readable description.
+ * @param {string} subject - The entity the finding is about.
+ * @returns {{code: string, message: string, subject: string}} The defect.
+ */
+const defect = (code, message, subject) => ({ code, message, subject });
+
+/**
+ * The evidence grammars a project may choose from, as SOURCE CONSTANTS.
+ *
+ * An allowlist, never a project-supplied regular expression: the coverage map
+ * is repo data an author edits, and compiling a pattern out of it would hand
+ * that author the gate's own execution. `call-title` reads a titled test call
+ * (`test("...")`, `it.skip('...')`); `line-field` reads a leading document
+ * field (`name: ...`), which is how flow-style runners title a file.
+ */
+export const EVIDENCE_KINDS = Object.freeze(["call-title", "line-field"]);
+
+/** A JavaScript identifier, the only shape a declared function name may take. */
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+/** A document field name, the only shape a declared field may take. */
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+
+/**
+ * True for a plain JSON object.
+ * @param {unknown} value - Candidate.
+ * @returns {boolean} Whether it is a non-array object.
+ */
+const isObject = value =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/**
+ * True for a non-empty array whose every entry passes a test.
+ * @param {unknown} value - Candidate.
+ * @param {(entry: unknown) => boolean} predicate - Entry test.
+ * @returns {boolean} Whether the array is usable.
+ */
+const isListOf = (value, predicate) =>
+  Array.isArray(value) && value.length > 0 && value.every(predicate);
+
+/**
+ * The problems that make one runner's discovery block unusable.
+ *
+ * Every one of these is refused rather than skipped. Skipping a malformed
+ * block would silently disable discovery for that runner — the same
+ * one-character fail-open the coverage floor already refuses.
+ * @param {string} runner - Runner name the block is keyed under.
+ * @param {unknown} config - The raw block.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {string[]} Reasons, empty when the block is usable.
+ */
+function configProblems(runner, config, contract) {
+  if (!contract.runnerPlatforms?.[runner]) {
+    return [`names runner ${runner}, which runnerPlatforms does not declare`];
+  }
+  if (!isObject(config)) return ["is not a JSON object"];
+  return [
+    ...rootProblems(config.roots),
+    ...(isListOf(config.extensions, entry => isExtension(entry))
+      ? []
+      : ['extensions must be a non-empty array of suffixes like ".spec.ts"']),
+    ...(config.ignore === undefined ||
+    (Array.isArray(config.ignore) &&
+      config.ignore.every(entry => typeof entry === "string"))
+      ? []
+      : ["ignore must be an array of repo-relative path prefixes"]),
+    ...evidenceProblems(config.evidence),
+  ];
+}
+
+/**
+ * Whether a declared extension is a usable suffix.
+ * @param {unknown} entry - Candidate extension.
+ * @returns {boolean} Whether it is a dot-prefixed suffix.
+ */
+function isExtension(entry) {
+  return typeof entry === "string" && entry.startsWith(".") && entry.length > 1;
+}
+
+/**
+ * Reject unusable or escaping roots.
+ * @param {unknown} roots - Declared roots.
+ * @returns {string[]} Reasons, empty when usable.
+ */
+function rootProblems(roots) {
+  if (
+    !isListOf(roots, entry => typeof entry === "string" && entry.length > 0)
+  ) {
+    return ["roots must be a non-empty array of repo-relative directories"];
+  }
+  return roots
+    .filter(
+      root =>
+        path.isAbsolute(root) ||
+        /^[a-zA-Z]:/.test(root) ||
+        root.split(/[\\/]/).includes("..")
+    )
+    .map(root => `root ${root} must be repo-relative and must not traverse up`);
+}
+
+/**
+ * Reject an evidence grammar the gate does not implement, or one whose
+ * parameters would end up inside a regular expression unvalidated.
+ * @param {unknown} evidence - Declared evidence grammar.
+ * @returns {string[]} Reasons, empty when usable.
+ */
+function evidenceProblems(evidence) {
+  if (!isObject(evidence)) return ["evidence must be a JSON object"];
+  if (!EVIDENCE_KINDS.includes(evidence.kind)) {
+    return [
+      `evidence.kind ${JSON.stringify(evidence.kind)} is not one of ${EVIDENCE_KINDS.join(", ")}`,
+    ];
+  }
+  if (evidence.kind === "call-title") {
+    return isListOf(
+      evidence.functions,
+      entry => typeof entry === "string" && IDENTIFIER.test(entry)
+    )
+      ? []
+      : ["evidence.functions must be a non-empty array of function names"];
+  }
+  return typeof evidence.field === "string" && FIELD_NAME.test(evidence.field)
+    ? []
+    : ["evidence.field must be a document field name"];
+}
+
+/**
+ * Read and validate the whole `testDiscovery` block.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {{configs: Map<string, object>, defects: object[]}} Usable configs and refusals.
+ */
+function readDiscovery(contract) {
+  const raw = contract.testDiscovery;
+  const configs = new Map();
+  const subject = "coverage-map.testDiscovery";
+  if (raw === undefined) return { configs, defects: [] };
+  if (!isObject(raw)) {
+    return {
+      configs,
+      defects: [
+        defect(
+          "discovery-invalid",
+          `${subject} must be a JSON object keyed by runner`,
+          subject
+        ),
+      ],
+    };
+  }
+  const defects = [];
+  for (const [runner, config] of Object.entries(raw)) {
+    if (runner.startsWith("_")) continue;
+    const problems = configProblems(runner, config, contract);
+    for (const problem of problems) {
+      defects.push(
+        defect(
+          "discovery-invalid",
+          `${subject}.${runner} ${problem}`,
+          `${subject}.${runner}`
+        )
+      );
+    }
+    if (problems.length === 0) configs.set(runner, config);
+  }
+  return { configs, defects };
+}
+
+/**
+ * Every titled test call in a source file, with the title taken VERBATIM from
+ * the source.
+ *
+ * A template-literal title is kept exactly as written — `${error.name}` and
+ * all. Rewriting or truncating it is how the fork this replaces produced
+ * evidence strings that matched nothing, which authors then had to paper over
+ * with exclusions for artifacts of the parser rather than of the repo. The
+ * verbatim text is a real substring of the file, so a mapping or exclusion
+ * naming it stays falsifiable exactly like any other evidence string.
+ * @param {string} source - File contents.
+ * @param {readonly string[]} functions - Declared test-function names.
+ * @returns {{evidence: string, dynamic: boolean}[]} Discovered titles in source order.
+ */
+function callTitles(source, functions) {
+  const pattern = new RegExp(
+    String.raw`\b(?:${functions.join("|")})(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*\s*\(\s*` +
+      String.raw`(?:"((?:[^"\\\n]|\\.)*)"|'((?:[^'\\\n]|\\.)*)'|\x60([^\x60]*)\x60)`,
+    "g"
+  );
+  const found = [];
+  for (const match of source.matchAll(pattern)) {
+    const template = match[3];
+    const evidence = match[1] ?? match[2] ?? template;
+    if (evidence === undefined || evidence.length === 0) continue;
+    found.push({
+      evidence,
+      dynamic: template !== undefined && template.includes("${"),
+    });
+  }
+  return found;
+}
+
+/**
+ * The leading document field a flow-style runner titles a file with.
+ *
+ * When the field is absent the file itself is the discovered unit and carries
+ * NO evidence — inventing a title from the filename would fabricate a string
+ * that appears nowhere in the file, which is the opposite of falsifiable.
+ * @param {string} source - File contents.
+ * @param {string} field - Declared field name.
+ * @returns {{evidence: string|null, dynamic: boolean}[]} Exactly one entry.
+ */
+function lineField(source, field) {
+  const match = new RegExp(String.raw`^\s*${field}:\s*(\S.*?)\s*$`, "m").exec(
+    source
+  );
+  return [{ evidence: match ? match[1] : null, dynamic: false }];
+}
+
+/**
+ * Walk one runner's declared roots and extract its tests.
+ * @param {object} input - Root, runner, its config, and the contract.
+ * @returns {object[]} Discovered specs.
+ */
+function discoverRunner({ root, runner, config, contract }) {
+  const platforms = [...(contract.runnerPlatforms?.[runner] ?? [])].sort();
+  const ignore = config.ignore ?? [];
+  const specs = [];
+  for (const declaredRoot of config.roots) {
+    for (const file of filesUnder(root, declaredRoot, config)) {
+      const relative = posix(path.relative(root, file));
+      if (ignore.some(prefix => relative.startsWith(prefix))) continue;
+      const source = fs.readFileSync(file, "utf8");
+      for (const found of extract(source, config.evidence)) {
+        specs.push({ runner, platforms, file: relative, ...found });
+      }
+    }
+  }
+  return specs;
+}
+
+/**
+ * Extract evidence from one file under the declared grammar.
+ * @param {string} source - File contents.
+ * @param {object} evidence - The declared evidence grammar.
+ * @returns {{evidence: string|null, dynamic: boolean}[]} Discovered entries.
+ */
+function extract(source, evidence) {
+  return evidence.kind === "call-title"
+    ? callTitles(source, evidence.functions)
+    : lineField(source, evidence.field);
+}
+
+/**
+ * List candidate files under one declared root.
+ *
+ * A root that does not exist yet is not an error — a project may declare where
+ * its flows WILL live. A root that resolves outside the repo is refused, on
+ * the same reasoning as a mapping path: repo data must never be able to read
+ * the runner's filesystem.
+ * @param {string} root - Repo root.
+ * @param {string} declaredRoot - One declared root.
+ * @param {object} config - The runner's discovery config.
+ * @returns {string[]} Absolute paths.
+ */
+function filesUnder(root, declaredRoot, config) {
+  const directory = path.join(root, declaredRoot);
+  if (!fs.existsSync(directory)) return [];
+  if (!resolveInsideRepo(root, declaredRoot).path) return [];
+  return listFiles(directory, file =>
+    config.extensions.some(extension => file.endsWith(extension))
+  );
+}
+
+/**
+ * Discover every test file the project's own configuration points at.
+ * @param {object} input - Repo root and the parsed contract.
+ * @returns {object} Specs, configured runners, declared roots, and refusals.
+ */
+export function discoverSpecs({ root, contract }) {
+  const { configs, defects } = readDiscovery(contract);
+  const specs = [];
+  const roots = [];
+  for (const [runner, config] of configs) {
+    roots.push(...config.roots.map(entry => posix(entry).replace(/\/+$/, "")));
+    specs.push(...discoverRunner({ root, runner, config, contract }));
+  }
+  return {
+    specs: specs.sort((a, b) =>
+      `${a.file}${a.evidence ?? ""}`.localeCompare(
+        `${b.file}${b.evidence ?? ""}`
+      )
+    ),
+    runners: [...configs.keys()].sort(),
+    roots: [...new Set(roots)].sort(),
+    defects,
+  };
+}
+
+/**
+ * Whether one map entry accounts for one discovered spec.
+ *
+ * An entry accounts for a spec when it names the same file AND its evidence
+ * string CONTAINS that spec's title. Containment in that direction is
+ * deliberate: an author may map `test("title"` or the bare title, but one
+ * short string can never come to account for every test in a file — which
+ * would rebuild the fail-open this check exists to close. A file-level entry
+ * (an exclusion with no evidence) accounts for the whole file, and so does any
+ * entry naming a file whose discovered unit has no title of its own.
+ * @param {object} entry - A mapping or exclusion.
+ * @param {object} spec - A discovered spec.
+ * @param {boolean} fileLevelAllowed - Whether a missing evidence string covers the file.
+ * @returns {boolean} Whether the spec is accounted for.
+ */
+function accountsFor(entry, spec, fileLevelAllowed) {
+  if (entry.file !== spec.file) return false;
+  if (typeof entry.evidence !== "string" || entry.evidence.length === 0) {
+    return fileLevelAllowed;
+  }
+  return spec.evidence === null || entry.evidence.includes(spec.evidence);
+}
+
+/**
+ * Whether any mapping or exclusion discloses a discovered spec.
+ * @param {object} spec - A discovered spec.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {boolean} Whether it is disclosed.
+ */
+export function isDisclosed(spec, contract) {
+  return (
+    (contract.mappings ?? []).some(mapping =>
+      accountsFor(mapping, spec, false)
+    ) ||
+    (contract.exclusions ?? []).some(exclusion =>
+      accountsFor(exclusion, spec, true)
+    )
+  );
+}
+
+/**
+ * Defects for every discovered spec the contract never mentions.
+ * @param {readonly object[]} specs - Discovered specs.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {object[]} Defects found.
+ */
+function undisclosedDefects(specs, contract) {
+  return specs
+    .filter(spec => !isDisclosed(spec, contract))
+    .map(spec =>
+      defect(
+        "spec-undisclosed",
+        `${spec.file}${spec.evidence === null ? "" : ` :: ${JSON.stringify(spec.evidence)}`} is discovered by runner ${spec.runner} but named by no mapping and no exclusion. Map it to a scenario, or record an exclusion with a reason.`,
+        spec.file
+      )
+    );
+}
+
+/**
+ * Defects for exclusions that no longer excuse anything.
+ *
+ * An exclusion is a standing claim that a real test aligns to no product
+ * behavior. Once its file is gone, its title has been renamed, or no
+ * configured root even covers it, the claim is about nothing — and a pile of
+ * such claims is how "unmapped test" stops meaning anything.
+ * @param {object} input - Root, contract, and the discovery result.
+ * @returns {object[]} Defects found.
+ */
+function exclusionDefects({ root, contract, discovery }) {
+  const defects = [];
+  for (const [index, exclusion] of (contract.exclusions ?? []).entries()) {
+    const at = `coverage-map.exclusions[${index}]`;
+    const subject = typeof exclusion.file === "string" ? exclusion.file : at;
+    defects.push(...exclusionMetadata(exclusion, at, subject));
+    if (typeof exclusion.file !== "string" || exclusion.file.length === 0) {
+      continue;
+    }
+    defects.push(
+      ...exclusionStale({ root, exclusion, discovery, at, subject })
+    );
+  }
+  return defects;
+}
+
+/**
+ * The bookkeeping an exclusion owes whoever has to re-litigate it.
+ * @param {object} exclusion - Raw exclusion entry.
+ * @param {string} at - Location label.
+ * @param {string} subject - Finding subject.
+ * @returns {object[]} Defects found.
+ */
+function exclusionMetadata(exclusion, at, subject) {
+  const defects = [];
+  if (typeof exclusion.file !== "string" || exclusion.file.length === 0) {
+    defects.push(defect("exclusion-metadata", `${at}: names no file`, subject));
+  }
+  if (typeof exclusion.reason !== "string" || exclusion.reason.trim() === "") {
+    defects.push(
+      defect(
+        "exclusion-metadata",
+        `${at}: has no reason; an exclusion with no stated reason is an undisclosed test with extra steps`,
+        subject
+      )
+    );
+  }
+  return defects;
+}
+
+/**
+ * The three ways an exclusion outlives what it excused.
+ * @param {object} input - Root, the exclusion, discovery, and labels.
+ * @returns {object[]} Defects found.
+ */
+function exclusionStale({ root, exclusion, discovery, at, subject }) {
+  const resolved = resolveInsideRepo(root, exclusion.file);
+  if (!resolved.path) {
+    return [
+      defect(
+        "exclusion-stale",
+        `${at}: ${exclusion.file} — ${resolved.error}; retire the exclusion or restore the file`,
+        subject
+      ),
+    ];
+  }
+  if (!discovery.roots.some(entry => exclusion.file.startsWith(`${entry}/`))) {
+    return [
+      defect(
+        "exclusion-stale",
+        `${at}: ${exclusion.file} is covered by no configured discovery root (${discovery.roots.join(", ") || "none declared"}), so the exclusion suppresses nothing`,
+        subject
+      ),
+    ];
+  }
+  return discovery.specs.some(spec => accountsFor(exclusion, spec, true))
+    ? []
+    : [
+        defect(
+          "exclusion-stale",
+          `${at}: no discovered test in ${exclusion.file} matches ${JSON.stringify(exclusion.evidence)}`,
+          subject
+        ),
+      ];
+}
+
+/**
+ * Every disclosure defect: undeclared specs and dead exclusions.
+ * @param {object} input - Root, contract, and the discovery result.
+ * @returns {object[]} Defects found.
+ */
+export function disclosureDefects({ root, contract, discovery }) {
+  return [
+    ...undisclosedDefects(discovery.specs, contract),
+    ...exclusionDefects({ root, contract, discovery }),
+  ];
+}
+
+/**
+ * The runners that declared a platform but no way to find their tests.
+ *
+ * Reported only where absence must fail, exactly like a missing coverage
+ * floor: a runner with no discovery block contributes nothing to the
+ * inventory, and a silent zero there is indistinguishable from a clean repo.
+ * @param {object} contract - Parsed coverage map.
+ * @param {object} discovery - The discovery result.
+ * @returns {object[]} Defects found.
+ */
+export function missingDiscoveryDefects(contract, discovery) {
+  return Object.keys(contract.runnerPlatforms ?? {})
+    .filter(runner => !runner.startsWith("_"))
+    .filter(runner => !discovery.runners.includes(runner))
+    .sort()
+    .map(runner =>
+      defect(
+        "discovery-missing",
+        `enforced mode: runner ${runner} declares platforms but testDiscovery says nothing about where its tests live, so no undeclared test of that runner can ever be found`,
+        `coverage-map.testDiscovery.${runner}`
+      )
+    );
+}

package/expo/copy-overwrite/scripts/bdd/envelope.mjs

@@ -39,11 +39,17 @@ const ENVELOPE_MODULE_PATHS = Object.freeze([
  * Everything here is a contract-QUALITY defect: the manifest is legible and
  * the adoption state is coherent, the contract just is not clean yet. Codes
  * about adoption integrity itself (bootstrap-metadata, bootstrap-expired,
- * adoption-drift, config-*) are deliberately absent, so they always fail.
+ * adoption-drift, config-*, discovery-invalid) are deliberately absent, so
+ * they always fail: a malformed discovery block would silently switch off the
+ * only check that can see an undeclared test, exactly as a quoted coverage
+ * floor silently switches off the ratchet.
  */
 export const WARNABLE_DEFECT_CODES = Object.freeze([
   "baseline",
+  "discovery-missing",
   "empty-contract",
+  "exclusion-metadata",
+  "exclusion-stale",
   "execution-results",
   "floor-missing",
   "floor-ratchet",
@@ -61,6 +67,7 @@ export const WARNABLE_DEFECT_CODES = Object.freeze([
   "scenario-platform",
   "scenario-provenance",
   "scenario-steps",
+  "spec-undisclosed",
   "tracker-missing",
   "tracker-orphan",
   "waiver-duplicate",
@@ -205,6 +212,8 @@ export function buildSummary({ adoptionState, report, defects, filesWritten }) {
     traceabilityPercentage: report.traceability.overall.percentage,
     executionEvidenceSupplied: report.execution.supplied,
     mappedTests: report.execution.mappedTests,
+    testsDiscovered: report.testInventory.discovered,
+    testsUndisclosed: report.testInventory.undisclosed.length,
     ...executionCounts(report.execution),
     waivedObligations: report.waived.count,
     floorOk: report.floor.ok,

package/expo/copy-overwrite/scripts/bdd/render.mjs

@@ -111,6 +111,47 @@ function floorTable(report) {
   return `| Platform | Committed floor | Current | Status |\n|---|---:|---:|---|\n${rows}`;
 }
 
+/**
+ * Render the discovered-test inventory: what the roots hold, and what of it
+ * the contract never mentions.
+ *
+ * The undisclosed list is printed in full rather than counted. A count is a
+ * number somebody can grow accustomed to; a named file with a named test is a
+ * thing somebody has to either map or excuse.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown section body.
+ */
+function inventorySection(report) {
+  const inventory = report.testInventory;
+  if (inventory.runners.length === 0) {
+    return "**No `testDiscovery` roots are declared**, so no test file was walked and an undeclared test cannot be found here. In enforced mode this is a `discovery-missing` defect.";
+  }
+  const rows =
+    inventory.undisclosed
+      .map(
+        item =>
+          `| ${cell(item.runner)} | \`${cell(item.file)}\` | ${item.evidence === null ? "*(file has no title)*" : cell(item.evidence)} |`
+      )
+      .join("\n") || "| — | — | None |";
+  return `${inventory.discovered} tests discovered under ${inventory.roots.map(root => `\`${cell(root)}\``).join(", ")}; ${inventory.disclosed} are named by a mapping or an exclusion. ${inventory.dynamicTitles} carry a computed (template-literal) title, taken verbatim from the source — a runner result cannot be joined to those by title.\n\n| Runner | File | Test not named by the contract |\n|---|---|---|\n${rows}`;
+}
+
+/**
+ * Render the exclusion ledger: tests deliberately aligned to no behavior.
+ * @param {object} report - The coverage report.
+ * @returns {string} Markdown table.
+ */
+function exclusionTable(report) {
+  const rows =
+    report.testInventory.exclusions
+      .map(
+        entry =>
+          `| \`${cell(entry.file)}\` | ${entry.evidence === null ? "*(whole file)*" : cell(entry.evidence)} | ${cell(entry.reason ?? "**unstated**")} |`
+      )
+      .join("\n") || "| — | — | None |";
+  return `| File | Test | Reason it aligns to no product behavior |\n|---|---|---|\n${rows}`;
+}
+
 /**
  * Group the remaining gaps by feature.
  * @param {object} report - The coverage report.
@@ -186,6 +227,18 @@ ${report.waived.note}
 
 ${waiverTable(report)}
 
+## Discovered tests the contract does not mention
+
+${report.testInventory.note}
+
+${inventorySection(report)}
+
+## Tests deliberately aligned to no behavior
+
+Every row here is a standing claim that a real test proves nothing about product behavior. An exclusion whose file is gone, whose title was renamed, or that no discovery root covers is a defect, not a permanent excuse.
+
+${exclusionTable(report)}
+
 ## Traceability to work items
 
 ${report.trackers.scenariosWithTag} of ${report.scenarios.declared} scenarios carry a tracker tag; ${report.trackers.scenariosWithoutTag} do not. Tags are validated for syntax and against this repo's declared trackers; the gate never contacts a tracker, so an unreachable issue can never block a merge.

package/expo/copy-overwrite/scripts/bdd/report.mjs

@@ -21,6 +21,50 @@ import {
   runnersByPlatform,
   trackerUrl,
 } from "./contract.mjs";
+import { isDisclosed } from "./discover.mjs";
+
+/** An empty discovery result, for callers that do not walk the tree. */
+const NO_DISCOVERY = Object.freeze({ specs: [], runners: [], roots: [] });
+
+/**
+ * Summarize what walking the project's declared roots actually found.
+ *
+ * Traceability answers "is every declared behavior automated". This answers
+ * the other direction — "is every automated test accounted for" — and the two
+ * are not the same question: a repo can be at 100% traceability while carrying
+ * end-to-end tests nobody has ever mapped to a behavior.
+ * @param {object} discovery - The discovery result.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {object} The report's `testInventory` block.
+ */
+function buildTestInventory(discovery, contract) {
+  const undisclosed = discovery.specs.filter(
+    spec => !isDisclosed(spec, contract)
+  );
+  return {
+    note: "Tests found by walking the roots declared in testDiscovery. A discovered test must be named by a mapping or by an exclusion carrying a reason; anything else is an undisclosed test, not a clean repo.",
+    runners: discovery.runners,
+    roots: discovery.roots,
+    discovered: discovery.specs.length,
+    disclosed: discovery.specs.length - undisclosed.length,
+    dynamicTitles: discovery.specs.filter(spec => spec.dynamic).length,
+    undisclosed: undisclosed.map(spec => ({
+      runner: spec.runner,
+      platforms: spec.platforms,
+      file: spec.file,
+      evidence: spec.evidence,
+    })),
+    exclusions: (contract.exclusions ?? [])
+      .map(exclusion => ({
+        file: exclusion.file ?? null,
+        evidence: exclusion.evidence ?? null,
+        reason: exclusion.reason ?? null,
+      }))
+      .sort((a, b) =>
+        `${a.file}${a.evidence}`.localeCompare(`${b.file}${b.evidence}`)
+      ),
+  };
+}
 
 /**
  * Summarize a subset of obligations against the covered set.
@@ -310,6 +354,7 @@ export function buildReport({
   runs,
   platforms,
   unresolved = new Set(),
+  discovery = NO_DISCOVERY,
 }) {
   const platformRunners = runnersByPlatform(contract.runnerPlatforms);
   const declared = declaredObligations(scenarios, platformRunners);
@@ -340,6 +385,7 @@ export function buildReport({
       byRunner: byRunnerSummary(contract, obligations, coveredKeys),
     },
     execution: buildExecution(contract.mappings ?? [], runs),
+    testInventory: buildTestInventory(discovery, contract),
     waived: waivedSummary(contract, scenarios, declared, waivedKeys),
     floor: evaluateFloor(contract, byPlatform, platforms),
     trackers: buildTrackerIndex(scenarios, contract.trackers),