@dependably/npm-check 1.9.0 → 1.10.1

package/src/facts/collect.js

@@ -0,0 +1,201 @@
+// src/facts/collect.js
+// One call that gathers every import fact the modules under `src/facts/` can
+// establish about a tree: the workspace (manifests, aliases, source files),
+// every first-party file's scan with each site resolved to the installed
+// copy it loads, the module graph through node_modules, the lockfile graph,
+// and — load-bearing — the list of everything that was NOT read.
+//
+// It reports; it never judges. There is no "reachable" here, no verdict
+// vocabulary at all: a consumer that owns those words (sbom-reach's npm
+// analyzer) builds them from these facts. What this module guarantees is
+// that the facts are complete OR say where they are not (`unanalyzable`):
+// a file that could not be read used to be a silent `continue` in the
+// consumer, and "nothing imports it" then rested on a file nobody read.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { discoverLockfileGraphs } from './lockfile-graph.js';
+import { walkModuleGraph } from './modulegraph.js';
+import { ModuleResolver } from './resolve.js';
+import { scanSource } from './scan.js';
+import { specifierToPackage } from './specifier.js';
+import { loadTypeScript } from './ts.js';
+import { discoverWorkspace } from './workspace.js';
+
+/** @typedef {import('./types.d.ts').CollectOptions} CollectOptions */
+/** @typedef {import('./types.d.ts').FirstPartyFile} FirstPartyFile */
+/** @typedef {import('./types.d.ts').ImportFacts} ImportFacts */
+/** @typedef {import('./types.d.ts').ModuleGraph} ModuleGraph */
+/** @typedef {import('./types.d.ts').ResolvedSite} ResolvedSite */
+/** @typedef {import('./types.d.ts').UnanalyzableEntry} UnanalyzableEntry */
+
+/**
+ * Relativizes paths against `srcDir` — realpath-aware. First-party files are
+ * spelled under `srcDir` as given; resolved node_modules files are realpath'd
+ * (pnpm symlinks, macOS `/var` → `/private/var`, `/tmp` → `/private/tmp`),
+ * and `srcDir` as given may not be. Relativize against whichever spelling of
+ * `srcDir` the file actually sits under: the one that needs FEWER `..`
+ * segments. "Prefer the realpath only when it lands inside the tree" was the
+ * first rule and it was wrong — with node_modules hoisted ABOVE the target
+ * and a symlinked prefix on `srcDir`, both spellings start with `..`, and the
+ * as-given one is a `../../../..`-to-root chain followed by the whole
+ * absolute path (adversarial review), poisoning every path in the document.
+ * Always POSIX separators: the document must compare across machines. The
+ * tree itself relativizes to `''`, exactly as sbom-reach's `relOf` does — a
+ * consumer emits that spelling verbatim, so it must not change.
+ * @param {string} srcDir
+ * @param {string} realSrcDir
+ * @returns {(file: string) => string}
+ */
+export function makeRelOf(srcDir, realSrcDir) {
+  return (file) => {
+    const direct = relative(srcDir, file);
+    if (realSrcDir === srcDir) return direct.split(sep).join('/');
+    const viaReal = relative(realSrcDir, file);
+    const chosen = parentSegments(viaReal) < parentSegments(direct) ? viaReal : direct;
+    return chosen.split(sep).join('/');
+  };
+}
+
+/**
+ * How many leading `..` segments a relative path climbs through.
+ * @param {string} rel
+ * @returns {number}
+ */
+function parentSegments(rel) {
+  let n = 0;
+  for (const part of rel.split(sep)) {
+    if (part !== '..') break;
+    n++;
+  }
+  return n;
+}
+
+/**
+ * Collect the import facts of the tree at `srcDir`.
+ *
+ * @param {string} srcDir - the tree to describe (relative paths resolve against cwd)
+ * @param {CollectOptions} [options]
+ * @returns {ImportFacts}
+ * @throws {import('./errors.js').FactsError} `TYPESCRIPT_MISSING` before any
+ *   work is done, when the optional `typescript` peer is not installed.
+ */
+export function collectImportFacts(srcDir, options = {}) {
+  // Fail before touching the tree: every other module here parses with the
+  // compiler, so there is nothing partial worth returning without it.
+  loadTypeScript();
+  const { moduleGraph = true, maxFiles, maxFileBytes, scan = scanSource } = options;
+
+  const absSrcDir = resolve(srcDir);
+  let realSrcDir = absSrcDir;
+  try {
+    realSrcDir = realpathSync(absSrcDir);
+  } catch {
+    // keep as given
+  }
+  const relOf = makeRelOf(absSrcDir, realSrcDir);
+
+  const workspace = discoverWorkspace(absSrcDir);
+  const resolver = new ModuleResolver(workspace.aliasScope);
+
+  /** @type {UnanalyzableEntry[]} */
+  const unanalyzable = [];
+  /** @type {FirstPartyFile[]} */
+  const files = [];
+  let dynamicUnknownTotal = 0;
+
+  for (const file of workspace.sourceFiles) {
+    const rel = relOf(file);
+    /** @type {string} */
+    let content;
+    try {
+      content = readFileSync(file, 'utf8');
+    } catch (err) {
+      // The consumer used to `continue` here silently. A file nobody read is
+      // a file whose imports are unknown, and it must be listed. The reason
+      // is the error CODE, never Node's message — that carries the absolute
+      // path, and reasons must stay machine-independent (`file` says where).
+      unanalyzable.push({ file: rel, kind: 'file', reason: `unreadable: ${errorCode(err)}` });
+      continue;
+    }
+    const result = scan(rel, content);
+    dynamicUnknownTotal += result.dynamicUnknown;
+    if (result.parseErrors && result.parseErrors.length > 0) {
+      // Sites collected before/around the problem are still reported; what
+      // this entry says is that their absence for some package is not a
+      // clean negative.
+      unanalyzable.push({ file: rel, kind: 'file-partial', reason: result.parseErrors.join('; ') });
+    }
+    /** @type {ResolvedSite[]} */
+    const sites = result.sites.map((site) => {
+      const pkg = specifierToPackage(site.specifier, workspace.aliasScope.for(file));
+      // Which installed copy does this statement load? Version-accurate
+      // attribution is the consumer's, but the fact — the copy the resolver
+      // lands in — is established here, once, with the same resolver the
+      // graph walk uses.
+      const resolution = resolver.resolve(file, site.specifier, site.kind === 'require' ? 'require' : 'import');
+      const installed =
+        (resolution.kind === 'file' || resolution.kind === 'asset') && resolution.pkg !== undefined
+          ? {
+              name: resolution.pkg.name,
+              dirName: resolution.pkg.dirName,
+              version: resolution.pkg.version,
+              root: resolution.pkg.root
+            }
+          : undefined;
+      return { ...site, package: pkg, ...(installed ? { installed } : {}) };
+    });
+    files.push({ file, rel, scan: result, sites });
+  }
+
+  /** @type {ModuleGraph | undefined} */
+  let graph;
+  let nodeModulesMissing = false;
+  if (moduleGraph) {
+    graph = walkModuleGraph({
+      srcDir: absSrcDir,
+      resolver,
+      roots: files.map((f) => ({ file: f.file, scan: f.scan })),
+      scan,
+      ...(maxFiles !== undefined ? { maxFiles } : {}),
+      ...(maxFileBytes !== undefined ? { maxFileBytes } : {})
+    });
+    nodeModulesMissing = graph.reached.size === 0 && graph.unresolved > 0 && !existsSync(join(absSrcDir, 'node_modules'));
+    for (const entry of graph.unanalyzable) {
+      unanalyzable.push({ file: relOf(entry.file), kind: 'node-modules-file', reason: entry.reason });
+    }
+    if (graph.truncated) {
+      unanalyzable.push({
+        file: 'node_modules',
+        kind: 'walk',
+        reason:
+          `file budget ${graph.filesParsed} reached; ${graph.filesPastBudget} resolved file(s) past that frontier ` +
+          'were not parsed, so packages they load are unobserved, not absent'
+      });
+    }
+  }
+
+  const lockfile = discoverLockfileGraphs(absSrcDir);
+
+  return {
+    srcDir: absSrcDir,
+    realSrcDir,
+    workspace,
+    files,
+    graph,
+    nodeModulesMissing,
+    lockfile,
+    unanalyzable,
+    dynamicUnknownTotal
+  };
+}
+
+/**
+ * A path-free spelling of an I/O failure: the `code` (`EACCES`, `EISDIR`,
+ * `ENOENT`…) when there is one, else the constructor name.
+ * @param {unknown} err
+ * @returns {string}
+ */
+export function errorCode(err) {
+  if (err && typeof err === 'object' && 'code' in err && typeof err.code === 'string') return err.code;
+  return err instanceof Error ? err.name : 'error';
+}

