@codyswann/lisa 3.4.0 → 3.5.0

package/dist/utils/yaml.js

@@ -0,0 +1,124 @@
+/**
+ * The single js-yaml entry point for all of Lisa.
+ *
+ * Why this exists rather than `import yaml from "js-yaml"` at each call site:
+ * Lisa is `"type": "module"`, so a default import compiles to a real ESM
+ * default import. js-yaml 5.x ships an ESM build that exports `load`/`dump`
+ * as *named* exports and no `default`, so the default import is a link-time
+ * `SyntaxError: The requested module 'js-yaml' does not provide an export
+ * named 'default'`. That error fires while the module graph is being
+ * instantiated — before any Lisa code runs — so the whole CLI is dead,
+ * including `lisa doctor`. Lisa declares js-yaml `^4.3.1` for itself, but a
+ * host project's `overrides`/`resolutions` collapse Lisa's nested copy onto
+ * whatever the host pinned, which is exactly how geminisportsai/frontend-v2
+ * ended up running Lisa against js-yaml 5 (CodySwannGT/lisa#2467).
+ *
+ * A namespace import links against any module shape, so the incompatibility
+ * becomes a *runtime* condition this module can inspect and report in plain
+ * language instead of a link-time crash with a stack trace.
+ *
+ * Compatibility is deliberately shape-based, not version-based: js-yaml 3, 4
+ * and 5 all expose a `load(source)` that Lisa uses identically, and Lisa uses
+ * nothing else from the package. Anything exposing that function works; a
+ * future major that renames it fails with a message naming the problem.
+ * @module utils/yaml
+ */
+import * as jsYaml from "js-yaml";
+import { LisaError } from "../errors/index.js";
+/** Human-readable statement of what Lisa can drive. */
+export const SUPPORTED_JS_YAML_DESCRIPTION = "js-yaml 3.x, 4.x and 5.x (any build exposing a load() function)";
+/**
+ * Raised when the resolved js-yaml cannot be driven by Lisa.
+ *
+ * Carries the remediation inline: the operator reading this in a postinstall
+ * warning has no other context to work from.
+ */
+export class IncompatibleYamlError extends LisaError {
+    /**
+     * Build the operator-facing incompatibility message.
+     * @param shape - Short description of what the resolved module did expose
+     */
+    constructor(shape) {
+        super("Lisa cannot use the installed js-yaml: the resolved package exposes no " +
+            `load() function (${shape}). Lisa supports ${SUPPORTED_JS_YAML_DESCRIPTION}. ` +
+            "This usually means a js-yaml pin, override, or resolution in your " +
+            "package.json forced Lisa onto an incompatible copy. Remove or widen " +
+            "that js-yaml entry, reinstall, and re-run `lisa doctor`.", "INCOMPATIBLE_JS_YAML");
+        this.name = "IncompatibleYamlError";
+    }
+}
+/**
+ * Pull a callable `load` off a candidate object.
+ * @param candidate - Namespace object, interop default, or anything else
+ * @returns The `load` function when present and callable
+ */
+function pickLoad(candidate) {
+    if (typeof candidate !== "object" || candidate === null) {
+        return undefined;
+    }
+    const { load } = candidate;
+    return typeof load === "function" ? load : undefined;
+}
+/**
+ * Describe what a resolved module actually exposed, for the failure message.
+ * @param moduleNamespace - The resolved js-yaml module namespace
+ * @returns A short, bounded description of its exports
+ */
+function describeShape(moduleNamespace) {
+    if (typeof moduleNamespace !== "object" || moduleNamespace === null) {
+        return `resolved to ${typeof moduleNamespace}`;
+    }
+    const keys = Object.keys(moduleNamespace);
+    return keys.length === 0
+        ? "no exports"
+        : `exports: ${keys.slice(0, 8).join(", ")}${keys.length > 8 ? ", ..." : ""}`;
+}
+/**
+ * Resolve Lisa's YAML surface from a js-yaml module namespace, tolerating both
+ * the named-export shape (3.x/4.x/5.x ESM) and the CJS interop shape where the
+ * whole module hangs off `default`.
+ *
+ * Exported so `lisa doctor` can probe compatibility without parsing anything,
+ * and so the failure path is directly testable.
+ * @param moduleNamespace - The resolved js-yaml module namespace
+ * @returns The YAML surface Lisa uses
+ * @throws IncompatibleYamlError when no callable `load` can be found
+ */
+export function resolveYamlApi(moduleNamespace) {
+    const named = pickLoad(moduleNamespace);
+    if (named) {
+        return { load: named };
+    }
+    const interop = pickLoad(moduleNamespace?.default);
+    if (interop) {
+        return { load: interop };
+    }
+    throw new IncompatibleYamlError(describeShape(moduleNamespace));
+}
+/**
+ * Parse a single YAML document using whichever js-yaml the install resolved.
+ * @param source - YAML text
+ * @returns The parsed document
+ * @throws IncompatibleYamlError when the resolved js-yaml is unusable
+ */
+export function loadYaml(source) {
+    return resolveYamlApi(jsYaml).load(source);
+}
+/**
+ * Probe the js-yaml this process actually resolved.
+ *
+ * Never throws: `lisa doctor` turns the result into a check line, and a doctor
+ * that crashed on the very incompatibility it is meant to report would be the
+ * silent-failure bug all over again.
+ * @returns The incompatibility message, or null when the resolved js-yaml works
+ */
+export function probeYamlRuntime() {
+    try {
+        resolveYamlApi(jsYaml);
+        return null;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+//# sourceMappingURL=yaml.js.map

package/dist/utils/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/utils/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,KAAK,MAAM,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAY/C,uDAAuD;AACvD,MAAM,CAAC,MAAM,6BAA6B,GACxC,iEAAiE,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,OAAO,qBAAsB,SAAQ,SAAS;IAClD;;;OAGG;IACH,YAAY,KAAa;QACvB,KAAK,CACH,yEAAyE;YACvE,oBAAoB,KAAK,oBAAoB,6BAA6B,IAAI;YAC9E,oEAAoE;YACpE,sEAAsE;YACtE,0DAA0D,EAC5D,sBAAsB,CACvB,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,SAAkB;IAClC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;QACxD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,EAAE,IAAI,EAAE,GAAG,SAAwC,CAAC;IAC1D,OAAO,OAAO,IAAI,KAAK,UAAU,CAAC,CAAC,CAAE,IAAwB,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5E,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,eAAwB;IAC7C,IAAI,OAAO,eAAe,KAAK,QAAQ,IAAI,eAAe,KAAK,IAAI,EAAE,CAAC;QACpE,OAAO,eAAe,OAAO,eAAe,EAAE,CAAC;IACjD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC1C,OAAO,IAAI,CAAC,MAAM,KAAK,CAAC;QACtB,CAAC,CAAC,YAAY;QACd,CAAC,CAAC,YAAY,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;AACjF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAAC,eAAwB;IACrD,MAAM,KAAK,GAAG,QAAQ,CAAC,eAAe,CAAC,CAAC;IACxC,IAAI,KAAK,EAAE,CAAC;QACV,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CACrB,eAAyD,EAAE,OAAO,CACpE,CAAC;IACF,IAAI,OAAO,EAAE,CAAC;QACZ,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC3B,CAAC;IACD,MAAM,IAAI,qBAAqB,CAAC,aAAa,CAAC,eAAe,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAc;IACrC,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,IAAI,CAAC;QACH,cAAc,CAAC,MAAM,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChE,CAAC;AACH,CAAC"}

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

@@ -27,8 +27,10 @@
  * @module scripts/bdd/baseline
  */
 import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
 
-import { declaredPlatforms } from "./contract.mjs";
+import { byCodeUnit, declaredPlatforms } from "./contract.mjs";
 import { parseFeatureSource, scenarioIdsIn } from "./parse.mjs";
 
 const defect = (code, message) => ({ code, message });
@@ -36,6 +38,77 @@ const defect = (code, message) => ({ code, message });
 /** The maintainer-applied PR label that authorizes giving coverage back. */
 export const BASELINE_LABEL = "bdd-floor-baseline";
 
+/**
+ * Fixed absolute locations git is installed at, tried before anything on PATH.
+ *
+ * Handing a bare command name to the process spawner delegates the choice of
+ * binary to whatever `PATH` happens to say, so any writable directory earlier
+ * on it decides what this gate executes. The gate reads a base revision to
+ * decide whether a pull request may merge, which makes that a real
+ * substitution risk and not a theoretical one.
+ */
+const GIT_CANDIDATES = Object.freeze([
+  "/usr/bin/git",
+  "/usr/local/bin/git",
+  "/opt/homebrew/bin/git",
+  "/bin/git",
+  "C:\\Program Files\\Git\\cmd\\git.exe",
+]);
+
+/** Resolved git path, or null; computed once per process. */
+let gitBinary;
+
+/**
+ * Whether a path names a file that exists.
+ * @param {string} candidate - Absolute path.
+ * @returns {boolean} Whether it is a regular file.
+ */
+function isFile(candidate) {
+  try {
+    return fs.statSync(candidate).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve git to an ABSOLUTE, verified path.
+ *
+ * Fixed system locations first, then each `PATH` entry resolved to an absolute
+ * path and confirmed to be a real file — a lookup, never a delegation, so the
+ * command actually executed is one this process chose and checked.
+ * @returns {string|null} The absolute path, or null when git is not installed.
+ */
+export function resolveGit() {
+  if (gitBinary !== undefined) return gitBinary;
+  const fromPath = (process.env.PATH ?? "")
+    .split(path.delimiter)
+    .filter(Boolean)
+    .flatMap(entry => ["git", "git.exe"].map(name => path.join(entry, name)))
+    .filter(candidate => path.isAbsolute(candidate));
+  gitBinary =
+    [...GIT_CANDIDATES, ...fromPath].find(candidate => isFile(candidate)) ??
+    null;
+  return gitBinary;
+}
+
+/**
+ * Run one git command at an absolute path, or report that git is unavailable.
+ * @param {string} root - Repo root.
+ * @param {readonly string[]} args - Arguments after the binary.
+ * @returns {{ok: boolean, stdout: string}} The verdict and its output.
+ */
+function git(root, args) {
+  const binary = resolveGit();
+  if (!binary) return { ok: false, stdout: "" };
+  const result = spawnSync(binary, [...args], {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  return { ok: result.status === 0, stdout: result.stdout ?? "" };
+}
+
 /**
  * Read one path at a git revision.
  * @param {string} root - Repo root.
@@ -44,12 +117,8 @@ export const BASELINE_LABEL = "bdd-floor-baseline";
  * @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;
+  const result = git(root, ["show", `${revision}:${relative}`]);
+  return result.ok ? result.stdout : null;
 }
 
 /**
@@ -59,12 +128,15 @@ export function showAtRevision(root, revision, relative) {
  * @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 [];
+  const result = git(root, [
+    "ls-tree",
+    "-r",
+    "--name-only",
+    revision,
+    "--",
+    "bdd/features",
+  ]);
+  if (!result.ok) return [];
   return result.stdout
     .split("\n")
     .map(line => line.trim())
@@ -79,21 +151,33 @@ function featureFilesAt(root, revision) {
  * an unknown tag the moment a pull request deleted the web runner from
  * `runnerPlatforms` — which would turn "I deleted the runner that proved this"
  * into an invisible change rather than the coverage loss it is.
+ *
+ * A base coverage map that EXISTS but does not parse makes the baseline
+ * UNAVAILABLE rather than empty. An empty `before` set produces no
+ * `coverage-regression` and no `scenario-deleted` finding at all, so treating
+ * an unreadable map as "nothing was covered before" would let one malformed
+ * character on the base revision switch off every non-regression check while
+ * the gate still reported that nothing regressed.
  * @param {string} root - Repo root.
  * @param {string} revision - Base commit-ish.
  * @param {ReadonlySet<string>} headPlatforms - The head contract's platforms.
- * @returns {{available: boolean, contract: object|null, scenarios: object[], scenarioIds: Set<string>}} Base state.
+ * @returns {{available: boolean, error: string|null, contract: object|null, scenarios: object[], scenarioIds: Set<string>}} Base state.
  */
 export function loadBaseline(root, revision, headPlatforms = new Set()) {
   const raw = showAtRevision(root, revision, "bdd/coverage-map.json");
   let contract = null;
+  let error = null;
   if (raw !== null) {
     try {
       contract = JSON.parse(raw);
-    } catch {
+    } catch (parseError) {
       contract = null;
+      error = `bdd/coverage-map.json at that revision is not valid JSON: ${parseError.message}`;
     }
   }
+  if (raw === null && !resolveGit()) {
+    error = "git was not found, so no base revision could be read";
+  }
   const documents = featureFilesAt(root, revision)
     .map(file => ({ file, source: showAtRevision(root, revision, file) }))
     .filter(document => document.source !== null);
@@ -102,7 +186,8 @@ export function loadBaseline(root, revision, headPlatforms = new Set()) {
     ...headPlatforms,
   ]);
   return {
-    available: raw !== null || documents.length > 0,
+    available: error === null && (raw !== null || documents.length > 0),
+    error,
     contract,
     scenarios: documents.flatMap(document =>
       parseFeatureSource(document.source, document.file, platforms)
@@ -230,7 +315,7 @@ export function checkCoverageRegression({
   const waived = waivedKeys(contract);
   return [...before]
     .filter(key => !after.has(key) && present.has(partsOf(key).scenario))
-    .sort()
+    .sort(byCodeUnit)
     .flatMap(key => regressionDefect(key, { retired, waived, labels }));
 }
 
@@ -291,7 +376,7 @@ export function checkNewObligations({ baseline, contract, scenarios }) {
   const covered = acceptedKeys(scenarios, contract);
   return [...obligationKeys(scenarios, contract)]
     .filter(key => !before.has(key) && !covered.has(key))
-    .sort()
+    .sort(byCodeUnit)
     .map(key => {
       const { scenario, platform } = partsOf(key);
       return defect(
@@ -317,7 +402,7 @@ export function checkDeletions({ baseIds, scenarios, contract, labels }) {
   );
   return [...baseIds]
     .filter(id => !present.has(id))
-    .sort()
+    .sort(byCodeUnit)
     .flatMap(id => deletionDefects(id, retired.get(id), labels));
 }
 

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

@@ -20,6 +20,25 @@
  */
 export const REPORT_SCHEMA_VERSION = 3;
 
+/**
+ * THE comparator every ordering in this gate uses.
+ *
+ * `Array.prototype.sort()` with no comparator coerces each element to a string
+ * and compares UTF-16 code units, which is right for the identifier lists this
+ * gate sorts and catastrophically wrong the first time someone sorts numbers
+ * (`[2, 10]` becomes `[10, 2]`). Stating the comparator makes that choice
+ * deliberate rather than inherited, and it reproduces the previous ordering
+ * exactly — deliberately NOT `localeCompare`, whose result depends on the
+ * runner's ICU data and would reorder committed report artifacts.
+ * @param {string} a - Left value.
+ * @param {string} b - Right value.
+ * @returns {number} Negative, zero, or positive.
+ */
+export const byCodeUnit = (a, b) => {
+  if (a < b) return -1;
+  return a > b ? 1 : 0;
+};
+
 /** Coverage-map schema versions this gate can read. */
 export const SUPPORTED_MAP_SCHEMA_VERSIONS = [1, 2];
 
@@ -115,7 +134,7 @@ export function runnersByPlatform(runnerPlatforms) {
       index.set(platform, [...(index.get(platform) ?? []), runner]);
     }
   }
-  for (const runners of index.values()) runners.sort();
+  for (const runners of index.values()) runners.sort(byCodeUnit);
   return index;
 }
 

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

@@ -20,8 +20,43 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { byCodeUnit } from "./contract.mjs";
 import { listFiles, posix, resolveInsideRepo } from "./parse.mjs";
 
+/**
+ * Normalize a repo-relative path or path prefix to one comparable spelling.
+ *
+ * `./e2e/`, `e2e`, and `e2e/` all name the same directory, and the repo root
+ * is spelled `.` in a `roots` list but never appears in a repo-relative file
+ * path at all. Comparing the raw strings made those spellings disagree.
+ * @param {string} value - A repo-relative path or prefix.
+ * @returns {string} Its canonical form; the empty string means the repo root.
+ */
+const canonicalPath = value =>
+  posix(String(value))
+    .replace(/^\.\/+/, "")
+    .replace(/\/+$/, "")
+    .replace(/^\.$/, "");
+
+/**
+ * Whether a repo-relative path lies at or under a path prefix, SEGMENT-WISE.
+ *
+ * A raw `startsWith` treats a prefix as a character prefix, so an ignore entry
+ * of `e2e/live` also swallowed `e2e/live-personas/…` — silently hiding a whole
+ * directory of undeclared tests, which is the one thing discovery exists to
+ * find. Matching is therefore on path segments: `e2e/live` covers `e2e/live`
+ * and `e2e/live/…` and nothing else.
+ * @param {string} relative - A repo-relative path.
+ * @param {string} prefix - A repo-relative path prefix.
+ * @returns {boolean} Whether the path is covered by the prefix.
+ */
+export function isUnderPrefix(relative, prefix) {
+  const target = canonicalPath(relative);
+  const root = canonicalPath(prefix);
+  if (root === "") return true;
+  return target === root || target.startsWith(`${root}/`);
+}
+
 /**
  * Build one defect record, always naming the entity it is about.
  * @param {string} code - Stable machine-readable defect code.
@@ -213,12 +248,18 @@ function callTitles(source, functions) {
   );
   const found = [];
   for (const match of source.matchAll(pattern)) {
+    // Exactly one of the three quoting alternatives participates in any match,
+    // so the others are genuinely `undefined` here. The tests are written by
+    // TYPE rather than against `undefined`: the intent is "did this call carry
+    // a usable title" and "did that title come from a template literal", and
+    // stating it that way is both what the code means and unambiguous to a
+    // static analyser reading the declared `string` element type.
     const template = match[3];
     const evidence = match[1] ?? match[2] ?? template;
-    if (evidence === undefined || evidence.length === 0) continue;
+    if (typeof evidence !== "string" || evidence.length === 0) continue;
     found.push({
       evidence,
-      dynamic: template !== undefined && template.includes("${"),
+      dynamic: typeof template === "string" && template.includes("${"),
     });
   }
   return found;
@@ -247,13 +288,15 @@ function lineField(source, field) {
  * @returns {object[]} Discovered specs.
  */
 function discoverRunner({ root, runner, config, contract }) {
-  const platforms = [...(contract.runnerPlatforms?.[runner] ?? [])].sort();
+  const platforms = [...(contract.runnerPlatforms?.[runner] ?? [])].sort(
+    byCodeUnit
+  );
   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;
+      if (ignore.some(prefix => isUnderPrefix(relative, prefix))) continue;
       const source = fs.readFileSync(file, "utf8");
       for (const found of extract(source, config.evidence)) {
         specs.push({ runner, platforms, file: relative, ...found });
@@ -306,7 +349,7 @@ export function discoverSpecs({ root, contract }) {
   const specs = [];
   const roots = [];
   for (const [runner, config] of configs) {
-    roots.push(...config.roots.map(entry => posix(entry).replace(/\/+$/, "")));
+    roots.push(...config.roots.map(canonicalPath));
     specs.push(...discoverRunner({ root, runner, config, contract }));
   }
   return {
@@ -315,8 +358,8 @@ export function discoverSpecs({ root, contract }) {
         `${b.file}${b.evidence ?? ""}`
       )
     ),
-    runners: [...configs.keys()].sort(),
-    roots: [...new Set(roots)].sort(),
+    runners: [...configs.keys()].sort(byCodeUnit),
+    roots: [...new Set(roots)].sort(byCodeUnit),
     defects,
   };
 }
@@ -445,11 +488,11 @@ function exclusionStale({ root, exclusion, discovery, at, subject }) {
       ),
     ];
   }
-  if (!discovery.roots.some(entry => exclusion.file.startsWith(`${entry}/`))) {
+  if (!discovery.roots.some(entry => isUnderPrefix(exclusion.file, 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`,
+        `${at}: ${exclusion.file} is covered by no configured discovery root (${discovery.roots.map(entry => entry || ".").join(", ") || "none declared"}), so the exclusion suppresses nothing`,
         subject
       ),
     ];
@@ -491,7 +534,7 @@ export function missingDiscoveryDefects(contract, discovery) {
   return Object.keys(contract.runnerPlatforms ?? {})
     .filter(runner => !runner.startsWith("_"))
     .filter(runner => !discovery.runners.includes(runner))
-    .sort()
+    .sort(byCodeUnit)
     .map(runner =>
       defect(
         "discovery-missing",

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

@@ -14,6 +14,7 @@ import {
   ID_PATTERN,
   LIFECYCLE_TAGS,
   PROVENANCE_PATTERN,
+  byCodeUnit,
   parseTrackerTag,
 } from "./contract.mjs";
 
@@ -87,7 +88,7 @@ export function listFiles(directory, predicate) {
       else if (entry.isFile() && predicate(full)) found.push(full);
     }
   }
-  return found.sort();
+  return found.sort(byCodeUnit);
 }
 
 /**
@@ -130,6 +131,12 @@ function categorize(tags, platforms) {
  * Tags accumulate until a `Feature:` or `Scenario:` consumes them, matching
  * Gherkin's own tag scoping. `Scenario Outline` is treated as one scenario:
  * the contract counts behaviors, not example rows.
+ *
+ * `Background:` steps are Gherkin's way of saying "every scenario in this
+ * feature starts here", so they SEED each scenario's primary steps. Ignoring
+ * them made a conforming feature file — Given in the Background, When/Then in
+ * each scenario — report `scenario-steps` defects it did not have, which in
+ * enforced mode fails a repo for writing correct Gherkin.
  * @param {string} source - File contents.
  * @param {string} file - Repo-relative path, for error locations.
  * @param {ReadonlySet<string>} platforms - The project's declared platform vocabulary.
@@ -144,6 +151,8 @@ export function parseFeatureSource(source, file, platforms) {
   let featureLine = 0;
   let pending = [];
   let current = null;
+  let background = null;
+  let backgroundSteps = [];
   for (let index = 0; index < lines.length; index += 1) {
     const trimmed = lines[index].trim();
     if (trimmed.startsWith("#")) continue;
@@ -165,6 +174,16 @@ export function parseFeatureSource(source, file, platforms) {
       featureLine = index + 1;
       pending = [];
       current = null;
+      background = null;
+      backgroundSteps = [];
+      continue;
+    }
+    if (/^Background:/.test(trimmed)) {
+      // Background is per-Feature, so it replaces any previous one rather than
+      // accumulating, and its steps are collected instead of a scenario's.
+      backgroundSteps = [];
+      background = backgroundSteps;
+      current = null;
       continue;
     }
     const scenarioMatch = /^Scenario(?: Outline| Template)?:\s*(.+)$/.exec(
@@ -189,14 +208,17 @@ export function parseFeatureSource(source, file, platforms) {
         featureLine,
         ...grouped,
         required: grouped.lifecycle.length === 0,
-        primarySteps: [],
+        primarySteps: [...backgroundSteps],
       };
       scenarios.push(current);
+      background = null;
       pending = [];
       continue;
     }
     const step = /^(Given|When|Then)\b/.exec(trimmed);
-    if (step && current) current.primarySteps.push(step[1]);
+    if (!step) continue;
+    if (background) background.push(step[1]);
+    else if (current) current.primarySteps.push(step[1]);
   }
   return scenarios;
 }

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

@@ -7,6 +7,7 @@
  *
  * @module scripts/bdd/render
  */
+import { byCodeUnit } from "./contract.mjs";
 
 /**
  * Format a coverage figure, refusing to print "100%" for an empty
@@ -175,7 +176,7 @@ function gapSections(report) {
       const rows = [...entries.entries()]
         .map(
           ([id, value]) =>
-            `| ${cell(id)} | ${cell(value.name)} | ${cell(value.platforms.sort().join(", "))} |`
+            `| ${cell(id)} | ${cell(value.name)} | ${cell([...value.platforms].sort(byCodeUnit).join(", "))} |`
         )
         .join("\n");
       return `### ${cell(feature)}\n\n| Scenario | Behavior with no mapped proof | Platforms |\n|---|---|---|\n${rows}`;