@proteinjs/reflection-build 2.0.2 → 2.1.0

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/test/Fs.getFilePathsMatchingGlob.test.ts

@@ -0,0 +1,70 @@
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { Fs } from '../src/Fs';
+
+/**
+ * Regression tests for the `Fs` glob helpers: the ignore patterns must PRUNE excluded
+ * directories, not merely filter them out of the results.
+ *
+ * `Fs` used to fold the base directory into one absolute pattern (`<dir>/<glob>`) and hand
+ * fast-glob the ignore list, which fast-glob then matched against the ABSOLUTE entry path. A
+ * globstar does not cross a dot-segment, so whenever the base path itself contained a
+ * dot-directory (`~/.n3xa/workspaces/<name>` — the default local workspaces root — or a
+ * `.scratch` estate) the ignore list matched nothing: the walk entered every node_modules/dist
+ * and followed the workspace symlinks inside them. On a materialized metarepo (70+
+ * node_modules trees) that is millions of entries held in fast-glob's unique-index, and the
+ * dev-skill Glob of every package.json exhausted a 12G heap three times running (2026-09-02).
+ * Matching relative to `cwd` keeps the ignore list and the entry paths in the same frame, so
+ * the prune holds under any base path.
+ *
+ * The oracle: an unreadable directory inside node_modules, under a dot-directory base path.
+ * A walk that enters node_modules hits EACCES, which fast-glob treats as fatal, and the call
+ * rejects; a pruned walk never sees it and resolves.
+ */
+describe('Fs glob helpers prune ignored directories under a dot-directory base path', () => {
+  const IGNORE = ['**/node_modules/**', '**/dist/**'];
+  let root: string;
+  let locked: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), '.fs-glob-prune-'));
+    locked = path.join(root, 'node_modules', 'dep', 'locked');
+    await fs.mkdir(locked, { recursive: true });
+    await fs.mkdir(path.join(root, 'packages', 'pkg', 'src'), { recursive: true });
+    await fs.mkdir(path.join(root, 'dist'), { recursive: true });
+    await fs.writeFile(path.join(root, 'package.json'), '{}');
+    await fs.writeFile(path.join(root, 'packages', 'pkg', 'package.json'), '{}');
+    await fs.writeFile(path.join(root, 'packages', 'pkg', 'src', 'b.ts'), '');
+    await fs.writeFile(path.join(root, 'node_modules', 'dep', 'package.json'), '{}');
+    await fs.writeFile(path.join(root, 'dist', 'out.js'), '');
+    await fs.chmod(locked, 0o000);
+  });
+
+  afterEach(async () => {
+    await fs.chmod(locked, 0o755).catch(() => undefined);
+    await fs.rm(root, { recursive: true, force: true });
+  });
+
+  const relative = (paths: string[]) => paths.map((p) => path.relative(root, p)).sort();
+
+  // chmod 000 does not stop root; the oracle is meaningless there.
+  const asRoot = typeof process.getuid === 'function' && process.getuid() === 0;
+  const it = asRoot ? test.skip : test;
+
+  it('getFilePathsMatchingGlob never enters node_modules, returns absolute paths', async () => {
+    const out = await Fs.getFilePathsMatchingGlob(root, '**/package.json', IGNORE);
+    expect(out.every((p) => path.isAbsolute(p))).toBe(true);
+    expect(relative(out)).toEqual(['package.json', 'packages/pkg/package.json']);
+  });
+
+  it('getFilePathsMatchingGlob: a trailing separator on the directory changes nothing', async () => {
+    const out = await Fs.getFilePathsMatchingGlob(root + path.sep, '**/package.json', IGNORE);
+    expect(relative(out)).toEqual(['package.json', 'packages/pkg/package.json']);
+  });
+
+  it('getFilePaths walks the whole tree except the ignored directories', async () => {
+    const out = await Fs.getFilePaths(root, IGNORE);
+    expect(relative(out)).toEqual(['package.json', 'packages/pkg/package.json', 'packages/pkg/src/b.ts']);
+  });
+});

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/test/PackageUtil.getLocalPackageMap.test.ts

