@dependably/npm-check 1.9.0 → 1.10.1

package/src/facts/sourcescan.js

@@ -0,0 +1,221 @@
+// src/facts/sourcescan.js
+// What an in-process analyzer is allowed to exclude from its FIRST-PARTY
+// source scan, and how it says so.
+//
+// The rule this file exists to enforce: **a directory's NAME is not evidence
+// that the code inside it is generated.** Excluding `build/` or `dist/` by
+// name was a guess, and where the guess was wrong an analyzer reported
+// `not-observed` -- "I looked and did not find" -- about files it never
+// opened. That is invariant 1's expensive direction (sbom-reach's CLAUDE.md),
+// and it was found in a real repo: SvelteDocs keeps its build pipeline in a
+// tracked, non-gitignored `build/`, the only importer of a high-severity
+// advisory (sbom-reach GitLab #31; sbom-reach commit 95f2b94).
+//
+// `.gitignore` is the authority instead: a project that builds into `dist/`
+// gitignores `dist/`, and one whose source lives in `build/` does not. That
+// moves the decision from a guess to the project's own statement about its
+// own tree.
+//
+// What a scan may STILL exclude by name is a location defined by a tool
+// rather than by convention, holding a COPY of the dependency closure --
+// `node_modules`. That is excluded for a different and correct reason: a
+// dependency's imports are the DEPENDENCY's, and counting them would make
+// every transitive dependency look first-party-imported.
+//
+// Ported verbatim (semantics preserved) from sbom-reach's
+// `packages/core/src/reach/sourcescan.ts`.
+//
+// That TypeScript file is this one's independently-maintained TWIN: npm's
+// facts moved out to this package, but `analyzer-pypi` still imports the
+// original directly, so the gitignore-bounding rules now live in two places.
+// The two were verified to agree by a differential fuzz at port time, but
+// nothing pins them together afterward -- a future change to gitignore
+// precedence or the `OUTPUT_DIR_SCANNED` wording made in only one of them
+// silently diverges the two ecosystems' scan-bounding rules. Port any change
+// to both, or note here why it does not apply to npm.
+import { readFileSync } from 'node:fs';
+import { dirname, relative, sep } from 'node:path';
+import fg from 'fast-glob';
+import ignoreFactory from 'ignore';
+
+/** @typedef {import('./types.d.ts').GitignoreLayer} GitignoreLayer */
+
+/**
+ * Every `.gitignore` under `srcDir`, deepest first -- not just the root one.
+ *
+ * Reading the root alone is not "letting gitignore decide": a monorepo
+ * routinely ignores `dist/` from `packages/foo/.gitignore` and says nothing
+ * about it at the root, so a root-only reader would start scanning exactly
+ * the built output that dropping hardcoded directory names is not meant to
+ * touch.
+ *
+ * `ignoreDirs` keeps the walk out of `node_modules`, which is both a large
+ * speedup and correct: a dependency's own `.gitignore` governs its own
+ * repository, not this tree.
+ *
+ * @param {string} srcDir
+ * @param {readonly string[]} ignoreDirs
+ * @returns {GitignoreLayer[]}
+ */
+export function loadGitignores(srcDir, ignoreDirs) {
+  const paths = fg.sync('**/.gitignore', {
+    cwd: srcDir,
+    absolute: true,
+    ignore: [...ignoreDirs],
+    dot: false,
+    followSymbolicLinks: false,
+    suppressErrors: true
+  });
+  /** @type {GitignoreLayer[]} */
+  const layers = [];
+  for (const path of paths) {
+    /** @type {string} */
+    let content;
+    try {
+      content = readFileSync(path, 'utf8');
+    } catch {
+      continue;
+    }
+    layers.push({
+      dir: relative(srcDir, dirname(path)).split(sep).join('/'),
+      matcher: ignoreFactory().add(content)
+    });
+  }
+  // Deepest first: git gives the nearest `.gitignore` the last word, including
+  // its right to re-include with `!` something a parent ignored.
+  layers.sort((a, b) => b.dir.length - a.dir.length || a.dir.localeCompare(b.dir));
+  return layers;
+}
+
+/**
+ * Is `rel` (relative to srcDir, `/`-joined) ignored, by git's own rules?
+ *
+ * Component by component, outermost first, because that is how git decides:
+ * each path component is judged by the NEAREST `.gitignore` that says
+ * anything about it, and an ignored DIRECTORY ends the walk -- git does not
+ * descend into one, so no deeper rule and no deeper `.gitignore` inside it
+ * can re-include anything. Doing it this way is what makes `!build/` in
+ * `tools/.gitignore` re-include `tools/build/` against a root that ignores
+ * `build/`, which real git does and a single flat matcher does not.
+ *
+ * @param {readonly GitignoreLayer[]} layers
+ * @param {string} rel
+ * @returns {boolean}
+ */
+export function isGitignored(layers, rel) {
+  if (layers.length === 0 || rel === '' || rel.startsWith('..')) return false;
+  const parts = rel.split('/');
+  for (let i = 0; i < parts.length; i++) {
+    const path = parts.slice(0, i + 1).join('/');
+    // A trailing slash is how `ignore` is told the path is a directory, which
+    // decides whether a directory-only pattern (`build/`) matches it at all.
+    const isDir = i < parts.length - 1;
+    if (componentIgnored(layers, path, isDir ? `${path}/` : path)) return true;
+  }
+  return false;
+}
+
+/**
+ * The nearest layer with an explicit verdict about one path component decides it.
+ * @param {readonly GitignoreLayer[]} layers
+ * @param {string} path
+ * @param {string} testPath
+ * @returns {boolean}
+ */
+function componentIgnored(layers, path, testPath) {
+  const slash = path.lastIndexOf('/');
+  const parent = slash === -1 ? '' : path.slice(0, slash);
+  for (const layer of layers) {
+    // Layers are deepest-first; one applies when its directory is the
+    // component's own directory or an ancestor of it.
+    if (layer.dir !== '' && parent !== layer.dir && !parent.startsWith(`${layer.dir}/`)) continue;
+    const rel = layer.dir === '' ? path : path.slice(layer.dir.length + 1);
+    const sub = layer.dir === '' ? testPath : testPath.slice(layer.dir.length + 1);
+    // `ignore` reports a path as ignored when an ANCESTOR directory of it
+    // matched, which is its own walk, not this one. Disregard that: the
+    // ancestor was judged on its own turn above, and reaching this component
+    // at all means a nearer layer re-included it.
+    if (rel.includes('/') && layer.matcher.test(`${rel.slice(0, rel.lastIndexOf('/'))}/`).ignored) {
+      continue;
+    }
+    const result = layer.matcher.test(sub);
+    if (result.ignored) return true;
+    if (result.unignored) return false;
+    // Silent about this component: keep walking outwards.
+  }
+  return false;
+}
+
+/**
+ * Drop the absolute paths under `srcDir` that a `.gitignore` in the tree ignores.
+ * @param {string} srcDir
+ * @param {readonly GitignoreLayer[]} layers
+ * @param {string[]} paths
+ * @returns {string[]}
+ */
+export function filterGitignored(srcDir, layers, paths) {
+  if (layers.length === 0) return paths;
+  return paths.filter((p) => !isGitignored(layers, relative(srcDir, p).split(sep).join('/')));
+}
+
+/**
+ * Directory names that usually DO hold generated or vendored output. Nothing
+ * is excluded for being on this list -- it exists only so that scanning one
+ * can be said out loud, for the project that commits its build output
+ * without gitignoring it and then wonders why its evidence points into a
+ * bundle.
+ * @type {readonly string[]}
+ */
+export const OUTPUT_SHAPED_DIRS = ['build', 'coverage', 'dist', 'out', 'vendor'];
+
+/**
+ * `OUTPUT_DIR_SCANNED`, or undefined when no such directory was scanned.
+ *
+ * Deliberately a NOTE, not a warning. A warning marks a run that examined
+ * LESS than it appears to -- a degraded run that must not look clean. This
+ * read MORE of the tree.
+ *
+ * Reading more is not free, and the honest version of this rationale says
+ * so: a newly-scanned directory can SHADOW a package name -- a top-level
+ * `build/` against the `build` distribution, a committed `vendor/js-yaml`
+ * against `js-yaml` -- and a consumer answers `unknown` for that, which
+ * gates LESS than the `reachable` it replaced. What holds is that no
+ * negative gets SILENTLY weaker: each of those is reported on the finding
+ * itself, naming the colliding name and the path that owns it, instead of
+ * becoming a confident negative (invariant 1). A warning marks a gap the
+ * findings do not carry; this one they do.
+ *
+ * It still has to be visible, because a user who sees evidence at
+ * `dist/bundle.js` should be able to find out why a bundle counted as
+ * first-party source. Raising it to a warning would also fire on every run
+ * of every repo that commits a built `dist/`, which is how a signal becomes
+ * noise everyone skims past.
+ *
+ * @param {readonly string[]} relPaths scanned source files, relative to srcDir, `/`-joined.
+ * @param {readonly string[]} [names]
+ * @returns {string | undefined}
+ */
+export function outputDirScannedDiagnostic(relPaths, names = OUTPUT_SHAPED_DIRS) {
+  const nameSet = new Set(names);
+  /** @type {Set<string>} */
+  const scanned = new Set();
+  for (const rel of relPaths) {
+    const segments = rel.split('/');
+    for (const segment of segments.slice(0, -1)) {
+      if (nameSet.has(segment)) scanned.add(segment);
+    }
+  }
+  if (scanned.size === 0) return undefined;
+  const listed = [...scanned]
+    .sort()
+    .map((n) => `${n}/`)
+    .join(', ');
+  return (
+    `OUTPUT_DIR_SCANNED: scanned source under ${listed}, which no .gitignore under srcDir ` +
+    'ignores. A directory name is not evidence, so those files are read as first-party source — ' +
+    'the alternative is claiming `not-observed` for a package only such a file imports. One of ' +
+    'them may also SHADOW a package of the same name, in which case that finding is reported ' +
+    '`unknown` naming the collision rather than as a negative. If they really are generated ' +
+    'output, gitignore them and they will be excluded.'
+  );
+}

