@dependably/npm-check 1.7.0

package/src/pruner.js

@@ -0,0 +1,177 @@
+// src/pruner.js
+import { detectLockfileVersion, LOCKFILE_VERSIONS } from './format-library.js';
+
+export class PrunerError extends Error {
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'PrunerError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+const ROOT_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+// npm 7+ auto-installs peers, so they count toward reachability everywhere
+const PACKAGE_SECTIONS = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+
+/**
+ * Resolve where npm would look up dependency `name` required from the package
+ * at `key`, following node_modules resolution: the package's own node_modules,
+ * then each ancestor's, ending at the top level.
+ * @returns {string[]} Candidate keys, nearest first
+ */
+function resolutionCandidates(key, name) {
+  const candidates = [];
+  let host = key;
+  for (;;) {
+    candidates.push(host === '' ? `node_modules/${name}` : `${host}/node_modules/${name}`);
+    if (host === '') break;
+    const idx = host.lastIndexOf('/node_modules/');
+    if (idx === -1) {
+      // workspace dir (e.g. 'packages/foo') or top-level 'node_modules/x' → root next
+      host = '';
+    } else {
+      host = host.slice(0, idx);
+    }
+  }
+  return candidates;
+}
+
+/**
+ * A root-like entry is the project itself ('') or a workspace source dir —
+ * anything not installed under a node_modules/ path.
+ */
+function isRootLike(key) {
+  return key === '' || !key.includes('node_modules/');
+}
+
+/**
+ * Mark `target` reachable and enqueue it, but only the first time it is seen
+ * and only when it exists in the packages map.
+ */
+function visit(target, packages, reachable, queue) {
+  if (packages[target] === undefined || reachable.has(target)) return;
+  reachable.add(target);
+  queue.push(target);
+}
+
+/**
+ * Follow the node_modules resolution chain for dependency `name` required from
+ * `key`, marking the nearest existing match reachable (like node resolution).
+ */
+function visitDependency(key, name, packages, reachable, queue) {
+  for (const candidate of resolutionCandidates(key, name)) {
+    if (packages[candidate] !== undefined) {
+      visit(candidate, packages, reachable, queue);
+      break; // nearest hit wins, like node resolution
+    }
+  }
+}
+
+/**
+ * Process one dequeued entry: follow its link target (if any) and every
+ * dependency edge in the sections that apply to its position in the tree.
+ */
+function walkEntry(key, entry, packages, reachable, queue) {
+  // Link entries point at their target (usually a workspace dir)
+  if (entry.link && typeof entry.resolved === 'string') {
+    visit(entry.resolved, packages, reachable, queue);
+  }
+
+  const sections = isRootLike(key) ? ROOT_SECTIONS : PACKAGE_SECTIONS;
+  for (const section of sections) {
+    const deps = entry[section];
+    if (!deps || typeof deps !== 'object') continue;
+    for (const name of Object.keys(deps)) {
+      visitDependency(key, name, packages, reachable, queue);
+    }
+  }
+}
+
+/**
+ * Derive the package name for an orphan entry: prefer its explicit `.name`,
+ * otherwise the last node_modules/ path segment.
+ */
+function orphanName(key, entry) {
+  if (entry && entry.name) return entry.name;
+  return key.slice(key.lastIndexOf('node_modules/') + 'node_modules/'.length);
+}
+
+/**
+ * Compute which packages-map entries are reachable from the root package and
+ * workspace entries by following dependency edges with npm's resolution rules.
+ *
+ * @param {object} lockfile - Parsed v2/v3 lockfile
+ * @returns {{reachable: Set<string>, orphans: Array<{key, name, version}>}}
+ */
+export function findOrphanedPackages(lockfile) {
+  if (detectLockfileVersion(lockfile) === LOCKFILE_VERSIONS.V1) {
+    throw new PrunerError(
+      'v1 lockfiles are not supported; run `npm-check migrate 3` first',
+      'UNSUPPORTED_VERSION'
+    );
+  }
+
+  const packages = lockfile.packages || {};
+  const reachable = new Set();
+  const queue = [];
+
+  // Roots: the project itself plus workspace source entries
+  for (const key of Object.keys(packages)) {
+    if (isRootLike(key)) {
+      reachable.add(key);
+      queue.push(key);
+    }
+  }
+
+  while (queue.length > 0) {
+    const key = queue.shift();
+    const entry = packages[key];
+    if (entry) walkEntry(key, entry, packages, reachable, queue);
+  }
+
+  const orphans = [];
+  for (const [key, entry] of Object.entries(packages)) {
+    if (!reachable.has(key)) {
+      orphans.push({ key, name: orphanName(key, entry), version: entry ? entry.version : undefined });
+    }
+  }
+
+  return { reachable, orphans };
+}
+
+/**
+ * Remove orphaned (unreachable) entries from the packages map.
+ * v2 lockfiles keep their legacy dependencies tree untouched (npm regenerates
+ * it on install); a warning is emitted recommending migration to v3.
+ *
+ * @param {object} lockfile - Parsed v2/v3 lockfile
+ * @returns {{lockfile, removed: Array<{key, name, version}>, warnings: string[]}}
+ */
+export function prunePackages(lockfile) {
+  const { orphans } = findOrphanedPackages(lockfile);
+  const warnings = [];
+
+  if (orphans.length === 0) {
+    return { lockfile, removed: [], warnings };
+  }
+
+  const removedKeys = new Set(orphans.map((o) => o.key));
+  const packages = {};
+  for (const [key, entry] of Object.entries(lockfile.packages)) {
+    if (!removedKeys.has(key)) {
+      packages[key] = entry;
+    }
+  }
+
+  const pruned = { ...lockfile, packages };
+
+  if (detectLockfileVersion(lockfile) === LOCKFILE_VERSIONS.V2 && lockfile.dependencies) {
+    warnings.push(
+      'v2 legacy dependencies tree was left untouched (npm regenerates it on install); ' +
+      'consider `npm-check migrate 3` to drop it entirely'
+    );
+  }
+
+  return { lockfile: pruned, removed: orphans, warnings };
+}

package/src/remediate.js

@@ -0,0 +1,389 @@
+// src/remediate.js
+// Dependency remediation: turns the deprecated/vulnerable findings into action.
+//
+// Scope (deliberate): npm-check is lockfile-first and does not re-resolve the
+// dependency graph — that is `npm install`'s job. So remediation here bumps the
+// *direct* dependencies in package.json that are themselves deprecated or carry
+// an advisory at/above the severity threshold, rewriting their range to the
+// registry's latest version and syncing the lockfile root. Transitive findings
+// (a flagged package that is not a direct dependency) are reported as guidance
+// only — they clear when their parent is upgraded or via npm `overrides`. After
+// writing, the caller must run `npm install` to materialize the new tree.
+import { checkDeprecations } from './deprecation.js';
+import { checkVulnerabilities } from './vuln.js';
+import { classifyRange } from './pinner.js';
+import { forEachPackageEntry } from './format-library.js';
+import { deriveRegistryBase, DEFAULT_REGISTRY, fetchLatestVersion } from './integrity.js';
+import { buildEnvelope } from './schema.js';
+
+export class RemediationError extends Error {
+  constructor(message, code, context = {}) {
+    super(message);
+    this.name = 'RemediationError';
+    this.code = code;
+    this.context = context;
+  }
+}
+
+const DEP_SECTIONS = ['dependencies', 'devDependencies', 'optionalDependencies', 'peerDependencies'];
+
+/**
+ * Rewrite a range to target `version`, preserving the existing operator
+ * (exact stays exact, ^ stays ^, ~ stays ~).
+ */
+function rewriteRange(currentRange, version, rangeType) {
+  if (rangeType === 'caret') return `^${version}`;
+  if (rangeType === 'tilde') return `~${version}`;
+  return version; // exact
+}
+
+/**
+ * Index the lockfile's top-level installed versions by package name
+ * (nearest install, i.e. `node_modules/<name>`), so we know each direct
+ * dependency's currently-resolved version.
+ */
+function topLevelVersions(lockfile) {
+  const versions = new Map();
+  forEachPackageEntry(lockfile, ({ key, entry, name }) => {
+    if (key.startsWith('node_modules/') && key.indexOf('/node_modules/', 'node_modules/'.length) === -1) {
+      if (entry.version) versions.set(name, { version: entry.version, resolved: entry.resolved });
+    }
+  });
+  return versions;
+}
+
+/**
+ * Validate inputs, throwing the appropriate RemediationError on failure.
+ */
+function assertValidInputs(lockfile, packageJson) {
+  if (!lockfile || typeof lockfile !== 'object') {
+    throw new RemediationError('lockfile data is required', 'MISSING_LOCKFILE');
+  }
+  if (!packageJson || typeof packageJson !== 'object') {
+    throw new RemediationError('package.json data is required', 'MISSING_PACKAGE_JSON');
+  }
+  if (lockfile.lockfileVersion === 1) {
+    throw new RemediationError('v1 lockfiles are not supported; run `npm-check migrate 3` first', 'UNSUPPORTED_VERSION');
+  }
+}
+
+/**
+ * Run the deprecation + vulnerability scanners and collapse their findings into
+ * a map of flagged package name → Set of reasons. Deprecated (any) + vulnerable
+ * at/above threshold (vuln errors carry an advisoryId; below-threshold ones are
+ * warnings and skipped).
+ */
+async function gatherFlagged(lockfile, options) {
+  const { includeDeprecated, timeoutMs, concurrency, defaultRegistry, minSeverity, fetchManifest, fetchAdvisories, onProgress } = options;
+
+  // remediate gathers *actual* findings to bump — it is not a CI gate, so it opts
+  // out of the scanners' fail-closed default (failOnUnresolved). Otherwise an
+  // unreachable-registry entry would land in `errors` and be mistaken for a finding.
+  const [deprecationResult, vulnResult] = await Promise.all([
+    includeDeprecated
+      ? checkDeprecations(lockfile, { timeoutMs, concurrency, defaultRegistry, fetchManifest, onProgress, failOnUnresolved: false })
+      : Promise.resolve({ warnings: [], errors: [] }),
+    checkVulnerabilities(lockfile, { timeoutMs, concurrency, defaultRegistry, minSeverity, fetchAdvisories, onProgress, failOnUnresolved: false })
+  ]);
+
+  const flagged = new Map(); // name -> Set of reasons
+  const flag = (name, reason) => {
+    if (!flagged.has(name)) flagged.set(name, new Set());
+    flagged.get(name).add(reason);
+  };
+  if (includeDeprecated) {
+    for (const w of [...deprecationResult.warnings, ...deprecationResult.errors]) {
+      if (w.package) flag(w.package, 'deprecated');
+    }
+  }
+  for (const e of vulnResult.errors) {
+    if (e.advisoryId && e.package) flag(e.package, 'vulnerable');
+  }
+  return flagged;
+}
+
+/**
+ * Map package.json's declared dependencies (across all sections) to their
+ * first-seen { section, range }, keyed by name.
+ */
+function indexDirectDeps(packageJson) {
+  const directDeps = new Map(); // name -> { section, range }
+  for (const section of DEP_SECTIONS) {
+    const deps = packageJson[section];
+    if (!deps || typeof deps !== 'object') continue;
+    for (const [name, range] of Object.entries(deps)) {
+      if (!directDeps.has(name)) directDeps.set(name, { section, range });
+    }
+  }
+  return directDeps;
+}
+
+/**
+ * Resolve the registry's latest version for a flagged dep, using the injected
+ * fetcher when provided. Returns { latest } on success, or { warning } when the
+ * registry is unreachable or has no latest version.
+ */
+async function resolveLatest(name, current, options) {
+  const { fetchLatest, defaultRegistry, timeoutMs } = options;
+  const registryBase = (current && deriveRegistryBase(current.resolved, name)) || defaultRegistry;
+  let latest;
+  try {
+    latest = fetchLatest
+      ? await fetchLatest(name, registryBase)
+      : await fetchLatestVersion(name, { registryBase, timeoutMs });
+  } catch (e) {
+    return { warning: { package: name, reason: `registry unreachable (${e.message})` } };
+  }
+  if (!latest) {
+    return { warning: { package: name, reason: 'registry has no latest version' } };
+  }
+  return { latest };
+}
+
+/**
+ * Decide what to do with a single flagged name and push the outcome onto the
+ * appropriate result bucket. Bumps a simple-ranged direct dep; otherwise records
+ * guidance (transitive / latest-still-affected), a skip, or a warning.
+ */
+async function processFlagged(name, reasons, ctx) {
+  const { directDeps, installed, buckets, options } = ctx;
+  const reasonList = [...reasons];
+  const direct = directDeps.get(name);
+
+  if (!direct) {
+    // Transitive — can't bump a range we don't own; report as guidance.
+    buckets.guidance.push({ package: name, reasons: reasonList, kind: 'transitive' });
+    return;
+  }
+
+  const rangeType = classifyRange(direct.range);
+  if (!['exact', 'caret', 'tilde'].includes(rangeType)) {
+    buckets.skipped.push({ package: name, section: direct.section, range: direct.range, reasons: reasonList, reason: `${rangeType} range — bump manually` });
+    return;
+  }
+
+  const current = installed.get(name);
+  const { latest, warning } = await resolveLatest(name, current, options);
+  if (warning) {
+    buckets.warnings.push(warning);
+    return;
+  }
+
+  // If the currently-installed version is already at registry latest, bumping
+  // the range string won't change what `npm install` resolves — it is a no-op
+  // fix.  This check must happen before the range-string comparison because
+  // a range like `^1.0.0` resolved to `1.4.2` (== latest) would produce a
+  // rewritten range of `^1.4.2` which differs from `^1.0.0`, misleading the
+  // old range-string check into classifying a no-op as a genuine bump.
+  if (current && current.version === latest) {
+    buckets.guidance.push({ package: name, reasons: reasonList, kind: 'latest-still-affected', range: direct.range });
+    return;
+  }
+
+  const newRange = rewriteRange(direct.range, latest, rangeType);
+  if (newRange === direct.range) {
+    // Range string already points at latest yet still flagged; guide.
+    buckets.guidance.push({ package: name, reasons: reasonList, kind: 'latest-still-affected', range: direct.range });
+    return;
+  }
+
+  buckets.bumped.push({
+    package: name,
+    section: direct.section,
+    from: direct.range,
+    to: newRange,
+    latest,
+    fromVersion: current ? current.version : null,
+    reasons: reasonList
+  });
+  // `latest` is a mutable, maintainer-controlled pointer: the bump pulls a
+  // version that hasn't itself been scanned. Flag it so the caller re-runs the
+  // scanners after `npm install` rather than assuming the bump is clean.
+  buckets.warnings.push({ package: name, reason: `bumped to unvetted latest (${latest}) — re-run \`npm-check\` after \`npm install\` to confirm it isn't itself vulnerable/deprecated` });
+}
+
+/**
+ * Apply the planned bumps to a fresh package.json + a copied lockfile, syncing
+ * the lockfile root entry's ranges. Returns the new pair.
+ */
+function applyBumps(lockfile, packageJson, bumped) {
+  const newPackageJson = JSON.parse(JSON.stringify(packageJson));
+  const newLockfile = { ...lockfile };
+  if (bumped.length > 0 && newLockfile.packages && newLockfile.packages['']) {
+    newLockfile.packages = { ...newLockfile.packages, '': { ...newLockfile.packages[''] } };
+  }
+  for (const b of bumped) {
+    newPackageJson[b.section] = { ...newPackageJson[b.section], [b.package]: b.to };
+    const root = newLockfile.packages && newLockfile.packages[''];
+    if (root && root[b.section] && Object.prototype.hasOwnProperty.call(root[b.section], b.package)) {
+      root[b.section] = { ...root[b.section], [b.package]: b.to };
+    }
+  }
+  return { newPackageJson, newLockfile };
+}
+
+/**
+ * Plan (and optionally apply) remediation bumps for flagged direct dependencies.
+ *
+ * @param {object} lockfile - Parsed lockfile (v2/v3)
+ * @param {object} packageJson - Parsed package.json
+ * @param {object} options
+ * @param {string} options.minSeverity - Advisory threshold that counts a dep as vulnerable (default: 'high')
+ * @param {boolean} options.includeDeprecated - Treat deprecated direct deps as remediation targets (default: true)
+ * @param {number} options.timeoutMs / options.concurrency / options.defaultRegistry
+ * @param {Function} options.fetchManifest / options.fetchAdvisories - Injected scan transports (tests)
+ * @param {Function} options.fetchLatest - Injected (name, registryBase) => Promise<version|null> (tests)
+ * @param {Function} options.onProgress
+ * @returns {Promise<object>} { packageJson, lockfile, bumped, guidance, skipped, warnings, changed }
+ */
+export async function remediateDependencies(lockfile, packageJson, options = {}) {
+  const {
+    minSeverity = 'high',
+    includeDeprecated = true,
+    timeoutMs = 10000,
+    concurrency = 8,
+    defaultRegistry = DEFAULT_REGISTRY,
+    fetchManifest = null,
+    fetchAdvisories = null,
+    fetchLatest = null,
+    onProgress = null
+  } = options;
+  const resolved = { minSeverity, includeDeprecated, timeoutMs, concurrency, defaultRegistry, fetchManifest, fetchAdvisories, fetchLatest, onProgress };
+
+  assertValidInputs(lockfile, packageJson);
+
+  // 1. Gather findings (reuse the existing scanners; transports are injectable for tests).
+  const flagged = await gatherFlagged(lockfile, resolved);
+
+  // 2. Map flagged names to direct dependencies in package.json.
+  const directDeps = indexDirectDeps(packageJson);
+  const installed = topLevelVersions(lockfile);
+
+  // 3. For each flagged name: bump if it's a simple-ranged direct dep, else guide.
+  const buckets = { bumped: [], guidance: [], skipped: [], warnings: [] };
+  const ctx = { directDeps, installed, buckets, options: resolved };
+  for (const [name, reasons] of flagged) {
+    await processFlagged(name, reasons, ctx);
+  }
+
+  // 4. Apply bumps to a fresh package.json + sync the lockfile root entry.
+  const { newPackageJson, newLockfile } = applyBumps(lockfile, packageJson, buckets.bumped);
+
+  // Stable ordering for readable output.
+  buckets.bumped.sort((a, b) => a.package.localeCompare(b.package));
+  buckets.guidance.sort((a, b) => a.package.localeCompare(b.package));
+  buckets.skipped.sort((a, b) => a.package.localeCompare(b.package));
+
+  return {
+    packageJson: newPackageJson,
+    lockfile: newLockfile,
+    bumped: buckets.bumped,
+    guidance: buckets.guidance,
+    skipped: buckets.skipped,
+    warnings: buckets.warnings,
+    changed: buckets.bumped.length > 0
+  };
+}
+
+// A remediation finding's reason set decides its category/severity/ruleId. A vuln
+// reason outranks a deprecation (it cleared the severity threshold, default high);
+// a deprecation-only finding is a soft `low` signal. remediate's buckets don't
+// retain the advisory's own id/severity, so the ruleId is a stable category id.
+function severityForReasons(reasons) {
+  return reasons.includes('vulnerable') ? 'high' : 'low';
+}
+function categoryForReasons(reasons) {
+  return reasons.includes('vulnerable') ? 'vulnerability' : 'deprecated';
+}
+function ruleIdForReasons(reasons) {
+  return reasons.includes('vulnerable') ? 'vulnerable' : 'deprecated';
+}
+
+/**
+ * Wrap a remediateDependencies() result in the shared finding-schema envelope.
+ * Each flagged direct/transitive dependency becomes one Finding: a planned bump,
+ * transitive/latest-still-affected guidance, or a manual-range skip. Operational
+ * warnings (unreachable registry, unvetted-latest) and the `changed` flag ride
+ * under `extra`. Mirrors vuln.js's vulnEnvelope.
+ *
+ * @param {object} result   - a remediateDependencies() result
+ * @param {object} meta
+ * @param {string} meta.target    - the directory/manifest scanned, as given
+ * @param {number} [meta.scanned] - packages examined (0 when unknown)
+ * @param {number} [meta.exitCode]- the real process exit code (default 0)
+ * @returns {object} the shared envelope
+ */
+export function remediateEnvelope(result, { target, scanned = 0, exitCode = 0 } = {}) {
+  const findings = [];
+
+  for (const b of result.bumped) {
+    findings.push({
+      severity: severityForReasons(b.reasons),
+      ruleId: ruleIdForReasons(b.reasons),
+      category: categoryForReasons(b.reasons),
+      message: `${b.package} ${b.from} → ${b.to} (${b.reasons.join(', ')})`,
+      location: null,
+      remediation: `upgrade to ${b.latest}`,
+      extra: {
+        package: b.package,
+        installedVersion: b.fromVersion ?? null,
+        fixedVersion: b.latest,
+        section: b.section,
+        action: 'bump',
+        reasons: b.reasons
+      }
+    });
+  }
+
+  for (const g of result.guidance) {
+    const isLatest = g.kind === 'latest-still-affected';
+    findings.push({
+      severity: severityForReasons(g.reasons),
+      ruleId: ruleIdForReasons(g.reasons),
+      category: categoryForReasons(g.reasons),
+      message: `${g.package}: ${g.reasons.join(', ')}${isLatest ? '; latest still affected' : ' (transitive)'}`,
+      location: null,
+      remediation: isLatest
+        ? `latest (${g.range}) is still affected — no fix available yet`
+        : 'upgrade the parent dependency or add an npm override',
+      extra: {
+        package: g.package,
+        action: 'guidance',
+        kind: g.kind,
+        reasons: g.reasons,
+        ...(g.range ? { range: g.range } : {})
+      }
+    });
+  }
+
+  for (const s of result.skipped) {
+    const reasons = Array.isArray(s.reasons) ? s.reasons : [];
+    findings.push({
+      severity: severityForReasons(reasons),
+      ruleId: ruleIdForReasons(reasons),
+      category: categoryForReasons(reasons),
+      message: `${s.section}/${s.package} (${s.range}): ${s.reason}`,
+      location: null,
+      remediation: 'bump the range manually',
+      extra: {
+        package: s.package,
+        section: s.section,
+        action: 'skip',
+        range: s.range,
+        reason: s.reason,
+        reasons
+      }
+    });
+  }
+
+  return buildEnvelope({
+    target,
+    scanned,
+    findings,
+    exitCode,
+    extra: {
+      changed: result.changed,
+      warnings: result.warnings
+    }
+  });
+}