@@ -0,0 +1,107 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import { PackageUtil } from '../src/PackageUtil';
+
+/**
+ * Regression tests for PackageUtil.getLocalPackageMap — workspace package discovery.
+ *
+ * The important property: discovery is a BOUNDED walk. It must not descend into
+ * hidden (dot-prefixed) directories, `node_modules`, or `dist`, and must never
+ * follow symlinks. The prior glob-based implementation violated all three at
+ * once in one spot: micromatch's default `dot: false` makes a leading `**` in
+ * an ignore pattern refuse to cross dot-segments, so beneath a hidden directory
+ * (e.g. a `.scratch/` full of throwaway checkouts) the
+ * `['**\/node_modules/**', '**\/dist/**']` ignores matched nothing while the
+ * walker still descended and followed symlinks — an unbounded traversal that
+ * OOMed every workspace command regardless of heap size.
+ */
+describe('PackageUtil.getLocalPackageMap — bounded discovery', () => {
+  let workspaceRoot: string;
+
+  beforeEach(async () => {
+    workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pkg-discovery-'));
+  });
+
+  afterEach(async () => {
+    if (workspaceRoot) {
+      await fs.rm(workspaceRoot, { recursive: true, force: true }).catch(() => {
+        /* ignore */
+      });
+    }
+  });
+
+  const writePackageJson = async (relDir: string, name: string) => {
+    const dir = path.join(workspaceRoot, relDir);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'package.json'), JSON.stringify({ name, version: '1.0.0' }, null, 2));
+  };
+
+  /**
+   * The incident signature, compressed: a hidden directory containing a
+   * checkout whose `node_modules` holds symlinks back to the checkout root.
+   * The old glob walker descended into `.scratch` (hidden dirs were not
+   * pruned), its node_modules ignore was dead under the dot-segment
+   * (micromatch `dot: false`), and it followed the symlinks — several cycle
+   * links give the expansion a branching factor, so the path space grows
+   * combinatorially (`loopN/node_modules/loopM/...`) and the walk allocates
+   * unboundedly, exactly the OOM every workspace command hit. Bounded
+   * discovery never enters `.scratch` at all, so this returns instantly.
+   */
+  it('does not descend into hidden directories (unbounded-traversal incident repro)', async () => {
+    await writePackageJson('.', 'root');
+    await writePackageJson('packages/a', '@test/a');
+    await writePackageJson('.scratch/checkout/packages/b', '@test/b');
+    const checkoutDir = path.join(workspaceRoot, '.scratch', 'checkout');
+    await fs.mkdir(path.join(checkoutDir, 'node_modules'), { recursive: true });
+    for (let i = 0; i < 4; i++) {
+      await fs.symlink(checkoutDir, path.join(checkoutDir, 'node_modules', `loop${i}`));
+    }
+
+    const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+
+    expect(Object.keys(packageMap).sort()).toEqual(['@test/a', 'root']);
+  }, 10000);
+
+  it('does not follow symlinked directories', async () => {
+    await writePackageJson('packages/a', '@test/a');
+    // A package OUTSIDE the workspace, reachable only via symlink — the old
+    // walker followed the link and admitted @test/outside as a member.
+    const outsideDir = await fs.mkdtemp(path.join(os.tmpdir(), 'pkg-outside-'));
+    try {
+      await fs.mkdir(path.join(outsideDir, 'c'), { recursive: true });
+      await fs.writeFile(
+        path.join(outsideDir, 'c', 'package.json'),
+        JSON.stringify({ name: '@test/outside', version: '1.0.0' })
+      );
+      await fs.symlink(path.join(outsideDir, 'c'), path.join(workspaceRoot, 'packages', 'linked'));
+
+      const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+
+      expect(Object.keys(packageMap)).toEqual(['@test/a']);
+    } finally {
+      await fs.rm(outsideDir, { recursive: true, force: true });
+    }
+  });
+
+  it('does not descend into node_modules or dist', async () => {
+    await writePackageJson('packages/a', '@test/a');
+    await writePackageJson('packages/a/node_modules/dep', '@test/dep');
+    await writePackageJson('packages/a/dist', '@test/dist-artifact');
+
+    const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+
+    expect(Object.keys(packageMap)).toEqual(['@test/a']);
+  });
+
+  it('survives a symlink cycle in the open (non-hidden) tree', async () => {
+    await writePackageJson('packages/a', '@test/a');
+    // Symlink from inside a package back to the workspace root — a cycle the
+    // old walker expanded path-by-path until the kernel refused to resolve it.
+    await fs.symlink(workspaceRoot, path.join(workspaceRoot, 'packages', 'a', 'back-to-root'));
+
+    const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+
+    expect(Object.keys(packageMap)).toEqual(['@test/a']);
+  });
+});

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/test/PackageUtil.pathKeyedIdentity.test.ts

