@dependably/npm-check 1.7.0

package/src/deprecation.js

@@ -0,0 +1,325 @@
+// src/deprecation.js
+// Deprecated-package scan: checks each locked package version against the npm
+// registry's per-version manifest `deprecated` field — the same signal npm
+// surfaces as "npm warn deprecated <pkg>@<ver>: <message>" during `npm ci`.
+//
+// Like the integrity and vuln checks it is lockfile-first (no node_modules) and
+// reuses the registry-base derivation + concurrency model. Deprecation is a soft
+// signal (npm itself only warns; it never fails the install), so findings are
+// warnings by default; pass `failOnDeprecated` to fail the run in CI. Identical
+// name@version@registry entries are fetched once and the result is attributed to
+// every lockfile path that shares them.
+import { createProgressReporter } from './progress-reporter.js';
+import { forEachPackageEntry } from './format-library.js';
+import { DEFAULT_REGISTRY, fetchPackumentManifest } from './integrity.js';
+import { buildEnvelope } from './schema.js';
+
+/**
+ * Custom error class for deprecation-scan operations
+ */
+export class DeprecationError extends Error {
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'DeprecationError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+/**
+ * Map items through an async fn with a concurrency cap, preserving input order.
+ * (Mirrors the private helper in checker.js/vuln.js — kept local to keep modules decoupled.)
+ */
+async function mapWithConcurrency(items, limit, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length || 1)) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+/**
+ * Normalize a manifest's `deprecated` field to a message string or null.
+ * npm marks a version deprecated with a non-empty string; an empty string means
+ * "un-deprecated", and a bare `true` (rare) carries no message of its own.
+ */
+function deprecationMessage(raw) {
+  if (typeof raw === 'string' && raw.trim() !== '') return raw;
+  if (raw === true) return 'deprecated';
+  return null;
+}
+
+/**
+ * Build a fresh, empty results accumulator with the public return shape.
+ */
+function createResults() {
+  return {
+    valid: true,
+    scanned: 0,
+    deprecated: 0,
+    clean: 0,
+    unresolved: 0,
+    skipped: 0,
+    errors: [],
+    warnings: [],
+    unresolvedItems: [],
+    details: []
+  };
+}
+
+/**
+ * Collect the verifiable candidates from the lockfile, counting everything that
+ * can't be checked this way as skipped (mirror checker.js / vuln.js skip logic).
+ */
+function collectCandidates(lockfileData, defaultRegistry, results) {
+  const candidates = [];
+  forEachPackageEntry(lockfileData, (info) => {
+    const { key, entry, name, isRoot, isWorkspaceSource, isLink, isBundled, isGitDep, isFileDep } = info;
+    if (isRoot) return results.skipped++;
+    if (isWorkspaceSource) return results.skipped++;
+    if (isLink) return results.skipped++;
+    if (isBundled || isGitDep || isFileDep) return results.skipped++; // no registry manifest to check
+    if (!entry.version) return results.skipped++;
+    const registryBase = info.registryBase || defaultRegistry;
+    candidates.push({ key, name, version: entry.version, registryBase });
+  });
+  return candidates;
+}
+
+/**
+ * Dedupe identical name@version@registry candidates into fetch units; each unit
+ * is fetched once and its result is attributed to every entry that shares it.
+ */
+function groupCandidates(candidates) {
+  const groups = new Map();
+  for (const c of candidates) {
+    const dedupeKey = `${c.registryBase}\n${c.name}\n${c.version}`;
+    if (!groups.has(dedupeKey)) {
+      groups.set(dedupeKey, { name: c.name, version: c.version, registryBase: c.registryBase, entries: [] });
+    }
+    groups.get(dedupeKey).entries.push(c);
+  }
+  return [...groups.values()];
+}
+
+/**
+ * Record an unresolved unit — registry unreachable or version not found, i.e. the
+ * scan could not complete for these entries — against every lockfile entry that
+ * shares it. Fails the run when failOnUnresolved (the default), so a registry
+ * outage can never be mistaken for "no deprecations". This is the operational
+ * scan-failure case, distinct from a clean unit (manifest fetched, not deprecated).
+ */
+function recordUnresolved(unit, networkError, failOnUnresolved, results) {
+  const reason = networkError
+    ? `registry unreachable (${networkError.message})`
+    : `registry has no manifest for ${unit.name}@${unit.version}`;
+  for (const cand of unit.entries) {
+    const item = { package: unit.name, version: unit.version, packagePath: cand.key, reason };
+    results.unresolved++;
+    results.unresolvedItems.push(item);
+    results.details.push({ unresolved: true, ...item });
+    if (failOnUnresolved) {
+      results.valid = false;
+      results.errors.push(item);
+    }
+  }
+}
+
+/**
+ * Record a deprecated unit against every lockfile entry that shares it; findings
+ * are warnings by default and errors when failOnDeprecated is set.
+ */
+function recordDeprecated(unit, message, failOnDeprecated, results) {
+  for (const cand of unit.entries) {
+    results.deprecated++;
+    const finding = { package: unit.name, version: unit.version, packagePath: cand.key, message };
+    if (failOnDeprecated) {
+      results.errors.push(finding);
+      results.valid = false;
+    } else {
+      results.warnings.push(finding);
+    }
+    results.details.push({ deprecated: true, ...finding });
+  }
+}
+
+/**
+ * Record a clean unit (manifest fetched, not deprecated) against every entry.
+ */
+function recordClean(unit, results) {
+  for (const cand of unit.entries) {
+    results.clean++;
+    results.details.push({ deprecated: false, package: unit.name, version: unit.version, packagePath: cand.key });
+  }
+}
+
+/**
+ * Resolve a single fetch unit's manifest and fold its outcome into results.
+ */
+async function processUnit(unit, fetcher, failOnDeprecated, failOnUnresolved, results) {
+  let manifest = null;
+  let networkError = null;
+  try {
+    manifest = await fetcher(unit.name, unit.version, unit.registryBase);
+  } catch (e) {
+    networkError = e;
+  }
+
+  if (networkError || manifest === null) {
+    recordUnresolved(unit, networkError, failOnUnresolved, results);
+  } else {
+    const message = deprecationMessage(manifest.deprecated);
+    if (message) {
+      recordDeprecated(unit, message, failOnDeprecated, results);
+    } else {
+      recordClean(unit, results);
+    }
+  }
+
+  results.scanned += unit.entries.length;
+}
+
+/**
+ * Scan locked packages for deprecation notices via the registry version manifest.
+ *
+ * Outcomes per entry:
+ *   - deprecated: registry manifest carries a `deprecated` message
+ *   - clean:      manifest fetched, not deprecated (obtained data, nothing found)
+ *   - unresolved: registry unreachable or version not found — the scan could not
+ *                 complete (FAILS the run by default; fail-closed)
+ *   - skipped:    not checkable this way (root/workspace/link/git/file/bundled, missing version)
+ *
+ * Deprecated entries are warnings by default (npm itself only warns); pass
+ * `failOnDeprecated` to make a *found* deprecation an error. Note this is separate
+ * from `failOnUnresolved`, which governs whether a scan that *couldn't run* fails.
+ *
+ * @param {object} lockfileData - Parsed lockfile data (v2/v3)
+ * @param {object} options
+ * @param {number} options.concurrency - Parallel registry GETs (default: 8)
+ * @param {number} options.timeoutMs - Per-request timeout (default: 10000)
+ * @param {string} options.defaultRegistry - Registry for entries without a derivable base
+ * @param {boolean} options.offline - Skip all network; report everything as skipped
+ * @param {boolean} options.failOnDeprecated - Treat a *found* deprecation as a failure (default: false)
+ * @param {boolean} options.failOnUnresolved - Fail the run when the scan can't complete
+ *   (registry unreachable / version not found). Default true (fail closed); set false to tolerate.
+ * @param {Function} options.fetchManifest - Injectable (name, version, registryBase) => Promise<object|null>
+ * @param {Function} options.onProgress - Progress callback
+ * @returns {Promise<object>} Results object with summary and details
+ */
+export async function checkDeprecations(lockfileData, options = {}) {
+  const {
+    concurrency = 8,
+    timeoutMs = 10000,
+    defaultRegistry = DEFAULT_REGISTRY,
+    offline = false,
+    failOnDeprecated = false,
+    failOnUnresolved = true, // fail closed: a scan that couldn't complete must not pass as "clean"
+    fetchManifest = null,
+    onProgress = null
+  } = options;
+
+  if (lockfileData && lockfileData.lockfileVersion === 1) {
+    throw new DeprecationError(
+      'v1 lockfiles are not supported; run `npm-check migrate 3` first',
+      'UNSUPPORTED_VERSION'
+    );
+  }
+
+  const results = createResults();
+
+  // Collect verifiable candidates (mirror checker.js / vuln.js skip logic).
+  const candidates = collectCandidates(lockfileData, defaultRegistry, results);
+
+  // Offline: nothing left to do — count remaining candidates as skipped.
+  if (offline) {
+    results.skipped += candidates.length;
+    return results;
+  }
+
+  const fetcher = fetchManifest ||
+    ((name, version, registryBase) => fetchPackumentManifest(name, version, { registryBase, timeoutMs }));
+
+  // Dedupe identical name@version@registry so each unique version is fetched once;
+  // the single manifest result is attributed to every lockfile entry that shares it.
+  const units = groupCandidates(candidates);
+
+  const reporter = onProgress ? createProgressReporter(units.length, {
+    onProgress,
+    stage: 'Scanning for deprecated packages'
+  }) : null;
+  let completed = 0;
+
+  await mapWithConcurrency(units, concurrency, async (unit) => {
+    await processUnit(unit, fetcher, failOnDeprecated, failOnUnresolved, results);
+    completed++;
+    if (reporter) reporter.update(completed);
+  });
+
+  if (reporter) reporter.finish();
+
+  return results;
+}
+
+/**
+ * Map one deprecation notice (from results.errors/warnings) into the suite's shared
+ * Finding shape. Deprecation is not itself on the severity ladder, so the gate bucket
+ * (error when failOnDeprecated, else warn) becomes a top-level ladder string the same
+ * way report.js maps it — error→`high`, warn→`low` — and rides on under `extra.gate`.
+ * `category` is `deprecated`; `location` is null (a deprecation is package-level).
+ */
+function toSchemaFinding(f, gate) {
+  return {
+    severity: gate === 'error' ? 'high' : 'low',
+    ruleId: 'deprecated',
+    category: 'deprecated',
+    message: `${f.package}@${f.version}: ${f.message}`,
+    location: null, // a deprecation notice is not file-scoped
+    remediation: 'replace deprecated package',
+    extra: {
+      package: f.package,
+      installedVersion: f.version,
+      gate
+    }
+  };
+}
+
+/**
+ * Wrap a checkDeprecations() result in the shared finding-schema envelope.
+ * `findings` is the COMPLETE list of deprecation notices (errors that carry a
+ * message — i.e. the failOnDeprecated case — plus warnings); scan-completeness
+ * state (clean/unresolved/skipped, which drives the fail-closed gate) is preserved
+ * under `extra.scan` so nothing is lost. Mirrors vuln.js's vulnEnvelope.
+ *
+ * @param {object} result   - a checkDeprecations() result
+ * @param {object} meta
+ * @param {string} meta.target   - the lockfile path scanned, as given
+ * @param {number} meta.exitCode - the real process exit code (0/1/2)
+ * @returns {object} the shared envelope
+ */
+export function deprecationEnvelope(result, { target, exitCode }) {
+  const findings = [
+    ...result.errors.filter((e) => e.message).map((e) => toSchemaFinding(e, 'error')),
+    ...result.warnings.map((w) => toSchemaFinding(w, 'warn'))
+  ];
+  return buildEnvelope({
+    target,
+    scanned: result.scanned,
+    findings,
+    exitCode,
+    extra: {
+      scan: {
+        deprecated: result.deprecated,
+        clean: result.clean,
+        unresolved: result.unresolved,
+        skipped: result.skipped,
+        valid: result.valid,
+        unresolvedItems: result.unresolvedItems
+      }
+    }
+  });
+}

