@codyswann/lisa 4.24.0 → 4.24.2

package/scripts/check-security-floors.mjs

@@ -164,16 +164,21 @@ function trackedManifests() {
 
 /**
  * Every version constraint declared across the template manifests.
- * @returns {{found: Map<string, Array<{file: string, path: string, spec: string}>>,
+ * @returns {{found: Map<string, Array<{file: string, path: string, spec: string,
+ *   lowest: number[]}>>,
  *   unresolved: Array<{file: string, path: string, name: string, spec: string}>,
- *   scanned: string[], unscanned: string[]|null}}
- *   Constraints by package name, self-references pointing at nothing, the
- *   manifests read, and any tracked manifest the patterns did not reach.
+ *   unparseable: Array<{file: string, path: string, name: string, spec: string,
+ *   reason: string}>, scanned: string[], unscanned: string[]|null}}
+ *   Constraints by package name with their resolved floors, self-references
+ *   pointing at nothing, floors that resolve to no lower bound, the manifests
+ *   read, and any tracked manifest the patterns did not reach.
  */
 export function collectFloors() {
   const found = new Map();
   /** `$name` references pointing at nothing this manifest declares. */
   const unresolved = [];
+  /** Floors carrying a version that resolves to no lower bound. */
+  const unparseable = [];
   const files = globSync(MANIFEST_PATTERNS).filter(
     file => !NOT_A_MANIFEST.some(fragment => file.includes(fragment))
   );
@@ -184,6 +189,30 @@ export function collectFloors() {
   const scanned = new Set(files);
   const unscanned =
     tracked === null ? null : tracked.filter(file => !scanned.has(file));
+  /**
+   * File one floor: comparable ones under their package, the rest as gaps.
+   *
+   * Resolved HERE, at collection, rather than in the audit loop, for two
+   * reasons beyond tidiness. It runs before any network call, so a floor with
+   * no lower bound is reported even on a run that is entirely rate-limited —
+   * the case where a silent skip is hardest to notice. And it makes every site
+   * in `found` carry a resolved floor, which removes the audit's null check
+   * instead of leaving a `continue` that a later reader has to re-litigate.
+   * @param {string} name npm package name.
+   * @param {string} file Manifest the floor was declared in.
+   * @param {string} path Governance group and section, dotted.
+   * @param {string} spec The version constraint to resolve.
+   */
+  const record = (name, file, path, spec) => {
+    const { version, reason } = resolveLowerBound(spec);
+    if (version === null) {
+      unparseable.push({ file, path, name, spec, reason });
+      return;
+    }
+    if (!found.has(name)) found.set(name, []);
+    found.get(name).push({ file, path, spec, lowest: version });
+  };
+
   for (const file of files) {
     let manifest;
     try {
@@ -221,33 +250,20 @@ export function collectFloors() {
               continue;
             }
             if (!/\d/.test(target)) continue;
-            if (!found.has(name)) found.set(name, []);
-            found
-              .get(name)
-              .push({ file, path: `${group}.${section}`, spec: target });
+            record(name, file, `${group}.${section}`, target);
             continue;
           }
           // A literal carrying no digits — "workspace:*", "latest" — is not a
-          // floor and there is nothing to compare.
+          // floor and there is nothing to compare. Kept ahead of `record` so
+          // these stay a deliberate non-floor rather than becoming a gap
+          // report: they are not failed attempts to state a floor.
           if (!/\d/.test(spec)) continue;
-          if (!found.has(name)) found.set(name, []);
-          found.get(name).push({ file, path: `${group}.${section}`, spec });
+          record(name, file, `${group}.${section}`, spec);
         }
       }
     }
   }