package/src/facts/document.js

@@ -0,0 +1,151 @@
+// src/facts/document.js
+// The JSON shape of an import-facts document: the in-memory `ImportFacts`
+// (Maps, Sets, absolute paths) rendered as plain data a consumer can parse
+// on any machine — Maps and Sets become sorted arrays, every absolute path
+// becomes a target-relative POSIX path, and the module-graph keys keep their
+// `\0` separator with the path half relativized the same way, so a key in
+// `chain`/`fromPackage` still matches its `reached` entry.
+//
+// Language facts only: no purls, no verdicts, no severities. The envelope
+// identity (`tool`, `toolVersion`, `schemaVersion`, `documentType`, `target`)
+// is added by `schema.js`'s `buildFactsEnvelope`; this module produces the
+// `summary` and the body sections.
+import { makeRelOf } from './collect.js';
+
+/** @typedef {import('./types.d.ts').ImportFacts} ImportFacts */
+/** @typedef {import('./types.d.ts').FactsDocumentBody} FactsDocumentBody */
+/** @typedef {import('./types.d.ts').FactsSummary} FactsSummary */
+/** @typedef {import('./types.d.ts').ReachedPackage} ReachedPackage */
+/** @typedef {import('./types.d.ts').DocumentReachedPackage} DocumentReachedPackage */
+
+/**
+ * Render collected facts as the document body: `summary` plus every section.
+ * `target` is recorded by the envelope, not here; paths are relative to the
+ * facts' own `srcDir` (which is the target the CLI scanned).
+ *
+ * @param {ImportFacts} facts
+ * @param {{ exitCode?: number }} [options] `exitCode` lands in `summary.exitCode`
+ *   and MUST equal the process exit code the run will return (0 here — a
+ *   successful scan never gates).
+ * @returns {FactsDocumentBody}
+ */
+export function factsDocument(facts, options = {}) {
+  const exitCode = options.exitCode ?? 0;
+  const relOf = makeRelOf(facts.srcDir, facts.realSrcDir);
+  /** @param {string} key */
+  const relKey = (key) => {
+    const nul = key.indexOf('\0');
+    return nul === -1 ? key : `${key.slice(0, nul)}\0${relOf(key.slice(nul + 1))}`;
+  };
+
+  const imports = facts.files.map((f) => ({
+    file: f.rel,
+    dynamicUnknown: f.scan.dynamicUnknown,
+    parseErrors: f.scan.parseErrors ?? [],
+    sites: f.sites.map((s) => ({
+      specifier: s.specifier,
+      package: s.package ?? null,
+      line: s.line,
+      snippet: s.snippet,
+      kind: s.kind,
+      bindings: s.bindings ?? [],
+      referenced: s.referenced ?? [],
+      opaque: s.opaque === true,
+      ...(s.installed ? { installed: { ...s.installed, root: relOf(s.installed.root) } } : {})
+    }))
+  }));
+
+  const graph = facts.graph;
+  /** @type {DocumentReachedPackage[]} */
+  const reached = graph
+    ? [...graph.reached.values()]
+        .map((entry) => ({
+          key: relKey(entry.key),
+          name: entry.name,
+          dirName: entry.dirName,
+          version: entry.version,
+          root: relOf(entry.root),
+          chain: entry.chain.map(relKey),
+          dynamic: entry.dynamic,
+          incomplete: entry.incomplete,
+          importers: entry.importers.map((imp) => ({
+            file: relOf(imp.file),
+            line: imp.line,
+            snippet: imp.snippet,
+            kind: imp.kind,
+            bindings: imp.bindings ?? [],
+            referenced: imp.referenced ?? [],
+            opaque: imp.opaque === true,
+            fromPackage: imp.fromPackage === undefined ? null : relKey(imp.fromPackage)
+          }))
+        }))
+        .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    : [];
+  const unresolvedByName = graph
+    ? [...graph.unresolvedByName]
+        .map(([pkg, sites]) => ({
+          package: pkg,
+          sites: sites.map((s) => ({ file: relOf(s.file), reason: s.reason }))
+        }))
+        .sort((a, b) => (a.package < b.package ? -1 : a.package > b.package ? 1 : 0))
+    : [];
+
+  const moduleGraph = {
+    enabled: graph !== undefined,
+    filesParsed: graph ? graph.filesParsed : 0,
+    filesSkippedForSize: graph ? graph.filesSkippedForSize : 0,
+    unresolved: graph ? graph.unresolved : 0,
+    truncated: graph ? graph.truncated : false,
+    nodeModulesMissing: facts.nodeModulesMissing,
+    weakPackages: graph ? graph.weakPackages : [],
+    reached,
+    unresolvedByName
+  };
+
+  const ws = facts.workspace;
+  const workspace = {
+    firstPartyNames: [...ws.firstPartyNames].sort(),
+    depScopes: [...ws.depScopes]
+      .map(([name, scope]) => ({ name, scope }))
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+    aliasPrefixes: [...ws.aliasPrefixes].sort(),
+    // `aliasScope` itself is a closure (`.for(file)`) and cannot be
+    // serialized; this projects the same per-config information it answers
+    // from, the way `reached`/`unresolvedByName` project the module graph's
+    // Maps above -- one entry per tsconfig/jsconfig that declared `paths`,
+    // `dir` made target-relative and POSIX like every other path here.
+    aliasScope: ws.aliasLayers
+      .map((layer) => ({ dir: relOf(layer.dir), prefixes: [...layer.prefixes].sort() }))
+      .sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0)),
+    devDeclaredBy: [...ws.devDeclaredBy]
+      .map(([name, manifests]) => ({ name, manifests: [...manifests].sort() }))
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0)),
+    sourceFiles: ws.sourceFiles.length,
+    diagnostics: ws.diagnostics
+  };
+
+  const lockfile = {
+    files: facts.lockfile.files.map(relOf),
+    packages: facts.lockfile.packages,
+    rootDependencies: facts.lockfile.rootDependencies,
+    edges: facts.lockfile.edges,
+    diagnostics: facts.lockfile.diagnostics
+  };
+
+  /** @type {FactsSummary} */
+  const summary = {
+    scanned: ws.sourceFiles.length,
+    analyzed: facts.files.length,
+    unanalyzable: facts.unanalyzable.length,
+    imports: facts.files.reduce((n, f) => n + f.sites.length, 0),
+    moduleGraph: {
+      filesParsed: moduleGraph.filesParsed,
+      reached: reached.length,
+      unresolved: moduleGraph.unresolved,
+      truncated: moduleGraph.truncated
+    },
+    exitCode
+  };
+
+  return { summary, workspace, imports, moduleGraph, lockfile, unanalyzable: facts.unanalyzable };
+}