@@ -0,0 +1,169 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import { PackageUtil } from '../src/PackageUtil';
+
+/**
+ * Regression tests for path-keyed package identity (metarepo issue #75).
+ *
+ * Every workspace root in the metarepo is named `root` — the metarepo root, the app root, and
+ * each nested lerna root (proteinjs, util, build, ...). Package IDENTITY must therefore be the
+ * package.json path, never the name: a name-keyed discovery map silently drops all but one of
+ * the same-named packages, and closure computation seeded from a shared name-keyed graph node
+ * conflates their dependencies.
+ *
+ * Live failure this reproduces: the app root (named `root`, declaring a registry dep on
+ * @proteinjs/build) collided with the metarepo root in the name-keyed packageMap and was
+ * additionally skipped by symlink-workspace's `root` skip — so its node_modules kept a STALE
+ * REGISTRY copy of @proteinjs/build (carrying an old @proteinjs/util-node) indefinitely, and
+ * the dev-server OOM persisted after the workspace fix had shipped.
+ *
+ * Fixture shape (mirrors the metarepo): two packages BOTH named `root` with DIFFERENT deps,
+ * plus regular workspace packages. Each root's closure and symlinks must derive from its OWN
+ * declarations.
+ */
+describe('PackageUtil — path-keyed package identity (same-named packages)', () => {
+  let workspaceRoot: string;
+
+  beforeEach(async () => {
+    workspaceRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'pkg-identity-'));
+  });
+
+  afterEach(async () => {
+    if (workspaceRoot) {
+      await fs.rm(workspaceRoot, { recursive: true, force: true }).catch(() => {
+        /* ignore */
+      });
+    }
+  });
+
+  /** Write a package.json and return its absolute file path. */
+  const writePackageJson = async (
+    relDir: string,
+    name: string,
+    deps: Record<string, string> = {},
+    devDeps: Record<string, string> = {}
+  ): Promise<string> => {
+    const dir = path.join(workspaceRoot, relDir);
+    await fs.mkdir(dir, { recursive: true });
+    const pkgPath = path.join(dir, 'package.json');
+    await fs.writeFile(
+      pkgPath,
+      JSON.stringify({ name, version: '1.0.0', dependencies: deps, devDependencies: devDeps }, null, 2)
+    );
+    return pkgPath;
+  };
+
+  /**
+   * The metarepo shape: metarepo root and app root are BOTH named `root`, with different
+   * workspace deps. `@test/build` itself depends on `@test/util-node` (the live transitive
+   * chain that carried the stale code).
+   */
+  const writeMetarepoFixture = async () => {
+    const metarepoRootPath = await writePackageJson('.', 'root', {}, { '@test/build': '^1.0.0' });
+    const appRootPath = await writePackageJson('packages/app', 'root', {}, { '@test/app-lib': '^1.0.0' });
+    const buildPath = await writePackageJson('packages/tools/build', '@test/build', {
+      '@test/util-node': '^1.0.0',
+    });
+    const utilNodePath = await writePackageJson('packages/tools/util-node', '@test/util-node');
+    const appLibPath = await writePackageJson('packages/app/packages/app-lib', '@test/app-lib');
+    return { metarepoRootPath, appRootPath, buildPath, utilNodePath, appLibPath };
+  };
+
+  test('discovery retains every same-named package, path-keyed', async () => {
+    const { metarepoRootPath, appRootPath } = await writeMetarepoFixture();
+
+    const packagePathMap = await PackageUtil.getLocalPackagePathMap(workspaceRoot);
+
+    // Both `root`-named packages are distinct entries under their own package.json paths.
+    expect(packagePathMap[metarepoRootPath]?.name).toBe('root');
+    expect(packagePathMap[appRootPath]?.name).toBe('root');
+    expect(Object.keys(packagePathMap)).toHaveLength(5);
+
+    // Workspace metadata carries the same collision-free map; the name-keyed index still
+    // resolves real (unique) dependency names.
+    const metadata = await PackageUtil.getWorkspaceMetadata(workspaceRoot);
+    expect(Object.keys(metadata.packagePathMap)).toHaveLength(5);
+    expect(metadata.packageMap['@test/build'].filePath).toBe(
+      path.join(workspaceRoot, 'packages/tools/build/package.json')
+    );
+  });
+
+  test('transitive closure derives from the given package instance, not a shared name-keyed node', async () => {
+    const { metarepoRootPath, appRootPath } = await writeMetarepoFixture();
+    const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+
+    // Construct the LocalPackage records from disk truth (discovery may or may not retain
+    // both same-named packages in a name-keyed map — closure must be correct regardless of
+    // which instance we hand it).
+    const metarepoRoot = {
+      name: 'root',
+      filePath: metarepoRootPath,
+      packageJson: JSON.parse(await fs.readFile(metarepoRootPath, 'utf-8')),
+    };
+    const appRoot = {
+      name: 'root',
+      filePath: appRootPath,
+      packageJson: JSON.parse(await fs.readFile(appRootPath, 'utf-8')),
+    };
+
+    const metarepoClosure = await PackageUtil.getTransitiveWorkspaceDependencies(metarepoRoot, packageMap);
+    const appClosure = await PackageUtil.getTransitiveWorkspaceDependencies(appRoot, packageMap);
+
+    // The metarepo root declares @test/build (which pulls @test/util-node) — and nothing else.
+    expect(metarepoClosure.sort()).toEqual(['@test/build', '@test/util-node']);
+    // The app root declares @test/app-lib — and nothing else. A name-keyed traversal seeded
+    // from the shared `root` node returns the OTHER root's deps here.
+    expect(appClosure.sort()).toEqual(['@test/app-lib']);
+  });
+
+  test('symlinkDependencies links each same-named consumer to ITS OWN workspace closure', async () => {
+    const { metarepoRootPath, appRootPath } = await writeMetarepoFixture();
+    const packageMap = await PackageUtil.getLocalPackageMap(workspaceRoot);
+    const metarepoRoot = {
+      name: 'root',
+      filePath: metarepoRootPath,
+      packageJson: JSON.parse(await fs.readFile(metarepoRootPath, 'utf-8')),
+    };
+    const appRoot = {
+      name: 'root',
+      filePath: appRootPath,
+      packageJson: JSON.parse(await fs.readFile(appRootPath, 'utf-8')),
+    };
+
+    await PackageUtil.symlinkDependencies(metarepoRoot, packageMap);
+    await PackageUtil.symlinkDependencies(appRoot, packageMap);
+
+    // Metarepo root gets its own closure: build + util-node, NOT app-lib.
+    const metarepoNodeModules = path.join(workspaceRoot, 'node_modules');
+    await expectSymlinkTo(
+      path.join(metarepoNodeModules, '@test/build'),
+      path.join(workspaceRoot, 'packages/tools/build')
+    );
+    await expectSymlinkTo(
+      path.join(metarepoNodeModules, '@test/util-node'),
+      path.join(workspaceRoot, 'packages/tools/util-node')
+    );
+    await expectAbsent(path.join(metarepoNodeModules, '@test/app-lib'));
+
+    // App root gets ITS closure: app-lib only, NOT the metarepo root's build chain.
+    const appNodeModules = path.join(workspaceRoot, 'packages/app/node_modules');
+    await expectSymlinkTo(
+      path.join(appNodeModules, '@test/app-lib'),
+      path.join(workspaceRoot, 'packages/app/packages/app-lib')
+    );
+    await expectAbsent(path.join(appNodeModules, '@test/build'));
+  });
+
+  const expectSymlinkTo = async (linkPath: string, expectedTargetDir: string) => {
+    const stat = await fs.lstat(linkPath).catch(() => undefined);
+    expect(stat?.isSymbolicLink() ?? false).toBe(true);
+    const resolved = await fs.realpath(linkPath);
+    expect(resolved).toBe(await fs.realpath(expectedTargetDir));
+  };
+
+  const expectAbsent = async (linkPath: string) => {
+    const stat = await fs.lstat(linkPath).catch(() => undefined);
+    expect(stat).toBeUndefined();
+  };
+});

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/test/WorkspaceDeclaration.test.ts

