@dependably/npm-check 1.7.0

package/src/migrator.js

@@ -0,0 +1,263 @@
+// src/migrator.js
+import { detectLockfileVersion, LOCKFILE_VERSIONS } from './format-library.js';
+
+export class MigrationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'MigrationError';
+  }
+}
+
+export function migrateToVersion(lockfile, targetVersion) {
+  const currentVersion = detectLockfileVersion(lockfile);
+  if (targetVersion === currentVersion) return lockfile;
+
+  if (![LOCKFILE_VERSIONS.V1, LOCKFILE_VERSIONS.V2, LOCKFILE_VERSIONS.V3].includes(targetVersion)) {
+    throw new MigrationError(`Unsupported target version: ${targetVersion}`);
+  }
+
+  const migrated = runMigrationPath(lockfile, currentVersion, targetVersion);
+  migrated.lockfileVersion = targetVersion;
+  return migrated;
+}
+
+// Dispatch to the concrete migration for a (current -> target) pair. Every pair
+// documented in CLAUDE.md is handled here (both upgrades and downgrades); the
+// multi-version hops (V1<->V3) are composed from the single-step migrations.
+function runMigrationPath(lockfile, currentVersion, targetVersion) {
+  const { V1, V2, V3 } = LOCKFILE_VERSIONS;
+  const key = `${currentVersion}->${targetVersion}`;
+  switch (key) {
+    case `${V1}->${V2}`: return migrateV1toV2(lockfile);
+    case `${V2}->${V3}`: return migrateV2toV3(lockfile);
+    case `${V3}->${V2}`: return migrateV3toV2(lockfile);
+    case `${V1}->${V3}`: return migrateV2toV3(migrateV1toV2(lockfile));
+    case `${V2}->${V1}`: return migrateV2toV1(lockfile);
+    case `${V3}->${V1}`: return migrateV2toV1(migrateV3toV2(lockfile));
+    default:
+      throw new MigrationError(`Unsupported migration path from ${currentVersion} to ${targetVersion}`);
+  }
+}
+
+// --- Path helpers -----------------------------------------------------------
+
+// Parse a packages-map install path into its node_modules name segments.
+// "node_modules/a"                       -> ['a']
+// "node_modules/@scope/a"                -> ['@scope/a']
+// "node_modules/a/node_modules/b"        -> ['a', 'b']
+// "node_modules/a/node_modules/@scope/b" -> ['a', '@scope/b']
+// Returns null for workspace source paths (e.g. "packages/app") which are not
+// node_modules installs and have no place in the legacy dependencies tree.
+function parseInstallPath(key) {
+  const prefix = 'node_modules/';
+  if (!key.startsWith(prefix)) return null;
+  return key.slice(prefix.length).split('/node_modules/');
+}
+
+// Merge a package entry's runtime/optional/peer dependency ranges into the
+// legacy tree's `requires` map (name -> range string). Returns null when empty.
+function buildRequires(pkg) {
+  const requires = {};
+  for (const section of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+    const deps = pkg[section];
+    if (deps && typeof deps === 'object') {
+      for (const [name, range] of Object.entries(deps)) {
+        if (typeof range === 'string') requires[name] = range;
+      }
+    }
+  }
+  return Object.keys(requires).length > 0 ? requires : null;
+}
+
+// Convert a v2/v3 packages-map entry into a legacy (v1/v2) dependencies-tree
+// node: a resolution object {version, resolved, integrity, requires, ...}.
+// `existing` preserves any nested `dependencies` already built from children
+// that were seen before their parent.
+function packageEntryToLegacyNode(pkg, existing) {
+  const node = { version: typeof pkg.version === 'string' ? pkg.version : '' };
+  if (pkg.resolved) node.resolved = pkg.resolved;
+  if (pkg.integrity) node.integrity = pkg.integrity;
+  if (pkg.dev) node.dev = true;
+  if (pkg.optional) node.optional = true;
+  const requires = buildRequires(pkg);
+  if (requires) node.requires = requires;
+  if (existing && existing.dependencies) node.dependencies = existing.dependencies;
+  return node;
+}
+
+// Reconstruct the nested legacy dependencies tree from a v2/v3 packages map.
+// Order-independent: parents seen after their children keep the children that
+// were already placed under them.
+function buildDependenciesTreeFromPackages(packages) {
+  const root = {};
+  for (const [key, pkg] of Object.entries(packages)) {
+    if (key === '' || !pkg || typeof pkg !== 'object') continue;
+    const segments = parseInstallPath(key);
+    if (!segments || segments.length === 0) continue; // workspace source dir, not an install
+
+    let tree = root;
+    for (let i = 0; i < segments.length - 1; i++) {
+      const seg = segments[i];
+      if (!tree[seg]) tree[seg] = { version: '' };
+      if (!tree[seg].dependencies) tree[seg].dependencies = {};
+      tree = tree[seg].dependencies;
+    }
+    const name = segments[segments.length - 1];
+    tree[name] = packageEntryToLegacyNode(pkg, tree[name]);
+  }
+  return root;
+}
+
+// npm hosted-git shorthands (github:/gitlab:/bitbucket:/gist:) as they appear in
+// a v1 lockfile's `version` field. Map them to a `git+`-form URL so v2/v3
+// classification (resolved startsWith git+/git://) recognizes them as git deps —
+// otherwise the entry looks like a plain registry package and gets a bogus
+// placeholder integrity stamped on it (EINTEGRITY on npm ci).
+const HOSTED_GIT_HOSTS = {
+  github: 'github.com',
+  gitlab: 'gitlab.com',
+  bitbucket: 'bitbucket.org',
+  gist: 'gist.github.com'
+};
+function normalizeHostedGitShorthand(version) {
+  if (typeof version !== 'string') return null;
+  const m = /^(github|gitlab|bitbucket|gist):(.+)$/.exec(version);
+  if (!m) return null;
+  return `git+https://${HOSTED_GIT_HOSTS[m[1]]}/${m[2]}`;
+}
+
+// Convert a v1 dependencies-tree node into a v2 packages-map entry (drops the
+// nested `dependencies` — those become their own path-keyed entries — and turns
+// `requires` back into a `dependencies` range map).
+// A v1 git dep carries its git URL in `version`, often with no `resolved`. v2/v3
+// classify git deps by a `git+`/`git://` `resolved`, so derive one — otherwise the
+// entry looks like a plain registry package and gets a bogus placeholder integrity
+// stamped on it. Covers explicit git URLs and npm's hosted-git shorthands
+// (github:/gitlab:/bitbucket:/gist:). Returns null when the version isn't a git ref.
+function v1GitResolved(node) {
+  if (typeof node.version !== 'string') return null;
+  if (node.version.startsWith('git+') || node.version.startsWith('git://')) return node.version;
+  return normalizeHostedGitShorthand(node.version);
+}
+
+function v1NodeToPackageEntry(node) {
+  const entry = {};
+  if (node.version !== undefined) entry.version = node.version;
+  if (node.resolved) entry.resolved = node.resolved;
+  if (node.integrity) entry.integrity = node.integrity;
+  if (node.dev) entry.dev = true;
+  if (node.optional) entry.optional = true;
+  // A v1 bundled dep is flagged `bundled: true`; v2/v3 spell it `inBundle`.
+  // Preserve it so forEachPackageEntry keeps classifying the entry as bundled
+  // (no registry tarball → the fixer must not stamp placeholder integrity).
+  if (node.bundled) entry.inBundle = true;
+  if (!entry.resolved) {
+    const gitUrl = v1GitResolved(node);
+    if (gitUrl) entry.resolved = gitUrl;
+  }
+  if (node.requires && typeof node.requires === 'object') {
+    entry.dependencies = { ...node.requires };
+  }
+  return entry;
+}
+
+// Walk a v1 nested dependencies tree, emitting one packages-map entry per node
+// keyed by its full node_modules install path.
+function walkV1Tree(tree, pathPrefix, packages) {
+  for (const [name, node] of Object.entries(tree)) {
+    if (!node || typeof node !== 'object') continue;
+    const key = `${pathPrefix}/${name}`;
+    packages[key] = v1NodeToPackageEntry(node);
+    if (node.dependencies && typeof node.dependencies === 'object') {
+      walkV1Tree(node.dependencies, `${key}/node_modules`, packages);
+    }
+  }
+}
+
+// Build the v2 packages map from a v1 lockfile's dependencies tree: a root
+// entry ('') with direct-dependency range strings, plus a path-keyed entry for
+// every node in the tree carrying its resolution data.
+function buildPackagesFromV1Tree(lockfile) {
+  const packages = {};
+  const tree = lockfile.dependencies || {};
+
+  const root = { name: lockfile.name, version: lockfile.version };
+  for (const [name, node] of Object.entries(tree)) {
+    if (!node || typeof node !== 'object' || typeof node.version !== 'string') continue;
+    const section = node.dev ? 'devDependencies' : 'dependencies';
+    root[section] = root[section] || {};
+    root[section][name] = node.version;
+  }
+  packages[''] = root;
+
+  walkV1Tree(tree, 'node_modules', packages);
+  return packages;
+}
+
+// --- Single-step migrations -------------------------------------------------
+
+// V1 -> V2: keep the v1 dependencies tree verbatim (it IS a valid v2 legacy
+// tree) and add the packages map derived from it. Nothing is lost.
+function migrateV1toV2(lockfile) {
+  const packages = buildPackagesFromV1Tree(lockfile);
+  return { ...lockfile, packages, requires: true };
+}
+
+// V2 -> V3: keep the packages map (including the root '' entry) verbatim; drop
+// the legacy dependencies tree and top-level `requires` that v3 must not carry.
+function migrateV2toV3(lockfile) {
+  // v3 carries neither the legacy dependencies tree nor top-level `requires`.
+  const rest = { ...lockfile };
+  delete rest.dependencies;
+  delete rest.requires;
+  let packages = lockfile.packages;
+  if (!packages || typeof packages !== 'object' || Object.keys(packages).length === 0) {
+    // A merge-damaged v2 may carry only the legacy dependencies tree. Rebuild
+    // the packages map from it rather than silently emitting an empty v3 that
+    // destroys every locked resolution (mirrors migrateV2toV1's fallback).
+    packages = buildPackagesFromV1Tree(lockfile);
+  } else {
+    packages = { ...packages };
+  }
+  return { ...rest, packages };
+}
+
+// V3 -> V2: keep the packages map verbatim; reconstruct the legacy dependencies
+// tree as resolution objects so npm 6 gets its locked versions back.
+function migrateV3toV2(lockfile) {
+  const packages = { ...(lockfile.packages || {}) };
+  const dependencies = buildDependenciesTreeFromPackages(packages);
+  return { ...lockfile, packages, dependencies, requires: true };
+}
+
+// V2 -> V1: drop the packages map (and `requires`), keep the legacy dependencies
+// tree. When a v2 file lacks that tree, reconstruct it from the packages map.
+function migrateV2toV1(lockfile) {
+  let dependencies = lockfile.dependencies;
+  if (!dependencies || typeof dependencies !== 'object' || Object.keys(dependencies).length === 0) {
+    dependencies = buildDependenciesTreeFromPackages(lockfile.packages || {});
+  }
+  // v1 carries neither the packages map nor top-level `requires`.
+  const rest = { ...lockfile };
+  delete rest.packages;
+  delete rest.requires;
+  return { ...rest, dependencies };
+}
+
+export class PackageLockMigrator {
+  constructor(options = {}) {
+    this.preserveMetadata = options.preserveMetadata || false;
+  }
+
+  migrate(lockfile, targetVersion) {
+    const migrated = migrateToVersion(lockfile, targetVersion);
+    if (this.preserveMetadata) {
+      const metadata = {
+        name: lockfile.name,
+        version: lockfile.version
+      };
+      return { ...migrated, ...metadata };
+    }
+    return migrated;
+  }
+}

