@codyswann/lisa 2.346.0 → 2.348.0

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

@@ -0,0 +1,210 @@
+/**
+ * Waiver validation.
+ *
+ * A waiver is a dated IOU, never coverage. It leaves the denominator, so the
+ * bookkeeping it owes is strict: who owns it, why, which ticket retires it,
+ * and when it expires. An IOU nobody owns and that never comes due is just a
+ * quieter coverage gap.
+ *
+ * @module scripts/bdd/waivers
+ */
+import { parseTrackerTag, runnersByPlatform } from "./contract.mjs";
+
+const defect = (code, message) => ({ code, message });
+
+/** Bookkeeping every waiver owes whoever has to re-litigate it later. */
+const REQUIRED_FIELDS = [
+  "reason",
+  "owner",
+  "ticket",
+  "recordedAt",
+  "expiresAt",
+];
+
+/** ISO calendar date, the only accepted date shape. */
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/**
+ * Validate every waiver in the coverage map.
+ * @param {object} input - Scenarios, contract, and the evaluation date.
+ * @returns {object[]} Defects found.
+ */
+export function validateWaivers({ scenarios, contract, today }) {
+  const byId = new Map(scenarios.map(scenario => [scenario.id, scenario]));
+  const platformRunners = runnersByPlatform(contract.runnerPlatforms);
+  const mapped = mappedKeys(contract);
+  const seen = new Set();
+  const defects = [];
+  for (const [index, waiver] of (contract.platformWaivers ?? []).entries()) {
+    const at = `coverage-map.platformWaivers[${index}] ${waiver.scenario ?? "(no scenario)"}`;
+    const scenario = byId.get(waiver.scenario);
+    const blocking = blockingError(waiver, scenario, at);
+    if (blocking) {
+      defects.push(blocking);
+      continue;
+    }
+    defects.push(...metadataDefects(waiver, at, today));
+    defects.push(...runnerDefects(waiver, platformRunners, at));
+    defects.push(...platformDefects(waiver, scenario, { mapped, seen }, at));
+  }
+  return defects;
+}
+
+/**
+ * Every `SCENARIO:platform` a mapping already claims.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {Set<string>} Claimed keys.
+ */
+function mappedKeys(contract) {
+  return new Set(
+    (contract.mappings ?? []).flatMap(mapping =>
+      (mapping.platforms ?? []).map(
+        platform => `${mapping.scenario}:${platform}`
+      )
+    )
+  );
+}
+
+/**
+ * The one problem that makes a waiver unusable, so its other checks are moot.
+ * @param {object} waiver - Raw waiver entry.
+ * @param {object|undefined} scenario - The scenario it names, if it exists.
+ * @param {string} at - Location label.
+ * @returns {object|undefined} The blocking defect, or undefined.
+ */
+function blockingError(waiver, scenario, at) {
+  if (!scenario) {
+    return defect(
+      "waiver-orphan",
+      `${at}: names a scenario that does not exist`
+    );
+  }
+  if (!scenario.required) {
+    return defect(
+      "waiver-excluded",
+      `${at}: scenario is already out of the denominator (${scenario.lifecycle.join(", ")})`
+    );
+  }
+  if (!Array.isArray(waiver.platforms) || waiver.platforms.length === 0) {
+    return defect("waiver-platform", `${at}: claims no platforms`);
+  }
+  return undefined;
+}
+
+/**
+ * Require the full owner/reason/ticket/expiry record, and refuse an expired
+ * waiver — the time-box is what stops an IOU from becoming permanent.
+ * @param {object} waiver - Raw waiver entry.
+ * @param {string} at - Location label.
+ * @param {string} today - ISO date the run is evaluated against.
+ * @returns {object[]} Defects found.
+ */
+function metadataDefects(waiver, at, today) {
+  const defects = REQUIRED_FIELDS.filter(field => !waiver[field]).map(field =>
+    defect("waiver-metadata", `${at}: has no ${field}`)
+  );
+  for (const field of ["recordedAt", "expiresAt"]) {
+    if (waiver[field] && !ISO_DATE.test(waiver[field])) {
+      defects.push(
+        defect(
+          "waiver-metadata",
+          `${at}: ${field} must be an ISO date (YYYY-MM-DD)`
+        )
+      );
+    }
+  }
+  if (
+    waiver.ticket &&
+    !parseTrackerTag(String(waiver.ticket).replace(/^@/, ""))
+  ) {
+    defects.push(
+      defect(
+        "waiver-metadata",
+        `${at}: ticket ${waiver.ticket} is not a valid tracker reference`
+      )
+    );
+  }
+  if (
+    waiver.expiresAt &&
+    ISO_DATE.test(waiver.expiresAt) &&
+    waiver.expiresAt < today
+  ) {
+    defects.push(
+      defect(
+        "waiver-expired",
+        `${at}: expired on ${waiver.expiresAt}; retire it or re-authorize it`
+      )
+    );
+  }
+  return defects;
+}
+
+/**
+ * A waiver says a RUNNER cannot decide a behavior, so when a platform has
+ * more than one configured runner the waiver must name which one.
+ * @param {object} waiver - Raw waiver entry.
+ * @param {Map<string, string[]>} platformRunners - Platform → configured runners.
+ * @param {string} at - Location label.
+ * @returns {object[]} Defects found.
+ */
+function runnerDefects(waiver, platformRunners, at) {
+  const ambiguous = waiver.platforms.filter(
+    platform => (platformRunners.get(platform) ?? []).length > 1
+  );
+  if (!waiver.runner) {
+    return ambiguous.length === 0
+      ? []
+      : [
+          defect(
+            "waiver-runner",
+            `${at}: ${ambiguous.join(", ")} has multiple configured runners, so the waiver must name one`
+          ),
+        ];
+  }
+  return waiver.platforms
+    .filter(
+      platform => !(platformRunners.get(platform) ?? []).includes(waiver.runner)
+    )
+    .map(platform =>
+      defect(
+        "waiver-runner",
+        `${at}: runner ${waiver.runner} does not cover ${platform}`
+      )
+    );
+}
+
+/**
+ * Per-platform problems on one usable waiver, recording accepted keys so the
+ * duplicate check works across waivers.
+ * @param {object} waiver - Raw waiver entry.
+ * @param {object} scenario - The scenario it names.
+ * @param {{mapped: Set<string>, seen: Set<string>}} keys - Claimed and already-seen keys.
+ * @param {string} at - Location label.
+ * @returns {object[]} Defects found.
+ */
+function platformDefects(waiver, scenario, { mapped, seen }, at) {
+  const defects = [];
+  for (const platform of waiver.platforms) {
+    const key = `${waiver.scenario}:${platform}`;
+    if (!scenario.platforms.includes(platform)) {
+      defects.push(
+        defect(
+          "waiver-platform",
+          `${at}: claims undeclared platform ${platform}`
+        )
+      );
+      continue;
+    }
+    if (mapped.has(key)) {
+      defects.push(
+        defect("waiver-masks-mapping", `${at}: ${key} already has a mapping`)
+      );
+    }
+    if (seen.has(key))
+      defects.push(
+        defect("waiver-duplicate", `${at}: duplicate waiver for ${key}`)
+      );
+    seen.add(key);
+  }
+  return defects;
+}

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

