@dependably/npm-check 1.8.0 → 1.10.0

package/src/facts/specifier.js

@@ -0,0 +1,48 @@
+// 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;
+}

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;
+}

package/src/facts/types.d.ts

@@ -0,0 +1,493 @@
+// src/facts/types.d.ts
+// Hand-written declarations for `@dependably/npm-check/facts`. The JS
+// modules under src/facts/ reference these through JSDoc
+// (`@typedef {import('./types.d.ts').X} X`) and are type-checked against
+// them with `npm run typecheck`; consumers get them through the subpath
+// export's `types` condition. Keep every exported runtime symbol declared
+// here too — this file IS the public surface.
+
+// ---------------------------------------------------------------- scan ----
+
+/**
+ * How a source file references a module. The string values are the same
+ * ones sbom-reach's `EvidenceKind` uses for its npm evidence, so a consumer
+ * can carry them through unchanged.
+ */
+export type ImportKind = 'import' | 'require' | 'dynamic-import' | 'export-from' | 'type-only-import';
+
+/** One module reference found in a source file. */
+export interface ImportSite {
+  specifier: string;
+  /** 1-based. */
+  line: number;
+  /** The statement's text, whitespace-collapsed, capped at 200 chars. */
+  snippet: string;
+  kind: ImportKind;
+  /**
+   * Imported/required binding names visible at this site: named-import /
+   * named-export-from ORIGINAL names (`import { a, b as c }` → "a", "b" —
+   * never the local alias), `require()`/dynamic-`import()` destructured
+   * names, and exactly ONE level of property access on a default/namespace
+   * import's local identifier (`_.template(x)` → "template"). Parse-level
+   * only: no type checker, no cross-file aliasing, no chasing past one
+   * property-access level. Absent/empty means "no binding names observed at
+   * this site" — NOT proof nothing was used; see `opaque`.
+   */
+  bindings?: string[];
+  /**
+   * The subset of `bindings` whose local identifier is actually REFERENCED
+   * somewhere in the module body after the declaration. A property-access
+   * binding is a reference by construction. Any occurrence counts (call,
+   * argument, spread, re-export, shorthand property): this is "referenced",
+   * not "called" — over-reporting use is the safe direction. A shadowing
+   * local is deliberately NOT excluded for the same reason. Absent when
+   * nothing was referenced.
+   */
+  referenced?: string[];
+  /**
+   * True when this site's default/namespace binding (or a bare
+   * `export * from` / `export * as ns from`) is used in a way a parse-level
+   * scan cannot resolve to specific property names — assigned, passed as an
+   * argument, spread, exported, returned, computed access, OR called /
+   * constructed / tagged / rendered directly. An opaque site "could use
+   * anything": a consumer must never read it as evidence that some symbol
+   * was NOT used.
+   */
+  opaque?: boolean;
+}
+
+export interface ScanResult {
+  sites: ImportSite[];
+  /** Count of require()/import() calls with non-literal arguments. */
+  dynamicUnknown: number;
+  /**
+   * Set only for `.svelte` files where `<script>` extraction is suspected of
+   * having gone wrong — the extracted text failed to parse, or a
+   * `<script`/`</script>` tag was found outside every span the extraction
+   * accounted for. Sites collected before/around the problem are still
+   * present; their absence for some package is not a clean negative.
+   */
+  parseErrors?: string[];
+}
+
+/**
+ * Parse-only scan of one source file with the TypeScript compiler API.
+ * `fileName` decides the script kind (`.tsx`, `.svelte`, …) and nothing else.
+ * Throws `FactsError` (`TYPESCRIPT_MISSING`) when `typescript` is not installed.
+ */
+export function scanSource(fileName: string, content: string): ScanResult;
+
+// ------------------------------------------------------------- resolve ----
+
+export interface PackageInfo {
+  /** The name from the package's own package.json (falls back to the directory name). */
+  name: string;
+  /**
+   * The node_modules directory name (scope included). Differs from `name`
+   * for an aliased install (`"string-width-cjs": "npm:string-width@^4"`).
+   */
+  dirName: string;
+  version: string;
+  /** Absolute path of the package root — the directory directly under node_modules. */
+  root: string;
+}
+
+export type Resolution =
+  /** A source file the walker should parse. */
+  | { kind: 'file'; path: string; pkg: PackageInfo | undefined }
+  /** A non-code file (JSON, WASM, CSS, native addon…) — a real edge, nothing to parse. */
+  | { kind: 'asset'; path: string; pkg: PackageInfo | undefined }
+  | { kind: 'builtin' }
+  /** A first-party path alias (tsconfig paths). */
+  | { kind: 'alias' }
+  | { kind: 'unresolved'; reason: string };
+
+export type ResolveMode = 'import' | 'require';
+
+/**
+ * A Node-style module resolver: symlink-aware (pnpm's `.pnpm` layout),
+ * `exports`/`imports` maps with import-vs-require conditions, `main`,
+ * `module`, `index.*`, `.js`→`.ts` probing, builtins. Reports rather than
+ * guesses: aliases, `.d.ts`-only targets, blocked exports and uninstalled
+ * packages come back as their own `Resolution` kinds.
+ */
+export class ModuleResolver {
+  constructor(aliasPrefixes?: ReadonlySet<string>);
+  readonly aliasPrefixes: ReadonlySet<string>;
+  resolve(fromFile: string, specifier: string, mode: ResolveMode): Resolution;
+  /**
+   * The package a file belongs to, from its path alone: the directory right
+   * after the LAST `node_modules/` segment (two for a scope); undefined for
+   * a first-party path.
+   */
+  packageOf(file: string): PackageInfo | undefined;
+}
+
+/** The package root for a path inside node_modules; undefined for a first-party path. */
+export function packageRootOf(file: string): string | undefined;
+
+/**
+ * Resolves a subpath (or `#import` key) against a package.json `exports` /
+ * `imports` value. Returns the target string, `null` when the map explicitly
+ * blocks it, or `undefined` when nothing matched.
+ */
+export function resolveExports(map: unknown, subpath: string, conditions: ReadonlySet<string>): string | null | undefined;
+
+// --------------------------------------------------------- modulegraph ----
+
+export interface GraphImporter {
+  /** Absolute path of the importing file. */
+  file: string;
+  line: number;
+  snippet: string;
+  kind: ImportKind;
+  bindings?: string[];
+  referenced?: string[];
+  opaque?: boolean;
+  /** Key of the package the importing file belongs to; undefined for first-party code. */
+  fromPackage?: string;
+}
+
+export interface ReachedPackage {
+  /**
+   * `${name}@${version}\0${root}` — one entry per INSTALLED COPY, since two
+   * copies of one version can differ only by location.
+   */
+  key: string;
+  name: string;
+  /** See `PackageInfo.dirName`. */
+  dirName: string;
+  version: string;
+  root: string;
+  /**
+   * Every import site from OUTSIDE this package that resolved into it —
+   * first-party and other packages' files alike; a package's own internal
+   * relative imports are traversed but never listed here.
+   */
+  importers: GraphImporter[];
+  /**
+   * The chain of package keys along which this package was FIRST reached
+   * (breadth-first over files from the roots, so short in practice, not a
+   * proven shortest package chain), this package last.
+   */
+  chain: string[];
+  /** A file in this package has a non-literal require()/import(). */
+  dynamic: boolean;
+  /** A file in this package was not parsed (size cap, unreadable) or has a dangling relative import; its edges are unknown. */
+  incomplete: boolean;
+}
+
+export interface ModuleGraph {
+  reached: Map<string, ReachedPackage>;
+  /** `${name}@${version}` (lower-cased name, both `name` and `dirName` spellings) → every reached copy of it. */
+  byNameVersion: Map<string, ReachedPackage[]>;
+  /** lower-cased name (both spellings) → every reached copy, any version. */
+  byName: Map<string, ReachedPackage[]>;
+  filesParsed: number;
+  filesSkippedForSize: number;
+  /** Files that resolved after the budget was hit and were therefore not parsed. */
+  filesPastBudget: number;
+  unresolved: number;
+  /**
+   * Bare specifiers the resolver could not follow, by the PACKAGE NAME they
+   * name (lower-cased) → where and why (at most five sites per name).
+   */
+  unresolvedByName: Map<string, { file: string; reason: string }[]>;
+  /** The file budget stopped the walk; packages past the frontier are unknown, not absent. */
+  truncated: boolean;
+  /** `name@version` of packages flagged dynamic or incomplete (deduplicated, sorted). */
+  weakPackages: string[];
+  /** node_modules files that resolved but were not parsed (unreadable, oversized), absolute paths. */
+  unanalyzable: { file: string; reason: string }[];
+}
+
+export interface WalkOptions {
+  /** Absolute path; used to relativize file names handed to `scan`. */
+  srcDir: string;
+  resolver: ModuleResolver;
+  /** First-party files with their already-computed scans — the roots. */
+  roots: Iterable<{ file: string; scan: ScanResult }>;
+  /** Parses a node_modules file. Injected so the caller's scanner (and any caching) is reused. */
+  scan: (relFile: string, content: string) => ScanResult;
+  /** Stop after this many node_modules files have been parsed. Default `DEFAULT_MAX_FILES`. */
+  maxFiles?: number;
+  /** Skip (and flag) files larger than this many bytes. Default `DEFAULT_MAX_FILE_BYTES`. */
+  maxFileBytes?: number;
+}
+
+export const DEFAULT_MAX_FILES: number;
+export const DEFAULT_MAX_FILE_BYTES: number;
+export function packageKey(pkg: PackageInfo): string;
+export function walkModuleGraph(opts: WalkOptions): ModuleGraph;
+
+// ------------------------------------------------------ lockfile-graph ----
+
+export interface DiscoveredPackage {
+  name: string;
+  version: string;
+  /**
+   * SPDX license expression verbatim from the lockfile entry (npm mirrors
+   * the package's own `license` field). Absent when the entry never carried
+   * one; never guessed. pnpm-lock.yaml carries no license data at all.
+   */
+  license?: string;
+  /**
+   * Whole-tree dev/runtime declaration, tri-state: `true` — reachable ONLY
+   * through devDependencies edges; `false` — some path reaches it without a
+   * dev edge ("runtime anywhere wins"); absent — the lockfile says nothing.
+   * package-lock.json states this for EVERY entry (npm's per-entry flags are
+   * a computed answer); pnpm-lock.yaml only for importer-direct packages.
+   */
+  devDeclared?: boolean;
+  /**
+   * "optional" only, when npm asserts the package is reachable EXCLUSIVELY
+   * through optionalDependencies. Absent otherwise — never asserted.
+   */
+  scope?: 'optional';
+}
+
+/** One dependency edge; both ends are "name@version" keys matching a `DiscoveredPackage`. */
+export interface DependencyEdge {
+  from: string;
+  to: string;
+}
+
+export interface LockfileGraph {
+  packages: DiscoveredPackage[];
+  /** "name@version" keys the project's own package.json directly depends on. */
+  rootDependencies: string[];
+  /** Edges among the resolved closure; does not include root-level edges. */
+  edges: DependencyEdge[];
+}
+
+/** `discoverLockfileGraphs`' result: every lockfile under the tree merged into one graph. */
+export interface LockfileDiscovery extends LockfileGraph {
+  /** Absolute paths of the lockfiles that parsed, in the order they were merged. */
+  files: string[];
+  /** `unparseable … at <rel>: <why>` per lockfile that failed; `NO_LOCKFILE: …` when none was found. */
+  diagnostics: string[];
+}
+
+export function mergeDiscovered(into: DiscoveredPackage, other: DiscoveredPackage): void;
+export function parsePackageLockJsonGraph(path: string): LockfileGraph;
+export function parsePackageLockJson(path: string): DiscoveredPackage[];
+export function parsePnpmLockYamlGraph(path: string): LockfileGraph;
+export function parsePnpmLockYaml(path: string): DiscoveredPackage[];
+export function discoverLockfileGraphs(srcDir: string): LockfileDiscovery;
+
+// ----------------------------------------------------------- specifier ----
+
+/**
+ * The npm package a specifier names (lower-cased), or undefined for a
+ * relative/absolute path, a builtin, a `#imports` key, a data:/file: URL, or
+ * a tsconfig/jsconfig path alias.
+ */
+export function specifierToPackage(spec: string, aliasPrefixes: ReadonlySet<string>): string | undefined;
+/** tsconfig/jsconfig `paths` keys ("@app/*", "utils") → alias bases ("@app", "utils"). */
+export function aliasBaseFromPathsKey(key: string): string;
+
+// ----------------------------------------------------------- workspace ----
+
+export type DepScope = 'runtime' | 'dev';
+
+export interface Workspace {
+  /** Names of package.json manifests found in the tree = first-party packages (lower-cased). */
+  firstPartyNames: Set<string>;
+  /** name → runtime|dev; "runtime anywhere wins" across all manifests. */
+  depScopes: Map<string, DepScope>;
+  /** tsconfig/jsconfig paths alias bases; specifiers matching these are never package imports. */
+  aliasPrefixes: Set<string>;
+  /** First-party source files, absolute paths, sorted. */
+  sourceFiles: string[];
+  diagnostics: string[];
+}
+
+export function discoverWorkspace(srcDir: string): Workspace;
+
+// ------------------------------------------------------------- collect ----
+
+/** An `ImportSite` with what it names and what it loads. */
+export interface ResolvedSite extends ImportSite {
+  /** The package the specifier names (see `specifierToPackage`); undefined for a non-package import. */
+  package: string | undefined;
+  /**
+   * The installed package copy the specifier resolved INTO, when it did.
+   * A fact, not a match: compare `name`/`dirName` against `package` before
+   * treating it as "the installed copy of the package this site names".
+   */
+  installed?: { name: string; dirName: string; version: string; root: string };
+}
+
+export interface FirstPartyFile {
+  /** Absolute path. */
+  file: string;
+  /** `srcDir`-relative POSIX path (realpath-aware). */
+  rel: string;
+  scan: ScanResult;
+  sites: ResolvedSite[];
+}
+
+export type UnanalyzableKind =
+  /** A first-party source file that could not be read; its imports are unknown. */
+  | 'file'
+  /** A first-party `.svelte` file whose `<script>` extraction reported a problem; sites are still present. */
+  | 'file-partial'
+  /** A node_modules file the walk resolved but did not parse (unreadable, oversized). */
+  | 'node-modules-file'
+  /** The walk stopped on its file budget; everything past the frontier is unobserved. */
+  | 'walk';
+
+export interface UnanalyzableEntry {
+  /** `srcDir`-relative POSIX path (or `node_modules` for a `walk` entry). */
+  file: string;
+  kind: UnanalyzableKind;
+  reason: string;
+}
+
+export interface CollectOptions {
+  /** Follow imports through node_modules. Default true. */
+  moduleGraph?: boolean;
+  maxFiles?: number;
+  maxFileBytes?: number;
+  /** The scanner to use for first-party AND node_modules files. Default `scanSource`. */
+  scan?: (relFile: string, content: string) => ScanResult;
+}
+
+export interface ImportFacts {
+  /** Absolute. */
+  srcDir: string;
+  /** `realpath(srcDir)`, or `srcDir` when that fails. */
+  realSrcDir: string;
+  workspace: Workspace;
+  files: FirstPartyFile[];
+  /** Undefined when `moduleGraph: false`. */
+  graph: ModuleGraph | undefined;
+  /** The walk reached nothing, something was unresolved, and there is no `node_modules` directory. */
+  nodeModulesMissing: boolean;
+  lockfile: LockfileDiscovery;
+  /** ALWAYS present (empty when nothing was skipped). Non-empty means the search was incomplete. */
+  unanalyzable: UnanalyzableEntry[];
+  /** Sum of `dynamicUnknown` over first-party files. */
+  dynamicUnknownTotal: number;
+}
+
+export function collectImportFacts(srcDir: string, options?: CollectOptions): ImportFacts;
+/**
+ * Realpath-aware relativizer producing POSIX paths: of the two spellings of
+ * `srcDir` (as given, realpath), the one the file sits under with fewer `..`
+ * segments wins. `srcDir` itself relativizes to `''`, as sbom-reach's `relOf`.
+ */
+export function makeRelOf(srcDir: string, realSrcDir: string): (file: string) => string;
+
+// ------------------------------------------------------------ document ----
+
+export interface FactsSummary {
+  /** First-party source files the workspace discovery found. */
+  scanned: number;
+  /** Of those, files read and parsed — the length of `imports`. */
+  analyzed: number;
+  /** Entries in `unanalyzable`, of every kind. Non-zero means the search was incomplete. */
+  unanalyzable: number;
+  /** Import sites summed over every first-party file. */
+  imports: number;
+  moduleGraph: { filesParsed: number; reached: number; unresolved: number; truncated: boolean };
+  /** The process exit code, `0` for every successful scan. */
+  exitCode: number;
+}
+
+export interface DocumentSite {
+  specifier: string;
+  package: string | null;
+  line: number;
+  snippet: string;
+  kind: ImportKind;
+  bindings: string[];
+  referenced: string[];
+  opaque: boolean;
+  installed?: { name: string; dirName: string; version: string; root: string };
+}
+
+export interface DocumentFile {
+  file: string;
+  dynamicUnknown: number;
+  parseErrors: string[];
+  sites: DocumentSite[];
+}
+
+export interface DocumentImporter {
+  file: string;
+  line: number;
+  snippet: string;
+  kind: ImportKind;
+  bindings: string[];
+  referenced: string[];
+  opaque: boolean;
+  fromPackage: string | null;
+}
+
+export interface DocumentReachedPackage {
+  /** `${name}@${version}\0${relative root}`. */
+  key: string;
+  name: string;
+  dirName: string;
+  version: string;
+  root: string;
+  chain: string[];
+  dynamic: boolean;
+  incomplete: boolean;
+  importers: DocumentImporter[];
+}
+
+export interface FactsDocumentBody {
+  summary: FactsSummary;
+  workspace: {
+    firstPartyNames: string[];
+    depScopes: { name: string; scope: DepScope }[];
+    aliasPrefixes: string[];
+    sourceFiles: number;
+    diagnostics: string[];
+  };
+  imports: DocumentFile[];
+  moduleGraph: {
+    enabled: boolean;
+    filesParsed: number;
+    filesSkippedForSize: number;
+    unresolved: number;
+    truncated: boolean;
+    nodeModulesMissing: boolean;
+    weakPackages: string[];
+    reached: DocumentReachedPackage[];
+    unresolvedByName: { package: string; sites: { file: string; reason: string }[] }[];
+  };
+  lockfile: {
+    files: string[];
+    packages: DiscoveredPackage[];
+    rootDependencies: string[];
+    edges: DependencyEdge[];
+    diagnostics: string[];
+  };
+  unanalyzable: UnanalyzableEntry[];
+}
+
+/** The full document as `npm-check imports --format json` prints it. */
+export interface FactsDocument extends FactsDocumentBody {
+  tool: 'npm-check';
+  toolVersion: string;
+  schemaVersion: string;
+  documentType: 'imports';
+  target: string;
+}
+
+export function factsDocument(facts: ImportFacts, options?: { exitCode?: number }): FactsDocumentBody;
+
+// --------------------------------------------------------------- misc ----
+
+export const FACTS_SCHEMA_VERSION: '1.0';
+
+export class FactsError extends Error {
+  constructor(code: string, message: string);
+  code: string;
+}
+
+/** The TypeScript compiler API, loaded once; throws `FactsError` (`TYPESCRIPT_MISSING`) when absent. */
+export function loadTypeScript(): typeof import('typescript');

package/src/facts/version.js

@@ -0,0 +1,11 @@
+// src/facts/version.js
+// The import-facts document's schema version — a SEPARATE version line from
+// `src/schema.js`'s `SCHEMA_VERSION` (the findings envelope's), so a change
+// to the facts shape never implies one to the findings envelope and vice
+// versa. Both are `1.0` today; a field added to the facts document bumps its
+// minor, a renamed or removed one its major.
+//
+// A dependency-free leaf on purpose: `src/schema.js` (loaded by every
+// lockfile command) imports THIS file to stamp `buildFactsEnvelope`, and the
+// facts barrel re-exports it — neither side pulls the other's imports in.
+export const FACTS_SCHEMA_VERSION = '1.0';