@@ -0,0 +1,174 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import * as os from 'os';
+import { PackageUtil } from '../src/PackageUtil';
+import { WorkspaceDeclaration, WorkspaceDeclarationError } from '../src/WorkspaceDeclaration';
+
+/**
+ * Workspace membership comes from the DECLARATION, never from a crawl (n3xah/app Deploy to Test
+ * run 33747781291, 2026-09-03): the scanner crawled every package.json under the app and keyed
+ * them by name, so CI fixture trees whose package.json files reused the app's own package names
+ * (`@n3xa/app-common/-server/-ui` under scripts/ci/fixtures) shadowed the real packages — walk
+ * order put the fixtures last, they had no build script, and build-workspace reported "1 package
+ * in workspace" (ops/error-bridge), shipping an image with no packages/server/dist.
+ *
+ * The rules pinned here:
+ *  - a directory holding lerna.json `packages` (or a root package.json `workspacePackages`) is a
+ *    workspace ROOT; its members are exactly what it declares, and it OWNS its subtree — nothing
+ *    undeclared beneath it is a member, however the tree is walked from above;
+ *  - a declared literal path with no package.json is a hard error naming the declaration;
+ *  - two leaf packages sharing a name is a hard error naming both paths (roots — the containers
+ *    every metarepo names `root` — are identified by path and exempt);
+ *  - an undeclared tree still crawls (bounded: no hidden dirs, node_modules, dist, symlinks), and
+ *    hands every declared root it meets to that root's declaration.
+ */
+describe('WorkspaceDeclaration — membership is declared, never crawled', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), 'ws-decl-')));
+  });
+
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => undefined);
+  });
+
+  const writeJson = async (relPath: string, json: unknown) => {
+    const filePath = path.join(root, relPath);
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, JSON.stringify(json, null, 2));
+    return filePath;
+  };
+  const writePackage = (relDir: string, name: string, extra: Record<string, unknown> = {}) =>
+    writeJson(path.join(relDir, 'package.json'), { name, version: '1.0.0', ...extra });
+  const buildable = { scripts: { build: 'tsc' } };
+  const rel = (filePaths: string[]) => filePaths.map((p) => path.relative(root, p)).sort();
+
+  it('resolves a declared package to ITS OWN package.json — a same-named fixture beneath the root is not a member (the 33747781291 shadowing repro)', async () => {
+    await writeJson('lerna.json', { packages: ['packages/common', 'packages/server'] });
+    const rootPkg = await writePackage('.', 'root');
+    const common = await writePackage('packages/common', '@t/common', buildable);
+    const server = await writePackage('packages/server', '@t/server', buildable);
+    // The impostor: same name, sorts AFTER the real one (walk order made it "win"), no build script.
+    await writePackage('scripts/ci/fixtures/floor-sync/repo/packages/server', '@t/server');
+    await writePackage('scripts/ci/fixtures/floor-sync/repo', 'root');
+
+    const { packageMap, packagePathMap, sortedPackageNames } = await PackageUtil.getWorkspaceMetadata(root);
+
+    expect(packageMap['@t/server'].filePath).toBe(server);
+    expect(packageMap['@t/server'].packageJson.scripts?.build).toBe('tsc');
+    expect(rel(Object.keys(packagePathMap))).toEqual(rel([rootPkg, common, server]));
+    expect(sortedPackageNames.filter((n) => n !== 'root').sort()).toEqual(['@t/common', '@t/server']);
+  });
+
+  it('expands lerna globs (packages/*, packages/**) and the root package.json `workspacePackages` extra roots', async () => {
+    await writeJson('lerna.json', { packages: ['packages/*'] });
+    const rootPkg = await writeJson('package.json', {
+      name: 'root',
+      version: '1.0.0',
+      [WorkspaceDeclaration.EXTRA_PACKAGES_FIELD]: ['ops/*'],
+    });
+    const a = await writePackage('packages/a', '@t/a', buildable);
+    const b = await writePackage('packages/b', '@t/b', buildable);
+    const bridge = await writePackage('ops/error-bridge', '@t/error-bridge', buildable);
+    await fs.mkdir(path.join(root, 'ops/notes'), { recursive: true }); // a glob match without package.json: skipped
+    await writePackage('packages/a/test/fixtures/x', '@t/a-fixture'); // not matched by packages/* — not a member
+
+    const { packagePathMap } = await PackageUtil.getWorkspaceMetadata(root);
+    expect(rel(Object.keys(packagePathMap))).toEqual(rel([rootPkg, a, b, bridge]));
+
+    // packages/** reaches nested dirs but still never enters hidden dirs, node_modules, dist, or symlinks.
+    await writeJson('lerna.json', { packages: ['packages/**'] });
+    const deep = await writePackage('packages/group/c', '@t/c', buildable);
+    await writePackage('packages/.hidden/h', '@t/hidden');
+    await writePackage('packages/a/node_modules/dep', '@t/dep');
+    await writePackage('packages/a/dist', '@t/dist-artifact');
+    const outside = await fs.mkdtemp(path.join(os.tmpdir(), 'ws-outside-'));
+    try {
+      await fs.mkdir(path.join(outside, 'o'));
+      await fs.writeFile(path.join(outside, 'o', 'package.json'), JSON.stringify({ name: '@t/outside' }));
+      await fs.symlink(path.join(outside, 'o'), path.join(root, 'packages', 'linked'));
+      const nested = await writePackage('packages/a/test/fixtures/x', '@t/a-fixture'); // packages/** DOES reach it
+      const { packagePathMap: deepMap } = await PackageUtil.getWorkspaceMetadata(root);
+      expect(rel(Object.keys(deepMap))).toEqual(rel([rootPkg, a, b, bridge, deep, nested]));
+    } finally {
+      await fs.rm(outside, { recursive: true, force: true });
+    }
+  });
+
+  it('a declared literal path with no package.json is a hard error naming the declaration and the path', async () => {
+    await writeJson('lerna.json', { packages: ['packages/common', 'packages/ui'] });
+    await writePackage('.', 'root');
+    await writePackage('packages/common', '@t/common', buildable);
+    await fs.mkdir(path.join(root, 'packages/ui'), { recursive: true }); // declared, but empty
+
+    await expect(PackageUtil.getWorkspaceMetadata(root)).rejects.toThrow(WorkspaceDeclarationError);
+    await expect(PackageUtil.getWorkspaceMetadata(root)).rejects.toThrow(
+      /lerna\.json declares "packages\/ui" but .*packages\/ui\/package\.json does not exist/
+    );
+  });
+
+  it('an undeclared tree crawls, and every declared root it meets owns its own subtree (the metarepo shape)', async () => {
+    // Metarepo root: no lerna.json, no workspacePackages — a crawl root, named `root` like every root.
+    const meta = await writePackage('.', 'root');
+    // packages/app is a declared root; its fixtures are NOT members even though the crawl passes above them.
+    await writeJson('packages/app/lerna.json', { packages: ['packages/common'] });
+    const app = await writePackage('packages/app', 'root');
+    const appCommon = await writePackage('packages/app/packages/common', '@t/app-common', buildable);
+    await writePackage('packages/app/scripts/ci/fixtures/f/packages/common', '@t/app-common');
+    await writePackage('packages/app/packages/undeclared', '@t/undeclared', buildable);
+    // A plain undeclared package elsewhere in the crawl stays a member (today's behavior for loose trees).
+    const loose = await writePackage('packages/loose', '@t/loose', buildable);
+
+    const { packageMap, packagePathMap } = await PackageUtil.getWorkspaceMetadata(root);
+    expect(rel(Object.keys(packagePathMap))).toEqual(rel([meta, app, appCommon, loose]));
+    expect(packageMap['@t/app-common'].filePath).toBe(appCommon);
+    expect(packageMap['@t/undeclared']).toBeUndefined();
+  });
+
+  it('two leaf packages sharing a name is a hard error naming both paths and which one is declared', async () => {
+    await writePackage('.', 'root');
+    await writeJson('packages/app/lerna.json', { packages: ['packages/common'] });
+    await writePackage('packages/app', 'root');
+    const declared = await writePackage('packages/app/packages/common', '@t/app-common', buildable);
+    const crawled = await writePackage('tools/impostor', '@t/app-common');
+
+    let error: unknown;
+    try {
+      await WorkspaceDeclaration.discover(root);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(WorkspaceDeclarationError);
+    const message = String((error as Error).message);
+    expect(message).toContain('@t/app-common');
+    expect(message).toContain(declared);
+    expect(message).toContain(crawled);
+    expect(message).toMatch(/declared by .*packages\/app\/lerna\.json/);
+    expect(message).toMatch(/crawled/);
+
+    // Declared vs declared collides the same way.
+    await fs.rm(path.join(root, 'tools'), { recursive: true });
+    await writeJson('packages/other/lerna.json', { packages: ['packages/*'] });
+    await writePackage('packages/other', 'root');
+    const otherCommon = await writePackage('packages/other/packages/common', '@t/app-common', buildable);
+    await expect(WorkspaceDeclaration.discover(root)).rejects.toThrow(otherCommon);
+  });
+
+  it('containers named `root` at every level stay legal — roots are identified by path, not name', async () => {
+    const meta = await writePackage('.', 'root');
+    await writeJson('packages/app/lerna.json', { packages: ['packages/*'] });
+    const app = await writePackage('packages/app', 'root');
+    const common = await writePackage('packages/app/packages/common', '@t/common', buildable);
+    await writeJson('packages/lib/lerna.json', {}); // lerna's default packages/* when the field is absent
+    const lib = await writePackage('packages/lib', 'root');
+    const libA = await writePackage('packages/lib/packages/a', '@t/lib-a', buildable);
+
+    const discovered = await WorkspaceDeclaration.discover(root);
+    expect(rel(discovered.map((d) => d.filePath))).toEqual(rel([meta, app, common, lib, libA]));
+    const byPath = new Map(discovered.map((d) => [d.filePath, d]));
+    expect(byPath.get(common)?.origin).toBe('declared');
+    expect(byPath.get(common)?.declaredBy).toBe(path.join(root, 'packages/app/lerna.json'));
+    expect(byPath.get(meta)?.origin).toBe('crawled');
+  });
+});

