@codyswann/lisa 2.346.0 → 2.348.0

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

@@ -0,0 +1,224 @@
+/**
+ * Base-revision comparisons: the coverage-floor ratchet and the
+ * scenario-deletion check.
+ *
+ * Both answer the same question — "did this change make the number look
+ * better by lowering the bar instead of raising the work?" — and both need a
+ * base revision to answer it, so they share one git read.
+ *
+ * @module scripts/bdd/baseline
+ */
+import { spawnSync } from "node:child_process";
+
+import { scenarioIdsIn } from "./parse.mjs";
+
+const defect = (code, message) => ({ code, message });
+
+/** The maintainer-applied PR label that authorizes a floor reduction. */
+export const BASELINE_LABEL = "bdd-floor-baseline";
+
+/**
+ * Read one path at a git revision.
+ * @param {string} root - Repo root.
+ * @param {string} revision - Commit-ish.
+ * @param {string} relative - Repo-relative path.
+ * @returns {string|null} File contents, or null when absent at that revision.
+ */
+export function showAtRevision(root, revision, relative) {
+  const result = spawnSync("git", ["show", `${revision}:${relative}`], {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return result.status === 0 ? result.stdout : null;
+}
+
+/**
+ * List the feature files that existed at a revision.
+ * @param {string} root - Repo root.
+ * @param {string} revision - Commit-ish.
+ * @returns {string[]} Repo-relative feature paths.
+ */
+function featureFilesAt(root, revision) {
+  const result = spawnSync(
+    "git",
+    ["ls-tree", "-r", "--name-only", revision, "--", "bdd/features"],
+    { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }
+  );
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line.endsWith(".feature"));
+}
+
+/**
+ * Load the base revision's contract and scenario IDs.
+ * @param {string} root - Repo root.
+ * @param {string} revision - Base commit-ish.
+ * @returns {{available: boolean, contract: object|null, scenarioIds: Set<string>}} Base state.
+ */
+export function loadBaseline(root, revision) {
+  const raw = showAtRevision(root, revision, "bdd/coverage-map.json");
+  let contract = null;
+  if (raw !== null) {
+    try {
+      contract = JSON.parse(raw);
+    } catch {
+      contract = null;
+    }
+  }
+  const sources = featureFilesAt(root, revision)
+    .map(file => showAtRevision(root, revision, file))
+    .filter(source => source !== null);
+  return {
+    available: raw !== null || sources.length > 0,
+    contract,
+    scenarioIds: scenarioIdsIn(sources),
+  };
+}
+
+/**
+ * The coverage-floor ratchet: a floor may rise, and may never fall.
+ *
+ * Lowering it takes TWO artifacts that one author cannot produce by editing
+ * one file: a `coverageFloorBaseline` record naming the exact drop, its
+ * reason, ticket, approver and authorizing run, AND the maintainer-applied
+ * `bdd-floor-baseline` label on the pull request. Either alone fails.
+ * @param {object} input - Base and head contracts plus the PR labels.
+ * @returns {object[]} Defects found.
+ */
+export function checkRatchet({ baseContract, contract, labels }) {
+  const before = baseContract?.coverageFloor ?? {};
+  const after = contract.coverageFloor ?? {};
+  const drops = Object.keys(before)
+    .filter(platform => typeof before[platform] === "number")
+    .filter(platform => (after[platform] ?? -Infinity) < before[platform])
+    .map(platform => ({
+      platform,
+      from: before[platform],
+      to: typeof after[platform] === "number" ? after[platform] : null,
+    }));
+  return drops.flatMap(drop => ratchetDefects(drop, contract, labels));
+}
+
+/**
+ * Defects for one attempted floor reduction.
+ * @param {object} drop - The observed reduction.
+ * @param {object} contract - Head contract.
+ * @param {readonly string[]} labels - PR labels.
+ * @returns {object[]} Defects found.
+ */
+function ratchetDefects(drop, contract, labels) {
+  const what =
+    drop.to === null
+      ? `coverageFloor.${drop.platform} was removed (was ${drop.from})`
+      : `coverageFloor.${drop.platform} lowered ${drop.from} → ${drop.to}`;
+  const record = (contract.coverageFloorBaseline ?? []).find(
+    entry =>
+      entry.platform === drop.platform &&
+      entry.from === drop.from &&
+      entry.to === drop.to
+  );
+  const defects = [];
+  if (!record) {
+    defects.push(
+      defect(
+        "floor-ratchet",
+        `${what}: the floor is a ratchet. A reduction needs a coverageFloorBaseline record naming this exact change (platform, from, to, reason, ticket, approvedBy, runUrl).`
+      )
+    );
+  } else {
+    defects.push(...baselineRecordDefects(record, what));
+  }
+  if (!labels.includes(BASELINE_LABEL)) {
+    defects.push(
+      defect(
+        "floor-ratchet",
+        `${what}: requires the maintainer-applied "${BASELINE_LABEL}" label. Changing the floor in the same pull request that changes the code is not an authorization.`
+      )
+    );
+  }
+  return defects;
+}
+
+/**
+ * Completeness of a baseline-update record. `runUrl` is validated for shape
+ * only — the gate never contacts a tracker or CI API, so a merge can never
+ * depend on one being reachable.
+ * @param {object} record - The coverageFloorBaseline entry.
+ * @param {string} what - Human description of the drop.
+ * @returns {object[]} Defects found.
+ */
+function baselineRecordDefects(record, what) {
+  const defects = ["reason", "ticket", "approvedBy", "runUrl", "recordedAt"]
+    .filter(field => !record[field])
+    .map(field =>
+      defect(
+        "floor-ratchet",
+        `${what}: coverageFloorBaseline record has no ${field}`
+      )
+    );
+  if (record.runUrl && !/^https:\/\/\S+$/.test(String(record.runUrl))) {
+    defects.push(
+      defect(
+        "floor-ratchet",
+        `${what}: coverageFloorBaseline.runUrl must be an https URL`
+      )
+    );
+  }
+  return defects;
+}
+
+/**
+ * Refuse scenario deletion used to shrink the denominator.
+ *
+ * The contract's answer to a retired behavior is `@superseded`, which keeps
+ * the audit trail. Deleting the scenario instead makes coverage look better
+ * by describing less of the product.
+ * @param {object} input - Base IDs, head scenarios, and the PR labels.
+ * @returns {object[]} Defects found.
+ */
+export function checkDeletions({ baseIds, scenarios, contract, labels }) {
+  const present = new Set(scenarios.map(scenario => scenario.id));
+  const retired = new Map(
+    (contract.retirements ?? []).map(entry => [entry.scenario, entry])
+  );
+  return [...baseIds]
+    .filter(id => !present.has(id))
+    .sort()
+    .flatMap(id => deletionDefects(id, retired.get(id), labels));
+}
+
+/**
+ * Defects for one deleted scenario.
+ * @param {string} id - The scenario ID that disappeared.
+ * @param {object|undefined} record - Its retirement record, if any.
+ * @param {readonly string[]} labels - PR labels.
+ * @returns {object[]} Defects found.
+ */
+function deletionDefects(id, record, labels) {
+  if (!record) {
+    return [
+      defect(
+        "scenario-deleted",
+        `${id} was deleted from the contract. Retiring a behavior is @superseded, not deletion — deleting it shrinks the denominator instead of the gap. A genuine removal needs a retirements record and the "${BASELINE_LABEL}" label.`
+      ),
+    ];
+  }
+  const missing = ["reason", "ticket", "approvedBy", "recordedAt"].filter(
+    field => !record[field]
+  );
+  const defects = missing.map(field =>
+    defect("scenario-deleted", `${id}: retirements record has no ${field}`)
+  );
+  if (!labels.includes(BASELINE_LABEL)) {
+    defects.push(
+      defect(
+        "scenario-deleted",
+        `${id}: a retirement needs the maintainer-applied "${BASELINE_LABEL}" label`
+      )
+    );
+  }
+  return defects;
+}

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

@@ -0,0 +1,121 @@
+/**
+ * Shared vocabulary for the BDD behavior contract gate.
+ *
+ * Everything a project may vary — platform names, runner names, tracker
+ * prefixes — is read from `bdd/coverage-map.json`. Nothing in this module
+ * names a test runner or a tracker vendor: that is the point of the contract
+ * (see Lisa rule `bdd-e2e-coverage`).
+ *
+ * @module scripts/bdd/contract
+ */
+
+/** Report/envelope schema emitted by the gate. See docs/bdd-coverage-schema.md. */
+export const REPORT_SCHEMA_VERSION = 2;
+
+/** Coverage-map schema versions this gate can read. */
+export const SUPPORTED_MAP_SCHEMA_VERSIONS = [1, 2];
+
+/** Stable scenario identity. Never renumbered, never reused. */
+export const ID_PATTERN = /^BDD-[A-Z][A-Z0-9]*-\d{3,}$/;
+
+/** Lifecycle tags that remove a scenario from the coverage denominator. */
+export const LIFECYCLE_TAGS = ["blocked", "reference-only", "superseded"];
+
+/** Provenance tags tying a scenario to the authority it came from. */
+export const PROVENANCE_PATTERN = /^(?:figma-|ratified-)/;
+
+/**
+ * THE portfolio tracker-tag grammar (one grammar, two schemes).
+ *
+ * 1. Key style — `@<KEY>-<number>`, for key-based trackers (Jira, Linear).
+ *    `@TUN-123`, `@SE-6833`. KEY is 2-10 uppercase alphanumerics starting
+ *    with a letter.
+ * 2. Repo-issue style — `@gh-<number>` for an issue in this repo, or
+ *    `@gh-<repo-slug>-<number>` for a sibling repo in the same org.
+ *    `@gh-2394`, `@gh-wiki-124`.
+ *
+ * The allowed KEYs and repo slugs are PER-REPO CONFIGURATION (`trackers` in
+ * the coverage map), never a list baked into this script: a global
+ * enumeration would mean a new project key could not be referenced until a
+ * new Lisa release shipped, which inverts the pinning contract (Lisa A5).
+ *
+ * Validation is SYNTACTIC plus membership in the repo's own declared sets.
+ * The gate never contacts a tracker — issue liveness must not be a merge
+ * dependency.
+ */
+export const TRACKER_KEY_PATTERN = /^([A-Z][A-Z0-9]{1,9})-(\d+)$/;
+
+/** Repo-issue style tracker tag. Group 1 is an optional repo slug. */
+export const TRACKER_GH_PATTERN = /^gh-(?:([a-z0-9]+(?:-[a-z0-9]+)*)-)?(\d+)$/;
+
+/** Adoption states. The ruleset context is required ONLY in `enforced`. */
+export const ADOPTION_STATES = ["not-adopted", "bootstrap", "enforced"];
+
+/**
+ * Classify a raw tag as a tracker reference, if it is one.
+ *
+ * A tag is *shaped like* a tracker reference independently of whether the
+ * repo declared it — that is what makes an orphan tag detectable rather than
+ * silently ignored as "some other tag".
+ * @param {string} tag - Raw tag text with the leading `@` already stripped.
+ * @returns {{scheme: string, key?: string, repo: string|null, number: number}|null} Parsed reference, or null when the tag is not tracker-shaped.
+ */
+export function parseTrackerTag(tag) {
+  const gh = TRACKER_GH_PATTERN.exec(tag);
+  if (gh) {
+    return { scheme: "gh", repo: gh[1] ?? null, number: Number(gh[2]) };
+  }
+  const key = TRACKER_KEY_PATTERN.exec(tag);
+  if (key) {
+    return { scheme: "key", key: key[1], repo: null, number: Number(key[2]) };
+  }
+  return null;
+}
+
+/**
+ * Render a tracker reference as a URL from the repo's declared templates.
+ *
+ * Emitting the link is a convenience; it is never fetched.
+ * @param {object} reference - Parsed reference from {@link parseTrackerTag}.
+ * @param {object} trackers - The `trackers` block of the coverage map.
+ * @returns {string|null} An absolute URL, or null when no template is declared.
+ */
+export function trackerUrl(reference, trackers) {
+  if (reference.scheme === "gh") {
+    const org = trackers?.github?.org;
+    const repo = reference.repo ?? trackers?.github?.defaultRepo;
+    if (!org || !repo) return null;
+    return `https://github.com/${org}/${repo}/issues/${reference.number}`;
+  }
+  const template = trackers?.keyUrlTemplate;
+  if (!template) return null;
+  return template
+    .replace("{key}", reference.key)
+    .replace("{number}", String(reference.number))
+    .replace("{id}", `${reference.key}-${reference.number}`);
+}
+
+/**
+ * Invert `runnerPlatforms` into platform → runners.
+ * @param {Record<string, readonly string[]>} runnerPlatforms - Declared runner coverage.
+ * @returns {Map<string, string[]>} Platform to the runners configured for it.
+ */
+export function runnersByPlatform(runnerPlatforms) {
+  const index = new Map();
+  for (const [runner, platforms] of Object.entries(runnerPlatforms ?? {})) {
+    for (const platform of platforms ?? []) {
+      index.set(platform, [...(index.get(platform) ?? []), runner]);
+    }
+  }
+  for (const runners of index.values()) runners.sort();
+  return index;
+}
+
+/**
+ * The project's own platform vocabulary, derived from its runner declaration.
+ * @param {Record<string, readonly string[]>} runnerPlatforms - Declared runner coverage.
+ * @returns {Set<string>} Every platform some configured runner covers.
+ */
+export function declaredPlatforms(runnerPlatforms) {
+  return new Set(runnersByPlatform(runnerPlatforms).keys());
+}

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

@@ -0,0 +1,231 @@
+/**
+ * Conform the BDD gate's result to Lisa's standard command envelope.
+ *
+ * The envelope contract is owned by `scripts/lisa-command-envelope.mjs` and
+ * its published schema; this module only maps the gate's vocabulary onto it.
+ * Inventing a second result shape is exactly what the envelope exists to
+ * prevent, so the envelope is BUILT BY that module whenever it is present —
+ * which also means its validator, not this file, decides conformance.
+ *
+ * @module scripts/bdd/envelope
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Where the shared envelope module can legitimately live, as SOURCE
+ * CONSTANTS — an allowlist, never a search of whatever happens to be nearby.
+ *
+ * First entry is the adopter layout (`all/copy-overwrite/scripts/` and
+ * `expo/copy-overwrite/scripts/` both land in the project's `scripts/`).
+ * Second is Lisa's own tree, where the two live in different template
+ * directories and this file is exercised by Lisa's tests.
+ */
+const ENVELOPE_MODULE_PATHS = Object.freeze([
+  "./lisa-command-envelope.mjs",
+  "../../../all/copy-overwrite/scripts/lisa-command-envelope.mjs",
+]);
+
+/**
+ * Defect codes bootstrap is PERMITTED to downgrade to a warning.
+ *
+ * This is an allowlist and it is load-bearing: an unrecognized code — a new
+ * check, a typo, a future contributor's addition — is treated as FATAL. A
+ * denylist of "fatal codes" would fail OPEN on exactly the value nobody
+ * anticipated, which is how a gate quietly stops gating.
+ *
+ * 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.
+ */
+export const WARNABLE_DEFECT_CODES = Object.freeze([
+  "baseline",
+  "empty-contract",
+  "execution-results",
+  "floor-missing",
+  "floor-ratchet",
+  "floor-regression",
+  "mapping-duplicate",
+  "mapping-evidence",
+  "mapping-file",
+  "mapping-orphan",
+  "mapping-platform",
+  "mapping-runner",
+  "scenario-deleted",
+  "scenario-duplicate-id",
+  "scenario-id",
+  "scenario-lifecycle",
+  "scenario-platform",
+  "scenario-provenance",
+  "scenario-steps",
+  "tracker-missing",
+  "tracker-orphan",
+  "waiver-duplicate",
+  "waiver-excluded",
+  "waiver-expired",
+  "waiver-masks-mapping",
+  "waiver-metadata",
+  "waiver-orphan",
+  "waiver-platform",
+  "waiver-runner",
+]);
+
+/**
+ * Envelope statuses that may exit 0.
+ *
+ * Mirrors `SUCCESS_STATUSES` in the shared envelope module. It is restated
+ * here because this gate must decide its exit code without waiting on a
+ * dynamic import — and a unit test asserts the two lists are identical, so the
+ * copy cannot drift silently.
+ */
+export const SUCCESS_STATUSES = Object.freeze([
+  "completed",
+  "no-op",
+  "not-adopted",
+]);
+
+/** Message prefixes that already name the subject a finding is about. */
+const SUBJECT_PREFIX = /^(?:bdd\/|coverage-map\.|BDD-[A-Z]|coverageFloor\.)/;
+
+/** Fallback subjects by code family, so every finding names something real. */
+const SUBJECT_BY_FAMILY = Object.freeze([
+  ["scenario-", "bdd/features"],
+  ["tracker-", "bdd/features"],
+  ["execution-results", "execution results"],
+  ["baseline", "base revision"],
+]);
+
+/**
+ * The entity a finding is about.
+ *
+ * Every defect message already begins with its location, so the subject is
+ * read from there rather than restated — a second copy would drift.
+ * @param {{code: string, message: string, subject?: string}} item - A defect.
+ * @returns {string} A non-empty subject.
+ */
+export function subjectFor(item) {
+  if (item.subject) return item.subject;
+  const head = item.message.split(/\s+/)[0] ?? "";
+  if (SUBJECT_PREFIX.test(head)) return head.replace(/[:,]$/, "");
+  const family = SUBJECT_BY_FAMILY.find(([prefix]) =>
+    item.code.startsWith(prefix)
+  );
+  return family ? family[1] : "bdd/coverage-map.json";
+}
+
+/**
+ * Whether any defect must fail the run, given the adoption state.
+ *
+ * `enforced` fails on any defect at all. `bootstrap` fails on any defect
+ * whose code is NOT on the warnable allowlist. `not-adopted` reaches here
+ * only with adoption-integrity defects, which are never warnable.
+ * @param {string} adoptionState - not-adopted | bootstrap | enforced.
+ * @param {readonly object[]} defects - Defects found.
+ * @returns {boolean} True when the run must fail.
+ */
+export function hasFatalDefect(adoptionState, defects) {
+  if (defects.length === 0) return false;
+  if (adoptionState === "enforced") return true;
+  return defects.some(item => !WARNABLE_DEFECT_CODES.includes(item.code));
+}
+
+/**
+ * Load the shared envelope module from the allowlisted locations.
+ * @param {string} scriptDir - Directory holding this gate's scripts.
+ * @returns {Promise<object|null>} The module, or null when it is not installed.
+ */
+export async function loadEnvelopeModule(scriptDir) {
+  for (const relative of ENVELOPE_MODULE_PATHS) {
+    const candidate = path.resolve(scriptDir, relative);
+    if (!fs.existsSync(candidate)) continue;
+    return import(pathToFileURL(candidate).href);
+  }
+  return null;
+}
+
+/**
+ * A correlation id that is stable for an unchanged tree.
+ *
+ * CI supplies the run id. Off CI the id is derived from the result itself, so
+ * two runs over the same tree produce byte-identical output — determinism the
+ * gate's own tests assert.
+ * @param {string|undefined} supplied - `BDD_CORRELATION_ID` from the environment.
+ * @param {object} material - Values that identify this result.
+ * @returns {string} The correlation id.
+ */
+export function correlationId(supplied, material) {
+  if (supplied) return supplied;
+  const digest = createHash("sha256")
+    .update(JSON.stringify(material))
+    .digest("hex")
+    .slice(0, 16);
+  return `bdd-local-${digest}`;
+}
+
+/**
+ * The project's own contract version for the state this gate reads.
+ * @param {object|null} contract - Parsed coverage map, when readable.
+ * @returns {string} A non-empty contract version.
+ */
+export function contractVersion(contract) {
+  if (!contract) return "bdd-coverage-map-unavailable";
+  return `bdd-coverage-map-v${contract.schemaVersion ?? "unknown"}@${contract.asOf ?? "undated"}`;
+}
+
+/**
+ * Counters describing the run, plus the adoption state the counts belong to.
+ *
+ * The five facts stay separate here exactly as they do in the report: what is
+ * DECLARED, what is MAPPED (traceability), what RAN, what those runs
+ * RETURNED, and what is WAIVED. A reader comparing two runs must never have
+ * to infer which one a percentage refers to.
+ * @param {object} input - Adoption state, report, defects, and files written.
+ * @returns {object} The envelope's `summary`.
+ */
+export function buildSummary({ adoptionState, report, defects, filesWritten }) {
+  const counts = {
+    deleted: 0,
+    created: filesWritten,
+    preserved: 0,
+    adoptionState,
+    findingsError: defects.filter(item => item.severity === "error").length,
+    findingsWarning: defects.filter(item => item.severity === "warning").length,
+  };
+  if (!report) return counts;
+  return {
+    ...counts,
+    scenariosDeclared: report.scenarios.declared,
+    scenariosRequired: report.scenarios.required,
+    scenariosExcluded: report.scenarios.excluded,
+    traceabilityCovered: report.traceability.overall.covered,
+    traceabilityTotal: report.traceability.overall.total,
+    traceabilityPercentage: report.traceability.overall.percentage,
+    executionEvidenceSupplied: report.execution.supplied,
+    mappedTests: report.execution.mappedTests,
+    ...executionCounts(report.execution),
+    waivedObligations: report.waived.count,
+    floorOk: report.floor.ok,
+  };
+}
+
+/**
+ * Execution counters, present only when run evidence was supplied.
+ *
+ * Absent evidence emits NO counters rather than zeros: a zero here reads as
+ * "nothing passed", which is a different claim from "nobody told me".
+ * @param {object} execution - The report's execution block.
+ * @returns {object} Execution counters, or an empty object.
+ */
+function executionCounts(execution) {
+  if (!execution.supplied) return {};
+  return {
+    executed: execution.executed,
+    passed: execution.passed,
+    failed: execution.failed,
+    skipped: execution.skipped,
+    notRun: execution.notRun,
+  };
+}