package/src/fixer.js

@@ -0,0 +1,207 @@
+// src/fixer.js
+import { migrateToVersion } from './migrator.js';
+import { LOCKFILE_VERSIONS, forEachPackageEntry } from './format-library.js';
+import { deduplicatePackages } from './updater.js';
+
+/**
+ * Fixer error class for explicit error reporting
+ */
+export class FixerError extends Error {
+  constructor(message, fixes = []) {
+    super(message);
+    this.name = 'FixerError';
+    this.fixes = fixes;
+  }
+}
+
+/**
+ * True when the value is a non-null object with a usable packages map.
+ * @param {object} lockfile - The lockfile to inspect
+ * @returns {boolean} Whether `lockfile.packages` is a usable object
+ */
+function hasPackagesMap(lockfile) {
+  return Boolean(lockfile.packages) && typeof lockfile.packages === 'object';
+}
+
+/**
+ * Sync the lockfile's root identity (name/version) with package.json when
+ * provided. A stale name/version here is exactly what the report's
+ * "Structure & format" errors flag after a package rename or version bump,
+ * and it's safe to correct without re-resolving the dependency tree.
+ * Mutates `fixed` (and `fixes`); returns the possibly-replaced lockfile.
+ * @param {object} fixed - The working lockfile
+ * @param {object} packageJson - The package.json to sync against
+ * @param {string[]} fixes - Accumulator for fix descriptions
+ * @returns {object} The working lockfile
+ */
+function syncRootIdentity(fixed, packageJson, fixes) {
+  if (!packageJson || typeof packageJson !== 'object') return fixed;
+
+  for (const field of ['name', 'version']) {
+    const desired = packageJson[field];
+    if (typeof desired !== 'string' || desired === '') continue;
+
+    if (fixed[field] !== desired) {
+      fixed[field] = desired;
+      fixes.push(`Synced lockfile ${field} to package.json ("${desired}")`);
+    }
+
+    if (!fixed.packages || !fixed.packages['']) continue;
+    const root = fixed.packages[''];
+    if (root[field] !== desired) {
+      fixed.packages = { ...fixed.packages, '': { ...root, [field]: desired } };
+      fixes.push(`Synced root package ${field} to package.json ("${desired}")`);
+    }
+  }
+  return fixed;
+}
+
+/**
+ * Run a migration step, translating failures into either a thrown FixerError
+ * (when `throwOnError`) or a warning fix entry. Returns the migrated lockfile,
+ * or the untouched input when the migration failed without throwing.
+ * @param {object} fixed - The working lockfile
+ * @param {number} targetVersion - The lockfile version to migrate to
+ * @param {string} successMsg - Fix description on success
+ * @param {string} failPrefix - Prefix for the failure message
+ * @param {boolean} throwOnError - Whether to throw on failure
+ * @param {string[]} fixes - Accumulator for fix descriptions
+ * @returns {object} The migrated (or untouched) lockfile
+ * @throws {FixerError} When migration fails and `throwOnError` is set
+ */
+function runMigration(fixed, targetVersion, successMsg, failPrefix, throwOnError, fixes) {
+  try {
+    const migrated = migrateToVersion(fixed, targetVersion);
+    fixes.push(successMsg);
+    return migrated;
+  } catch (e) {
+    if (throwOnError) {
+      throw new FixerError(`${failPrefix}: ${e.message}`, fixes);
+    }
+    fixes.push(`${failPrefix}: ${e.message}`);
+    return fixed;
+  }
+}
+
+/**
+ * Apply the requested explicit normalization plus the default v1→v2
+ * auto-migration. Returns the possibly-migrated lockfile.
+ * @param {object} fixed - The working lockfile
+ * @param {number|null} normalizeTo - Requested target version, if any
+ * @param {boolean} throwOnError - Whether to throw on failure
+ * @param {string[]} fixes - Accumulator for fix descriptions
+ * @returns {object} The working lockfile
+ */
+function applyMigrations(fixed, normalizeTo, throwOnError, fixes) {
+  const supported = [LOCKFILE_VERSIONS.V1, LOCKFILE_VERSIONS.V2, LOCKFILE_VERSIONS.V3];
+
+  // Normalize format if requested
+  if (normalizeTo && supported.includes(normalizeTo)) {
+    fixed = runMigration(
+      fixed, normalizeTo,
+      `Migrated lockfile to v${normalizeTo}`,
+      `Failed to migrate lockfile to v${normalizeTo}`,
+      throwOnError, fixes,
+    );
+  }
+
+  // If lockfile is v1 and has dependencies but no packages map, migrate to v2 by
+  // default — but only when the caller did NOT ask for an explicit target. When
+  // `normalizeTo` is given (even v1), honor it verbatim; otherwise this default
+  // would override the caller's stated target and silently re-upgrade to v2.
+  if (!normalizeTo && fixed.lockfileVersion === LOCKFILE_VERSIONS.V1 && fixed.dependencies) {
+    fixed = runMigration(
+      fixed, LOCKFILE_VERSIONS.V2,
+      'Auto-migrated v1 dependencies tree to v2 packages map',
+      'Auto-migration v1→v2 failed',
+      throwOnError, fixes,
+    );
+  }
+  return fixed;
+}
+
+/**
+ * Fill placeholder integrity hashes for registry package entries that have none.
+ * Only registry deps legitimately carry an integrity hash, so entries the
+ * integrity/checksum tooling deliberately skips — the root, workspace source
+ * dirs, links, and git/file/bundled deps — are left alone (stamping a fake hash
+ * on them corrupts an otherwise-valid lockfile). Entries already holding a hash
+ * are untouched. Mutates entries in place on the (already-cloned) working copy.
+ * @param {object} fixed - The working lockfile (a private copy)
+ * @param {string[]} fixes - Accumulator for fix descriptions
+ */
+function fillPlaceholderIntegrity(fixed, fixes) {
+  if (!hasPackagesMap(fixed)) return;
+
+  forEachPackageEntry(fixed, ({ key, entry, isRoot, isWorkspaceSource, isLink, isGitDep, isFileDep, isBundled }) => {
+    // Only registry entries carry an integrity hash; everything else legitimately
+    // has none (matches the checksum-fixer / integrity-checker skip list).
+    if (isRoot || isWorkspaceSource || isLink || isGitDep || isFileDep || isBundled) return;
+    if (!entry || typeof entry !== 'object') return;
+    // Already has a placeholder or a real hash, no action needed
+    if (entry.integrity) return;
+
+    entry.integrity = 'sha512-PLACEHOLDER';
+    fixes.push(`Added placeholder integrity for package at ${key}`);
+  });
+}
+
+/**
+ * Run the preserve-only deduplication step, reporting how many entries were
+ * removed. Failures become a thrown FixerError or a warning fix entry.
+ * @param {object} fixed - The working lockfile
+ * @param {boolean} throwOnError - Whether to throw on failure
+ * @param {string[]} fixes - Accumulator for fix descriptions
+ * @returns {object} The working lockfile
+ * @throws {FixerError} When deduplication fails and `throwOnError` is set
+ */
+function applyDedupe(fixed, throwOnError, fixes) {
+  if (!hasPackagesMap(fixed)) return fixed;
+
+  try {
+    const beforeCount = Object.keys(fixed.packages).length;
+    fixed = deduplicatePackages(fixed, { keepLatest: true });
+    const afterCount = Object.keys(fixed.packages).length;
+    if (afterCount < beforeCount) {
+      fixes.push(`Deduplicated packages: removed ${beforeCount - afterCount} entries`);
+    }
+  } catch (e) {
+    if (throwOnError) {
+      throw new FixerError(`Deduplication failed: ${e.message}`, fixes);
+    }
+    fixes.push(`Deduplication failed: ${e.message}`);
+  }
+  return fixed;
+}
+
+/**
+ * Attempt to automatically fix common package-lock issues.
+ * Returns { fixedLockfile, fixes } where `fixes` is an array of descriptions.
+ * @param {object} lockfile - The lockfile to fix
+ * @param {object} options - Fix options
+ * @returns {{fixedLockfile: object, fixes: string[]}} Result with fixed lockfile and descriptions
+ * @throws {FixerError} If a critical error occurs during fixing
+ */
+export function fixPackageLock(lockfile, options = {}) {
+  const fixes = [];
+  // Deep-copy up front so every fix step (incl. the in-place integrity fill) is
+  // non-destructive — the caller's lockfile object is never written through.
+  let fixed = structuredClone(lockfile);
+
+  const { fillMissingIntegrity = true, dedupe = true, normalizeTo = null, throwOnError = false, packageJson = null } = options;
+
+  fixed = syncRootIdentity(fixed, packageJson, fixes);
+  fixed = applyMigrations(fixed, normalizeTo, throwOnError, fixes);
+
+  if (fillMissingIntegrity) {
+    fillPlaceholderIntegrity(fixed, fixes);
+  }
+
+  if (dedupe) {
+    fixed = applyDedupe(fixed, throwOnError, fixes);
+  }
+
+  return { fixedLockfile: fixed, fixes };
+}
+
+export default { fixPackageLock, FixerError };