package/src/facts/errors.js

@@ -0,0 +1,19 @@
+// src/facts/errors.js
+// The one error type the import-facts modules throw for a condition the caller
+// is expected to handle by code rather than by message: `TYPESCRIPT_MISSING`
+// (the optional `typescript` peer is not installed). Everything else — an
+// unreadable file, an unparseable lockfile — is reported IN the facts, never
+// thrown, because a facts document that aborts on one bad file has told the
+// consumer nothing about the rest of the tree.
+
+export class FactsError extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   */
+  constructor(code, message) {
+    super(message);
+    this.name = 'FactsError';
+    this.code = code;
+  }
+}

package/src/facts/index.js

@@ -0,0 +1,37 @@
+// src/facts/index.js
+// Barrel for `@dependably/npm-check/facts` — the npm LANGUAGE-FACTS layer:
+// per-file imports, bindings and referenced names; Node-style resolution;
+// the walk through node_modules; lockfile graphs; workspace discovery.
+// Facts, not findings: nothing exported here carries a severity, a verdict
+// or a package identifier beyond the name and version on disk. The main
+// barrel (`src/index.js`) deliberately does NOT re-export this — the
+// lockfile commands must never load the TypeScript compiler.
+//
+// Precedent: pycheck's `--imports` document (its readme, "Import facts") —
+// report not gate, a `documentType` discriminator, `unanalyzable[]`
+// load-bearing, additive fields only.
+
+// The facts document's own schema version — what `buildFactsEnvelope`
+// (src/schema.js) writes as `schemaVersion`, a SEPARATE version line from
+// the findings envelope's `SCHEMA_VERSION`. See version.js for why it is a
+// leaf module rather than living here or in schema.js.
+export { FACTS_SCHEMA_VERSION } from './version.js';
+
+export { FactsError } from './errors.js';
+export { loadTypeScript } from './ts.js';
+export { collectImportFacts, makeRelOf } from './collect.js';
+export { factsDocument } from './document.js';
+export { scanSource } from './scan.js';
+export { ModuleResolver, packageRootOf, resolveExports } from './resolve.js';
+export { walkModuleGraph, packageKey, DEFAULT_MAX_FILES, DEFAULT_MAX_FILE_BYTES } from './modulegraph.js';
+export {
+  discoverLockfileGraphs,
+  mergeDiscovered,
+  parsePackageLockJson,
+  parsePackageLockJsonGraph,
+  parsePnpmLockYaml,
+  parsePnpmLockYamlGraph
+} from './lockfile-graph.js';
+export { specifierToPackage, aliasBaseFromPathsKey, fixedAliasScope, asAliasScope } from './specifier.js';
+export { discoverWorkspace, governedByManifest } from './workspace.js';
+export { loadGitignores, isGitignored, filterGitignored, OUTPUT_SHAPED_DIRS, outputDirScannedDiagnostic } from './sourcescan.js';