@dependably/npm-check 1.7.0

package/bin/cli.js

@@ -0,0 +1,1577 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'node:url';
+import { parseLockfile } from '../src/parser.js';
+import { validatePackageLock } from '../src/validator.js';
+import { validatePackageJson } from '../src/package-json-validator.js';
+import { validateNpmrc } from '../src/npmrc-validator.js';
+import { migrateToVersion } from '../src/migrator.js';
+import { upgradeIntegrityHashes, deduplicatePackages } from '../src/updater.js';
+import { fixPackageLock } from '../src/fixer.js';
+import { createBackup, listBackups, restoreFromLatestBackup, cleanOldBackups, BackupError } from '../src/backup.js';
+import { createProgressBar } from '../src/progress-reporter.js';
+import { checkIntegrity, checkLicenses } from '../src/checker.js';
+import { checkVulnerabilities, vulnEnvelope } from '../src/vuln.js';
+import { checkDeprecations, deprecationEnvelope } from '../src/deprecation.js';
+import { remediateDependencies, remediateEnvelope } from '../src/remediate.js';
+import { detectLockfileVersion, detectLockfileFlavor } from '../src/format-library.js';
+import { validatePnpmWorkspace } from '../src/pnpm-workspace-validator.js';
+import { fixChecksums } from '../src/checksum-fixer.js';
+import { pinVersions, detectIndent } from '../src/pinner.js';
+import { runAudit, formatAuditReport } from '../src/audit.js';
+import { loadAuditConfig, mergeConfig } from '../src/audit-config.js';
+import { runReport, formatReport } from '../src/report.js';
+import { prunePackages } from '../src/pruner.js';
+import { findUnusedDependencies } from '../src/usage-scanner.js';
+
+const argv = process.argv.slice(2);
+
+function printHelp() {
+  console.log(`
+npm-check — npm lockfile toolkit
+
+Usage:
+  npm-check [command] [file] [options]
+
+  With no command, npm-check runs the full report (all checks) on ./package-lock.json
+  (or ./pnpm-lock.yaml when present). pnpm lockfiles support the read-only checks
+  (report/integrity/vuln/deprecated); the write/transform commands are npm-only.
+
+Commands:
+
+  Read & report (inspect; never mutate the lockfile):
+    report [file]            Run ALL checks and print one grouped report (default)
+    validate [file]          Validate package-lock.json, package.json, and .npmrc
+    vuln [file]              Scan locked packages for known vulnerabilities (registry advisories)
+    deprecated [file]        Scan locked packages for deprecation notices (the npm ci warnings)
+    check [file]             Verify integrity hashes and licenses
+    audit [file]             Lint lockfile for best practices (non-zero exit on failure)
+    unused [dir]             Flag declared dependencies the application never imports
+
+  Fix & transform (npm-only; mutate the lockfile with --write):
+    fix [file] [--write]     Run automated fixer with optional write
+    fix-checksums [file]     Fill missing/placeholder/sha1 hashes from the registry
+    upgrade-hashes [file]    Upgrade integrity hashes sha1→sha512
+    migrate [file] [target]  Migrate to target version (1, 2, or 3; default: 3)
+                             (alias: upgrade — \`npm-check upgrade\` == \`migrate 3\`)
+    pin [dir]                Pin ^/~ ranges in package.json to lockfile versions
+    prune [file]             Remove orphaned packages unreachable from the dependency graph
+    dedupe [file]            Deduplicate packages in lockfile
+    remediate [dir]          Bump direct deps that are deprecated/vulnerable to latest (then npm install)
+
+  Backups:
+    backups [file]           List all backups for a file
+    restore [file]           Restore from latest backup
+    clean-backups [file]     Clean old backup files with optional --keep N
+
+CI Gate (the one mechanism — repeatable):
+  --fail-on severity=<level> Fail if any finding is at/above the level
+                             (info|low|moderate|high|critical)
+  --fail-on count=<N>        Fail if the total finding count exceeds N
+                             (replaces --max-warnings; count=0 == old --strict)
+  Default gate (no --fail-on): vulnerabilities trip the run; the fail-closed
+  default on packages that could not be scanned stays on (see --allow-unresolved).
+  Deprecated aliases (still work, will be removed): --min-severity → --fail-on severity=,
+  --max-warnings → --fail-on count=, --strict → --fail-on count=0, --fail-on-deprecated.
+
+Report Options:
+  --offline                  Skip all network checks (integrity + vuln + deprecated); offline rules only
+  --no-integrity             Skip the integrity check
+  --no-vuln                  Skip the known-vulnerability scan
+  --no-deprecated            Skip the deprecation scan
+  --no-license               Skip the license check
+  --config <file>            Suite config (.dependably-check), discovered by walking
+                             up to the repo root; .npm-checkrc.json is a fallback
+  --format human|json        Output format (default: human; json emits the shared finding schema)
+  --allow-unresolved         Don't fail when a registry-backed scan can't complete
+                             (registry down / endpoint unsupported). Default: FAIL CLOSED
+  --concurrency / --timeout / --registry / --licenses-csv   (as in Check Options)
+
+Check Options:
+  --check hash               Verify locked integrity hashes against the registry
+  --check license            Only verify licenses against approved list
+  --check all                Run both checks (default)
+  --licenses-csv <path>      Path to approved licenses CSV
+  --strict                   Treat warnings as errors
+  --concurrency N            Parallel registry requests for hash check (default: 8)
+  --timeout MS               Per-request timeout in milliseconds (default: 10000)
+  --registry <url>           Registry for entries without a derivable base
+  --allow-unresolved         Don't fail on entries that can't be verified (default: FAIL CLOSED)
+
+Vuln Options:
+  --fail-on severity=<level> Severity that fails the run (default: high)
+  --format human|json        Output format (default: human; json emits the shared finding schema)
+  --offline                  Skip the scan (report everything as skipped)
+  --allow-unresolved         Don't fail on packages that can't be checked
+                             (registry down/unsupported). Default: FAIL CLOSED — a scan
+                             that couldn't run never reports "clean"
+  --concurrency N            Parallel registry requests (default: 8)
+  --timeout MS               Per-request timeout in milliseconds (default: 10000)
+  --registry <url>           Registry for entries without a derivable base
+
+Deprecated Options:
+  --format human|json        Output format (default: human; json emits the shared finding schema)
+  --offline                  Skip the scan (report everything as skipped)
+  --fail-on ...              Fail the run when a locked package is deprecated
+                             (--fail-on-deprecated is a deprecated alias; default: warn)
+  --allow-unresolved         Don't fail on packages that can't be checked (default: FAIL CLOSED)
+  --concurrency N            Parallel registry requests (default: 8)
+  --timeout MS               Per-request timeout in milliseconds (default: 10000)
+  --registry <url>           Registry for entries without a derivable base
+
+Fix-Checksums Options:
+  --concurrency N            Parallel registry requests (default: 8)
+  --timeout MS               Per-request timeout in milliseconds (default: 10000)
+  --registry <url>           Default registry for entries without a resolved URL
+  --local-fallback           Hash node_modules copies when the registry fails
+                             (flagged: these are NOT npm tarball hashes)
+
+Remediate Options:
+  --write                    Apply the bumps to package.json + lockfile root (backs up first)
+  --fail-on severity=<level> Advisory level that counts a dep as vulnerable (default: high)
+  --no-deprecated            Don't treat deprecated direct deps as remediation targets
+  --format human|json        Output format (default: human; json emits the shared finding schema)
+  --registry <url>           Registry for entries without a derivable base
+  (only DIRECT deps are bumped; transitive findings are reported as guidance.
+   Run 'npm install' afterward to re-resolve the tree.)
+
+Pin Options:
+  --include-peer             Also pin peerDependencies (off by default)
+
+Unused Options:
+  --include-dev              Also check devDependencies (off by default)
+  --format human|json        Output format (default: human; json is machine-readable)
+
+Audit Options:
+  --config <file>            Suite config (.dependably-check), discovered by walking
+                             up to the repo root; .npm-checkrc.json is a fallback
+  --rule <id>:<severity>     Override a rule severity (error|warn|off); repeatable
+  --fail-on count=<N>        Fail when the warning count exceeds N (count=0 fails on
+                             any warning; --max-warnings / --strict are deprecated aliases)
+  --format stylish|json      Report format (default: stylish)
+
+General Options:
+  --write                    Write changes to file (creates backup)
+  -h, --help                 Show this help
+  --version                  Show version (long-only; -v is NOT version)
+
+Exit Codes:
+  0  success — clean run, or --help / --version
+  1  findings — vulnerabilities / audit problems / checks failed (a blocking result)
+  2  usage or operational error — unknown command/flag, invalid flag value,
+     missing/unreadable lockfile, unsupported input, or an internal failure
+
+Examples:
+  npm-check validate
+  npm-check upgrade --write                    # Lockfile v2 → v3
+  npm-check fix-checksums --write              # Real integrity hashes from registry
+  npm-check pin --write                        # Lock down ^/~ versions
+  npm-check prune --write                      # Remove orphaned lockfile entries
+  npm-check unused                             # Flag never-imported dependencies
+  npm-check audit                              # Lint with default rules
+  npm-check audit --fail-on count=0 --format json   # Any warning fails the run
+  npm-check audit --rule pinned-versions:error
+  npm-check vuln                               # Scan for known vulnerabilities
+  npm-check vuln --fail-on severity=critical --format json
+  npm-check deprecated                         # Scan for deprecated packages (npm ci warnings)
+  npm-check deprecated --fail-on count=0       # Fail CI when any locked package is deprecated
+  npm-check check --check hash                 # Only verify integrity
+  npm-check restore
+  npm-check clean-backups --keep 5
+
+Default file: ./package-lock.json
+`);
+}
+
+function getVersion() {
+  try {
+    const packageJsonPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '../package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+// Pick the default lockfile when none is given: prefer an existing
+// package-lock.json, else an existing pnpm-lock.yaml, else the npm default
+// (whose absence is reported downstream).
+function resolveDefaultLockfile() {
+  const npmLock = path.resolve('package-lock.json');
+  if (fs.existsSync(npmLock)) return npmLock;
+  const pnpmLock = path.resolve('pnpm-lock.yaml');
+  if (fs.existsSync(pnpmLock)) return pnpmLock;
+  return npmLock;
+}
+
+function getFilePath(arg1) {
+  // Determine if arg1 is a file path or needs to use default
+  if (!arg1 || arg1.startsWith('-')) {
+    return resolveDefaultLockfile();
+  }
+
+  // Check if arg1 looks like a numeric target version or other command arg
+  if (arg1.match(/^\d+$/)) {
+    return resolveDefaultLockfile();
+  }
+
+  // arg1 is a file path
+  return path.resolve(arg1);
+}
+
+// True when a path points at a pnpm (YAML) lockfile.
+function isPnpmLockPath(filePath) {
+  const base = path.basename(filePath).toLowerCase();
+  return base === 'pnpm-lock.yaml' || base.endsWith('.yaml') || base.endsWith('.yml');
+}
+
+// Guard the write/transform commands: a pnpm-lock.yaml is machine-generated and
+// must never be hand-patched. Refuse with guidance instead of corrupting it.
+// Exit 2: this is a usage error (the command was given input it cannot accept).
+function refuseIfPnpm(filePath, command) {
+  if (isPnpmLockPath(filePath)) {
+    console.error(`\n\`${command}\` does not support pnpm-lock.yaml.`);
+    console.error('   pnpm lockfiles are machine-generated — regenerate with `pnpm install` instead.');
+    process.exit(2);
+  }
+}
+
+// Exit 2: a missing required input (the lockfile/file the command operates on) is
+// a usage error, per the suite convention — not a "findings" failure (exit 1).
+function ensureFileExists(filePath) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`Error: File not found: ${filePath}`);
+    process.exit(2);
+  }
+}
+
+// Operational / internal error handler. Exit 2 per the suite convention: a thrown
+// exception (bad input, unsupported lockfile, registry/scan failure, internal bug)
+// is an operational error, distinct from a clean "findings found" run (exit 1).
+function handleError(error, context = '') {
+  console.error(`\n${context || 'Error'}:`);
+  if (error instanceof BackupError) {
+    console.error(`   Backup Error: ${error.message}`);
+  } else if (error.fixes) {
+    console.error(`   ${error.message}`);
+    if (error.fixes.length > 0) {
+      console.error('   Partial fixes attempted:');
+      error.fixes.forEach(fix => console.error(`     • ${fix}`));
+    }
+  } else {
+    console.error(`   ${error.message}`);
+  }
+  process.exit(2);
+}
+
+// Build a progress callback that redraws the bar only when the percentage
+// changes, to avoid flicker. Each caller keeps its own `lastProgress` state.
+function makeProgressReporter() {
+  let lastProgress = null;
+  return (progress) => {
+    if (!lastProgress || progress.percentage !== lastProgress.percentage) {
+      process.stderr.write(`\r${createProgressBar(progress)} ${progress.stage}`);
+      lastProgress = progress;
+    }
+  };
+}
+
+// Read the value that follows a flag in argv, or undefined when absent.
+function flagValue(name) {
+  const i = argv.indexOf(name);
+  return i !== -1 && argv[i + 1] ? argv[i + 1] : undefined;
+}
+
+// Parse a flag's value as a positive integer, exiting with `code` on a bad value.
+// Returns `fallback` when the flag is absent.
+function parsePositiveIntFlag(name, fallback, label, code = 2) {
+  const raw = flagValue(name);
+  if (raw === undefined) return fallback;
+  const parsed = parseInt(raw, 10);
+  if (isNaN(parsed) || parsed < 1) {
+    console.error(`Invalid ${label} value. Must be a positive number`);
+    process.exit(code);
+  }
+  return parsed;
+}
+
+// Validate a --format flag against the allowed values, exiting with `code` on a bad value.
+function parseFormatFlag(allowed, fallback, code = 2) {
+  const raw = flagValue('--format');
+  if (raw === undefined) return fallback;
+  if (!allowed.includes(raw)) {
+    console.error(`Invalid --format value. Use: ${allowed.join(' or ')}`);
+    process.exit(code);
+  }
+  return raw;
+}
+
+// Every option token the CLI recognizes, split by whether it consumes the
+// following token as its value. Used by rejectUnknownOptions() to fail closed
+// on an unrecognized `-`/`--` token (a typo'd flag must never be silently
+// dropped — that is a fail-open that can disable a CI gate).
+//
+// VALUED flags consume the next argv token (`--format json`); its value must
+// NOT itself be treated as an unknown option. BOOLEAN flags stand alone.
+// Keep these in sync with the flags parsed throughout this file.
+const VALUED_OPTIONS = new Set([
+  '--format', '--config', '--fail-on', '--concurrency', '--timeout',
+  '--registry', '--licenses-csv', '--check', '--rule', '--keep',
+  // deprecated valued aliases (still parsed)
+  '--min-severity', '--max-warnings'
+]);
+const BOOLEAN_OPTIONS = new Set([
+  '--offline', '--allow-unresolved',
+  '--no-integrity', '--no-vuln', '--no-deprecated', '--no-license',
+  '--include-dev', '--include-peer', '--write', '--local-fallback',
+  '--version', '--help', '-h',
+  // deprecated boolean aliases (still parsed)
+  '--strict', '--fail-on-deprecated'
+]);
+
+// Collect the positional arguments after the command word (argv[0]), correctly
+// skipping flags AND the value token that follows a valued flag. Reading a fixed
+// slot like argv[1] is a footgun: `pin --write <path>` puts the flag in argv[1],
+// so the path is never seen and a dir-oriented command silently falls back to
+// cwd — which once wrote to the wrong project. Always resolve a target through
+// this so flag order never changes which file is touched.
+function positionals() {
+  const out = [];
+  let i = 1; // skip argv[0], the command word
+  while (i < argv.length) {
+    const tok = argv[i];
+    if (typeof tok === 'string' && tok.startsWith('-') && tok !== '-') {
+      if (VALUED_OPTIONS.has(tok)) i++; // also skip this flag's value
+      i++;
+      continue;
+    }
+    out.push(tok);
+    i++;
+  }
+  return out;
+}
+
+// Reject any unrecognized option token, matching the unknown-command behavior
+// (and the .NET suite tools): print `unknown option: '<x>'` to stderr and exit 2
+// (a usage error). Positionals (the lockfile/dir/target), the VALUE that follows
+// a valued flag (`--format json`, `--registry <url>`), and recognized flags all
+// pass through untouched.
+function rejectUnknownOptions() {
+  let i = 0;
+  while (i < argv.length) {
+    const tok = argv[i];
+    i++;
+    if (typeof tok !== 'string' || !tok.startsWith('-') || tok === '-') {
+      continue; // positional / command / a bare '-'
+    }
+    if (VALUED_OPTIONS.has(tok)) {
+      i++; // skip this flag's value so a value like `-1` is never mis-read as a flag
+      continue;
+    }
+    if (BOOLEAN_OPTIONS.has(tok)) continue;
+    console.error(`unknown option: '${tok}'`);
+    process.exit(2);
+  }
+}
+
+const SEVERITIES = ['info', 'low', 'moderate', 'high', 'critical'];
+
+// Emit a one-line deprecation notice to stderr (never stdout, so machine output
+// stays clean). Each retired flag is a thin alias that still maps onto --fail-on.
+function warnDeprecated(oldFlag, replacement) {
+  console.error(`${oldFlag} is deprecated; use \`${replacement}\` instead.`);
+}
+
+// Parse the unified, repeatable CI gate: `--fail-on <key>=<value>`.
+//   severity=<info|low|moderate|high|critical>  trip if any finding is at/above
+//   count=<N>                                   trip if total findings exceed N
+// Returns { severity, count } with each null when unset. Bad input is exit 2.
+function parseFailOn(code = 2) {
+  const out = { severity: null, count: null };
+  argv.forEach((arg, i) => {
+    if (arg !== '--fail-on') return;
+    const spec = argv[i + 1];
+    if (!spec || !spec.includes('=')) {
+      console.error('Invalid --fail-on. Use --fail-on <key>=<value> (severity=<level> or count=<N>)');
+      process.exit(code);
+    }
+    const eq = spec.indexOf('=');
+    const key = spec.slice(0, eq);
+    const value = spec.slice(eq + 1);
+    if (key === 'severity') {
+      if (!SEVERITIES.includes(value)) {
+        console.error(`Invalid --fail-on severity value. Use: ${SEVERITIES.join(', ')}`);
+        process.exit(code);
+      }
+      out.severity = value;
+    } else if (key === 'count') {
+      const n = parseInt(value, 10);
+      if (isNaN(n) || n < 0 || String(n) !== value.trim()) {
+        console.error('Invalid --fail-on count value. Must be a non-negative integer');
+        process.exit(code);
+      }
+      out.count = n;
+    } else {
+      console.error(`Unknown --fail-on key "${key}". Use: severity or count`);
+      process.exit(code);
+    }
+  });
+  return out;
+}
+
+// `--fail-on-deprecated` is retired in favour of the unified `--fail-on`, but
+// kept as a thin deprecated alias (deprecation has no place on the severity
+// ladder, so it stays a distinct toggle that still fails the run when set).
+function resolveFailOnDeprecated() {
+  if (!argv.includes('--fail-on-deprecated')) return false;
+  warnDeprecated('--fail-on-deprecated', '--fail-on (deprecations fail when this is set)');
+  return true;
+}
+
+// Assert that --fail-on specs are applicable for the calling command.
+// `supportedKeys` shapes:
+//   { severity: true|false, count: true|false|'zero-only' }
+// When a key was supplied in argv but is not supported (or only count=0 is
+// supported and a non-zero value was given), exit 2 (usage error) with a
+// clear message — a silently-dropped gate key is a fail-open CI footgun.
+function assertFailOnSupported(supportedKeys, commandName) {
+  const failOn = parseFailOn();
+  if (failOn.severity !== null && !supportedKeys.severity) {
+    console.error(`--fail-on severity= is not supported by the "${commandName}" command`);
+    if (supportedKeys.count === 'zero-only') {
+      console.error('   Use --fail-on count=0 to fail when any deprecated package is found');
+    } else if (supportedKeys.count) {
+      console.error('   Use --fail-on count=<N> to set a finding count budget');
+    }
+    process.exit(2);
+  }
+  if (failOn.count !== null) {
+    if (!supportedKeys.count) {
+      console.error(`--fail-on count= is not supported by the "${commandName}" command`);
+      if (supportedKeys.severity) {
+        console.error('   Use --fail-on severity=<level> to set the minimum severity threshold');
+      }
+      process.exit(2);
+    }
+    if (supportedKeys.count === 'zero-only' && failOn.count > 0) {
+      console.error(`--fail-on count=${failOn.count} is not supported by the "${commandName}" command`);
+      console.error('   Use --fail-on count=0 to fail when any deprecated package is found');
+      process.exit(2);
+    }
+  }
+}
+
+// Resolve the severity gate (the level at/above which a finding fails the run).
+// Precedence: `--fail-on severity=` > the deprecated `--min-severity` alias > fallback.
+function resolveSeverityGate(fallback = 'high', code = 2) {
+  const failOn = parseFailOn(code);
+  if (failOn.severity) return failOn.severity;
+
+  const legacy = flagValue('--min-severity');
+  if (legacy !== undefined) {
+    if (!SEVERITIES.includes(legacy)) {
+      console.error(`Invalid --min-severity value. Use: ${SEVERITIES.join(', ')}`);
+      process.exit(code);
+    }
+    warnDeprecated('--min-severity', '--fail-on severity=<level>');
+    return legacy;
+  }
+  return fallback;
+}
+
+// The registry-verification flags shared by the network-backed commands.
+// Invalid flag values are usage errors (exit 2) by default.
+function parseNetworkFlags(code = 2) {
+  return {
+    concurrency: parsePositiveIntFlag('--concurrency', 8, '--concurrency', code),
+    timeoutMs: parsePositiveIntFlag('--timeout', 10000, '--timeout', code),
+    defaultRegistry: flagValue('--registry')
+  };
+}
+
+// Spread the optional registry override only when one was supplied.
+function registryOption(defaultRegistry) {
+  return defaultRegistry ? { defaultRegistry } : {};
+}
+
+// Clear the in-progress progress bar line.
+function clearProgressLine() {
+  process.stderr.write('\r' + ' '.repeat(80) + '\r');
+}
+
+// Resolve the directory argument for dir-oriented commands (pin/unused/remediate).
+// Accepts either a directory or a lockfile/package.json file path (deriving the
+// directory from it), so `pin path/to/package-lock.json` targets the right
+// project the same way the file-oriented commands do.
+function getDirArg() {
+  const pos = positionals()[0];
+  if (!pos) return process.cwd();
+  const resolved = path.resolve(pos);
+  if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+    return path.dirname(resolved);
+  }
+  return resolved;
+}
+
+// Write `data` as pretty JSON to a file, creating a backup first.
+function writeJsonFile(targetPath, data, indent = 2) {
+  createBackup(targetPath);
+  fs.writeFileSync(targetPath, JSON.stringify(data, null, indent) + '\n', 'utf8');
+}
+
+// Guard for the report/vuln/deprecated commands: a missing lockfile is exit 2.
+function requireLockfileOrExit2(filePath, command) {
+  if (!fs.existsSync(filePath)) {
+    console.error(`No lockfile found at ${filePath}`);
+    console.error(`   Run \`npm-check ${command} <path>\` or \`npm-check --help\`.`);
+    process.exit(2);
+  }
+}
+
+// Apply repeatable --rule <id>:<severity> overrides onto an audit config.
+// Exits 2 when the spec is missing a colon or has an empty severity part —
+// a bare `--rule <id>` would silently set severity=undefined and be dropped
+// by mergeConfig (a fail-open that could leave a CI gate disabled).
+function applyRuleOverrides(config) {
+  const ruleOverrides = {};
+  argv.forEach((arg, i) => {
+    if (arg === '--rule' && argv[i + 1]) {
+      const spec = argv[i + 1];
+      const colonIdx = spec.indexOf(':');
+      if (colonIdx === -1 || colonIdx === spec.length - 1) {
+        console.error(`Invalid --rule spec "${spec}". Use --rule <id>:<severity> (error|warn|off)`);
+        process.exit(2);
+      }
+      const ruleId = spec.slice(0, colonIdx);
+      const severity = spec.slice(colonIdx + 1);
+      ruleOverrides[ruleId] = severity;
+    }
+  });
+  if (Object.keys(ruleOverrides).length === 0) return;
+  const merged = mergeConfig({ maxWarnings: config.maxWarnings, rules: ruleOverrides });
+  for (const ruleId of Object.keys(ruleOverrides)) {
+    if (!merged.rules[ruleId]) continue;
+    config.rules[ruleId] = {
+      severity: merged.rules[ruleId].severity,
+      options: { ...config.rules[ruleId].options }
+    };
+  }
+}
+
+// Resolve the finding-count gate onto an audit config.
+// Precedence: `--fail-on count=N` > the deprecated `--strict` / `--max-warnings`
+// aliases. `count=N` (and `--max-warnings N`) trip when warnings exceed N;
+// `--strict` is shorthand for count=0 (any warning fails).
+function applyMaxWarnings(config) {
+  const failOn = parseFailOn();
+  if (failOn.count !== null) {
+    config.maxWarnings = failOn.count;
+    return;
+  }
+  if (argv.includes('--strict')) {
+    warnDeprecated('--strict', '--fail-on count=0');
+    config.maxWarnings = 0;
+  }
+  const raw = flagValue('--max-warnings');
+  if (raw === undefined) return;
+  const parsed = parseInt(raw, 10);
+  if (isNaN(parsed)) {
+    console.error('Invalid --max-warnings value. Must be a number');
+    process.exit(2);
+  }
+  warnDeprecated('--max-warnings', '--fail-on count=<N>');
+  config.maxWarnings = parsed;
+}
+
+// Load the package.json sibling to a lockfile, or null when absent/unparseable.
+function loadSiblingPackageJson(filePath, { tolerant = false } = {}) {
+  const pkgPath = path.join(path.dirname(filePath), 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  if (!tolerant) return JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  try { return JSON.parse(fs.readFileSync(pkgPath, 'utf8')); } catch { return null; }
+}
+
+// Resolve every report option from argv (audit config, format, toggles, network).
+function parseReportOptions() {
+  const config = loadAuditConfig(process.cwd(), flagValue('--config') || null);
+  applyRuleOverrides(config);
+
+  // The count gate (`--fail-on count=`, or the deprecated `--strict`/`--max-warnings`)
+  // lands on config.maxWarnings. `strict` stays a separate signal for the license
+  // check (treat unknown-license warnings as failures).
+  applyMaxWarnings(config);
+  const strict = argv.includes('--strict');
+  const maxWarnings = config.maxWarnings;
+
+  return {
+    config,
+    strict,
+    maxWarnings,
+    format: parseFormatFlag(['human', 'json'], 'human'),
+    // Network/integrity + license toggles.
+    integrity: !argv.includes('--offline') && !argv.includes('--no-integrity'),
+    license: !argv.includes('--no-license'),
+    vuln: !argv.includes('--offline') && !argv.includes('--no-vuln'),
+    deprecated: !argv.includes('--offline') && !argv.includes('--no-deprecated'),
+    // Fail closed by default: a registry-backed scan that couldn't complete must not
+    // pass the report. `--allow-unresolved` opts back into the old lenient behavior.
+    failOnUnresolved: !argv.includes('--allow-unresolved'),
+    failOnDeprecated: resolveFailOnDeprecated(),
+    minSeverity: resolveSeverityGate(),
+    concurrency: parsePositiveIntFlag('--concurrency', 8, '--concurrency', 2),
+    timeoutMs: parsePositiveIntFlag('--timeout', 10000, '--timeout', 2),
+    defaultRegistry: flagValue('--registry'),
+    licensesCsv: flagValue('--licenses-csv')
+  };
+}
+
+async function runReportCommand() {
+  // `report` takes its file positional only when invoked explicitly.
+  const filePath = getFilePath(argv[0] === 'report' ? positionals()[0] : undefined);
+  requireLockfileOrExit2(filePath, 'report');
+
+  let report;
+  try {
+    const opts = parseReportOptions();
+    const dir = path.dirname(filePath);
+    const lockfile = parseLockfile(filePath);
+    const packageJson = loadSiblingPackageJson(filePath);
+
+    if ((opts.integrity || opts.vuln || opts.deprecated) && opts.format === 'human') {
+      console.error('Running all checks (querying the registry)…');
+    }
+    const onProgress = opts.format === 'human' ? makeProgressReporter() : null;
+
+    report = await runReport(
+      { lockfile, packageJson, filePath: path.relative(process.cwd(), filePath) || filePath, dir },
+      {
+        auditConfig: opts.config, integrity: opts.integrity, license: opts.license, vuln: opts.vuln,
+        deprecated: opts.deprecated, failOnDeprecated: opts.failOnDeprecated, minSeverity: opts.minSeverity,
+        strict: opts.strict, maxWarnings: opts.maxWarnings, concurrency: opts.concurrency,
+        timeoutMs: opts.timeoutMs, failOnUnresolved: opts.failOnUnresolved, onProgress,
+        ...registryOption(opts.defaultRegistry),
+        ...(opts.licensesCsv ? { licensesCsv: opts.licensesCsv } : {})
+      }
+    );
+
+    if (onProgress) clearProgressLine();
+    const rendered = formatReport(report, { format: opts.format });
+    console.log(opts.format === 'human' ? '\n' + rendered : rendered);
+  } catch (error) {
+    console.error(`\nReport error: ${error.message}`);
+    process.exit(2);
+  }
+
+  process.exit(report.summary.pass ? 0 : 1);
+}
+
+// Validate the sibling package.json (if present). A malformed manifest is itself a
+// validation failure to report — not a reason to abort the whole command.
+function loadPackageJsonResult(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    return validatePackageJson(JSON.parse(fs.readFileSync(pkgPath, 'utf8')));
+  } catch (e) {
+    return { valid: false, errors: [{ code: 'PJ_PARSE_ERROR', message: `package.json is not valid JSON: ${e.message}` }], warnings: [] };
+  }
+}
+
+// Validate the project-level .npmrc (if present), threading the flavor through so
+// pnpm-ignored keys are flagged.
+function loadNpmrcResult(dir, isPnpm) {
+  const npmrcPath = path.join(dir, '.npmrc');
+  if (!fs.existsSync(npmrcPath)) return null;
+  return validateNpmrc(fs.readFileSync(npmrcPath, 'utf8'), isPnpm ? { flavor: 'pnpm' } : {});
+}
+
+// Validate pnpm-workspace.yaml (pnpm projects only).
+function loadPnpmWorkspaceResult(dir, isPnpm) {
+  const wsPath = path.join(dir, 'pnpm-workspace.yaml');
+  if (!isPnpm || !fs.existsSync(wsPath)) return null;
+  return validatePnpmWorkspace(fs.readFileSync(wsPath, 'utf8'));
+}
+
+// Errors are Error subclass instances, whose `message` is non-enumerable and so
+// vanishes under JSON.stringify — normalize to {code, message} so the JSON output
+// is actually readable.
+function normalizeValidationResult(r) {
+  if (!r || typeof r !== 'object' || !Array.isArray(r.errors)) return r;
+  return { ...r, errors: r.errors.map((e) => ({ code: e.code, message: e.message })) };
+}
+
+function runValidateCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  const dir = path.dirname(filePath);
+
+  const lockfile = parseLockfile(filePath);
+  const isPnpm = detectLockfileFlavor(lockfile) === 'pnpm';
+
+  // The npm lockfile validator is npm-shape only; a pnpm-lock.yaml is
+  // machine-generated, so we validate the files that govern its install instead.
+  const lockResult = isPnpm ? null : validatePackageLock(lockfile);
+  const pkgResult = loadPackageJsonResult(dir);
+  const npmrcResult = loadNpmrcResult(dir, isPnpm);
+  const wsResult = loadPnpmWorkspaceResult(dir, isPnpm);
+
+  const norm = (r, fallback) => normalizeValidationResult(r) || fallback;
+  const out = isPnpm
+    ? {
+      'pnpm-lock.yaml': 'machine-generated (structural validation skipped; regenerate with `pnpm install`)',
+      'package.json': norm(pkgResult, 'not found (skipped)'),
+      '.npmrc': norm(npmrcResult, 'not found (skipped)'),
+      'pnpm-workspace.yaml': norm(wsResult, 'not found (skipped)')
+    }
+    : {
+      'package-lock.json': normalizeValidationResult(lockResult),
+      'package.json': norm(pkgResult, 'not found (skipped)'),
+      '.npmrc': norm(npmrcResult, 'not found (skipped)')
+    };
+
+  console.log('\nValidation Result:');
+  console.log(JSON.stringify(out, null, 2));
+
+  const valid = [lockResult, pkgResult, npmrcResult, wsResult].every((r) => !r || r.valid);
+  process.exit(valid ? 0 : 1);
+}
+
+function runMigrateCommand() {
+  // `migrate [target] [file]` — the numeric target and the file path may appear
+  // in either order; split the positionals by shape rather than by fixed slot.
+  const pos = positionals();
+  const numericArg = pos.find((a) => /^\d+$/.test(a));
+  const fileArg = pos.find((a) => !/^\d+$/.test(a));
+  const filePath = getFilePath(fileArg);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'migrate');
+
+  // Get target version (default: 3)
+  const target = numericArg ? parseInt(numericArg, 10) : 3;
+
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+  const migrated = migrateToVersion(lockfile, target);
+
+  console.log(`\nMigrated lockfile to version ${target}`);
+
+  if (hasWrite) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(migrated, null, 2) + '\n', 'utf8');
+    console.log(`Changes written to ${filePath}`);
+  } else {
+    console.log('\nUse --write flag to save changes');
+    console.log(JSON.stringify(migrated, null, 2));
+  }
+}
+
+function runUpgradeCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'upgrade');
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+  const sourceVersion = detectLockfileVersion(lockfile);
+
+  if (sourceVersion === 3) {
+    console.log('\nAlready at version 3, nothing to do');
+    return;
+  }
+
+  const migrated = migrateToVersion(lockfile, 3);
+  console.log(`\nMigrated lockfile v${sourceVersion} → v3`);
+
+  if (hasWrite) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(migrated, null, 2) + '\n', 'utf8');
+    console.log(`Changes written to ${filePath}`);
+  } else {
+    console.log('\nUse --write flag to save changes');
+  }
+}
+
+// Print the fix-checksums result summary, changes, unresolved entries and warnings.
+function printChecksumResult(result, hasWrite) {
+  clearProgressLine();
+  console.log('\nChecksum fix complete');
+  console.log(`   Candidates:          ${result.summary.candidates}`);
+  console.log(`   Fixed from registry: ${result.summary.fixedFromRegistry}`);
+  console.log(`   Fixed locally:       ${result.summary.fixedFromLocal}${result.summary.fixedFromLocal > 0 ? ' (flagged)' : ''}`);
+  console.log(`   Unresolved:          ${result.summary.unresolved}`);
+  console.log(`   Skipped:             ${result.summary.skipped}`);
+
+  if (result.changes.length > 0 && !hasWrite) {
+    console.log('\n   Changes:');
+    result.changes.forEach((change) => {
+      console.log(`     • ${change.packagePath}: ${change.from || '(missing)'} → ${change.to.slice(0, 40)}... [${change.source}]`);
+    });
+  }
+  if (result.unresolved.length > 0) {
+    console.log('\n   Unresolved packages:');
+    result.unresolved.forEach((item) => {
+      console.log(`     • ${item.packagePath}: ${item.reason}`);
+    });
+  }
+  result.warnings.forEach((warning) => console.log(`\n${warning}`));
+}
+
+async function runFixChecksumsCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'fix-checksums');
+  const hasWrite = argv.includes('--write');
+  const localFallback = argv.includes('--local-fallback');
+  const { concurrency, timeoutMs, defaultRegistry } = parseNetworkFlags();
+
+  const lockfile = parseLockfile(filePath);
+  const onProgress = makeProgressReporter();
+
+  console.log('Fixing integrity checksums...');
+  const lockfileDir = path.dirname(filePath);
+  const result = await fixChecksums(lockfile, {
+    onProgress, concurrency, timeoutMs, localFallback,
+    baseDir: lockfileDir,
+    nodeModulesPath: path.join(lockfileDir, 'node_modules'),
+    ...registryOption(defaultRegistry)
+  });
+
+  printChecksumResult(result, hasWrite);
+
+  if (hasWrite && result.changes.length > 0) {
+    writeJsonFile(filePath, result.lockfile);
+    console.log(`\nChanges written to ${filePath}`);
+  } else if (result.changes.length > 0) {
+    console.log('\nUse --write flag to save changes');
+  }
+
+  process.exit(result.unresolved.length > 0 ? 1 : 0);
+}
+
+function runPinCommand() {
+  // pin operates on a directory containing both package.json and the lockfile
+  const dir = getDirArg();
+  const hasWrite = argv.includes('--write');
+  const includePeer = argv.includes('--include-peer');
+
+  const packageJsonPath = path.join(dir, 'package.json');
+  const lockfilePath = path.join(dir, 'package-lock.json');
+  ensureFileExists(packageJsonPath);
+  ensureFileExists(lockfilePath);
+
+  const packageJsonRaw = fs.readFileSync(packageJsonPath, 'utf8');
+  const packageJson = JSON.parse(packageJsonRaw);
+  const lockfile = parseLockfile(lockfilePath);
+
+  const result = pinVersions(packageJson, lockfile, { includePeer });
+
+  console.log('\nPin Results:');
+  if (result.changes.length === 0) {
+    console.log('   Nothing to pin — all ranges already exact (or skipped)');
+  } else {
+    result.changes.forEach((change) => {
+      console.log(`   • ${change.section}/${change.name}  ${change.from} → ${change.to}`);
+    });
+  }
+
+  if (result.skipped.length > 0) {
+    console.log('\n   Skipped:');
+    result.skipped.forEach((skip) => {
+      console.log(`     • ${skip.section}/${skip.name} (${skip.range}): ${skip.reason}`);
+    });
+  }
+
+  result.warnings.forEach((warning) => {
+    console.log(`\n${warning}`);
+  });
+
+  if (hasWrite && result.changes.length > 0) {
+    const indent = detectIndent(packageJsonRaw);
+    createBackup(packageJsonPath);
+    createBackup(lockfilePath);
+    fs.writeFileSync(packageJsonPath, JSON.stringify(result.packageJson, null, indent) + '\n', 'utf8');
+    fs.writeFileSync(lockfilePath, JSON.stringify(result.lockfile, null, 2) + '\n', 'utf8');
+    console.log(`\nChanges written to ${packageJsonPath} and ${lockfilePath}`);
+  } else if (result.changes.length > 0) {
+    console.log('\nUse --write flag to save changes');
+  }
+}
+
+function runPruneCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'prune');
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+  const result = prunePackages(lockfile);
+
+  console.log('\nPrune Results:');
+  if (result.removed.length === 0) {
+    console.log('   No orphaned packages found — lockfile is fully connected');
+  } else {
+    console.log(`   Removed ${result.removed.length} orphaned package(s):`);
+    result.removed.forEach((orphan) => {
+      const detail = orphan.version ? ` (${orphan.name}@${orphan.version})` : '';
+      console.log(`     • ${orphan.key}${detail}`);
+    });
+  }
+
+  result.warnings.forEach((warning) => {
+    console.log(`\n${warning}`);
+  });
+
+  if (hasWrite && result.removed.length > 0) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(result.lockfile, null, 2) + '\n', 'utf8');
+    console.log(`\nChanges written to ${filePath}`);
+  } else if (result.removed.length > 0) {
+    console.log('\nUse --write flag to save changes');
+  }
+}
+
+function runUnusedCommand() {
+  const dir = getDirArg();
+  const includeDev = argv.includes('--include-dev');
+  // Machine output is selected with `--format json` (the suite-wide spelling);
+  // the old boolean `--json` switch is retired.
+  const asJson = parseFormatFlag(['human', 'json'], 'human') === 'json';
+
+  const packageJsonPath = path.join(dir, 'package.json');
+  ensureFileExists(packageJsonPath);
+
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  const result = findUnusedDependencies(packageJson, dir, { includeDev });
+
+  if (asJson) {
+    console.log(JSON.stringify({
+      scannedFiles: result.scannedFiles,
+      appFiles: result.appFiles,
+      buildFiles: result.buildFiles,
+      buildDirsScanned: result.buildDirsScanned,
+      sectionsChecked: result.sectionsChecked,
+      buildOnly: result.buildOnly,
+      unused: result.unused
+    }, null, 2));
+  } else {
+    const split = result.buildFiles
+      ? ` — ${result.appFiles} app, ${result.buildFiles} build [${result.buildDirsScanned.join(', ')}]`
+      : '';
+    console.log(`\nScanned ${result.scannedFiles} source file(s)${split} (${result.sectionsChecked.join(', ')})`);
+    if (result.buildOnly.length > 0) {
+      console.log(`   ${result.buildOnly.length} package(s) imported only by build tooling (kept): ${result.buildOnly.join(', ')}`);
+    }
+    if (result.unused.length === 0) {
+      console.log('   All declared dependencies are imported by the application');
+    } else {
+      console.log(`   ${result.unused.length} package(s) flagged for removal (never imported):`);
+      result.unused.forEach((dep) => {
+        console.log(`     • ${dep.name} (${dep.section}: ${dep.version})`);
+      });
+      console.log('\n   Heuristic results — packages loaded via config files or CLI-only');
+      console.log('   tools can be false positives. Verify before removing, e.g.:');
+      result.unused.forEach((dep) => {
+        console.log(`     npm uninstall ${dep.name}`);
+      });
+    }
+  }
+}
+
+function runAuditCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  // The audit command gates on warning/finding count, not severity level.
+  // `--fail-on severity=` is a no-op here — reject it before the run so a CI
+  // pipeline that meant `--fail-on count=` never silently passes.
+  assertFailOnSupported({ severity: false, count: true }, 'audit');
+
+  let report;
+  try {
+    if (!fs.existsSync(filePath)) {
+      throw new Error(`File not found: ${filePath}`);
+    }
+
+    // Resolve config: file (discovered or --config) + CLI overrides
+    const config = loadAuditConfig(process.cwd(), flagValue('--config') || null);
+    applyRuleOverrides(config);
+    applyMaxWarnings(config);
+    const format = parseFormatFlag(['stylish', 'json'], 'stylish');
+
+    const lockfile = parseLockfile(filePath);
+    // package.json is optional; the pinned-versions rule degrades gracefully
+    const packageJson = loadSiblingPackageJson(filePath);
+
+    report = runAudit({ lockfile, packageJson, filePath: path.relative(process.cwd(), filePath) || filePath }, config);
+    console.log('\n' + formatAuditReport(report, { format }));
+  } catch (error) {
+    console.error(`\nAudit error: ${error.message}`);
+    process.exit(2);
+  }
+
+  process.exit(report.pass ? 0 : 1);
+}
+
+function runUpgradeHashesCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'upgrade-hashes');
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+
+  // Setup progress reporting
+  const onProgress = makeProgressReporter();
+
+  const upgraded = upgradeIntegrityHashes(lockfile, { onProgress });
+
+  // Clear progress line and show completion
+  clearProgressLine();
+  console.log('\nUpgraded integrity hashes');
+
+  if (hasWrite) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(upgraded, null, 2) + '\n', 'utf8');
+    console.log(`Changes written to ${filePath}`);
+  } else {
+    console.log('\nUse --write flag to save changes');
+    console.log(JSON.stringify(upgraded, null, 2));
+  }
+}
+
+function runDedupeCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'dedupe');
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+  const beforeCount = lockfile.packages ? Object.keys(lockfile.packages).length : 0;
+
+  // Setup progress reporting
+  const onProgress = makeProgressReporter();
+
+  const deduped = deduplicatePackages(lockfile, { onProgress });
+  const afterCount = deduped.packages ? Object.keys(deduped.packages).length : 0;
+
+  // Clear progress line and show completion
+  clearProgressLine();
+  console.log(`\nDeduplication complete`);
+  console.log(`   Packages: ${beforeCount} → ${afterCount} (removed ${beforeCount - afterCount})`);
+  if (afterCount === beforeCount && beforeCount > 0) {
+    console.log('   (a v2/v3 packages map is keyed by install path — every entry is required,');
+    console.log('    so there is nothing to collapse. Use `npm-check prune` to remove orphaned entries.)');
+  }
+
+  if (hasWrite) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(deduped, null, 2) + '\n', 'utf8');
+    console.log(`Changes written to ${filePath}`);
+  } else {
+    console.log('\nUse --write flag to save changes');
+    console.log(JSON.stringify(deduped, null, 2));
+  }
+}
+
+function runFixCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+  refuseIfPnpm(filePath, 'fix');
+  const hasWrite = argv.includes('--write');
+
+  const lockfile = parseLockfile(filePath);
+  // Load the sibling package.json (if present) so the fixer can sync the
+  // lockfile's stale root name/version — the "Structure & format" errors.
+  let pkgJson = null;
+  const pkgJsonPath = path.join(path.dirname(filePath), 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    try { pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8')); } catch { /* ignore malformed package.json */ }
+  }
+  const { fixedLockfile, fixes } = fixPackageLock(lockfile, { packageJson: pkgJson });
+
+  console.log('\nFixer Results:');
+  if (fixes.length === 0) {
+    console.log('   • Nothing to fix — lockfile structure is already consistent');
+  } else {
+    fixes.forEach(fix => console.log(`   • ${fix}`));
+  }
+
+  if (hasWrite) {
+    createBackup(filePath);
+    fs.writeFileSync(filePath, JSON.stringify(fixedLockfile, null, 2) + '\n', 'utf8');
+    console.log(`Changes written to ${filePath}`);
+  } else {
+    console.log('\nUse --write flag to save changes');
+    console.log(JSON.stringify(fixedLockfile, null, 2));
+  }
+}
+
+function runBackupsCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  const fileName = path.basename(filePath);
+
+  const backups = listBackups(filePath);
+
+  if (backups.length === 0) {
+    console.log(`\nNo backups found for ${fileName}`);
+  } else {
+    console.log(`\nBackups for ${fileName}:`);
+    backups.forEach((backup, i) => {
+      console.log(`   ${i + 1}. ${backup.name} (${backup.created.toLocaleString()})`);
+    });
+  }
+}
+
+function runRestoreCommand() {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+
+  restoreFromLatestBackup(filePath);
+  console.log(`\nFile restored successfully`);
+}
+
+function runCleanBackupsCommand() {
+  const filePath = getFilePath(positionals()[0]);
+
+  // Parse --keep flag
+  let keepCount = 5;
+  const keepIndex = argv.indexOf('--keep');
+  if (keepIndex !== -1 && argv[keepIndex + 1]) {
+    const parsed = parseInt(argv[keepIndex + 1], 10);
+    if (!isNaN(parsed) && parsed > 0) {
+      keepCount = parsed;
+    } else {
+      console.error('Invalid --keep value. Must be a positive number');
+      process.exit(2);
+    }
+  }
+
+  const deleted = cleanOldBackups(filePath, keepCount);
+  if (deleted === 0) {
+    console.log(`\nNo old backups to clean (keeping ${keepCount})`);
+  } else {
+    console.log(`\nCleaned ${deleted} old backup(s), keeping ${keepCount}`);
+  }
+}
+
+// Validate the --check flag, exiting on a bad value.
+function parseCheckType() {
+  const raw = flagValue('--check');
+  if (raw === undefined) return 'all';
+  if (!['hash', 'license', 'all'].includes(raw)) {
+    console.error('Invalid check type. Use: hash, license, or all');
+    process.exit(2);
+  }
+  return raw;
+}
+
+// Print the integrity (hash) check result: counts, mismatches, unresolved entries.
+function printHashResult(hashResult, failOnUnresolved) {
+  clearProgressLine();
+  console.log(`   Checked: ${hashResult.checked}`);
+  console.log(`   Passed: ${hashResult.passed}`);
+  console.log(`   Failed: ${hashResult.failed}`);
+  console.log(`   Skipped: ${hashResult.skipped}`);
+  console.log(`   Unresolved: ${hashResult.unresolved}`);
+
+  const mismatches = hashResult.errors.filter(e => e.expected && e.actual);
+  if (mismatches.length > 0) {
+    console.log('\n   Hash mismatches (lockfile differs from registry):');
+    mismatches.forEach(err => {
+      console.log(`     • ${err.package}`);
+      console.log(`       Registry: ${err.expected.slice(0, 50)}...`);
+      console.log(`       Lockfile: ${err.actual.slice(0, 50)}...`);
+    });
+  }
+  if (hashResult.unresolvedItems.length > 0) {
+    console.log('\n   Unresolved (could not verify against the registry):');
+    hashResult.unresolvedItems.forEach(item => {
+      console.log(`     • ${item.package}@${item.version}: ${item.reason}`);
+    });
+    if (failOnUnresolved) {
+      console.log('   (unresolved entries fail the check — they could not be verified; pass --allow-unresolved to treat them as non-fatal)');
+    } else {
+      console.log('   (unresolved entries are NOT failing the check because --allow-unresolved is set)');
+    }
+  }
+}
+
+// Print the license check result: counts, unapproved licenses, warnings.
+function printLicenseResult(licenseResult, strict) {
+  clearProgressLine();
+  console.log(`   Checked: ${licenseResult.checked}`);
+  console.log(`   Approved: ${licenseResult.approved}`);
+  console.log(`   Rejected: ${licenseResult.rejected}`);
+  console.log(`   Unknown: ${licenseResult.unknown}`);
+
+  if (licenseResult.errors.length > 0) {
+    console.log('\n   Unapproved/Unknown licenses:');
+    licenseResult.errors.forEach(err => {
+      console.log(`     • ${err.package}: ${err.license || 'UNKNOWN'}`);
+    });
+  }
+  if (licenseResult.warnings.length > 0 && !strict) {
+    console.log('\n   Warnings (unknown licenses):');
+    licenseResult.warnings.forEach(warn => {
+      console.log(`     • ${warn.package}: ${warn.license || 'UNKNOWN'}`);
+    });
+  }
+}
+
+async function runCheckCommand(command) {
+  const filePath = getFilePath(positionals()[0]);
+  ensureFileExists(filePath);
+
+  const checkType = parseCheckType();
+  const strict = argv.includes('--strict');
+  const licensesCsv = flagValue('--licenses-csv') || './approved-licenses.csv';
+  // Fail closed by default: an entry we couldn't verify against the registry must
+  // not pass as "verified". `--allow-unresolved` opts back into lenient behavior.
+  const failOnUnresolved = !argv.includes('--allow-unresolved');
+  // Registry-verification flags (hash check)
+  const { concurrency, timeoutMs, defaultRegistry } = parseNetworkFlags();
+
+  const lockfile = parseLockfile(filePath);
+  const onProgress = makeProgressReporter();
+  const options = { onProgress, strict, csvPath: licensesCsv };
+
+  let allValid = true;
+  try {
+    // Run hash check (verifies locked integrity against the registry)
+    if (checkType === 'hash' || checkType === 'all') {
+      console.log('Verifying integrity against the registry...');
+      const hashResult = await checkIntegrity(lockfile, {
+        ...options, concurrency, timeoutMs, failOnUnresolved, ...registryOption(defaultRegistry)
+      });
+      printHashResult(hashResult, failOnUnresolved);
+      allValid = allValid && hashResult.valid;
+    }
+
+    // Run license check
+    if (checkType === 'license' || checkType === 'all') {
+      console.log('\nChecking licenses...');
+      const licenseResult = await checkLicenses(lockfile, options);
+      printLicenseResult(licenseResult, strict);
+      allValid = allValid && licenseResult.valid;
+    }
+
+    console.log(allValid ? '\nAll checks passed' : '\nSome checks failed');
+    process.exit(allValid ? 0 : 1);
+  } catch (error) {
+    handleError(error, `${command} command failed`);
+  }
+}
+
+// Print the vuln-scan result in pretty form: counts, advisories, unresolved entries.
+function printVulnResult(result, minSeverity, failOnUnresolved) {
+  console.log(`   Scanned: ${result.scanned}`);
+  console.log(`   Vulnerable: ${result.vulnerable}`);
+  console.log(`   Skipped: ${result.skipped}`);
+  console.log(`   Unresolved: ${result.unresolved}`);
+
+  if (result.errors.length > 0) {
+    console.log(`\n   Vulnerabilities at/above ${minSeverity} (fail the run):`);
+    result.errors.forEach(e => {
+      // Skip only reason-bearing (unresolved) errors — rendered separately below.
+      // A genuine advisory, even one lacking an `id`, must still be printed.
+      if (e.reason) return;
+      console.log(`     • ${e.package}@${e.version}: ${e.title} (${e.severity})`);
+      if (e.url) console.log(`       ${e.url}`);
+    });
+  }
+  if (result.warnings.length > 0) {
+    console.log(`\n   Advisories below ${minSeverity} (warnings):`);
+    result.warnings.forEach(w => {
+      console.log(`     • ${w.package}@${w.version}: ${w.title} (${w.severity})`);
+    });
+  }
+  if (result.unresolvedItems.length > 0) {
+    console.log('\n   Unresolved (could not check against the registry):');
+    result.unresolvedItems.forEach(item => {
+      console.log(`     • ${item.package}@${item.version}: ${item.reason}`);
+    });
+    if (failOnUnresolved) {
+      console.log('   (unresolved entries FAIL the scan — these packages could not be checked; pass --allow-unresolved to treat them as non-fatal)');
+    } else {
+      console.log('   (unresolved entries are NOT failing the scan because --allow-unresolved is set)');
+    }
+  }
+  console.log(result.valid ? '\nNo known vulnerabilities at/above the threshold' : '\nScan failed (vulnerabilities found or packages could not be scanned)');
+}
+
+async function runVulnCommand(command) {
+  const filePath = getFilePath(positionals()[0]);
+  // `count=` has no meaning for a per-package severity scanner — reject it early
+  // so a CI pipeline that meant `--fail-on severity=` never silently passes.
+  assertFailOnSupported({ severity: true, count: false }, 'vuln');
+  requireLockfileOrExit2(filePath, 'vuln');
+
+  const format = parseFormatFlag(['human', 'json'], 'human');
+  const minSeverity = resolveSeverityGate();
+  const offline = argv.includes('--offline');
+  // Fail closed by default: a package the scan couldn't check (registry down /
+  // endpoint unsupported) must not pass as "no vulnerabilities". Opt out with
+  // `--allow-unresolved` (or skip the network entirely with `--offline`).
+  const failOnUnresolved = !argv.includes('--allow-unresolved');
+  const { concurrency, timeoutMs, defaultRegistry } = parseNetworkFlags(2);
+
+  const lockfile = parseLockfile(filePath);
+  const onProgress = format === 'human' ? makeProgressReporter() : null;
+
+  try {
+    if (format === 'human' && !offline) console.log('Scanning locked packages for known vulnerabilities…');
+    const result = await checkVulnerabilities(lockfile, {
+      concurrency, timeoutMs, minSeverity, offline, failOnUnresolved, onProgress,
+      ...registryOption(defaultRegistry)
+    });
+
+    if (onProgress) clearProgressLine();
+
+    const exitCode = result.valid ? 0 : 1;
+    if (format === 'json') {
+      // The shared finding-schema envelope is the ONLY thing on stdout in json mode.
+      const target = path.relative(process.cwd(), filePath) || filePath;
+      console.log(JSON.stringify(vulnEnvelope(result, { target, exitCode }), null, 2));
+    } else {
+      printVulnResult(result, minSeverity, failOnUnresolved);
+    }
+
+    process.exit(exitCode);
+  } catch (error) {
+    handleError(error, `${command} command failed`);
+  }
+}
+
+// Print the deprecation-scan result in pretty form: counts, notices, unresolved, verdict.
+function printDeprecatedResult(result, failOnUnresolved) {
+  console.log(`   Scanned: ${result.scanned}`);
+  console.log(`   Deprecated: ${result.deprecated}`);
+  console.log(`   Skipped: ${result.skipped}`);
+  console.log(`   Unresolved: ${result.unresolved}`);
+
+  if (result.errors.some(e => e.message)) {
+    console.log('\n   Deprecated (fail the run):');
+    result.errors.forEach(e => {
+      if (!e.message) return;
+      console.log(`     • ${e.package}@${e.version}: ${e.message}`);
+    });
+  }
+  if (result.warnings.length > 0) {
+    console.log('\n   Deprecated (warnings):');
+    result.warnings.forEach(w => {
+      console.log(`     • ${w.package}@${w.version}: ${w.message}`);
+    });
+  }
+  if (result.unresolvedItems.length > 0) {
+    console.log('\n   Unresolved (could not check against the registry):');
+    result.unresolvedItems.forEach(item => {
+      console.log(`     • ${item.package}@${item.version}: ${item.reason}`);
+    });
+    if (failOnUnresolved) {
+      console.log('   (unresolved entries FAIL the scan — these packages could not be checked; pass --allow-unresolved to treat them as non-fatal)');
+    } else {
+      console.log('   (unresolved entries are NOT failing the scan because --allow-unresolved is set)');
+    }
+  }
+  if (!result.valid && result.deprecated === 0) {
+    console.log('\nScan incomplete — some packages could not be checked (see unresolved above)');
+  } else if (result.deprecated === 0) {
+    console.log('\nNo deprecated packages found');
+  } else if (result.valid) {
+    console.log('\nDeprecated packages found (warnings; pass --fail-on count=0 to fail the run)');
+  } else {
+    console.log('\nDeprecated packages found');
+  }
+}
+
+async function runDeprecatedCommand(command) {
+  const filePath = getFilePath(positionals()[0]);
+  // Deprecation is not on the severity ladder (`severity=` is a no-op here).
+  // Only `count=0` (fail on ANY deprecation) is supported; a non-zero budget
+  // (count=3) has no defined semantics for this command — reject both early.
+  assertFailOnSupported({ severity: false, count: 'zero-only' }, 'deprecated');
+  requireLockfileOrExit2(filePath, 'deprecated');
+
+  const format = parseFormatFlag(['human', 'json'], 'human');
+  const offline = argv.includes('--offline');
+  // Deprecation isn't on the severity ladder, so the canonical gate spelling is
+  // `--fail-on count=0` (fail on any deprecation); `--fail-on-deprecated` is the
+  // deprecated alias for the same effect.
+  const failOnDeprecated = resolveFailOnDeprecated() || parseFailOn().count === 0;
+  // Fail closed by default: a package the scan couldn't check must not pass as
+  // clean. `--allow-unresolved` (or `--offline`) opts back into lenient behavior.
+  const failOnUnresolved = !argv.includes('--allow-unresolved');
+  const { concurrency, timeoutMs, defaultRegistry } = parseNetworkFlags(2);
+
+  const lockfile = parseLockfile(filePath);
+  const onProgress = format === 'human' ? makeProgressReporter() : null;
+
+  try {
+    if (format === 'human' && !offline) console.log('Scanning locked packages for deprecation notices…');
+    const result = await checkDeprecations(lockfile, {
+      concurrency, timeoutMs, offline, failOnDeprecated, failOnUnresolved, onProgress,
+      ...registryOption(defaultRegistry)
+    });
+
+    if (onProgress) clearProgressLine();
+
+    const exitCode = result.valid ? 0 : 1;
+    if (format === 'json') {
+      // The shared finding-schema envelope is the ONLY thing on stdout in json mode.
+      const target = path.relative(process.cwd(), filePath) || filePath;
+      console.log(JSON.stringify(deprecationEnvelope(result, { target, exitCode }), null, 2));
+    } else {
+      printDeprecatedResult(result, failOnUnresolved);
+    }
+
+    process.exit(exitCode);
+  } catch (error) {
+    handleError(error, `${command} command failed`);
+  }
+}
+
+// Print the remediation result in pretty form: bumps, guidance, skips, warnings.
+function printRemediateResult(result) {
+  console.log('\nRemediation Results:');
+  if (result.bumped.length === 0) {
+    console.log('   • No direct dependencies to bump');
+  } else {
+    result.bumped.forEach((b) => {
+      console.log(`   • ${b.section}/${b.package}  ${b.from} → ${b.to}  (${b.reasons.join(', ')})`);
+    });
+  }
+
+  if (result.guidance.length > 0) {
+    console.log('\n   Transitive / manual (not a direct dep — bump the parent or add an npm override):');
+    result.guidance.forEach((g) => {
+      const note = g.kind === 'latest-still-affected' ? `${g.reasons.join(', ')}; latest still affected` : g.reasons.join(', ');
+      console.log(`     • ${g.package}: ${note}`);
+    });
+  }
+  if (result.skipped.length > 0) {
+    console.log('\n   Skipped:');
+    result.skipped.forEach((s) => console.log(`     • ${s.section}/${s.package} (${s.range}): ${s.reason}`));
+  }
+  result.warnings.forEach((w) => console.log(`\n${w.package}: ${w.reason}`));
+}
+
+async function runRemediateCommand(command) {
+  // Operates on a directory containing both package.json and the lockfile.
+  const dir = getDirArg();
+  const hasWrite = argv.includes('--write');
+
+  const packageJsonPath = path.join(dir, 'package.json');
+  const lockfilePath = path.join(dir, 'package-lock.json');
+  ensureFileExists(packageJsonPath);
+  ensureFileExists(lockfilePath);
+
+  const format = parseFormatFlag(['human', 'json'], 'human');
+  const minSeverity = resolveSeverityGate();
+  const includeDeprecated = !argv.includes('--no-deprecated');
+  const defaultRegistry = flagValue('--registry');
+
+  const packageJsonRaw = fs.readFileSync(packageJsonPath, 'utf8');
+  const packageJson = JSON.parse(packageJsonRaw);
+  const lockfile = parseLockfile(lockfilePath);
+
+  const onProgress = format === 'human' ? makeProgressReporter() : null;
+
+  try {
+    if (format === 'human') console.log('Scanning for remediable direct dependencies…');
+    const result = await remediateDependencies(lockfile, packageJson, {
+      minSeverity, includeDeprecated, onProgress,
+      ...registryOption(defaultRegistry)
+    });
+    if (onProgress) clearProgressLine();
+
+    if (format === 'json') {
+      // The shared finding-schema envelope is the ONLY thing on stdout in json mode.
+      // remediate is an action command, not a CI gate — it always exits 0.
+      const target = path.relative(process.cwd(), dir) || dir;
+      const scanned = lockfile && lockfile.packages && typeof lockfile.packages === 'object'
+        ? Object.keys(lockfile.packages).filter((k) => k !== '').length : 0;
+      console.log(JSON.stringify(remediateEnvelope(result, { target, scanned, exitCode: 0 }), null, 2));
+      process.exit(0);
+    }
+
+    printRemediateResult(result);
+
+    if (hasWrite && result.changed) {
+      const indent = detectIndent(packageJsonRaw);
+      writeJsonFile(packageJsonPath, result.packageJson, indent);
+      writeJsonFile(lockfilePath, result.lockfile);
+      console.log(`\nChanges written to ${packageJsonPath} and ${lockfilePath}`);
+      console.log('   Run `npm install` to re-resolve the dependency tree, then re-run `npm-check`.');
+    } else if (result.changed) {
+      console.log('\nUse --write to apply these bumps (then run `npm install`)');
+    }
+    process.exit(0);
+  } catch (error) {
+    handleError(error, `${command} command failed`);
+  }
+}
+
+// Dispatch table: command name → handler. Handlers that report their own
+// errors with the originating command name take it as an argument.
+const COMMAND_HANDLERS = {
+  report: () => runReportCommand(),
+  validate: () => runValidateCommand(),
+  migrate: () => runMigrateCommand(),
+  upgrade: () => runUpgradeCommand(),
+  'fix-checksums': () => runFixChecksumsCommand(),
+  pin: () => runPinCommand(),
+  prune: () => runPruneCommand(),
+  unused: () => runUnusedCommand(),
+  audit: () => runAuditCommand(),
+  'upgrade-hashes': () => runUpgradeHashesCommand(),
+  dedupe: () => runDedupeCommand(),
+  fix: () => runFixCommand(),
+  backups: () => runBackupsCommand(),
+  restore: () => runRestoreCommand(),
+  'clean-backups': () => runCleanBackupsCommand(),
+  check: (command) => runCheckCommand(command),
+  vuln: (command) => runVulnCommand(command),
+  deprecated: (command) => runDeprecatedCommand(command),
+  remediate: (command) => runRemediateCommand(command)
+};
+
+async function main() {
+  if (argv.includes('-h') || argv.includes('--help')) {
+    printHelp();
+    return;
+  }
+
+  // Version is long-only (`--version`); `-v` is intentionally NOT a version alias
+  // (canonical suite vocabulary: `-v` is never version).
+  if (argv.includes('--version')) {
+    console.log(`npm-check version ${getVersion()}`);
+    return;
+  }
+
+  // Fail closed on a typo'd/unknown flag (exit 2) — a silently-dropped option
+  // could disable the CI gate. Runs after --help/--version so those still work.
+  rejectUnknownOptions();
+
+  // Bare `npm-check` (no command, or only flags) runs the full report.
+  const command = (!argv[0] || argv[0].startsWith('-')) ? 'report' : argv[0];
+
+  const handler = COMMAND_HANDLERS[command];
+  if (!handler) {
+    // Unknown command is a usage error → exit 2 (suite convention).
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(2);
+    return;
+  }
+
+  try {
+    await handler(command);
+  } catch (error) {
+    handleError(error, `${command} command failed`);
+  }
+}
+
+main().catch(error => {
+  handleError(error, 'Fatal error');
+});