mandrel-platform 1.2.0 → 1.4.0

package/README.md

@@ -51,7 +51,7 @@ aggregator context, and the pin-by-tag/SHA versioning model.
 | [`deploy-cloudflare.yml`](docs/reusable-workflows.md#deploy-cloudflareyml) | Defence-in-depth Cloudflare deploy with a frozen deploy-secret allowlist. |
 | [`secret-scan-push.yml`](docs/reusable-workflows.md#secret-scan-pushyml) | Full-history gitleaks secret scan on push to the default branch. |
 | [`release-automation.yml`](docs/reusable-workflows.md#release-automationyml) | Conventional-commit release lifecycle (version bump + `CHANGELOG.md` + tag) via release-please. |
-| [`codeql.yml`](docs/reusable-workflows.md#codeqlyml) | CodeQL SAST analysis — dual-mode: runs on this repo's push/PR/schedule **and** is `workflow_call`-consumable. |
+| [`codeql.yml`](docs/reusable-workflows.md#codeqlyml) | CodeQL SAST analysis — dual-mode: runs on this repo's weekly schedule **and** is `workflow_call`-consumable (this repo's `ci.yml` calls it as a merge-blocking `code-scanning` job). |
 
 > `smoke-dispatch.yml` is a **platform-internal** cross-repo smoke trigger
 > (`push` / `workflow_dispatch`, not `workflow_call`). It appears in the
@@ -177,13 +177,19 @@ export default config;
 
 #### `stryker.base.json`
 
-Shared Stryker mutation-testing defaults (pnpm package manager,
-`perTest` coverage analysis, HTML + clear-text + progress reporters,
-`ignoreStatic`, a 60 s timeout, and high/low/break thresholds). Stryker's
-`extends` resolves a **local JSON path**, not an npm-package specifier, so
-the working mechanism is a `stryker.config.mjs` (or `.js` when
-`"type": "module"`) module that imports the base JSON and spreads it, then
-pins the test runner and mutate set:
+Shared Stryker mutation-testing defaults: pnpm package manager, `perTest`
+coverage analysis, HTML + clear-text + progress reporters, `ignoreStatic`,
+`disableBail: true`, the timeout budget a bail-free run needs
+(`timeoutMS: 120000` — 120 s — plus `timeoutFactor: 3` and
+`dryRunTimeoutMinutes: 15`), and high/low/break thresholds.
+
+Stryker has **no `extends` option at all** — its config reader loads exactly
+one config file and merges CLI arguments over it, and `extends` is not among
+the top-level properties its schema accepts, so a config that declares one is
+reported as an unknown option and otherwise ignored. The working mechanism is
+therefore a `stryker.config.mjs` (or `.js` when `"type": "module"`) module
+that imports the base JSON **by package specifier** and spreads it, then pins
+the test runner and mutate set:
 
 ```js
 // stryker.config.mjs — import the base and spread it
@@ -197,6 +203,12 @@ export default {
 };
 ```
 
+Adopting the base is not a drop-in bump: `disableBail: true` changes what the
+mutation score *means*, so any baseline captured under bail has to be
+re-derived, and the base's `break: 50` is a fleet floor of last resort rather
+than a calibrated target. Both are covered in
+[Adopting the bail-free Stryker base](docs/patterns.md#4a-adopting-the-bail-free-stryker-base).
+
 #### `commitlint.base.mjs`
 
 Single-sources the conventional-commit **type-enum** — the eleven types
@@ -480,10 +492,17 @@ app.use("*", createHonoRateLimit({ limit: 100, windowMs: 60_000 }));
 
 ### `scripts/audit-check.mjs`
 
-CVE gate script. Runs `pnpm audit --prod` and blocks on any **unsuppressed**
-High or Critical vulnerability in the production dependency graph. This is the
-stricter athportal/swarm-os policy: all unsuppressed High/Critical are
-blocking, not just fixable ones.
+Dependency gate script with **two independent blocking conditions**. It exits
+non-zero when *either* fires — a clean CVE scan does not excuse an unbounded
+override, and vice versa:
+
+1. **CVE gate.** Runs `pnpm audit --prod` and blocks on any **unsuppressed**
+   High or Critical vulnerability in the production dependency graph. This is
+   the stricter athportal/swarm-os policy: all unsuppressed High/Critical are
+   blocking, not just fixable ones.
+2. **Unbounded-override lint.** Blocks on any dependency override written
+   without an upper bound — **independently of the CVE scan, and with zero
+   CVEs present**. It runs *first*, before `pnpm audit` is invoked at all.
 
 Known/accepted CVEs are suppressed via a **dated, self-expiring allowlist**
 (`audit-allowlist.json` in the project root). Expired entries are treated as
@@ -504,6 +523,44 @@ Or copy the script into your repo's `scripts/` directory when you need
 local customization (and pin a semver range on `mandrel-platform` so drift
 is detected by Renovate).
 
+**Flags:**
+
+| Flag | Default | Purpose |
+| ---- | ------- | ------- |
+| `--allowlist <path>` | `audit-allowlist.json` in the invoking directory | Where to read the dated CVE allowlist from. An absent file means "no suppressions". |
+| `--package-json <path>` | `package.json` in the invoking directory | Which manifest the unbounded-override lint reads. Point it at a workspace member's manifest to lint that package instead of the root. An absent file skips the lint (the audit still runs). |
+
+**Unbounded-override lint:**
+
+An override *rewrites* a transitive dependent's declared range, so whatever is
+written there is the only thing standing between your tree and the next release
+of that package. Written open-endedly, the committed lockfile becomes the sole
+pin — and the moment anything re-resolves (a fresh install, a lockfile-less CI
+leg, a dependent's own bump) the newest release wins and can cross a major.
+Nothing else in the toolchain lints for this, so the gate names each offending
+override and its bound, then exits 1.
+
+Every override field is checked — `overrides`, `resolutions`, and
+`pnpm.overrides` — including dependent-scoped nested objects, which are
+reported by their full path (`overrides.some-dep.left-pad`).
+
+| Bound | Verdict | Why |
+| ----- | ------- | --- |
+| `1.2.3`, `=1.2.3` | ✅ bounded | Exact pin. |
+| `^1.2.3`, `~1.2.3` | ✅ bounded | Cannot cross a major on its own. |
+| `1.2.x`, `1.*` | ✅ bounded | The major is fixed; only lower positions float. |
+| `>=1.2.3 <2.0.0`, `1.2.3 - 2.0.0` | ✅ bounded | Carries an explicit upper bound. |
+| `npm:other-pkg@^1.2.3` | ✅ bounded | An alias is judged on the range it carries. |
+| `>=1.2.3`, `>1.2.3` | ❌ blocking | A bare lower bound; the next major satisfies it. |
+| `*`, `x`, `x.x`, `x.x.x`, `*.*.*` | ❌ blocking | npm reads a wildcard major as "any version". |
+| `latest`, `next` | ❌ blocking | A dist-tag pins nothing. |
+| `github:owner/repo`, `git+https://…`, `workspace:*`, `file:../pkg` | ❌ blocking | Non-registry specifiers re-resolve to whatever the source holds at install time. A git URL carrying an explicit `#semver:<range>` fragment is judged on that range instead. |
+| `^1.0.0 \|\| >=2.0.0` | ❌ blocking | A `\|\|` union is only as bounded as its loosest arm. |
+
+To fix a blocking override, give the bound an upper limit — `"^1.2.3"`,
+`"~1.2.3"`, or `">=1.2.3 <2.0.0"`. There is no allowlist for this check: the
+allowlist suppresses CVEs only.
+
 **Allowlist format (`audit-allowlist.json`):**
 
 ```jsonc

package/config/stryker.base.json

@@ -1,12 +1,17 @@
 {
   "$schema": "https://raw.githubusercontent.com/stryker-mutator/stryker-js/master/packages/api/schema/stryker-core.json",
-  "_comment": "Shared Stryker base for mandrel-platform consumers. Consumers extend via stryker.config.json's `extends` (string or array): { \"extends\": [\"mandrel-platform/stryker.base.json\"], \"testRunner\": \"vitest\", \"mutate\": [\"src/**/*.ts\"] }. testRunner, mutate, and per-repo thresholds stay consumer-tunable.",
+  "_comment": "Shared Stryker base for mandrel-platform consumers. Stryker has NO `extends` option — its config reader loads exactly one config file and merges CLI arguments over it, and `extends` is not among the top-level properties its schema accepts, so a config declaring one is reported as an unknown option and otherwise ignored. Adopt this base by importing it by package specifier and spreading it into a `stryker.config.mjs`; the single worked example lives in the mandrel-platform README under `stryker.base.json`. testRunner, mutate, and per-repo thresholds stay consumer-tunable. Asserted by scripts/stryker-base-config.test.mjs.",
   "packageManager": "pnpm",
   "reporters": ["html", "clear-text", "progress"],
   "coverageAnalysis": "perTest",
   "ignoreStatic": true,
   "cleanTempDir": true,
-  "timeoutMS": 60000,
+  "disableBail_comment": "Bail is OFF deliberately. Under Stryker's default bail the vitest runner can score a mutant Survived having completed zero of its covering tests, so a run reports a number nothing measured and a committed baseline becomes a floor under it. Every mutant now runs its full covering set, which lengthens the run — the three timeouts below are sized for that and must move together with this flag. Asserted by scripts/stryker-base-config.test.mjs.",
+  "disableBail": true,
+  "timeoutMS": 120000,
+  "timeoutFactor": 3,
+  "dryRunTimeoutMinutes": 15,
+  "thresholds_comment": "`break: 50` is unchanged, and deliberately so. It was chosen while bail deflated the measured score (a consumer recorded 53.5% against a real 72.29%), but that deflation runs one way only: a bail-free score is higher, so a break calibrated against a deflated number cannot fail a run it would previously have passed. Raising it fleet-wide would be the very sin the flag above exists to prevent — a fail-closed number nothing measured, imposed on consumers whose real scores are unknown from here. So 50 stays a floor of last resort rather than a calibrated target: after re-deriving a baseline on the bail-free base (docs/patterns.md, 'Adopting the bail-free Stryker base'), set a tighter break locally. `high`/`low` are report-colour bands and fail nothing.",
   "thresholds": {
     "high": 80,
     "low": 60,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^2.7.0"
+    "mandrel": "^2.31.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/audit-check.mjs

@@ -18,16 +18,28 @@
  *   an uninterpretable report means the gate cannot prove the graph is
  *   clean, so it must fail closed rather than wave the build through.
  *
+ * Unbounded-override lint (Story #365):
+ *   A dependency override REWRITES a transitive dependent's declared range.
+ *   Written as a bare lower bound (`">=1.2.3"`, `"*"`, `"x.x.x"`) or as a
+ *   non-registry specifier (`"github:owner/repo"`, `"workspace:*"`) it is
+ *   open-ended, so
+ *   the committed lockfile becomes the only pin and any fresh resolution
+ *   re-picks the newest release — which can cross a major. Nothing else in the
+ *   toolchain lints for that, so this gate names each such override and its
+ *   bound before it runs the audit.
+ *
  * Usage:
  *   node scripts/audit-check.mjs
  *   node scripts/audit-check.mjs --allowlist path/to/allowlist.json
+ *   node scripts/audit-check.mjs --package-json path/to/package.json
  *
  * Exit codes:
  *   0 — no blocking vulnerabilities (all High/Critical suppressed with
- *       valid, non-expired allowlist entries, or none found)
+ *       valid, non-expired allowlist entries, or none found) and every
+ *       dependency override carries an upper bound
  *   1 — one or more unsuppressed High/Critical CVEs, expired allowlist
- *       entries were encountered, or the audit report was uninterpretable
- *       while pnpm audit exited non-zero
+ *       entries were encountered, an override was unbounded, or the audit
+ *       report was uninterpretable while pnpm audit exited non-zero
  *
  * Allowlist format (JSON):
  *   [
@@ -183,6 +195,251 @@ export function partitionAllowlist(allowlist, today) {
   return { suppressed, expired, invalid };
 }
 
+/**
+ * Fields a package.json can express dependency overrides through. All three
+ * are checked, because a repo that has migrated package managers routinely
+ * carries more than one and an unbounded bound is equally open-ended in any
+ * of them.
+ */
+const OVERRIDE_FIELDS = ["overrides", "resolutions", "pnpm.overrides"];
+
+/**
+ * Specifier prefixes that are not registry semver ranges at all: a git ref, a
+ * workspace sibling, a local path, a tarball URL. Each re-resolves to whatever
+ * that source holds at install time — `github:owner/repo` tracks the default
+ * branch, `workspace:*` tracks the sibling's current version — so none of them
+ * expresses an upper bound and none can be judged bounded. Before Story #375
+ * they all fell through to the catch-all and were reported bounded.
+ */
+const NON_SEMVER_PROTOCOLS = [
+  "bitbucket:",
+  "file:",
+  "gist:",
+  "git+",
+  "git:",
+  "github:",
+  "gitlab:",
+  "http:",
+  "https:",
+  "link:",
+  "portal:",
+  "workspace:",
+];
+
+/**
+ * Is `value` a wildcard that pins nothing — `*`, a dist-tag, or a dotted
+ * wildcard such as `x.x.x`, `x.x` or `*.*.*`?
+ *
+ * The MAJOR position is the whole test, because npm reads `x.x.x` and `x.x` as
+ * exactly `*` (any version). A wildcard below the major — `1.2.x`, `1.*` —
+ * stays inside major 1 and is genuinely bounded, so only a wildcard in the
+ * first position is open-ended. Story #375: the enumerated regex this replaces
+ * listed `*`, `x` and `*.*.*` but not the dotted `x` forms, which is how the
+ * exact shape the lint exists to catch read as bounded.
+ *
+ * Deliberately answers for a SINGLE bare token only. A compound range spells
+ * its own upper bound out (`x.x <2.0.0`, `x.x.x - 2.0.0`) and is judged on
+ * that by the caller; reading the first dot-segment of the whole string would
+ * call such a range unbounded purely on its lower end.
+ *
+ * @param {string} value trimmed specifier
+ * @returns {boolean}
+ */
+function isWildcardSpec(value) {
+  if (/\s/.test(value)) {
+    return false;
+  }
+
+  if (/^(latest|next)$/i.test(value)) {
+    return true;
+  }
+
+  return /^[*xX]$/.test(value.split(".")[0]);
+}
+
+/**
+ * Strip a leading range operator from a single bare token.
+ *
+ * `isWildcardSpec` reads the major position, which a leading operator shifts
+ * out of view: `^x.x.x` splits to `^x`, matches nothing, and reads as a real
+ * version. An operator applied to "any version" is still any version, so the
+ * operator has to come off before the major position can be judged.
+ *
+ * @param {string} term single bare token
+ * @returns {string}
+ */
+function stripRangeOperator(term) {
+  return term.replace(/^(?:[<>]=?|[\^~=])+/, "");
+}
+
+/**
+ * Does this single bare token carry a real upper bound?
+ *
+ * A wildcard pins nothing, and a bare lower bound (`>=1.0.0`) is open above by
+ * construction. Anything else — an exact pin, a caret/tilde range, an `x`-style
+ * partial with a fixed major, an explicit `<` cap — closes the range.
+ *
+ * @param {string} term single bare token
+ * @returns {boolean}
+ */
+function termCarriesUpperBound(term) {
+  if (isWildcardSpec(stripRangeOperator(term))) {
+    return false;
+  }
+
+  return !/^>=?/.test(term);
+}
+
+/**
+ * Is this override specifier bounded above?
+ *
+ * An override REWRITES a transitive dependent's declared range, so whatever is
+ * written here is the only thing standing between the tree and the next
+ * release of that package. A bare lower bound (`>=1.2.3`, `>1.2.3`, `*`,
+ * `x.x.x`, `latest`) leaves the committed lockfile as the sole pin: the moment
+ * anything re-resolves — a fresh install, a lockfile-less CI leg, a
+ * dependent's own bump — the newest release wins and can cross a major. That
+ * is how a major jump silently emptied a consumer's test suite.
+ *
+ * Bounded means the specifier can never cross a major on its own: an exact
+ * pin, a caret/tilde range, an `x`-style partial whose major is fixed
+ * (`1.2.x`), or a compound range carrying an explicit upper bound
+ * (`>=1.2.3 <2`).
+ *
+ * @param {string} spec
+ * @returns {boolean}
+ */
+export function isBoundedOverride(spec) {
+  if (typeof spec !== "string") {
+    return false;
+  }
+
+  const value = spec.trim();
+  if (value === "") {
+    return false;
+  }
+
+  // `npm:other-pkg@<range>` and `pkg@<range>` alias forms are judged on the
+  // range they carry, not on the alias target.
+  if (value.startsWith("npm:")) {
+    const aliasMatch = /^npm:(?:@[^/]+\/)?[^@\s]+@(.+)$/.exec(value);
+    return aliasMatch ? isBoundedOverride(aliasMatch[1]) : false;
+  }
+
+  // A non-registry specifier resolves outside semver entirely. Only the
+  // explicit `#semver:<range>` fragment a git URL may carry is a real range,
+  // and it is judged on its own merits exactly as an `npm:` alias is.
+  const lower = value.toLowerCase();
+  if (NON_SEMVER_PROTOCOLS.some((protocol) => lower.startsWith(protocol))) {
+    const semverFragment = /#semver:(.+)$/.exec(value);
+    return semverFragment ? isBoundedOverride(semverFragment[1]) : false;
+  }
+
+  // A `||` union is only as bounded as its loosest arm.
+  if (value.includes("||")) {
+    return value.split("||").every((arm) => isBoundedOverride(arm));
+  }
+
+  // Wildcards and dist-tags pin nothing at all — including behind a leading
+  // range operator, which shifts the major position out of view.
+  if (isWildcardSpec(stripRangeOperator(value))) {
+    return false;
+  }
+
+  // A hyphen range is bounded by its right-hand side alone: `x.x.x - 2.0.0`
+  // caps at 2.0.0 however loose its lower end is, and `x.x - x.x` caps at
+  // nothing however much it is spelled like a range.
+  //
+  // A real hyphen range takes plain versions on both sides. A comparator on
+  // either end (`>=1.0.0 - 2.0.0`) is malformed, so reading its right-hand
+  // side as the cap would answer a range npm never agreed to parse — that one
+  // is left to the compound logic below, which keeps failing closed on it.
+  const hyphenRange = /^(.+?)\s+-\s+(.+)$/.exec(value);
+  if (hyphenRange) {
+    const lowerEnd = hyphenRange[1].trim();
+    const upperEnd = hyphenRange[2].trim();
+    if (!/^[<>]/.test(lowerEnd) && !/^[<>]/.test(upperEnd)) {
+      return termCarriesUpperBound(upperEnd);
+    }
+  }
+
+  // An explicit upper bound anywhere in a space-separated compound closes it.
+  if (/[<]/.test(value)) {
+    return true;
+  }
+
+  // Otherwise a compound is only as bounded as its terms: when every one of
+  // them is a wildcard or a bare lower bound, nothing caps the range and the
+  // range-like spelling is the only thing suggesting otherwise.
+  if (/\s/.test(value) && !value.split(/\s+/).some(termCarriesUpperBound)) {
+    return false;
+  }
+
+  // A bare lower bound is the unbounded shape this check exists to name.
+  if (/^[>]=?/.test(value)) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Report every override in `pkgJson` expressed as an unbounded lower bound.
+ *
+ * Pure and package-manager agnostic: the caller supplies the parsed
+ * package.json, so this is unit-testable without a fixture tree.
+ *
+ * @param {unknown} pkgJson parsed package.json
+ * @returns {Array<{ field: string; package: string; bound: string }>}
+ */
+export function findUnboundedOverrides(pkgJson) {
+  /** @type {Array<{ field: string; package: string; bound: string }>} */
+  const findings = [];
+
+  if (pkgJson === null || typeof pkgJson !== "object") {
+    return findings;
+  }
+
+  for (const field of OVERRIDE_FIELDS) {
+    /** @type {unknown} */
+    let node = pkgJson;
+    for (const segment of field.split(".")) {
+      node =
+        node !== null && typeof node === "object"
+          ? /** @type {Record<string, unknown>} */ (node)[segment]
+          : undefined;
+    }
+
+    if (node === null || typeof node !== "object" || Array.isArray(node)) {
+      continue;
+    }
+
+    for (const [name, spec] of Object.entries(
+      /** @type {Record<string, unknown>} */ (node),
+    )) {
+      // A nested override object scopes a bound to one dependent; recurse so a
+      // nested unbounded bound is named too, keyed by its full path.
+      if (spec !== null && typeof spec === "object" && !Array.isArray(spec)) {
+        for (const nested of findUnboundedOverrides({ overrides: spec })) {
+          findings.push({
+            field,
+            package: `${name}.${nested.package}`,
+            bound: nested.bound,
+          });
+        }
+        continue;
+      }
+
+      const bound = typeof spec === "string" ? spec : String(spec);
+      if (!isBoundedOverride(bound)) {
+        findings.push({ field, package: name, bound });
+      }
+    }
+  }
+
+  return findings;
+}
+
 /**
  * True when `report` has the recognizable pnpm-audit shape: an object with
  * an `advisories` object. This is the discriminator the fail-closed contract
@@ -304,23 +561,30 @@ export function evaluateReport(report, auditExitCode, suppressed) {
  *
  * @param {string[]} argv
  * @param {string} [cwd]
- * @returns {{ allowlistPath: string }}
+ * @returns {{ allowlistPath: string; packageJsonPath: string }}
  */
 export function parseArgs(argv, cwd = process.cwd()) {
   let allowlistPath = null;
+  let packageJsonPath = null;
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === "--allowlist" && argv[i + 1]) {
       allowlistPath = resolve(cwd, argv[i + 1]);
       i++;
+    } else if (argv[i] === "--package-json" && argv[i + 1]) {
+      packageJsonPath = resolve(cwd, argv[i + 1]);
+      i++;
     }
   }
 
   if (allowlistPath === null) {
     allowlistPath = resolve(cwd, "audit-allowlist.json");
   }
+  if (packageJsonPath === null) {
+    packageJsonPath = resolve(cwd, "package.json");
+  }
 
-  return { allowlistPath };
+  return { allowlistPath, packageJsonPath };
 }
 
 /**
@@ -346,6 +610,57 @@ export function loadAllowlist(allowlistPath) {
   return parsed;
 }
 
+/**
+ * Gate a package.json on unbounded dependency overrides. Returns the process
+ * exit code (0 clean, 1 blocking) and prints what is wrong and how to fix it.
+ *
+ * Split out of `runCli` so BOTH outcomes are executable in a test: the clean
+ * path returns here without ever reaching `pnpm audit`, which needs a real
+ * lockfile and a network. A missing package.json is not this gate's business —
+ * the audit is what proves the graph.
+ *
+ * @param {string} packageJsonPath
+ * @returns {number}
+ */
+export function lintOverrides(packageJsonPath) {
+  if (!existsSync(packageJsonPath)) {
+    return 0;
+  }
+
+  /** @type {unknown} */
+  let pkgJson;
+  try {
+    pkgJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  } catch (err) {
+    console.error(
+      `[audit-check] ERROR: could not parse ${packageJsonPath}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return 1;
+  }
+
+  const unbounded = findUnboundedOverrides(pkgJson);
+  if (unbounded.length === 0) {
+    return 0;
+  }
+
+  console.error(
+    `[audit-check] ${unbounded.length} unbounded dependency override(s) in ${packageJsonPath}:`,
+  );
+  for (const finding of unbounded) {
+    console.error(
+      `  - ${finding.field}.${finding.package}: "${finding.bound}" has no upper bound`,
+    );
+  }
+  console.error(
+    "\n[audit-check] An override rewrites a dependent's range, so a bare lower bound leaves " +
+      "the lockfile as the only pin and lets a fresh resolution cross a major. Give each " +
+      'bound an upper limit — "^1.2.3", "~1.2.3", or ">=1.2.3 <2.0.0". Exit 1.',
+  );
+  return 1;
+}
+
 /**
  * Run `pnpm audit --prod --json`, returning the raw stdout and exit code.
  * pnpm audit exits non-zero when vulnerabilities are found; we want the JSON
@@ -372,7 +687,17 @@ function runPnpmAudit() {
  * @returns {number}
  */
 export function runCli(argv) {
-  const { allowlistPath } = parseArgs(argv);
+  const { allowlistPath, packageJsonPath } = parseArgs(argv);
+
+  // --- Lint dependency overrides -------------------------------------------
+  //
+  // Runs BEFORE the audit: an unbounded override is a standing invitation for
+  // the next resolution to cross a major, and nothing else in the toolchain
+  // looks for one.
+  const overrideExit = lintOverrides(packageJsonPath);
+  if (overrideExit !== 0) {
+    return overrideExit;
+  }
 
   // --- Load & validate the allowlist ---------------------------------------