-  return { found, unresolved, scanned: files, unscanned };
-}
-
-/**
- * Lowest version a spec permits, as a comparable tuple.
- * @param {string} spec A range like ">=5.0.7", "^1.2.3", "~2.0.0".
- * @returns {number[]|null} [major, minor, patch], or null if unparseable.
- */
-export function lowestPermitted(spec) {
-  const match = /(\d+)\.(\d+)\.(\d+)/.exec(spec);
-  if (!match) return null;
-  return match.slice(1, 4).map(Number);
+  return { found, unresolved, unparseable, scanned: files, unscanned };
 }
 
 /**
@@ -263,6 +279,200 @@ function compare(left, right) {
   return 0;
 }
 
+/** The comparator an npm term may lead with. */
+const TERM_OPERATOR = /^(>=|<=|>|<|=|\^|~)/;
+
+/**
+ * The version half of a term, anchored end to end.
+ *
+ * Anchored deliberately. The predecessor was an unanchored
+ * `/(\d+)\.(\d+)\.(\d+)/` scan, and a scan cannot tell a version from a number
+ * that merely follows one: on `^1.2.3-alpha.4` a global sweep finds `1.2.3`
+ * and then finds `4` in the prerelease tag and reads it as a second term. An
+ * anchored match either consumes the whole thing or rejects it, which is the
+ * property that lets a rejection mean "report this" instead of "guess".
+ *
+ * The operator and any prerelease or build tag are removed before this runs,
+ * rather than being alternatives inside it. Splitting the three concerns keeps
+ * each pattern simple enough to read, and the tag is discarded regardless
+ * because every comparison in this file is on the [major, minor, patch] tuple.
+ */
+const TERM_VERSION = /^v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?$/;
+
+/**
+ * Lower bound of one comparator term.
+ *
+ * Three outcomes, kept distinct because collapsing any two of them is how a
+ * floor goes unchecked:
+ *
+ * - `bound` — the term states a lowest permitted version.
+ * - `floorless` — the term is an upper bound (`<8`, `<=2.0.0`). It states no
+ *   floor at all; it permits every release beneath it.
+ * - `unreadable` — this check cannot tell which of the two it is.
+ * @param {string} term A single comparator, e.g. ">=1.2.3" or "^8".
+ * @returns {{kind: string, version?: number[]}} The classification.
+ */
+function termLowerBound(term) {
+  const operator = TERM_OPERATOR.exec(term)?.[1] ?? "";
+  if (operator === "<" || operator === "<=") return { kind: "floorless" };
+  // A prerelease or build tag is the only place a `-` or `+` survives this
+  // far: hyphen RANGES were split before the term was formed. Taking the head
+  // is what stops `-alpha.4` contributing a `4` to the version.
+  const [core] = term.slice(operator.length).split(/[-+]/);
+
+  const match = TERM_VERSION.exec(core);
+  if (!match) return { kind: "unreadable" };
+  // `x` and `*` are wildcards, so they and everything after them are
+  // unspecified. `1.x.5` is not a version anyone means; truncating at the
+  // first wildcard is what makes `1.x` and `1` resolve identically.
+  const specified = [];
+  for (const part of [match[1], match[2], match[3]]) {
+    if (part === undefined || /^[xX*]$/.test(part)) break;
+    specified.push(Number(part));
+  }
+  // An absent minor or patch is zero, not missing: `^8` is `>=8.0.0`. Leaving
+  // them undefined would put NaN into the tuple, and NaN compares as neither
+  // higher nor lower than anything — it disables the comparison it feeds
+  // rather than failing it.
+  const lower = [...specified, 0, 0].slice(0, 3);
+  if (operator !== ">") return { kind: "bound", version: lower };
+
+  // npm expands a STRICT comparator before comparing: `>1` is `>=2.0.0` and
+  // `>1.2` is `>=1.3.0`. Reading either as merely 1.0.0 or 1.2.0 invents
+  // versions the range does not permit, which in this file means comparing a
+  // release the floor already excludes.
+  const lastSpecified = specified.length - 1;
+  lower[lastSpecified] += 1;
+  for (let index = lastSpecified + 1; index < 3; index += 1) lower[index] = 0;
+  return { kind: "bound", version: lower };
+}
+
+/**
+ * Lower bound of one `||` branch: the HIGHEST floor its terms state.
+ *
+ * A branch is a conjunction — `>=1.2.3 <2.0.0` permits a version only if every
+ * term admits it — so the binding floor is the strongest one present. Terms
+ * that state no floor (`<2.0.0`) constrain the ceiling and are passed over;
+ * a branch made only of those has no floor.
+ * @param {string} branch One branch of a `||` range.
+ * @returns {{kind: string, version?: number[]}} The classification.
+ */
+function branchLowerBound(branch) {
+  const trimmed = branch.trim();
+  if (trimmed === "") return { kind: "unreadable" };
+  // A hyphen range's floor is its LEFT side. Both sides are bare versions, so
+  // measuring every term and keeping the highest would return `2.0.0` for
+  // `1.2.3 - 2.0.0` — the ceiling reported as the floor, which is the one
+  // direction that clears a vulnerable release instead of flagging it.
+  const [beneathAnyCeiling] = trimmed.split(/\s+-\s+/);
+  // semver permits whitespace between an operator and its version, so `>= 8`
+  // is `>=8`. Closing the gap before splitting on whitespace stops a legal
+  // range being split into a bare operator plus a bare version — which would
+  // read as unreadable and report a floor that is in fact perfectly clear.
+  const terms = beneathAnyCeiling
+    .replace(/(>=|<=|>|<|=|\^|~)\s+/g, "$1")
+    .split(/\s+/)
+    .filter(Boolean);
+  let strongest = null;
+  for (const term of terms) {
+    const resolved = termLowerBound(term);
+    if (resolved.kind === "unreadable") return { kind: "unreadable" };
+    if (resolved.kind === "floorless") continue;
+    if (strongest === null || compare(resolved.version, strongest) > 0) {
+      strongest = resolved.version;
+    }
+  }
+  return strongest === null
+    ? { kind: "floorless" }
+    : { kind: "bound", version: strongest };
+}
+
+/**
+ * Lowest version a spec permits, with the reason when there is none.
+ *
+ * The reason is produced here rather than by a second pass, so the message a
+ * reader sees and the decision the audit makes come from the same parse and
+ * cannot disagree.
+ *
+ * Note what `[0, 0, 0]` would mean if this returned it for an upper-bound-only
+ * spec, which is how the sibling collision checker in the templates models a
+ * floorless range: {@link withinRange} would compare 0.0.0 against an advisory
+ * range like `>= 4.0.0, < 5.0.8`, find it outside, and report the floor CLEAN.
+ * A spec that permits every vulnerable release would come back green. The two
+ * files are therefore deliberately NOT unified — there, zero means "weakest
+ * possible, loses every comparison"; here, no comparison at that end exists,
+ * so a floorless spec has to be reported instead of compared.
+ * @param {string} spec A range like ">=5.0.7", "^8", "~2.0", "^7 || ^8".
+ * @returns {{version: number[]|null, reason: string|null}} Bound, or reason.
+ */
+function resolveLowerBound(spec) {
+  const raw = typeof spec === "string" ? spec.trim() : "";
+  if (raw === "") return { version: null, reason: "is empty" };
+  // An alias versions a DIFFERENT package. Its number cannot be compared
+  // against advisories filed for this name, and comparing it anyway would
+  // answer confidently about the wrong package.
+  if (/^npm:/i.test(raw)) {
+    return {
+      version: null,
+      reason:
+        "is an alias, so its version belongs to another package and cannot be compared against this one's advisories",
+    };
+  }
+
+  const branches = raw.split("||").map(branchLowerBound);
+  if (branches.some(branch => branch.kind === "unreadable")) {
+    return {
+      version: null,
+      reason: "is not a version range this check knows how to read",
+    };
+  }
+  // A disjunction permits the union of its branches, so one floorless branch
+  // makes the whole spec floorless: `<8 || ^9` permits everything below 8.
+  // Filtering that branch out would let the strongest branch speak for the
+  // weakest, reporting a floor the spec does not have.
+  if (branches.some(branch => branch.kind === "floorless")) {
+    return {
+      version: null,
+      reason:
+        "sets only an upper bound, so it permits every earlier release including vulnerable ones",
+    };
+  }
+  return {
+    version: branches.reduce(
+      (lowest, branch) =>
+        compare(branch.version, lowest) < 0 ? branch.version : lowest,
+      branches[0].version
+    ),
+    reason: null,
+  };
+}
+
+/**
+ * Lowest version a spec permits, as a comparable tuple.
+ *
+ * Partial and wildcard constraints resolve to their floor — `^8` is `8.0.0`,
+ * `~8.2` is `8.2.0`, `5.x` is `5.0.0` — rather than to null. Requiring all
+ * three components meant every such floor came back null, and the audit's
+ * `if (!lowest) continue` then skipped it in silence (lisa#3438).
+ *
+ * `null` now means only "no floor was read here" and never "nothing to
+ * check". Callers must report it; {@link lowerBoundGap} supplies the wording.
+ * @param {string} spec A range like ">=5.0.7", "^8", "~2.0", "^7 || ^8".
+ * @returns {number[]|null} [major, minor, patch], or null when there is none.
+ */
+export function lowestPermitted(spec) {
+  return resolveLowerBound(spec).version;
+}
+
+/**
+ * Why a spec has no comparable floor, in words an operator can act on.
+ * @param {string} spec A version constraint.
+ * @returns {string|null} The reason, or null when the spec does resolve.
+ */
+export function lowerBoundGap(spec) {
+  return resolveLowerBound(spec).reason;
+}
+
 /**
  * Whether a version falls inside an advisory's vulnerable range.
  * @param {number[]} version Candidate version.
@@ -346,10 +556,17 @@ async function advisoriesFor(name) {
 /**
  * Audit every collected floor.
  * @returns {Promise<{problems: Array, unreachable: Array, unresolved: Array,
- *   unscanned: string[]|null, manifests: number, checked: number}>} Findings.
+ *   unparseable: Array, unscanned: string[]|null, manifests: number,
+ *   checked: number}>} Findings.
  */
 async function audit() {
-  const { found: floors, unresolved, scanned, unscanned } = collectFloors();
+  const {
+    found: floors,
+    unresolved,
+    unparseable,
+    scanned,
+    unscanned,
+  } = collectFloors();
   const problems = [];
   const unreachable = [];
   for (const [name, sites] of floors) {
@@ -364,9 +581,15 @@ async function audit() {
       for (const vulnerability of advisory.vulnerabilities ?? []) {
         if (vulnerability.package?.name !== name) continue;
         for (const site of sites) {
-          const lowest = lowestPermitted(site.spec);
-          if (!lowest) continue;
-          if (!withinRange(lowest, vulnerability.vulnerable_version_range)) {
+          // No null check here, deliberately. This loop used to open with
+          // `const lowest = lowestPermitted(site.spec); if (!lowest) continue;`
+          // — the skip that made an unreadable floor indistinguishable from a
+          // floor that passed. Every site in `found` now carries a floor
+          // resolved at collection time, and the ones that resolve to nothing
+          // are in `unparseable`, where they are reported and gate `--strict`.
+          if (
+            !withinRange(site.lowest, vulnerability.vulnerable_version_range)
+          ) {
             continue;
           }
           problems.push({
@@ -385,6 +608,7 @@ async function audit() {
     problems,
     unreachable,
     unresolved,
+    unparseable,
     unscanned,
     manifests: scanned.length,
     checked: floors.size,
@@ -394,13 +618,28 @@ async function audit() {
 async function main() {
   const strict = process.argv.includes("--strict");
   const asJson = process.argv.includes("--json");
-  const { problems, unreachable, unresolved, unscanned, manifests, checked } =
-    await audit();
+  const {
+    problems,
+    unreachable,
+    unresolved,
+    unparseable,
+    unscanned,
+    manifests,
+    checked,
+  } = await audit();
 
   if (asJson) {
     console.log(
       JSON.stringify(
-        { problems, unreachable, unresolved, unscanned, manifests, checked },
+        {
+          problems,
+          unreachable,
+          unresolved,
+          unparseable,
+          unscanned,
+          manifests,
+          checked,
+        },
         null,
         2
       )
@@ -443,6 +682,24 @@ async function main() {
     );
   }
 
+  // A floor whose version cannot be resolved to a lowest permitted release is
+  // a floor this audit did not compare. It used to be passed over in silence,
+  // which put it in the output as nothing at all — and nothing at all is what
+  // a floor that passed also looks like.
+  if (!asJson && unparseable.length > 0) {
+    console.log(
+      `\n> **${unparseable.length} floor(s) could NOT be checked.** Each states a version this audit could not read as a lowest permitted release, so none of them were compared against the advisory database. This is not a clean result for them.`
+    );
+    for (const entry of unparseable) {
+      console.log(
+        `> - \`${entry.name}: ${entry.spec}\` in ${entry.file} ${entry.path} — ${entry.reason}`
+      );
+    }
+    console.log(
+      "> Fix by rewriting each one as a constraint with a lower bound — `>=x.y.z`, `^x.y.z`, `~x.y.z`, or an exact version."
+    );
+  }
+
   // A manifest the patterns never opened is the same failure as a package the
   // advisory API never answered for: unexamined, and reported clean unless the
   // difference is stated. Printed whether or not anything else went wrong.
@@ -488,11 +745,13 @@ async function main() {
   // does: it is a floor nobody checked, and letting it pass reports it clean.
   // An unscanned tracked manifest gates for the same reason an inconclusive
   // lookup does: it is a floor nobody checked, and passing reports it clean.
+  // A floor with no readable lower bound gates for that reason a fourth time.
   if (
     strict &&
     (problems.length > 0 ||
       unreachable.length > 0 ||
       unresolved.length > 0 ||
+      unparseable.length > 0 ||
       (unscanned !== null && unscanned.length > 0))
   ) {
     process.exitCode = 1;

package/scripts/two-channel-couplings.json

@@ -7,7 +7,7 @@
     "workflows": 23,
     "steps": 639,
     "couplings": 27,
-    "inventory": 58
+    "inventory": 59
   },
   "counts": {
     "package-backed": 10,

package/typescript/copy-overwrite/.prettierignore

@@ -65,6 +65,7 @@ amplify
 scripts/bdd-matrix.mjs
 scripts/check-bdd-coverage.mjs
 scripts/check-conflict-markers.mjs
+scripts/check-orphaned-branches.mjs
 scripts/check-e2e-coverage.mjs
 scripts/check-lighthouse-details.mjs
 scripts/check-nightly-e2e-health.mjs