@dependably/npm-check 1.9.0 → 1.10.1

package/README.md

@@ -54,8 +54,55 @@ for every command, flag, and exit code.
 - **Vulnerabilities & deprecations** — scan locked versions against the npm advisory endpoint and deprecation notices.
 - **Licenses** — validate SPDX expressions against an approved list.
 - **Pin / prune / unused** — lock ranges (incl. `overrides`) to exact versions, remove orphaned entries, flag unused deps.
+- **Import facts** — report what the source tree imports (per-file imports, bindings, the module graph through `node_modules`, lockfile graphs) as a JSON document for another tool to consume. See below.
 - **pnpm** — read-only checks and config validation for `pnpm-lock.yaml`.
 
+## Import facts (`npm-check imports`)
+
+`npm-check imports <dir>` exports what a JavaScript/TypeScript/Svelte tree
+imports, as data for another tool. It is the same parse-only scan
+[sbom-reach](https://github.com/dependably/sbom-reach) uses for its npm
+reachability verdicts — the imports of every first-party file, the binding
+names each site introduces and which of them the file actually references,
+each site resolved to the installed copy it loads, the statically resolved
+module graph *through* `node_modules`, and the dependency graph the lockfiles
+record — published instead of judged. Nothing is written, nothing is gated: a
+successful scan always exits `0`.
+
+```bash
+npm-check imports ./src                     # the facts document, as JSON
+npm-check imports ./src --format human      # its summary
+npm-check imports ./src --no-module-graph   # first-party imports only
+```
+
+npm-check reports **npm language facts only**. It knows nothing about purls,
+SBOMs or vulnerabilities, and it draws no conclusion: whether a package is
+*reachable* is a verdict, and verdicts belong to the consumer.
+
+**Facts are not findings.** An import site has no severity — "lodash is
+imported on line 3" is not a problem to fix — so squeezing it into the
+findings envelope's `findings` array would be a lie, and would let `--fail-on`
+gate CI on ordinary imports. `imports` therefore emits a **sibling document
+type**: the same envelope identity every Dependably tool shares (`tool`,
+`toolVersion`, `schemaVersion`, `target`, `summary`), with `findings` replaced
+by the facts sections, and an explicit `documentType: "imports"`
+discriminator so a consumer never has to guess the payload from whichever key
+happens to be present. A document with no `documentType` is a findings
+document (schema `1.0` predates the split, and the findings envelope is
+unchanged). This is the same contract pycheck's `--imports` established for
+Python.
+
+The load-bearing part is `unanalyzable`: every file the scan could not read,
+every `.svelte` file whose `<script>` extraction reported a problem, every
+`node_modules` file the walk skipped, and a walk cut off by its file budget is
+listed with a `kind` and a `reason`, so that an absence of evidence is only
+ever read as a negative when the search actually ran. The command needs the
+optional `typescript` peer dependency (any 5.6+ release) and exits `2` with
+`TYPESCRIPT_MISSING` when it is not installed. The full document shape is in
+the [CLI reference](https://github.com/dependably/npm-check/blob/main/docs/CLI.md#imports-command);
+the library form (`@dependably/npm-check/facts`) is in the
+[API guide](https://github.com/dependably/npm-check/blob/main/docs/API.md#import-facts-dependablynpm-checkfacts).
+
 ## Documentation
 
 - **[CLI reference](https://github.com/dependably/npm-check/blob/main/docs/CLI.md)** — all commands, flags, exit codes, JSON output

package/bin/cli.js

@@ -25,6 +25,7 @@ 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';
+import { buildFactsEnvelope } from '../src/schema.js';
 
 const argv = process.argv.slice(2);
 
@@ -49,6 +50,9 @@ Commands:
     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
+    imports [dir]            Report the tree's import facts (per-file imports, bindings,
+                             the module graph through node_modules, lockfile graphs) as
+                             a JSON document — data for another tool, never a gate
 
   Fix & transform (npm-only; mutate the lockfile with --write):
     fix [file] [--write]     Run automated fixer with optional write
@@ -147,6 +151,16 @@ Unused Options:
   --include-dev              Also check devDependencies (off by default)
   --format human|json        Output format (default: human; json is machine-readable)
 
+Imports Options:
+  --format json|human        Output format (default: json — the facts document, with
+                             documentType "imports"; human prints its summary)
+  --no-module-graph          Do not follow imports through node_modules
+  --max-files N              Stop the node_modules walk after N files (default: 25000)
+  --max-file-bytes N         Skip (and report) node_modules files larger than N bytes
+                             (default: 1500000)
+  (needs the optional \`typescript\` peer dependency; exits 2 with TYPESCRIPT_MISSING
+   when it is not installed. A successful scan always exits 0 — facts are not findings.)
+
 Audit Options:
   --config <file>            Suite config (.dependably; .dependably-check is a
                              deprecated alias), discovered by walking up to the
@@ -175,6 +189,7 @@ Examples:
   npm-check pin --write                        # Lock down ^/~ versions
   npm-check prune --write                      # Remove orphaned lockfile entries
   npm-check unused                             # Flag never-imported dependencies
+  npm-check imports ./src > imports.json       # Import facts for another tool to consume
   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
@@ -325,6 +340,7 @@ function parseFormatFlag(allowed, fallback, code = 2) {
 const VALUED_OPTIONS = new Set([
   '--format', '--config', '--fail-on', '--concurrency', '--timeout',
   '--registry', '--licenses-csv', '--check', '--rule', '--keep',
+  '--max-files', '--max-file-bytes',
   // deprecated valued aliases (still parsed)
   '--min-severity', '--max-warnings'
 ]);
@@ -332,7 +348,7 @@ const BOOLEAN_OPTIONS = new Set([
   '--offline', '--allow-unresolved',
   '--no-integrity', '--no-vuln', '--no-deprecated', '--no-license',
   '--include-dev', '--include-peer', '--write', '--local-fallback', '--verbose',
-  '--show-suppressed',
+  '--show-suppressed', '--no-module-graph',
   '--version', '--help', '-h',
   // deprecated boolean aliases (still parsed)
   '--strict', '--fail-on-deprecated'
@@ -993,6 +1009,81 @@ function runUnusedCommand() {
   }
 }
 
+// `imports` is a data report, not a check: it emits the import-facts document
+// (`documentType: "imports"` — language facts only, no verdicts, no
+// severities), so it defaults to `--format json`, exits 0 on every successful
+// scan, and NEVER exits 1 — there is nothing to gate on. Exit 2 is the usage
+// tier: a missing target, a bad flag value, or the optional `typescript` peer
+// being absent (`TYPESCRIPT_MISSING`). The facts modules are imported lazily
+// so the lockfile-only commands never load the TypeScript compiler.
+async function runImportsCommand() {
+  const dir = getDirArg();
+  const target = positionals()[0] ?? '.';
+  const format = parseFormatFlag(['json', 'human'], 'json');
+  const moduleGraph = !argv.includes('--no-module-graph');
+  const maxFiles = parsePositiveIntFlag('--max-files', undefined, '--max-files');
+  const maxFileBytes = parsePositiveIntFlag('--max-file-bytes', undefined, '--max-file-bytes');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    console.error(`Error: Directory not found: ${dir}`);
+    process.exit(2);
+  }
+
+  const { collectImportFacts, factsDocument, FactsError } = await import('../src/facts/index.js');
+  let facts;
+  try {
+    facts = collectImportFacts(dir, {
+      moduleGraph,
+      ...(maxFiles !== undefined ? { maxFiles } : {}),
+      ...(maxFileBytes !== undefined ? { maxFileBytes } : {})
+    });
+  } catch (error) {
+    if (error instanceof FactsError && error.code === 'TYPESCRIPT_MISSING') {
+      console.error(`Error: ${error.code}: ${error.message}`);
+      process.exit(2);
+    }
+    throw error;
+  }
+
+  const { summary, ...body } = factsDocument(facts, { exitCode: 0 });
+  if (format === 'json') {
+    // The facts envelope is the ONLY thing on stdout in json mode.
+    console.log(JSON.stringify(buildFactsEnvelope({ target, summary, body }), null, 2));
+    return;
+  }
+  printImportsSummary(target, summary, body);
+}
+
+// The human rendering of the facts document is its summary — the document
+// itself is data for another tool, and a page of import sites is not
+// something a person reads at a terminal.
+function printImportsSummary(target, summary, body) {
+  console.log(`\nImport facts for ${target}`);
+  console.log(`   ${summary.scanned} first-party source file(s) found, ${summary.analyzed} analyzed, ${summary.unanalyzable} unanalyzable entr${summary.unanalyzable === 1 ? 'y' : 'ies'}`);
+  const dynamic = body.imports.reduce((n, f) => n + f.dynamicUnknown, 0);
+  console.log(`   ${summary.imports} import site(s); ${dynamic} require()/import() call(s) with non-literal arguments could not be attributed`);
+  const mg = body.moduleGraph;
+  if (!mg.enabled) {
+    console.log('   module graph: not walked (--no-module-graph)');
+  } else if (mg.nodeModulesMissing) {
+    console.log(`   module graph: node_modules is not installed — ${mg.unresolved} import(s) unresolved, nothing followed`);
+  } else {
+    const truncated = mg.truncated ? ' (truncated at the file budget)' : '';
+    console.log(`   module graph: ${mg.filesParsed} node_modules file(s) parsed, ${summary.moduleGraph.reached} installed package copy(ies) reached, ${mg.unresolved} import(s) unresolved${truncated}`);
+    if (mg.weakPackages.length > 0) {
+      console.log(`   ${mg.weakPackages.length} reached package(s) load modules dynamically or were not fully parsed: ${mg.weakPackages.slice(0, 5).join(', ')}${mg.weakPackages.length > 5 ? ', …' : ''}`);
+    }
+  }
+  const lock = body.lockfile;
+  if (lock.files.length > 0) {
+    console.log(`   lockfile graph: ${lock.packages.length} package(s), ${lock.edges.length} edge(s) from ${lock.files.join(', ')}`);
+  }
+  for (const d of [...body.workspace.diagnostics, ...lock.diagnostics]) console.log(`   note: ${d}`);
+  if (body.unanalyzable.length > 0) {
+    console.log('\n   Not analyzed (absence of evidence from these is not a negative):');
+    for (const u of body.unanalyzable) console.log(`     • ${u.file} [${u.kind}] ${u.reason}`);
+  }
+}
+
 // Print .dependably config notices (deprecated filename/section, unknown keys)
 // to stderr. Never affects exit codes or the JSON payload on stdout.
 function emitConfigWarnings(warnings, format) {
@@ -1559,6 +1650,7 @@ const COMMAND_HANDLERS = {
   pin: () => runPinCommand(),
   prune: () => runPruneCommand(),
   unused: () => runUnusedCommand(),
+  imports: () => runImportsCommand(),
   audit: () => runAuditCommand(),
   'upgrade-hashes': () => runUpgradeHashesCommand(),
   dedupe: () => runDedupeCommand(),

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@dependably/npm-check",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "A comprehensive tool for validating, migrating, and updating npm package-lock.json files across versions 1, 2, and 3.",
   "main": "src/index.js",
   "type": "module",
   "exports": {
     ".": "./src/index.js",
+    "./facts": {
+      "types": "./src/facts/types.d.ts",
+      "default": "./src/facts/index.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -32,7 +36,8 @@
     "docker:test:node24": "docker-compose -f tests/integration/docker/docker-compose.yml run --rm test-node24-npm11",
     "docker:test:all": "docker-compose -f tests/integration/docker/docker-compose.yml up --abort-on-container-exit",
     "lint": "eslint .",
-    "sbom": "cyclonedx-npm --output-format json --output-file sbom.json",
+    "typecheck": "tsc -p tsconfig.facts.json --noEmit",
+    "sbom":"cyclonedx-npm --output-format json --output-file sbom.json",
     "sbom:prod": "cyclonedx-npm --omit dev --output-format json --output-file sbom-prod.json",
     "prepublishOnly": "npm run test && npm run lint"
   },
@@ -69,6 +74,8 @@
     "npm": ">=10.0.0"
   },
   "dependencies": {
+    "fast-glob": "3.3.3",
+    "ignore": "7.0.5",
     "yaml": "2.9.0"
   },
   "devDependencies": {
@@ -76,11 +83,21 @@
     "@babel/preset-env": "7.28.6",
     "@cyclonedx/cyclonedx-npm": "5.0.0",
     "@eslint/js": "10.0.1",
+    "@types/node": "22.20.1",
     "babel-jest": "30.2.0",
     "eslint": "10.5.0",
     "globals": "17.6.0",
     "jest": "29.7.0",
-    "sonarqube-scanner": "5.0.0"
+    "sonarqube-scanner": "5.0.0",
+    "typescript": "5.9.3"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.6"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "allowScripts": {
     "fsevents": true,

package/src/audit-config.js

@@ -66,6 +66,10 @@ export const DEFAULT_CONFIG = {
     // unlike `allowedRegistryHosts` this list is NOT unioned from shared config —
     // a pin that only ever widens would not be a pin.
     'resolved-registry-pin': ['error', { hosts: [] }],
+    // 3 days: stricter than pnpm v11's own 1-day default and the ecosystem's
+    // 1-day baseline, deliberately — this tool is prescriptive. Lower it per
+    // project via the rule's `minDays` option.
+    'min-release-age': ['warn', { minDays: 3 }],
     'pinned-versions': ['error', {
       sections: ['dependencies', 'devDependencies', 'optionalDependencies'],
       ignore: []
@@ -230,16 +234,41 @@ function unknownKeyWarnings(section, label, warnings) {
  * under the npm-check section per the single merge rule (§5). Returns the audit
  * settings plus parsed exceptions and any warnings.
  */
-function resolveToolSection(parsed, warnings) {
-  const common = parsed && parsed.common;
+// Pick the tool's own section, preferring the canonical key over the deprecated
+// alias and warning about a deprecated or duplicated section.
+function pickToolSection(parsed, warnings) {
   const canonical = parsed && parsed[SECTION_KEY];
   const alias = parsed && parsed[DEPRECATED_SECTION_KEY];
-  const tool = canonical !== undefined ? canonical : alias;
-  if (canonical === undefined && alias !== undefined) {
-    warnings.push({ code: 'DEPRECATED_ALIAS_SECTION', message: `section "${DEPRECATED_SECTION_KEY}" is deprecated; rename it to "${SECTION_KEY}"` });
-  } else if (canonical !== undefined && alias !== undefined) {
-    warnings.push({ code: 'DEPRECATED_ALIAS_SECTION', message: `both "${SECTION_KEY}" and "${DEPRECATED_SECTION_KEY}" sections present; using "${SECTION_KEY}"` });
+  if (alias !== undefined) {
+    const message = canonical === undefined
+      ? `section "${DEPRECATED_SECTION_KEY}" is deprecated; rename it to "${SECTION_KEY}"`
+      : `both "${SECTION_KEY}" and "${DEPRECATED_SECTION_KEY}" sections present; using "${SECTION_KEY}"`;
+    warnings.push({ code: 'DEPRECATED_ALIAS_SECTION', message });
   }
+  return canonical !== undefined ? canonical : alias;
+}
+
+// maxWarnings is a scalar: the tool section overrides common.
+function pickMaxWarnings(common, tool) {
+  const of = (s) => (s && s.maxWarnings !== undefined ? s.maxWarnings : undefined);
+  const toolMax = of(tool);
+  return toolMax !== undefined ? toolMax : of(common);
+}
+
+// Exceptions: common (tolerant) + own section (strict selector/rule checks).
+function mergeExceptions(common, tool) {
+  const commonEx = parseExceptions(common && common.exceptions, {
+    source: 'common', applicableSelectors: APPLICABLE_SELECTORS
+  });
+  const ownEx = parseExceptions(tool && tool.exceptions, {
+    source: 'own', applicableSelectors: APPLICABLE_SELECTORS, knownRules: KNOWN_RULES
+  });
+  return [...commonEx, ...ownEx];
+}
+
+function resolveToolSection(parsed, warnings) {
+  const common = parsed && parsed.common;
+  const tool = pickToolSection(parsed, warnings);
 
   unknownKeyWarnings(tool, SECTION_KEY, warnings);
 
@@ -251,22 +280,11 @@ function resolveToolSection(parsed, warnings) {
   const failOn = pickFailOn(common && common.failOn, tool && tool.failOn);
   if (failOn) settings.failOn = failOn;
 
-  const pickMax = (s) => (s && s.maxWarnings !== undefined ? s.maxWarnings : undefined);
-  const toolMax = pickMax(tool);
-  const commonMax = pickMax(common);
-  if (toolMax !== undefined) settings.maxWarnings = toolMax;
-  else if (commonMax !== undefined) settings.maxWarnings = commonMax;
+  const maxWarnings = pickMaxWarnings(common, tool);
+  if (maxWarnings !== undefined) settings.maxWarnings = maxWarnings;
 
   settings.exclude = unionList(common && common.exclude, tool && tool.exclude);
-
-  // Exceptions: common (tolerant) + own section (strict selector/rule checks).
-  const commonEx = parseExceptions(common && common.exceptions, {
-    source: 'common', applicableSelectors: APPLICABLE_SELECTORS
-  });
-  const ownEx = parseExceptions(tool && tool.exceptions, {
-    source: 'own', applicableSelectors: APPLICABLE_SELECTORS, knownRules: KNOWN_RULES
-  });
-  settings.exceptions = [...commonEx, ...ownEx];
+  settings.exceptions = mergeExceptions(common, tool);
 
   return settings;
 }
@@ -364,47 +382,68 @@ export function loadSharedConfig(cwd = process.cwd()) {
   };
 }
 
+// An explicit `--config` file: either the shared (sectioned) shape or a legacy
+// flat tool-config. Fills the same slots the discovery path does.
+function loadExplicitConfig(explicitPath, shared) {
+  const configPath = path.resolve(explicitPath);
+  if (!fs.existsSync(configPath)) {
+    throw new AuditConfigError(`Config file not found: ${configPath}`, 'CONFIG_NOT_FOUND');
+  }
+  const parsed = readJsonConfig(configPath);
+  if (!isSharedShape(configPath, parsed)) {
+    // Legacy flat tool-config (.npm-checkrc.json shape) given explicitly.
+    return { configPath, toolConfig: parsed };
+  }
+
+  validateSharedShape(parsed, configPath);
+  const warnings = [];
+  const settings = resolveToolSection(parsed, warnings);
+  shared.warnings.push(...warnings);
+  return {
+    configPath,
+    toolConfig: {
+      ...(settings.rules ? { rules: settings.rules } : {}),
+      ...(settings.maxWarnings !== undefined ? { maxWarnings: settings.maxWarnings } : {})
+    },
+    explicitSharedHosts: collectSharedHosts(parsed),
+    // { exceptions, exclude, failOn } from an explicit shared-shape file
+    explicitExtras: { exceptions: settings.exceptions, exclude: settings.exclude, failOn: settings.failOn || null }
+  };
+}
+
+// Discover a tool-specific config in the working directory (fallback for
+// back-compat; the shared `.dependably` is the primary source).
+function discoverToolConfig(cwd) {
+  for (const name of CONFIG_FILENAMES) {
+    const candidate = path.join(cwd, name);
+    if (fs.existsSync(candidate)) {
+      return { configPath: candidate, toolConfig: readJsonConfig(candidate) };
+    }
+  }
+  return { configPath: null, toolConfig: {} };
+}
+
+// failOn.count is the standard form of maxWarnings; a legacy maxWarnings in a
+// tool-config still wins if it was set (it flowed through mergeConfig).
+function applyFailOn(config, failOn, maxWarningsAlreadySet) {
+  if (!failOn) return;
+  if (failOn.count !== undefined && !maxWarningsAlreadySet) {
+    if (typeof failOn.count !== 'number' || !Number.isInteger(failOn.count) || failOn.count < 0) {
+      throw new AuditConfigError(`failOn.count must be a non-negative integer, got: ${JSON.stringify(failOn.count)}`, 'INVALID_FAIL_ON');
+    }
+    config.maxWarnings = failOn.count;
+  }
+  config.failOnSeverity = failOn.severity || null;
+}
+
 export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
   // The shared `.dependably` (discovered by walking up to the repo root) is the
   // PRIMARY config source. A tool-specific `.npm-checkrc.json` (or an explicit
   // `--config`) overrides it.
   const shared = loadSharedConfig(cwd);
 
-  let toolConfig = {};
-  let configPath = null;
-  let explicitSharedHosts = [];
-  let explicitExtras = null; // { exceptions, exclude, failOn } from an explicit shared-shape file
-
-  if (explicitPath) {
-    configPath = path.resolve(explicitPath);
-    if (!fs.existsSync(configPath)) {
-      throw new AuditConfigError(`Config file not found: ${configPath}`, 'CONFIG_NOT_FOUND');
-    }
-    const parsed = readJsonConfig(configPath);
-    if (isSharedShape(configPath, parsed)) {
-      validateSharedShape(parsed, configPath);
-      const warnings = [];
-      const settings = resolveToolSection(parsed, warnings);
-      shared.warnings.push(...warnings);
-      toolConfig = { ...(settings.rules ? { rules: settings.rules } : {}), ...(settings.maxWarnings !== undefined ? { maxWarnings: settings.maxWarnings } : {}) };
-      explicitSharedHosts = collectSharedHosts(parsed);
-      explicitExtras = { exceptions: settings.exceptions, exclude: settings.exclude, failOn: settings.failOn || null };
-    } else {
-      // Legacy flat tool-config (.npm-checkrc.json shape) given explicitly.
-      toolConfig = parsed;
-    }
-  } else {
-    // Discover a tool-specific config in the working directory (fallback for
-    // back-compat; the shared `.dependably` above is the primary source).
-    for (const name of CONFIG_FILENAMES) {
-      const candidate = path.join(cwd, name);
-      if (fs.existsSync(candidate)) {
-        configPath = candidate;
-        toolConfig = readJsonConfig(candidate);
-        break;
-      }
-    }
-  }
+  const { configPath, toolConfig, explicitSharedHosts = [], explicitExtras = null } =
+    explicitPath ? loadExplicitConfig(explicitPath, shared) : discoverToolConfig(cwd);
 
   // Shared audit settings are the base; the tool-specific config overrides them.
   const userConfig = { ...shared.auditSettings, ...toolConfig };
@@ -417,18 +456,9 @@ export function loadAuditConfig(cwd = process.cwd(), explicitPath = null) {
     extendAllowedHosts(config, hosts);
   }
 
-  // failOn.count is the standard form of maxWarnings; a legacy maxWarnings in a
-  // tool-config still wins if it was set (it flowed through mergeConfig above).
-  const failOn = explicitExtras ? explicitExtras.failOn : shared.failOn;
-  if (failOn) {
-    if (failOn.count !== undefined && toolConfig.maxWarnings === undefined && shared.auditSettings.maxWarnings === undefined) {
-      if (typeof failOn.count !== 'number' || !Number.isInteger(failOn.count) || failOn.count < 0) {
-        throw new AuditConfigError(`failOn.count must be a non-negative integer, got: ${JSON.stringify(failOn.count)}`, 'INVALID_FAIL_ON');
-      }
-      config.maxWarnings = failOn.count;
-    }
-    config.failOnSeverity = failOn.severity || null;
-  }
+  const maxWarningsAlreadySet =
+    toolConfig.maxWarnings !== undefined || shared.auditSettings.maxWarnings !== undefined;
+  applyFailOn(config, explicitExtras ? explicitExtras.failOn : shared.failOn, maxWarningsAlreadySet);
 
   config.exceptions = explicitExtras ? explicitExtras.exceptions : shared.exceptions;
   config.exclude = explicitExtras ? explicitExtras.exclude : shared.exclude;