package/src/facts/specifier.js

@@ -0,0 +1,89 @@
+// src/facts/specifier.js
+// Module specifier → npm package name. This coexists with usage-scanner.js's
+// `specifierToPackageName` on purpose: that one answers "which declared
+// dependency does this mention count towards" for the unused-dependency
+// heuristic (and so treats `@types/foo` specially); this one is the language
+// fact — the package a specifier names, or nothing when it names no package.
+import { builtinModules } from 'node:module';
+
+const BUILTINS = new Set(builtinModules);
+
+/**
+ * Map a module specifier to the npm package it belongs to (lower-cased, since
+ * npm names are case-insensitively unique), or undefined when the specifier is
+ * not a package import: a relative/absolute path, a builtin, a `#imports`
+ * key, a data:/file: URL, or a tsconfig/jsconfig path alias.
+ *
+ * @param {string} spec
+ * @param {ReadonlySet<string>} aliasPrefixes
+ * @returns {string | undefined}
+ */
+export function specifierToPackage(spec, aliasPrefixes) {
+  if (spec.length === 0) return undefined;
+  if (spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('#')) return undefined;
+  if (spec.startsWith('node:') || spec.startsWith('data:') || spec.startsWith('file:')) {
+    return undefined;
+  }
+  if (BUILTINS.has(spec.split('/')[0])) return undefined;
+
+  for (const alias of aliasPrefixes) {
+    if (spec === alias || spec.startsWith(`${alias}/`)) return undefined;
+  }
+
+  const parts = spec.split('/');
+  if (spec.startsWith('@')) {
+    if (parts.length < 2) return undefined;
+    return `${parts[0]}/${parts[1]}`.toLowerCase();
+  }
+  return parts[0].toLowerCase();
+}
+
+/**
+ * tsconfig/jsconfig `paths` keys ("@app/*", "utils") → alias bases ("@app", "utils").
+ * @param {string} key
+ * @returns {string}
+ */
+export function aliasBaseFromPathsKey(key) {
+  return key.endsWith('/*') ? key.slice(0, -2) : key;
+}
+
+/** @typedef {import('./types.d.ts').AliasScope} AliasScope */
+
+/**
+ * Which path aliases are in scope for a given file.
+ *
+ * A `paths` map belongs to the tsconfig/jsconfig that declares it and governs
+ * that project's own files -- which is what `tsc` does, and what this
+ * models. One flat workspace-wide set was the earlier shape, and it let ANY
+ * config anywhere under the scanned tree delete a package's evidence in
+ * EVERY file: with output-shaped directory names no longer excluded by name,
+ * a committed `vendor/lib/tsconfig.json` mapping `js-yaml` turned a live
+ * import in `src/` into `not-observed` at high confidence with no evidence
+ * and no diagnostic (sbom-reach commit 95f2b94, round-3 adversarial review).
+ * Narrowing by subtree, rather than by a skip-list of directory names, is the
+ * fix that does not reintroduce name-based reasoning one layer up.
+ *
+ * @type {ReadonlySet<string>}
+ */
+const NO_ALIASES = new Set();
+
+/**
+ * An `AliasScope` that answers the same set everywhere -- tests, and the
+ * empty default.
+ * @param {ReadonlySet<string>} [prefixes]
+ * @returns {AliasScope}
+ */
+export function fixedAliasScope(prefixes = NO_ALIASES) {
+  return { for: () => prefixes };
+}
+
+/**
+ * Accept either shape at an API boundary without making every caller care.
+ * @param {ReadonlySet<string> | AliasScope} aliases
+ * @returns {AliasScope}
+ */
+export function asAliasScope(aliases) {
+  return typeof (/** @type {AliasScope} */ (aliases).for) === 'function'
+    ? /** @type {AliasScope} */ (aliases)
+    : fixedAliasScope(/** @type {ReadonlySet<string>} */ (aliases));
+}