@@ -0,0 +1,278 @@
+#!/usr/bin/env node
+/**
+ * bdd-matrix — the per-scenario traceability matrix.
+ *
+ * The human-readable companion to `check-bdd-coverage.mjs`. It reuses that
+ * gate's parser and the same `bdd/coverage-map.json`, so the two can never
+ * disagree about what is covered.
+ *
+ * Every row separates the five facts the gate keeps apart: the behavior
+ * DECLARED, where it came from, whether automation is MAPPED per runner
+ * (traceability), whether that automation RAN, and what it returned. A `✓` in
+ * the mapped column asserts an aligned test exists and still contains its
+ * evidence string — never that it passed.
+ *
+ * Usage: node scripts/bdd-matrix.mjs [--write] [--results <file>]
+ *
+ * @module scripts/bdd-matrix
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { declaredPlatforms, trackerUrl } from "./bdd/contract.mjs";
+import { loadScenarios } from "./bdd/parse.mjs";
+import { loadExecutionResults } from "./check-bdd-coverage.mjs";
+
+const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+const OUT_REL = path.join("docs", "bdd-scenario-matrix.md");
+
+/**
+ * Index mappings by scenario and runner.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {Map<string, object[]>} Scenario ID → its mappings.
+ */
+function mappingsByScenario(contract) {
+  const index = new Map();
+  for (const mapping of contract.mappings ?? []) {
+    index.set(mapping.scenario, [
+      ...(index.get(mapping.scenario) ?? []),
+      mapping,
+    ]);
+  }
+  return index;
+}
+
+/**
+ * Index execution results by runner, file, and evidence.
+ * @param {readonly object[]} runs - Parsed execution-result documents.
+ * @returns {Map<string, object>} Lookup keyed by `runner|file|evidence`.
+ */
+function resultsIndex(runs) {
+  const index = new Map();
+  for (const run of runs) {
+    for (const result of run.results ?? []) {
+      index.set(`${run.runner}|${result.file}|${result.evidence}`, result);
+    }
+  }
+  return index;
+}
+
+/**
+ * Every `SCENARIO:platform` a waiver removes from the denominator.
+ *
+ * The matrix must know about waivers or it contradicts the burndown: a
+ * waived obligation is not an uncovered one, it is a dated IOU.
+ * @param {object} contract - Parsed coverage map.
+ * @returns {Set<string>} Waived keys.
+ */
+function waivedKeys(contract) {
+  return new Set(
+    (contract.platformWaivers ?? []).flatMap(waiver =>
+      (waiver.platforms ?? []).map(platform => `${waiver.scenario}:${platform}`)
+    )
+  );
+}
+
+/**
+ * Render one scenario's mapped-automation cell for one runner.
+ * @param {readonly string[]} required - Platforms the scenario demands this runner cover.
+ * @param {readonly object[]} mappings - Mappings for this scenario and runner.
+ * @param {(platform: string) => boolean} isWaived - Whether that platform is waived.
+ * @returns {string} Cell text.
+ */
+function mappedCell(required, mappings, isWaived) {
+  if (required.length === 0) return "n/a";
+  const covered = new Set(mappings.flatMap(mapping => mapping.platforms ?? []));
+  const hit = required.filter(platform => covered.has(platform));
+  const waived = required.filter(
+    platform => !covered.has(platform) && isWaived(platform)
+  );
+  const parts = [];
+  if (hit.length > 0) parts.push(`✓ ${hit.join("+")}`);
+  if (waived.length > 0) parts.push(`waived ${waived.join("+")}`);
+  const accounted = hit.length + waived.length;
+  if (accounted === 0) return "✗ none";
+  if (accounted < required.length) parts.push("✗ rest");
+  return parts.join(", ");
+}
+
+/**
+ * Render one scenario's execution cell.
+ * @param {readonly object[]} mappings - Mappings for this scenario.
+ * @param {Map<string, object>} results - Execution results index.
+ * @param {boolean} supplied - Whether any run evidence was supplied.
+ * @returns {string} Cell text.
+ */
+function executionCell(mappings, results, supplied) {
+  if (!supplied) return "not supplied";
+  if (mappings.length === 0) return "—";
+  const statuses = mappings.map(
+    mapping =>
+      results.get(`${mapping.runner}|${mapping.file}|${mapping.evidence}`)
+        ?.status ?? "not run"
+  );
+  const tally = counts =>
+    Object.entries(counts)
+      .map(([key, value]) => `${value} ${key}`)
+      .join(", ");
+  const counted = {};
+  for (const status of statuses) counted[status] = (counted[status] ?? 0) + 1;
+  return tally(counted);
+}
+
+/**
+ * Render a scenario's provenance and tracker references.
+ * @param {object} scenario - Parsed scenario.
+ * @param {object} trackers - The `trackers` block of the coverage map.
+ * @returns {string} Cell text.
+ */
+function sourceCell(scenario, trackers) {
+  const provenance = scenario.provenance.map(tag => `\`${tag}\``);
+  const tickets = scenario.trackers.map(reference => {
+    const url = trackerUrl(reference, trackers);
+    return url ? `[${reference.tag}](${url})` : reference.tag;
+  });
+  return [...provenance, ...tickets].join("<br>") || "—";
+}
+
+/**
+ * Render the full matrix document.
+ * @param {string} root - Repo root.
+ * @param {readonly string[]} resultFiles - Execution result documents to join.
+ * @returns {string} Markdown document.
+ */
+export function renderMatrix(root, resultFiles) {
+  const contract = JSON.parse(
+    fs.readFileSync(path.join(root, "bdd", "coverage-map.json"), "utf8")
+  );
+  const platforms = declaredPlatforms(contract.runnerPlatforms);
+  const scenarios = loadScenarios(root, platforms);
+  const execution = loadExecutionResults(root, resultFiles);
+  const results = resultsIndex(execution.runs);
+  const byScenario = mappingsByScenario(contract);
+  const waived = waivedKeys(contract);
+  const runners = Object.keys(contract.runnerPlatforms ?? {}).sort();
+  const byFeature = new Map();
+  for (const scenario of scenarios) {
+    byFeature.set(scenario.feature, [
+      ...(byFeature.get(scenario.feature) ?? []),
+      scenario,
+    ]);
+  }
+  const header = [
+    "| ID | Behavior | Source | Lifecycle",
+    ...runners.map(runner => ` | Mapped (${runner})`),
+    " | Executed |",
+  ].join("");
+  const divider = `|---|---|---|---|${runners.map(() => "---|").join("")}---|`;
+  const sections = [...byFeature.keys()]
+    .sort((a, b) => a.localeCompare(b))
+    .map(feature =>
+      renderFeature({
+        feature,
+        scenarios: byFeature.get(feature),
+        byScenario,
+        contract,
+        runners,
+        results,
+        waived,
+        supplied: execution.runs.length > 0,
+        header,
+        divider,
+      })
+    )
+    .join("\n");
+  return preamble(scenarios, execution.runs.length > 0) + sections;
+}
+
+/**
+ * Render one feature's table.
+ * @param {object} input - Feature, its scenarios, and the shared indexes.
+ * @returns {string} Markdown section.
+ */
+function renderFeature({
+  feature,
+  scenarios,
+  byScenario,
+  contract,
+  runners,
+  results,
+  waived,
+  supplied,
+  header,
+  divider,
+}) {
+  const rows = scenarios
+    .map(scenario => {
+      const mappings = byScenario.get(scenario.id) ?? [];
+      const cells = runners.map(runner => {
+        const covers = new Set(contract.runnerPlatforms[runner] ?? []);
+        const required = scenario.platforms.filter(platform =>
+          covers.has(platform)
+        );
+        return mappedCell(
+          required,
+          mappings.filter(mapping => mapping.runner === runner),
+          platform => waived.has(`${scenario.id}:${platform}`)
+        );
+      });
+      const lifecycle =
+        scenario.lifecycle.length > 0
+          ? scenario.lifecycle.join(", ")
+          : "required";
+      return `| \`${scenario.id ?? "(no id)"}\` | ${scenario.name} | ${sourceCell(scenario, contract.trackers)} | ${lifecycle} | ${cells.join(" | ")} | ${executionCell(mappings, results, supplied)} |`;
+    })
+    .join("\n");
+  return `### ${feature}\n\n${header}\n${divider}\n${rows}\n`;
+}
+
+/**
+ * The explanatory preamble.
+ * @param {readonly object[]} scenarios - Parsed scenarios.
+ * @param {boolean} supplied - Whether run evidence was supplied.
+ * @returns {string} Markdown preamble.
+ */
+function preamble(scenarios, supplied) {
+  const required = scenarios.filter(scenario => scenario.required).length;
+  return `# BDD scenario traceability matrix
+
+Every declared behavior, where it came from, and what actually proves it.
+Generated by \`node scripts/bdd-matrix.mjs --write\`; never hand-edited.
+
+- **Mapped** — aligned automation exists in that runner for the platforms the scenario requires, and its evidence string still resolves. This is **traceability**, not a result: a mapped test that fails still shows \`✓\`.
+- **Executed** — what the supplied run evidence returned for those mapped tests. ${supplied ? "Run evidence was supplied for this render." : "**No run evidence was supplied for this render**, so this column reads `not supplied` throughout — nothing here asserts any test ran."}
+- **Lifecycle** — \`required\` counts toward coverage; \`blocked\`, \`reference-only\`, and \`superseded\` are excluded until that changes.
+
+${scenarios.length} scenarios declared, ${required} required.
+
+`;
+}
+
+/**
+ * CLI entry point.
+ * @returns {void}
+ */
+function main() {
+  const root = process.env.BDD_COVERAGE_ROOT || PACKAGE_ROOT;
+  const argv = process.argv.slice(2);
+  const resultFiles = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === "--results" && argv[index + 1])
+      resultFiles.push(argv[index + 1]);
+  }
+  const body = renderMatrix(root, resultFiles);
+  if (!argv.includes("--write")) {
+    console.log(body);
+    return;
+  }
+  fs.mkdirSync(path.join(root, "docs"), { recursive: true });
+  fs.writeFileSync(path.join(root, OUT_REL), body);
+  console.log(`[bdd-matrix] wrote ${OUT_REL}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
+  main();