@dependably/npm-check 1.10.0 → 1.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dependably/npm-check",
-  "version": "1.10.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",

package/src/facts/collect.js

@@ -95,7 +95,7 @@ export function collectImportFacts(srcDir, options = {}) {
   const relOf = makeRelOf(absSrcDir, realSrcDir);
 
   const workspace = discoverWorkspace(absSrcDir);
-  const resolver = new ModuleResolver(workspace.aliasPrefixes);
+  const resolver = new ModuleResolver(workspace.aliasScope);
 
   /** @type {UnanalyzableEntry[]} */
   const unanalyzable = [];
@@ -127,7 +127,7 @@ export function collectImportFacts(srcDir, options = {}) {
     }
     /** @type {ResolvedSite[]} */
     const sites = result.sites.map((site) => {
-      const pkg = specifierToPackage(site.specifier, workspace.aliasPrefixes);
+      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

package/src/facts/document.js

@@ -109,6 +109,17 @@ export function factsDocument(facts, options = {}) {
       .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
   };

package/src/facts/index.js

@@ -32,5 +32,6 @@ export {
   parsePnpmLockYaml,
   parsePnpmLockYamlGraph
 } from './lockfile-graph.js';
-export { specifierToPackage, aliasBaseFromPathsKey } from './specifier.js';
-export { discoverWorkspace } from './workspace.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';

package/src/facts/resolve.js

@@ -31,6 +31,9 @@
 import { readFileSync, realpathSync, statSync } from 'node:fs';
 import { builtinModules } from 'node:module';
 import { basename, dirname, isAbsolute, join, resolve as pathResolve, sep } from 'node:path';
+import { asAliasScope } from './specifier.js';
+
+/** @typedef {import('./types.d.ts').AliasScope} AliasScope */
 
 /** @typedef {import('./types.d.ts').PackageInfo} PackageInfo */
 /** @typedef {import('./types.d.ts').Resolution} Resolution */
@@ -61,12 +64,16 @@ const NODE_MODULES = 'node_modules';
 
 export class ModuleResolver {
   /**
-   * @param {ReadonlySet<string>} [aliasPrefixes] tsconfig/jsconfig path-alias
-   *   bases; a specifier under one resolves to `{ kind: 'alias' }`.
+   * `aliases` is per-FILE (`AliasScope`), because a tsconfig's `paths`
+   * governs its own project rather than the whole tree. A plain set is still
+   * accepted and means "these everywhere", which is what most callers and
+   * tests want.
+   * @param {ReadonlySet<string> | AliasScope} [aliases] tsconfig/jsconfig
+   *   path-alias bases; a specifier under one resolves to `{ kind: 'alias' }`.
    */
-  constructor(aliasPrefixes = new Set()) {
-    /** @type {ReadonlySet<string>} */
-    this.aliasPrefixes = aliasPrefixes;
+  constructor(aliases = new Set()) {
+    /** @type {AliasScope} */
+    this.aliasScope = asAliasScope(aliases);
     /** @type {Map<string, 'file' | 'dir' | null>} */
     this.statCache = new Map();
     /** @type {Map<string, PackageJson | null>} */
@@ -104,7 +111,7 @@ export class ModuleResolver {
     }
     if (cleaned.startsWith('#')) return this.resolveImportsField(fromFile, cleaned, mode);
 
-    for (const alias of this.aliasPrefixes) {
+    for (const alias of this.aliasScope.for(fromFile)) {
       if (cleaned === alias || cleaned.startsWith(`${alias}/`)) return { kind: 'alias' };
     }
     return this.resolveBare(fromFile, cleaned, mode);

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

@@ -46,3 +46,44 @@ export function specifierToPackage(spec, aliasPrefixes) {
 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/types.d.ts

@@ -112,8 +112,12 @@ export type ResolveMode = 'import' | 'require';
  * packages come back as their own `Resolution` kinds.
  */
 export class ModuleResolver {
-  constructor(aliasPrefixes?: ReadonlySet<string>);
-  readonly aliasPrefixes: ReadonlySet<string>;
+  /**
+   * `aliases` is per-FILE (`AliasScope`), because a tsconfig's `paths`
+   * governs its own project rather than the whole tree. A plain set is still
+   * accepted and means "these everywhere".
+   */
+  constructor(aliases?: ReadonlySet<string> | AliasScope);
   resolve(fromFile: string, specifier: string, mode: ResolveMode): Resolution;
   /**
    * The package a file belongs to, from its path alone: the directory right
@@ -286,23 +290,95 @@ export function specifierToPackage(spec: string, aliasPrefixes: ReadonlySet<stri
 /** tsconfig/jsconfig `paths` keys ("@app/*", "utils") → alias bases ("@app", "utils"). */
 export function aliasBaseFromPathsKey(key: string): string;
 
+/**
+ * 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. One flat
+ * workspace-wide set would let ANY config anywhere under the scanned tree
+ * delete a package's evidence in EVERY file.
+ */
+export interface AliasScope {
+  /** Alias bases in scope for `file`, an absolute path. */
+  for(file: string): ReadonlySet<string>;
+}
+
+/** An `AliasScope` that answers the same set everywhere -- tests, and the empty default. */
+export function fixedAliasScope(prefixes?: ReadonlySet<string>): AliasScope;
+/** Accept either shape at an API boundary without making every caller care. */
+export function asAliasScope(aliases: ReadonlySet<string> | AliasScope): AliasScope;
+
+// ---------------------------------------------------------- sourcescan ----
+
+/**
+ * What an in-process analyzer is allowed to exclude from its first-party
+ * source scan, and how it says so. See `sourcescan.js` for the full
+ * rationale: a directory's NAME is not evidence that the code inside it is
+ * generated -- `.gitignore` is the authority instead.
+ */
+export interface GitignoreLayer {
+  /** Directory the file sits in, relative to srcDir, `/`-joined; `''` for the root one. */
+  dir: string;
+  /** An `ignore` package matcher built from that directory's `.gitignore` content. */
+  matcher: { test(path: string): { ignored: boolean; unignored: boolean } };
+}
+
+/** Every `.gitignore` under `srcDir`, deepest first -- not just the root one. */
+export function loadGitignores(srcDir: string, ignoreDirs: readonly string[]): GitignoreLayer[];
+/** Is `rel` (relative to srcDir, `/`-joined) ignored, by git's own rules? */
+export function isGitignored(layers: readonly GitignoreLayer[], rel: string): boolean;
+/** Drop the absolute paths under `srcDir` that a `.gitignore` in the tree ignores. */
+export function filterGitignored(srcDir: string, layers: readonly GitignoreLayer[], paths: string[]): string[];
+/** Directory names that usually DO hold generated or vendored output; nothing is excluded for being on this list. */
+export const OUTPUT_SHAPED_DIRS: readonly string[];
+/** `OUTPUT_DIR_SCANNED`, or undefined when no such directory was scanned. A NOTE, not a warning. */
+export function outputDirScannedDiagnostic(relPaths: readonly string[], names?: readonly string[]): string | undefined;
+
 // ----------------------------------------------------------- workspace ----
 
 export type DepScope = 'runtime' | 'dev';
 
+/** One tsconfig/jsconfig's own `paths` alias bases and the directory it governs (absolute path). */
+export interface AliasLayer {
+  dir: string;
+  prefixes: string[];
+}
+
 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. */
+  /**
+   * Every tsconfig/jsconfig paths alias base found anywhere in the tree.
+   *
+   * FOR REPORTING ONLY -- never decide a specifier with this. A `paths` map
+   * governs the project that declares it, so use `aliasScope`, which answers
+   * per file.
+   */
   aliasPrefixes: Set<string>;
+  /** Which alias bases apply to a given file -- see `AliasScope`. */
+  aliasScope: AliasScope;
+  /** The raw per-config layers `aliasScope` is built from (absolute directories); carried for JSON serialization. */
+  aliasLayers: AliasLayer[];
+  /**
+   * name -> the manifests that declared it a DEV dependency, `/`-joined and
+   * relative to srcDir, for names no manifest declares runtime.
+   *
+   * A dev claim is one manifest's view, and a manifest's view covers its own
+   * subtree. Recording WHERE the claim came from is what lets a consumer
+   * refuse a vendored tool's `devDependencies` as the reason a package
+   * imported from `src/` is exempt from a build gate.
+   */
+  devDeclaredBy: Map<string, string[]>;
   /** First-party source files, absolute paths, sorted. */
   sourceFiles: string[];
   diagnostics: string[];
 }
 
 export function discoverWorkspace(srcDir: string): Workspace;
+/** Is `rel` (a `/`-joined path) inside the directory of the manifest at `manifestRel`? */
+export function governedByManifest(manifestRel: string, rel: string): boolean;
 
 // ------------------------------------------------------------- collect ----
 
@@ -444,6 +520,16 @@ export interface FactsDocumentBody {
     firstPartyNames: string[];
     depScopes: { name: string; scope: DepScope }[];
     aliasPrefixes: string[];
+    /**
+     * `aliasScope`'s raw per-config layers, JSON-safe: `aliasScope` itself is
+     * a closure and cannot be serialized, so this projects the same
+     * information the live `AliasScope` answers `.for(file)` from -- one
+     * entry per tsconfig/jsconfig that declared `paths`, `dir` relative to
+     * the target and `/`-joined.
+     */
+    aliasScope: { dir: string; prefixes: string[] }[];
+    /** `devDeclaredBy`, JSON-safe: one entry per name with an unresolved dev claim. */
+    devDeclaredBy: { name: string; manifests: string[] }[];
     sourceFiles: number;
     diagnostics: string[];
   };
@@ -482,7 +568,7 @@ export function factsDocument(facts: ImportFacts, options?: { exitCode?: number
 
 // --------------------------------------------------------------- misc ----
 
-export const FACTS_SCHEMA_VERSION: '1.0';
+export const FACTS_SCHEMA_VERSION: '1.1';
 
 export class FactsError extends Error {
   constructor(code: string, message: string);

package/src/facts/version.js

@@ -2,10 +2,15 @@
 // 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.
+// versa. `src/schema.js`'s version is still `1.0`; a field added to the
+// facts document bumps its minor, a renamed or removed one its major. Bumped
+// to `1.1` when `workspace.aliasScope` and `workspace.devDeclaredBy` were
+// added — both are additive, so a consumer already reading `1.0` still
+// parses the document, but can now tell "this producer predates these
+// fields" apart from "no manifest made a dev claim", which is the whole
+// point of tracking the minor at all.
 //
 // 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';
+export const FACTS_SCHEMA_VERSION = '1.1';

package/src/facts/workspace.js

@@ -1,33 +1,50 @@
 // src/facts/workspace.js
 // What the tree under `srcDir` declares about itself: the first-party package
 // names (every package.json's `name`), the dev/runtime scope each manifest
-// gives its dependencies ("runtime anywhere wins" across manifests), the
-// tsconfig/jsconfig `paths` alias bases (specifiers under one are never a
-// package import), and the first-party source files themselves — everything
-// the scan and the module-graph walk take as their starting point.
+// gives its dependencies ("runtime anywhere wins" across manifests, with
+// `devDeclaredBy` tracking WHICH manifest made a dev claim), the
+// tsconfig/jsconfig `paths` alias bases scoped to the subtree of the config
+// that declares them, and the first-party source files themselves -- bounded
+// by `.gitignore`, never by a directory name -- everything the scan and the
+// module-graph walk take as their starting point.
 //
-// Ported from sbom-reach's `packages/analyzer-npm/src/workspace.ts`.
+// Ported from sbom-reach's `packages/analyzer-npm/src/workspace.ts` as it
+// existed after commit 95f2b94 ("fix(npm,pypi): bound the source scan by
+// .gitignore, never by a directory name", GitLab #31).
 import { readFileSync } from 'node:fs';
 import { dirname, join, relative, sep } from 'node:path';
 import fg from 'fast-glob';
-import ignoreFactory from 'ignore';
 import { aliasBaseFromPathsKey } from './specifier.js';
+import { filterGitignored, loadGitignores, outputDirScannedDiagnostic } from './sourcescan.js';
 import { loadTypeScript } from './ts.js';
 
 /** @typedef {import('./types.d.ts').DepScope} DepScope */
 /** @typedef {import('./types.d.ts').Workspace} Workspace */
+/** @typedef {import('./types.d.ts').AliasScope} AliasScope */
+/** @typedef {import('./types.d.ts').AliasLayer} AliasLayer */
 
-const IGNORE_DIRS = [
-  '**/node_modules/**',
-  '**/.git/**',
-  '**/dist/**',
-  '**/build/**',
-  '**/out/**',
-  '**/coverage/**',
-  '**/.next/**',
-  '**/.turbo/**',
-  '**/vendor/**'
-];
+/**
+ * The only directories excluded from the source scan BY NAME.
+ *
+ * Both are universal rather than conventional. `.git` holds no source. And
+ * `node_modules` is not a naming convention at all -- it is the location the
+ * Node resolver defines, and its contents are a DEPENDENCY's own imports,
+ * not first-party code; counting them would make every transitive
+ * dependency look first-party-imported. The module graph walks it
+ * deliberately (`modulegraph.js`), which is a different pass with a
+ * different question.
+ *
+ * Everything else that used to live here -- `dist`, `build`, `out`,
+ * `coverage`, `.next`, `.turbo`, `vendor` -- was a GUESS from a directory
+ * name that the file it excluded was generated output. In a real tree those
+ * names are often source. `.gitignore`, loaded below, is the real authority
+ * on what is generated: a project that builds into `dist/` gitignores
+ * `dist/`.
+ *
+ * Note that dot-directories stay excluded regardless, via the globber's
+ * `dot: false` -- a hidden-directory convention, not a guess about content.
+ */
+const IGNORE_DIRS = ['**/node_modules/**', '**/.git/**'];
 
 const SOURCE_GLOB = '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs,svelte}';
 
@@ -40,15 +57,9 @@ export function discoverWorkspace(srcDir) {
   /** @type {string[]} */
   const diagnostics = [];
 
-  const gitignore = loadGitignore(srcDir);
+  const gitignores = loadGitignores(srcDir, IGNORE_DIRS);
   /** @param {string[]} paths @returns {string[]} */
-  const filterIgnored = (paths) => {
-    if (!gitignore) return paths;
-    return paths.filter((p) => {
-      const rel = relative(srcDir, p).split(sep).join('/');
-      return rel === '' || !gitignore.ignores(rel);
-    });
-  };
+  const filterIgnored = (paths) => filterGitignored(srcDir, gitignores, paths);
 
   const manifestPaths = filterIgnored(
     fg.sync('**/package.json', {
@@ -64,6 +75,9 @@ export function discoverWorkspace(srcDir) {
   const firstPartyNames = new Set();
   /** @type {Map<string, DepScope>} */
   const depScopes = new Map();
+  /** name -> manifests declaring it dev; pruned below for anything declared runtime. */
+  /** @type {Map<string, string[]>} */
+  const devDeclaredBy = new Map();
 
   for (const path of manifestPaths) {
     /** @type {Record<string, unknown>} */
@@ -82,11 +96,20 @@ export function discoverWorkspace(srcDir) {
     }
     for (const name of depNames(json.devDependencies)) {
       if (depScopes.get(name) !== 'runtime') depScopes.set(name, 'dev');
+      devDeclaredBy.set(name, [...(devDeclaredBy.get(name) ?? []), relative(srcDir, path).split(sep).join('/')]);
     }
   }
+  // "Runtime anywhere wins" already decided `depScopes`; drop the dev trail
+  // for anything that ended up runtime, so the map only ever describes a
+  // live claim.
+  const runtimeDeclared = [...devDeclaredBy.keys()].filter((n) => depScopes.get(n) !== 'dev');
+  for (const name of runtimeDeclared) devDeclaredBy.delete(name);
 
   /** @type {Set<string>} */
   const aliasPrefixes = new Set();
+  /** One entry per config file: the directory it governs, and what it declares. */
+  /** @type {AliasLayer[]} */
+  const aliasLayers = [];
   const aliasConfigPaths = filterIgnored(
     fg.sync(['**/tsconfig*.json', '**/jsconfig*.json'], {
       cwd: srcDir,
@@ -121,16 +144,35 @@ export function discoverWorkspace(srcDir) {
           .../** @type {object | undefined} */ (parentConfig.compilerOptions),
           .../** @type {object | undefined} */ (config.compilerOptions)
         },
-        extends: parentConfig.extends
+        extends: /** @type {{extends?: unknown}} */ (parentConfig).extends
       };
       current = parentPath;
     }
     const compilerOptions = /** @type {{ paths?: Record<string, unknown> } | undefined} */ (config.compilerOptions);
     const paths = compilerOptions?.paths;
     if (paths) {
-      for (const key of Object.keys(paths)) aliasPrefixes.add(aliasBaseFromPathsKey(key));
+      /** @type {Set<string>} */
+      const prefixes = new Set();
+      for (const key of Object.keys(paths)) {
+        const base = aliasBaseFromPathsKey(key);
+        prefixes.add(base);
+        aliasPrefixes.add(base);
+      }
+      // Scoped to the directory of the config that was FOUND, not of
+      // whatever it `extends`: a base config supplies the paths, the
+      // project that extends it supplies the files they apply to -- as tsc
+      // does.
+      //
+      // The approximation is CONTAINMENT, and tsc's real answer is
+      // `include` / `files` / `rootDir`. A config that reaches outside its
+      // own directory governs those files in tsc and not here, so their
+      // imports keep naming packages and a legitimate alias is dropped.
+      // That over-reports use -- the loud direction (invariant 1), and the
+      // opposite of the silent suppression this scoping exists to stop.
+      if (prefixes.size > 0) aliasLayers.push({ dir: dirname(path), prefixes: [...prefixes] });
     }
   }
+  const aliasScope = buildAliasScope(aliasLayers);
 
   const sourceFiles = filterIgnored(
     fg.sync(SOURCE_GLOB, {
@@ -142,7 +184,73 @@ export function discoverWorkspace(srcDir) {
     })
   ).sort();
 
-  return { firstPartyNames, depScopes, aliasPrefixes, sourceFiles, diagnostics };
+  // Say it out loud when a directory whose NAME suggests generated output
+  // was scanned anyway, because nothing ignored it. A note, not a warning --
+  // see `outputDirScannedDiagnostic` for why.
+  const outputDirs = outputDirScannedDiagnostic(sourceFiles.map((f) => relative(srcDir, f).split(sep).join('/')));
+  if (outputDirs) diagnostics.push(outputDirs);
+
+  return {
+    firstPartyNames,
+    depScopes,
+    aliasPrefixes,
+    aliasScope,
+    aliasLayers,
+    devDeclaredBy,
+    sourceFiles,
+    diagnostics
+  };
+}
+
+/**
+ * A file is governed by every config at or above its own directory. Nothing
+ * is matched by NAME here: a `vendor/lib/tsconfig.json` is not
+ * special-cased, it simply governs `vendor/lib/`, and the file in `src/`
+ * that a global set used to silence is outside it.
+ *
+ * Memoized per directory -- a tree with one root tsconfig (the common case)
+ * does one prefix walk per directory and then answers from the cache.
+ *
+ * @param {AliasLayer[]} layers directories are ABSOLUTE paths
+ * @returns {AliasScope}
+ */
+function buildAliasScope(layers) {
+  /** @type {ReadonlySet<string>} */
+  const empty = new Set();
+  if (layers.length === 0) return { for: () => empty };
+  /** @type {Map<string, ReadonlySet<string>>} */
+  const cache = new Map();
+  return {
+    for(file) {
+      const dir = dirname(file);
+      const cached = cache.get(dir);
+      if (cached !== undefined) return cached;
+      /** @type {Set<string> | undefined} */
+      let hits;
+      for (const layer of layers) {
+        if (dir !== layer.dir && !dir.startsWith(layer.dir.endsWith(sep) ? layer.dir : `${layer.dir}${sep}`)) {
+          continue;
+        }
+        hits ??= new Set();
+        for (const prefix of layer.prefixes) hits.add(prefix);
+      }
+      const result = hits ?? empty;
+      cache.set(dir, result);
+      return result;
+    }
+  };
+}
+
+/**
+ * Is `rel` (a `/`-joined path) inside the directory of the manifest at `manifestRel`?
+ * @param {string} manifestRel
+ * @param {string} rel
+ * @returns {boolean}
+ */
+export function governedByManifest(manifestRel, rel) {
+  const slash = manifestRel.lastIndexOf('/');
+  if (slash === -1) return true; // root manifest governs the whole tree
+  return rel.startsWith(`${manifestRel.slice(0, slash)}/`);
 }
 
 /**
@@ -154,19 +262,6 @@ function depNames(section) {
   return Object.keys(/** @type {Record<string, unknown>} */ (section)).map((n) => n.toLowerCase());
 }
 
-/**
- * @param {string} srcDir
- * @returns {ReturnType<typeof ignoreFactory> | undefined}
- */
-function loadGitignore(srcDir) {
-  try {
-    const content = readFileSync(join(srcDir, '.gitignore'), 'utf8');
-    return ignoreFactory().add(content);
-  } catch {
-    return undefined;
-  }
-}
-
 /**
  * @param {string} spec
  * @param {string} fromDir