package/src/npmrc-validator.js

@@ -0,0 +1,205 @@
+// src/npmrc-validator.js
+// Parse and validate an ini-style project `.npmrc`, mirroring validator.js's
+// contract: validateNpmrc(contentOrParsed, options) => { valid, errors, warnings, info }.
+// We only ever inspect the project-level `.npmrc` (the committed, reproducible
+// artifact) — not the machine's ~/.npmrc — so results match between local and CI.
+
+export class NpmrcValidationError extends Error {
+  constructor(message, code) {
+    super(message);
+    this.name = 'NpmrcValidationError';
+    this.code = code;
+  }
+}
+
+/**
+ * Parse ini-style .npmrc content into entries, recording 1-based line numbers.
+ * Tolerant and comment-aware (`;` and `#` start comments, inline too); strips
+ * surrounding quotes from values. A non-comment, non-blank line without `=` is a
+ * bare boolean key: npm parses `.npmrc` with the `ini` package, which reads
+ * `engine-strict` as `engine-strict = true`, so we do the same (value `'true'`)
+ * and let the entry flow through the normal checks (a bare typo still trips the
+ * unknown-key warning) rather than hard-erroring on legal config.
+ *
+ * @returns {{ key: string|null, value: string|null, line: number, raw?: string, malformed?: boolean }[]}
+ */
+export function parseNpmrc(content) {
+  const entries = [];
+  const lines = (content || '').split(/\r?\n/);
+  lines.forEach((raw, i) => {
+    // Strip comments: a `;`/`#` starts a comment only at line-start or when
+    // preceded by whitespace (npm/ini semantics) — so `_password=pa#ss` keeps
+    // its literal value and a secret can't be truncated out of detection.
+    const line = raw.replace(/(^|\s)[;#].*$/, '$1').trim();
+    if (!line) return;
+    const eq = line.indexOf('=');
+    if (eq === -1) {
+      // Bare boolean key (`ini` semantics): `engine-strict` === `engine-strict=true`.
+      entries.push({ key: line.toLowerCase(), value: 'true', line: i + 1 });
+      return;
+    }
+    const value = line.slice(eq + 1).trim().replace(/(?:^["'])|(?:["']$)/g, '');
+    entries.push({
+      key: line.slice(0, eq).trim().toLowerCase(),
+      value,
+      line: i + 1
+    });
+  });
+  return entries;
+}
+
+// Common, recognized npm config keys — used only to *warn* on unknowns, so this
+// is intentionally a generous subset rather than an exhaustive list.
+const KNOWN_KEYS = new Set([
+  'registry', 'fund', 'audit', 'audit-level', 'save', 'save-exact', 'save-prefix',
+  'package-lock', 'package-lock-only', 'engine-strict', 'strict-ssl', 'ca', 'cafile',
+  'cert', 'key', 'proxy', 'https-proxy', 'noproxy', 'always-auth', 'init-author-name',
+  'init-author-email', 'init-author-url', 'init-license', 'init-version', 'loglevel',
+  'prefix', 'cache', 'legacy-peer-deps', 'fetch-retries', 'fetch-retry-mintimeout',
+  'fetch-retry-maxtimeout', 'fetch-timeout', 'access', 'tag', 'lockfile-version',
+  'omit', 'include', 'ignore-scripts', 'foreground-scripts', 'node-options',
+  'progress', 'prefer-offline', 'prefer-online', 'offline', 'global', 'unsafe-perm',
+  'user-agent', 'maxsockets', 'before', 'workspaces', 'workspace'
+]);
+
+// Plaintext-credential keys: bare `_auth`/`_authtoken`/`_password`, or the
+// scoped `//host/:_authToken` form npm uses for per-registry auth.
+const SECRET_KEY_RE = /(^|\/|:)_(auth|authtoken|authbase64|password)$/i;
+const ENV_REF_RE = /\$\{[^}]+\}/;
+// A value that is ENTIRELY an env reference is safe; a partial one
+// (`realsecret${X}`) must NOT exempt the line, or a plaintext secret slips by.
+const ENV_REF_ONLY_RE = /^\$\{[^}]+\}$/;
+
+const ALWAYS_ERROR_CODES = new Set([
+  'NPMRC_PLAINTEXT_SECRET',
+  'NPMRC_STRICT_SSL_OFF',
+  'NPMRC_REJECT_UNAUTHORIZED_OFF'
+]);
+
+/**
+ * Security-critical codes that should fail a run regardless of how the audit
+ * rule's severity is configured. Exported so the audit rule can force them.
+ */
+export const NPMRC_SECURITY_CODES = ALWAYS_ERROR_CODES;
+
+// Each check below inspects one parsed entry and pushes into the shared
+// errors/warnings arrays via `sink`. It returns `true` when it has fully
+// handled the entry (the caller then moves on), so the security/registry rules
+// short-circuit the later unknown-key warning exactly as before.
+
+// Plaintext credential keys: error unless the value is entirely an env ref.
+// Auth lines are always "handled" so they never trip the unknown-key warning.
+function checkSecret({ key, value, line }, sink) {
+  if (!SECRET_KEY_RE.test(key)) return false;
+  if (!ENV_REF_ONLY_RE.test(value)) {
+    sink.errors.push(new NpmrcValidationError(
+      `plaintext credential at line ${line} ("${key}") — use an env var reference like \${NPM_TOKEN}`,
+      'NPMRC_PLAINTEXT_SECRET'));
+  }
+  return true;
+}
+
+// TLS / verification weakening: strict-ssl=false/0 and any *rejectUnauthorized
+// disabled are always hard errors.
+function checkTls({ key, value, line }, sink) {
+  if (key === 'strict-ssl' && /^(false|0)$/i.test(value)) {
+    sink.errors.push(new NpmrcValidationError(`strict-ssl=${value} at line ${line} disables TLS verification`, 'NPMRC_STRICT_SSL_OFF'));
+    return true;
+  }
+  if (key.endsWith('rejectunauthorized') && /^(false|0)$/i.test(value)) {
+    sink.errors.push(new NpmrcValidationError(`rejectUnauthorized disabled at line ${line}`, 'NPMRC_REJECT_UNAUTHORIZED_OFF'));
+    return true;
+  }
+  return false;
+}
+
+// Privilege escalation: unsafe-perm enabled runs lifecycle scripts elevated.
+function checkUnsafePerm({ key, value, line }, sink) {
+  if (key !== 'unsafe-perm' || !/^(true|1)$/i.test(value)) return false;
+  sink.warnings.push({ code: 'NPMRC_UNSAFE_PERM', message: `unsafe-perm enabled at line ${line} — lifecycle scripts run with elevated privileges` });
+  return true;
+}
+
+// Registry URL validity / scheme. Env-interpolated URLs can't be parsed, so
+// they're accepted as-is; anything else must be a valid URL, and http:// warns.
+function checkRegistry({ key, value, line }, sink) {
+  if (key !== 'registry' && !key.endsWith(':registry')) return false;
+  if (ENV_REF_RE.test(value)) return true; // env-interpolated URL — can't statically parse
+  let url = null;
+  try {
+    url = new URL(value);
+  } catch {
+    sink.errors.push(new NpmrcValidationError(`invalid registry URL at line ${line}: "${value}"`, 'NPMRC_INVALID_REGISTRY'));
+  }
+  if (url && url.protocol === 'http:') {
+    sink.warnings.push({ code: 'NPMRC_INSECURE_REGISTRY', message: `registry over http:// at line ${line} (${value}) — prefer https://` });
+  }
+  return true;
+}
+
+// Unknown key (warn only). `//host/...` lines are per-registry auth/config and
+// are skipped; a scoped key is matched on its bare suffix too.
+function checkUnknownKey({ key, line }, sink) {
+  if (key.startsWith('//')) return; // per-registry auth/config line
+  const bareKey = key.includes(':') ? key.slice(key.lastIndexOf(':') + 1) : key;
+  if (!KNOWN_KEYS.has(key) && !KNOWN_KEYS.has(bareKey)) {
+    sink.warnings.push({ code: 'NPMRC_UNKNOWN_KEY', message: `unrecognized npm config key "${key}" at line ${line}` });
+  }
+}
+
+// npm-specific keys that pnpm genuinely does NOT read from .npmrc. pnpm reads
+// virtually every other setting from `.npmrc` — registry/auth, TLS, proxies, and
+// its install behaviour (`shamefully-hoist`, `node-linker`, `hoist-pattern`,
+// `strict-peer-dependencies`, …) — across pnpm 7-10, so warning on "everything
+// non-auth" is factually wrong for most pnpm projects. We flag ONLY these
+// npm-only keys, each of which has a differently-named pnpm equivalent (or none)
+// and is therefore silently dropped by pnpm. The value is a remediation hint.
+const PNPM_IGNORED_KEYS = new Map([
+  ['package-lock', 'pnpm uses `lockfile`'],
+  ['package-lock-only', 'pnpm uses `lockfile-only`'],
+  ['legacy-peer-deps', 'pnpm uses `auto-install-peers` / `strict-peer-dependencies`']
+]);
+
+// pnpm flavor: flag the handful of npm-only settings pnpm does not honor. Reached
+// only for entries not already claimed by the secret/TLS/registry checks.
+function checkPnpmIgnored({ key, line }, sink) {
+  const hint = PNPM_IGNORED_KEYS.get(key);
+  if (!hint) return;
+  sink.warnings.push({
+    code: 'NPMRC_PNPM_IGNORED',
+    message: `npm-only setting "${key}" at line ${line} in .npmrc is not honored by pnpm — ${hint}`
+  });
+}
+
+// Run the security/registry checks in order; the first to claim the entry wins.
+// When none does, the entry falls through to the unknown-key (npm) or
+// pnpm-ignored (pnpm) warning.
+function validateEntry(entry, sink, flavor) {
+  if (entry.malformed) {
+    sink.errors.push(new NpmrcValidationError(`malformed line ${entry.line}: "${entry.raw}" (expected key=value)`, 'NPMRC_SYNTAX'));
+    return;
+  }
+  if (checkSecret(entry, sink)) return;
+  if (checkTls(entry, sink)) return;
+  if (checkUnsafePerm(entry, sink)) return;
+  if (checkRegistry(entry, sink)) return;
+  if (flavor === 'pnpm') {
+    checkPnpmIgnored(entry, sink);
+  } else {
+    checkUnknownKey(entry, sink);
+  }
+}
+
+export function validateNpmrc(input, options = {}) {
+  const entries = typeof input === 'string' ? parseNpmrc(input) : (input || []);
+  const sink = { errors: [], warnings: [] };
+  const info = { keys: entries.filter((e) => e.key).map((e) => e.key) };
+
+  for (const e of entries) {
+    validateEntry(e, sink, options.flavor);
+  }
+
+  const { errors, warnings } = sink;
+  const valid = errors.length === 0 && !(options.strictMode && warnings.length > 0);
+  return { valid, errors, warnings, info };
+}

package/src/overrides.js

@@ -0,0 +1,71 @@
+// src/overrides.js
+// Shared walker for npm `overrides` and the pnpm `pnpm.overrides` manifest field.
+//
+// npm `overrides` is NESTED: a value is either a range string or a nested object
+// whose "." key overrides the parent package itself and whose other keys override
+// that package's own children. A string value beginning with "$" is a REFERENCE
+// to a direct dependency's version, not a range, and must be skipped.
+//
+// pnpm `pnpm.overrides` is a FLAT map whose keys are selectors (`foo`, `foo@1`,
+// `parent>child`) and whose values are range strings (also possibly "$ref"); the
+// flat form is just the non-nested base case of the same walk.
+//
+// Zero dependencies — a pure structural generator. Consumers (pinner, audit
+// pinned-versions rule, package.json validator) classify/validate the ranges.
+
+/**
+ * Derive the overridden package name from an override key, stripping a trailing
+ * `@version` selector (npm allows `"foo@2"`, `"@scope/foo@^1.0.0"` to scope an
+ * override to matching versions). The leading `@` of a scope is preserved.
+ * @param {string} key
+ * @returns {string}
+ */
+function overrideName(key) {
+  const at = key.lastIndexOf('@');
+  return at > 0 ? key.slice(0, at) : key;
+}
+
+/**
+ * Walk an overrides object, yielding every value leaf (each non-object entry).
+ * `$name` references are skipped (they point at a direct dep's version, not a
+ * range). A leaf's `range` is usually a string but MAY be a non-string for a
+ * malformed manifest — consumers classify/validate it (classifyRange and
+ * isValidRange both handle non-strings), so the validator can flag bad values.
+ *
+ * @param {object} overrides - The overrides object (npm `overrides` or `pnpm.overrides`)
+ * @param {object} [opts] - Internal recursion state: { parentName, path }
+ * @yields {{ path: string, name: string, range: *, container: object, key: string }}
+ *   path      - human-readable location ("foo", "bar > baz", "bar > .")
+ *   name      - the effective package name overridden (the parent for a "." key,
+ *               with any `@version` selector stripped)
+ *   range     - the leaf value (a range string, or a non-string if malformed)
+ *   container - the object holding the leaf (so a caller can rewrite in place)
+ *   key       - the leaf's key within `container`
+ */
+// Build the leaf descriptor for a non-object override value, or null when the
+// leaf should be skipped: a "$name" reference (points at a direct dep's version,
+// not a range) or a stray "." with no parent (malformed).
+function overrideLeaf(container, key, value, name, path) {
+  if (typeof value === 'string' && value.startsWith('$')) return null;
+  if (name == null) return null;
+  return { path, name, range: value, container, key };
+}
+
+export function* walkOverrides(overrides, opts = {}) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) return;
+  const { parentName = null, path = '' } = opts;
+
+  for (const [key, value] of Object.entries(overrides)) {
+    const here = path ? `${path} > ${key}` : key;
+    // "." refers to the parent package itself (npm nested form).
+    const name = key === '.' ? parentName : overrideName(key);
+
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      // Nested override object: the "." inside it refers to THIS key's package.
+      yield* walkOverrides(value, { parentName: name, path: here });
+    } else {
+      const leaf = overrideLeaf(overrides, key, value, name, here);
+      if (leaf) yield leaf;
+    }
+  }
+}