package/test/examples/source-repository/a/node_modules/@proteinjs/util-node/tsconfig.json

@@ -1,5 +1,6 @@
 {
   "compilerOptions": {
+    "noEmitOnError": true,
     "target": "es5",
     "module": "commonjs",
     "declaration": true,

package/test/examples/source-repository/a/package-lock.json

@@ -10,10 +10,10 @@
       "license": "MIT",
       "dependencies": {
         "@dagrejs/graphlib": "2.1.4",
-        "@proteinjs/reflection": "^1.1.12",
+        "@proteinjs/reflection": "^1.2.0",
         "@proteinjs/reflection-build-test-b": "file:../b",
-        "@proteinjs/util": "^1.6.1",
-        "@proteinjs/util-node": "^1.10.1",
+        "@proteinjs/util": "^1.6.2",
+        "@proteinjs/util-node": "^1.11.0",
         "globby": "11.0.1",
         "gulp": "4.0.2",
         "gulp-shell": "0.8.0",
@@ -36,9 +36,9 @@
       "license": "ISC",
       "dependencies": {
         "@dagrejs/graphlib": "2.1.4",
-        "@proteinjs/reflection": "^1.1.12",
-        "@proteinjs/util": "^1.6.1",
-        "@proteinjs/util-node": "^1.10.1",
+        "@proteinjs/reflection": "^1.2.0",
+        "@proteinjs/util": "^1.6.2",
+        "@proteinjs/util-node": "^1.11.0",
         "globby": "11.0.1",
         "gulp": "4.0.2",
         "gulp-shell": "0.8.0",
@@ -1104,9 +1104,9 @@
       }
     },
     "node_modules/@proteinjs/reflection": {
-      "version": "1.1.12",
-      "resolved": "https://registry.npmjs.org/@proteinjs/reflection/-/reflection-1.1.12.tgz",
-      "integrity": "sha512-w+sL7Nqppk4DXdFxrfwjEGHSPykCwB3GWaiQXcP6X+8Qtj32BI0wmTvAt6hXvtbXPhvIHPFnTfSs9qlW0FYf9Q==",
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/@proteinjs/reflection/-/reflection-1.2.0.tgz",
+      "integrity": "sha512-AsoipvjpRD0WA1VC4770D5NsN0BDdli9UipdzHHPxcA+BJYcxwPLPLA7h+AAXTNMNfpr/BbEFkxHC0oSCiTkNg==",
       "license": "ISC",
       "dependencies": {
         "@dagrejs/graphlib": "2.1.4",
@@ -1118,9 +1118,9 @@
       "link": true
     },
     "node_modules/@proteinjs/util": {
-      "version": "1.6.1",
-      "resolved": "https://registry.npmjs.org/@proteinjs/util/-/util-1.6.1.tgz",
-      "integrity": "sha512-bFy6++l1u6RtMMeZEDYvMQWg14SAG2gCgUrcPy9M0Ctl0ATVMdQbU3h4IUQOlxwW32mWoni0qDTt9BkmHwAQjg==",
+      "version": "1.6.2",
+      "resolved": "https://registry.npmjs.org/@proteinjs/util/-/util-1.6.2.tgz",
+      "integrity": "sha512-ZY7rMImFNnGV7x/Bqkkav1/gy9IvRR823JcnRJ4SoWXSlA29kuPdaHfnBay6eTQ7+kjiGGtJ+tMWM6NvZW9rUw==",
       "license": "ISC",
       "dependencies": {
         "@dagrejs/graphlib": "2.1.4",
@@ -1128,13 +1128,13 @@
       }
     },
     "node_modules/@proteinjs/util-node": {
-      "version": "1.10.1",
-      "resolved": "https://registry.npmjs.org/@proteinjs/util-node/-/util-node-1.10.1.tgz",
-      "integrity": "sha512-950BkiO4ccf9Bbt0CpvPj5pUalNH9dV1zqr7Cw1Dh3tg9xny6R02p1QrKvPU7anoZcnSp2Us6lBv0rlutYoSWw==",
+      "version": "1.11.0",
+      "resolved": "https://registry.npmjs.org/@proteinjs/util-node/-/util-node-1.11.0.tgz",
+      "integrity": "sha512-+G6Q2w/F5NqmB/3wpNlhj6anpFs503xeKGiec4Hh0+WAsN1JkZCMmEQsHrrzaLGide0b6LyY3Kdo1eycFWRwGw==",
       "license": "ISC",
       "dependencies": {
         "@dagrejs/graphlib": "2.1.4",
-        "@proteinjs/util": "^1.6.1",
+        "@proteinjs/util": "^1.6.2",
         "fs-extra": "11.1.1",
         "globby": "11.0.1",
         "typescript": "5.2.2"

package/test/examples/source-repository/a/package.json

@@ -19,10 +19,10 @@
   },
   "dependencies": {
     "@dagrejs/graphlib": "2.1.4",
-    "@proteinjs/reflection": "^1.1.12",
+    "@proteinjs/reflection": "^1.2.0",
     "@proteinjs/reflection-build-test-b": "file:../b",
-    "@proteinjs/util": "^1.6.1",
-    "@proteinjs/util-node": "^1.10.1",
+    "@proteinjs/util": "^1.6.2",
+    "@proteinjs/util-node": "^1.11.0",
     "globby": "11.0.1",
     "gulp": "4.0.2",
     "gulp-shell": "0.8.0",

package/test/examples/source-repository/a/src/ExtendsForeignType.ts

@@ -57,7 +57,7 @@ export interface ExtendsNotLoadableForeignInterface extends NotLoadableForeignIn
   b: number;
 }
 
-export class ImplementsExtendsLocalNotLoadableInterface implements ExtendsNotLoadableForeignInterface {
+export class ImplementsExtendsNotLoadableForeignInterface implements ExtendsNotLoadableForeignInterface {
   z = 1;
   b = 2;
 }

package/test/examples/source-repository/b/dist/codegen/CanonicalSourceGraph.d.ts

@@ -0,0 +1,22 @@
+import { Graph } from '@dagrejs/graphlib';
+/**
+ * The emitted form of a source graph: the same nodes, values and edges, in an order that is a
+ * function of the graph's content alone — never of the order the builder happened to visit the
+ * sources or insert placeholder parents. The generated index serializes nodes and edges in
+ * insertion order, so this order is the artifact's byte order (and the runtime's `objects()`
+ * order within one package).
+ *
+ * - Nodes by the declaring file's package-relative path, then by qualified name. A placeholder
+ *   (a parent referenced here but declared elsewhere) has no file and sorts by name ahead of
+ *   the declared nodes.
+ * - Edges by child, then parent (a source graph is never a multigraph: one edge per pair).
+ *
+ * Both keys are package-relative strings compared by code unit, so they are the same on every
+ * machine and in every checkout location.
+ */
+export declare class CanonicalSourceGraph {
+    /** A copy of `graph` whose node and edge order is canonical. */
+    static of(graph: Graph): Graph;
+    private static nodeOrder;
+    private static edgeOrder;
+}