package/src/facts/ts.js

@@ -0,0 +1,47 @@
+// src/facts/ts.js
+// `typescript` is an OPTIONAL peer dependency: the lockfile commands never need
+// it, and a consumer of the package root must not pay for a 10 MB compiler it
+// never loads. It is therefore resolved lazily and synchronously (createRequire,
+// the same pattern `parser.js` uses for `yaml`), the first time a facts module
+// actually parses something, and its absence is a coded error — the CLI maps
+// `TYPESCRIPT_MISSING` to a usage error (exit 2) with an install hint rather
+// than a stack trace.
+//
+// NOTHING here runs at module load. `createRequire` is built inside
+// `loadTypeScript()`, from `__filename` when a CJS bundle defines it and from
+// `import.meta.url` otherwise: esbuild rewrites `import.meta.url` to
+// `undefined` in a CJS bundle, and `createRequire(undefined)` throws
+// `ERR_INVALID_ARG_VALUE` — at import time, as a plain Error no
+// `TYPESCRIPT_MISSING` handler would ever see (adversarial review). Importing
+// the barrel must never throw; only a parse can.
+import { createRequire } from 'node:module';
+import { FactsError } from './errors.js';
+
+/** @type {typeof import('typescript') | undefined} */
+let cached;
+
+/**
+ * The TypeScript compiler API, loaded once.
+ * @returns {typeof import('typescript')}
+ * @throws {FactsError} `TYPESCRIPT_MISSING` when the peer is not installed.
+ */
+export function loadTypeScript() {
+  if (cached) return cached;
+  // `__filename` is only defined in a CommonJS context (a bundle); in ESM the
+  // `typeof` guard keeps the reference from throwing.
+  const anchor = typeof __filename !== 'undefined' ? __filename : import.meta.url;
+  const require = createRequire(anchor);
+  try {
+    cached = /** @type {typeof import('typescript')} */ (require('typescript'));
+  } catch (err) {
+    const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
+    if (code !== 'MODULE_NOT_FOUND' && code !== 'ERR_MODULE_NOT_FOUND') throw err;
+    throw new FactsError(
+      'TYPESCRIPT_MISSING',
+      'import facts need the `typescript` package (an optional peer dependency of @dependably/npm-check), ' +
+        'which is not installed. Install it alongside npm-check: `npm install --save-dev typescript` ' +
+        '(any 5.6+ release).'
+    );
+  }
+  return cached;
+}