package/src/format-library.js

@@ -0,0 +1,132 @@
+// src/format-library.js
+import { deriveRegistryBase } from './integrity.js';
+import { forEachPnpmPackageEntry } from './pnpm-format.js';
+
+export const LOCKFILE_VERSIONS = {
+  V1: 1,
+  V2: 2,
+  V3: 3
+};
+
+export function detectLockfileVersion(lockfile) {
+  const version = lockfile.lockfileVersion;
+  if (version === 1) return LOCKFILE_VERSIONS.V1;
+  if (version === 2) return LOCKFILE_VERSIONS.V2;
+  if (version === 3) return LOCKFILE_VERSIONS.V3;
+  throw new Error(`Unsupported lockfile version: ${version}`);
+}
+
+/**
+ * Identify which package manager produced a parsed lockfile.
+ * pnpm-lock.yaml uses a STRING `lockfileVersion` ('9.0', '6.0', …) and carries
+ * `importers`/`snapshots`; npm uses a NUMERIC `lockfileVersion` and a `packages`
+ * map keyed by install path. The parser stamps `__npmCheckMeta.flavor`, which is
+ * trusted first when present.
+ * @param {object} lockfile - Parsed lockfile
+ * @returns {'npm'|'pnpm'} Flavor
+ */
+export function detectLockfileFlavor(lockfile) {
+  if (!lockfile || typeof lockfile !== 'object') return 'npm';
+  if (lockfile.__npmCheckMeta && lockfile.__npmCheckMeta.flavor) return lockfile.__npmCheckMeta.flavor;
+  if (typeof lockfile.lockfileVersion === 'string') return 'pnpm';
+  if (lockfile.importers || lockfile.snapshots) return 'pnpm';
+  return 'npm';
+}
+
+// Collapse the boolean classification flags into the normalized node `kind`.
+function npmEntryKind(flags) {
+  if (flags.isRoot) return 'root';
+  if (flags.isWorkspaceSource) return 'workspace';
+  if (flags.isLink) return 'link';
+  if (flags.isGitDep) return 'git';
+  if (flags.isFileDep) return 'file';
+  if (flags.isBundled) return 'bundled';
+  return 'registry';
+}
+
+export function hasPackagesMap(version) {
+  return version === LOCKFILE_VERSIONS.V2 || version === LOCKFILE_VERSIONS.V3;
+}
+
+export function hasDependenciesTree(version) {
+  return version === LOCKFILE_VERSIONS.V1;
+}
+
+/**
+ * Resolve the real package name for a packages-map entry.
+ * Uses entry.name when present (set for npm: aliases), otherwise the
+ * last node_modules/ segment of the key (handles scoped packages).
+ * @param {string} key - Key in the packages map
+ * @param {object} entry - Package entry data
+ * @returns {string|null} Package name or null for the root entry
+ */
+export function resolvePackageName(key, entry) {
+  if (entry && entry.name) return entry.name;
+  if (!key) return null;
+  const marker = 'node_modules/';
+  const idx = key.lastIndexOf(marker);
+  if (idx === -1) return key;
+  return key.slice(idx + marker.length);
+}
+
+/**
+ * Iterate a lockfile's package entries, classifying each one. Dispatches by flavor:
+ * the npm v2/v3 `packages` map (keyed by install path) or pnpm-lock's `packages` +
+ * `importers`. Both flavors emit the SAME callback shape:
+ *   { key, entry, name, isRoot, isWorkspaceSource, isLink, isBundled, isGitDep,
+ *     isFileDep, registryBase, node }
+ * `registryBase` is the per-package registry (npm: derived from the entry's
+ * `resolved` URL, may be null; pnpm: resolved from config) so consumers read one
+ * uniform field instead of re-deriving it. `node` is the normalized package node.
+ * @param {object} lockfile - Parsed lockfile (npm v2/v3 or pnpm)
+ * @param {function} callback - Called for each entry
+ */
+export function forEachPackageEntry(lockfile, callback) {
+  if (detectLockfileFlavor(lockfile) === 'pnpm') {
+    return forEachPnpmPackageEntry(lockfile, callback);
+  }
+  const packages = lockfile.packages || {};
+  for (const [key, entry] of Object.entries(packages)) {
+    const resolved = (entry && entry.resolved) || '';
+    const name = resolvePackageName(key, entry);
+    const flags = {
+      isRoot: key === '',
+      isWorkspaceSource: key !== '' && !key.includes('node_modules/'),
+      isLink: Boolean(entry && entry.link),
+      isBundled: Boolean(entry && entry.inBundle),
+      isGitDep: resolved.startsWith('git+') || resolved.startsWith('git://'),
+      isFileDep: resolved.startsWith('file:')
+    };
+    // Per-package registry from the resolved URL (null when not derivable — the
+    // historical `deriveRegistryBase(...) || defaultRegistry` fallback lives in the
+    // consumers, so behavior is byte-identical).
+    const registryBase = deriveRegistryBase(resolved, name);
+    callback({
+      key,
+      entry,
+      name,
+      ...flags,
+      registryBase,
+      node: {
+        name,
+        version: (entry && entry.version) || null,
+        integrity: (entry && entry.integrity) || null,
+        registryBase,
+        kind: npmEntryKind(flags),
+        path: key
+      }
+    });
+  }
+}
+
+export function parseLockfile(content) {
+  try {
+    return JSON.parse(content);
+  } catch (e) {
+    throw new Error('Invalid JSON in lockfile', { cause: e });
+  }
+}
+
+export function stringifyLockfile(lockfile) {
+  return JSON.stringify(lockfile, null, 2);
+}