@proteinjs/reflection-build 2.0.2 → 2.1.0

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

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/util-node",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "description": "Util libs for node",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
   },
   "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"
@@ -42,5 +42,6 @@
     "eslint-plugin-prettier": "5.1.3",
     "jest": "^29.6.4",
     "ts-jest": "^29.1.1"
-  }
+  },
+  "gitHead": "6ddfa98b5143e30991703881a29d1a73cec35e85"
 }

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

@@ -9,11 +9,14 @@ export const parseArgsMap = (rawArgs: string[]): ArgsMap => {
       return;
     }
 
-    const keyValue = arg.slice(2).split('=');
-    if (keyValue.length > 1) {
-      args[keyValue[0]] = keyValue[1];
+    // Split on the FIRST '=' only — values legitimately contain '=' (e.g. --note=port=9040)
+    // and must be preserved in full.
+    const keyValue = arg.slice(2);
+    const separatorIndex = keyValue.indexOf('=');
+    if (separatorIndex >= 0) {
+      args[keyValue.slice(0, separatorIndex)] = keyValue.slice(separatorIndex + 1);
     } else {
-      args[keyValue[0]] = true;
+      args[keyValue] = true;
     }
   });
   return args;

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

@@ -104,21 +104,24 @@ export class Fs {
   // @param globIgnorePatterns ie. ['**/node_modules/**', '**/dist/**'] to ignore these directories
   // @return string[] of file paths
   static async getFilePaths(dir: string, globIgnorePatterns: string[] = []) {
-    return await globby(dir + '**/*', {
-      ignore: [...globIgnorePatterns],
-    });
+    return await Fs.getFilePathsMatchingGlob(dir, '**/*', globIgnorePatterns);
   }
 
   // @param dirPrefix recursively search for files in this dir
   // @param glob file matching pattern ie. **/package.json
   // @param globIgnorePatterns ie. ['**/node_modules/**', '**/dist/**'] to ignore these directories
-  // @return string[] of file paths
+  // @return string[] of absolute file paths
   static async getFilePathsMatchingGlob(dirPrefix: string, glob: string, globIgnorePatterns: string[] = []) {
-    if (dirPrefix[dirPrefix.length - 1] != path.sep) {
-      dirPrefix += path.sep;
-    }
-
-    return await globby(dirPrefix + glob, {
+    // Match relative to the directory (`cwd`) rather than folding it into an absolute pattern.
+    // In the absolute form fast-glob matched the ignore list against the absolute entry path,
+    // and a globstar does not cross a dot-segment — so under any base path containing a
+    // dot-directory (`~/.n3xa/workspaces/<name>`, a `.scratch` estate) the ignore list matched
+    // nothing: every node_modules/dist was walked in full, workspace symlinks followed into
+    // cycles, and the caller ran out of heap on a large tree. Relative matching keeps the ignore
+    // list and the entry paths in the same frame, so the prune holds under any base path.
+    return await globby(glob, {
+      cwd: dirPrefix,
+      absolute: true,
       ignore: [...globIgnorePatterns],
     });
   }

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

@@ -4,6 +4,7 @@ import * as fs from 'fs/promises';
 import { Graph, GraphAlgorithms } from '@proteinjs/util';
 import { cmd } from './cmd';
 import { Fs } from './Fs';
+import { WorkspaceDeclaration } from './WorkspaceDeclaration';
 
 export type Package = {
   name: string;
@@ -23,12 +24,31 @@ export type LocalPackage = {
   };
 };
 
+/**
+ * Name-keyed resolution index: dependency declarations reference packages BY NAME, so name →
+ * package is how a declared dep resolves to a workspace member. Names are not identities —
+ * every workspace root in a metarepo is named `root` — so when several packages share a name,
+ * this map holds only one of them (deterministically: the lexicographically last package.json
+ * path wins). Enumeration and identity questions belong to `LocalPackagePathMap`.
+ */
 export type LocalPackageMap = {
   [packageName: string]: LocalPackage;
 };
 
+/**
+ * Path-keyed identity map: one entry per discovered package.json, keyed by its absolute path.
+ * This is the DISCOVERY truth — same-named packages (the metarepo root, the app root, and every
+ * nested lerna root are all named `root`) never collide here. Use it wherever the question is
+ * "which packages exist" (enumeration, symlink coverage); use `LocalPackageMap` only to resolve
+ * a dependency NAME to its workspace member.
+ */
+export type LocalPackagePathMap = {
+  [packageJsonPath: string]: LocalPackage;
+};
+
 export type WorkspaceMetadata = {
   packageMap: LocalPackageMap;
+  packagePathMap: LocalPackagePathMap; // every discovered package, path-keyed (collision-free)
   packageGraph: any; // @dagrejs/graphlib.Graph
   sortedPackageNames: string[]; // local package names, in dependency order (ie. if a depends on b, [b, a] will be returned)
   workspaceToPackageMap: { [workspacePath: string]: string[] }; // string[] is names of packages in workspace
@@ -155,23 +175,40 @@ export class PackageUtil {
   }
 
   /**
-   * Get map of local packages within repo specified by directory path
+   * Get the name-keyed resolution index of local packages within the repo specified by
+   * directory path. Derived from `getLocalPackagePathMap` (which owns discovery); see
+   * `LocalPackageMap` for the name-collision semantics.
    *
    * @param dir dir path that contains local packages
-   * @param globIgnorePatterns already includes: ['**\/node_modules/**', '**\/dist/**']
    * @returns {[packageName: string]: LocalPackage}
    */
-  static async getLocalPackageMap(dir: string, globIgnorePatterns: string[] = []): Promise<LocalPackageMap> {
-    const packageMap: { [packageName: string]: LocalPackage } = {};
-    const filePaths = await Fs.getFilePathsMatchingGlob(dir, '**/package.json', [
-      '**/node_modules/**',
-      '**/dist/**',
-      ...globIgnorePatterns,
-    ]);
-    for (const filePath of filePaths) {
-      const packageJson = JSON.parse(await Fs.readFile(filePath));
+  static async getLocalPackageMap(dir: string): Promise<LocalPackageMap> {
+    return PackageUtil.toNameKeyedMap(await PackageUtil.getLocalPackagePathMap(dir));
+  }
+
+  /**
+   * Every member package of the workspace rooted at `dir`, keyed by package.json path — the
+   * package's IDENTITY. Same-named packages (every workspace root is named `root`) are distinct
+   * entries here; anything that enumerates workspace members must start from this map, not from
+   * the name-keyed index.
+   *
+   * Membership is DECLARED, never crawled — `WorkspaceDeclaration` is the one owner: a root's
+   * lerna.json `packages` (plus the root package.json's `workspacePackages` extra roots) names
+   * exactly its members, a declared root owns its subtree, and only a tree with no declaration
+   * at its root is walked (bounded: never into hidden directories, `node_modules`, `dist`, or
+   * through symlinks — the unbounded-glob OOM of 2026-09-02 stays fixed). A same-named
+   * package.json nobody declared (the CI fixture trees that shadowed the app's packages in
+   * n3xah/app run 33747781291) is not a member; a leaf-name collision among members is a hard
+   * error naming both paths.
+   *
+   * @param dir dir path that contains local packages
+   * @returns {[packageJsonPath: string]: LocalPackage}
+   */
+  static async getLocalPackagePathMap(dir: string): Promise<LocalPackagePathMap> {
+    const packagePathMap: LocalPackagePathMap = {};
+    for (const { filePath, packageJson } of await WorkspaceDeclaration.discover(dir)) {
       const name = packageJson['name'];
-      packageMap[name] = {
+      packagePathMap[filePath] = {
         name,
         filePath,
         packageJson,
@@ -186,7 +223,7 @@ export class PackageUtil {
         const workspaceLernaJson = (await Fs.exists(workspaceLernaJsonPath))
           ? JSON.parse(await Fs.readFile(workspaceLernaJsonPath))
           : undefined;
-        packageMap[name].workspace = {
+        packagePathMap[filePath].workspace = {
           path: workspacePath,
           rootPackageJson: workspacePackageJson,
           lernaJson: workspaceLernaJson,
@@ -194,7 +231,7 @@ export class PackageUtil {
       }
     }
 
-    return packageMap;
+    return packagePathMap;
   }
 
   /**
@@ -309,7 +346,8 @@ export class PackageUtil {
    * @returns `WorkspaceMetadata`
    */
   static async getWorkspaceMetadata(workspacePath: string): Promise<WorkspaceMetadata> {
-    const packageMap = await PackageUtil.getLocalPackageMap(workspacePath);
+    const packagePathMap = await PackageUtil.getLocalPackagePathMap(workspacePath);
+    const packageMap = PackageUtil.toNameKeyedMap(packagePathMap);
     const packageGraph = await PackageUtil.getPackageDependencyGraph(packageMap);
     const sortedPackageNames = PackageUtil.getDependencyOrder(packageGraph).filter(
       (packageName) => !!packageMap[packageName]
@@ -317,6 +355,7 @@ export class PackageUtil {
     const workspaceToPackageMap = PackageUtil.getWorkspaceToPackageMap(packageMap);
     return {
       packageMap,
+      packagePathMap,
       packageGraph,
       sortedPackageNames,
       workspaceToPackageMap,
@@ -359,17 +398,18 @@ export class PackageUtil {
   /**
    * Compute the transitive closure of workspace dependencies for `localPackage`.
    *
-   * Reuses `getPackageDependencyGraph`, which already crawls `dependencies` and
-   * `devDependencies` (transitively, across the whole workspace) and adds an
-   * edge `consumer -> dependency` for each. So the workspace deps reachable from
-   * a package are exactly the nodes reachable by following `successors` from its
-   * node. We do a cycle-safe traversal (a `visited` set), since the dependency
-   * graph can contain cycles. The package itself is excluded from the result.
+   * Traverses dependency DECLARATIONS (`dependencies` + `devDependencies`) starting from THIS
+   * package instance's own package.json, resolving each declared name through
+   * `localPackageMap` and expanding through the resolved packages' declarations in turn.
+   * Cycle safety and the visited set are PATH-KEYED (package.json paths): identity is the
+   * path, never the name. The closure is never seeded from a shared name-keyed graph node —
+   * same-named packages (every workspace root is named `root`) share such a node, so a
+   * graph-seeded closure conflates their dependencies and computes another package's closure
+   * for whichever same-named instance lost the name-keyed collision.
    *
-   * Only names present in `localPackageMap` are returned — i.e. packages that
-   * actually live in the workspace and can be symlinked (the graph already
-   * filters to file:/relative/workspace deps in `addDependencies`, but we filter
-   * again here so the result is exactly the set of linkable packages).
+   * Only names present in `localPackageMap` are traversed and returned — i.e. packages that
+   * actually live in the workspace and can be symlinked. The package itself is excluded from
+   * the result (its own path seeds the visited set).
    *
    * Public: WorkspaceDoctor (@proteinjs/build) diagnoses the same closure this method links —
    * verification and repair must agree on the set of packages that ought to be symlinked.
@@ -380,25 +420,24 @@ export class PackageUtil {
     localPackage: LocalPackage,
     localPackageMap: LocalPackageMap
   ): Promise<string[]> {
-    const graph = await PackageUtil.getPackageDependencyGraph(localPackageMap);
-    const rootPackageName = localPackage.packageJson['name'];
-
     const transitiveDependencies = new Set<string>();
-    const visited = new Set<string>([rootPackageName]);
-    const stack: string[] = [rootPackageName];
+    const visitedPaths = new Set<string>([localPackage.filePath]);
+    const stack: LocalPackage[] = [localPackage];
     while (stack.length > 0) {
       const current = stack.pop()!;
-      const successors = (graph.successors(current) as string[] | void) || [];
-      for (const dependencyPackageName of successors) {
-        if (visited.has(dependencyPackageName)) {
+      const declared = {
+        ...(current.packageJson['dependencies'] ?? {}),
+        ...(current.packageJson['devDependencies'] ?? {}),
+      };
+      for (const dependencyPackageName of Object.keys(declared)) {
+        const dependencyPackage = localPackageMap[dependencyPackageName];
+        if (!dependencyPackage || visitedPaths.has(dependencyPackage.filePath)) {
           continue;
         }
 
-        visited.add(dependencyPackageName);
-        stack.push(dependencyPackageName);
-        if (localPackageMap[dependencyPackageName]) {
-          transitiveDependencies.add(dependencyPackageName);
-        }
+        visitedPaths.add(dependencyPackage.filePath);
+        transitiveDependencies.add(dependencyPackageName);
+        stack.push(dependencyPackage);
       }
     }
 
@@ -527,4 +566,19 @@ export class PackageUtil {
       }
     }
   }
+
+  /**
+   * Derive the name-keyed resolution index from the path-keyed discovery map. When several
+   * packages share a name, the lexicographically last package.json path wins — deterministic,
+   * and irrelevant for real dependency names (nothing declares a dep on `root`; uniquely-named
+   * packages resolve identically either way).
+   */
+  private static toNameKeyedMap(packagePathMap: LocalPackagePathMap): LocalPackageMap {
+    const packageMap: LocalPackageMap = {};
+    for (const filePath of Object.keys(packagePathMap).sort()) {
+      const localPackage = packagePathMap[filePath];
+      packageMap[localPackage.name] = localPackage;
+    }
+    return packageMap;
+  }
 }

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

@@ -0,0 +1,340 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+
+/** A declared-workspace rule was broken. The message names every path involved. */
+export class WorkspaceDeclarationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WorkspaceDeclarationError';
+    Object.setPrototypeOf(this, WorkspaceDeclarationError.prototype); // ES5 target: keep instanceof true across the Error subclass
+  }
+}
+
+export type DiscoveredPackage = {
+  /** Absolute package.json path — the package's identity. */
+  filePath: string;
+  packageJson: any;
+  /** `declared`: named by a workspace declaration; `crawled`: found by the bounded walk of an undeclared tree. */
+  origin: 'declared' | 'crawled';
+  /** The declaration file (lerna.json or the root package.json) that named a `declared` package. */
+  declaredBy?: string;
+};
+
+type Declaration = {
+  rootDir: string;
+  /** Each pattern with the file that declared it, in declaration order. */
+  patterns: Array<{ pattern: string; source: string }>;
+};
+
+/**
+ * The ONE owner of workspace membership: which package.json files belong to the workspace rooted
+ * at a directory.
+ *
+ * Membership is DECLARED, never crawled. A directory holding a `lerna.json` (its `packages`
+ * globs; lerna's own default `packages/*` when the field is absent) or a root `package.json`
+ * carrying `workspacePackages` (extra roots the workspace tooling builds alongside lerna's
+ * members — e.g. an app's `ops/*` tools that lerna must not version) 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 member that is itself a root expands through
+ * its own declaration (the metarepo's nested lerna roots).
+ *
+ * Why: the previous crawl (every package.json under the root, keyed by name, last path wins)
+ * let a CI fixture tree whose package.json files reused the app's own package names shadow the
+ * real packages — build-workspace built "1 package in workspace" and the release image shipped
+ * with no server dist (n3xah/app Deploy to Test run 33747781291, 2026-09-03). A declaration
+ * cannot be shadowed by a file nobody declared.
+ *
+ * A tree with no declaration at its root (the n3xa metarepo root) still crawls — bounded exactly
+ * as before: never into hidden directories, `node_modules`, `dist`, or through symlinks — and
+ * hands every declared root it meets to that root's declaration.
+ *
+ * Hard errors, each naming its paths: a declared literal path with no package.json; two leaf
+ * packages sharing a name (dependencies resolve to members BY NAME). Containers — a package.json
+ * with members beneath it; every root in the metarepo is named `root` — are identified by path
+ * and exempt from the name rule.
+ *
+ * npm's own `workspaces` field is deliberately NOT read: it changes how `npm i` installs at the
+ * root, which is a different install model from the per-package installs this tooling performs.
+ */
+export class WorkspaceDeclaration {
+  /** Root package.json field naming extra member globs beside lerna's `packages`. */
+  static readonly EXTRA_PACKAGES_FIELD = 'workspacePackages';
+  private static readonly lernaDefaultPackages = ['packages/*'];
+  private static readonly prunedDirNames = new Set(['node_modules', 'dist']);
+
+  /** Every member package.json of the workspace rooted at `rootDir`, sorted by path. */
+  static async discover(rootDir: string): Promise<DiscoveredPackage[]> {
+    const found = new Map<string, DiscoveredPackage>();
+    const root = path.resolve(rootDir);
+    const declaration = await WorkspaceDeclaration.read(root);
+    if (declaration) {
+      await WorkspaceDeclaration.discoverDeclared(declaration, found);
+    } else {
+      await WorkspaceDeclaration.crawl(root, found);
+    }
+    const discovered = Array.from(found.values()).sort((a, b) =>
+      a.filePath < b.filePath ? -1 : a.filePath > b.filePath ? 1 : 0
+    );
+    WorkspaceDeclaration.assertNoLeafNameCollisions(discovered);
+    return discovered;
+  }
+
+  /** The declaration at `dir` when `dir` is a workspace root; undefined otherwise. */
+  static async read(dir: string): Promise<Declaration | undefined> {
+    const patterns: Declaration['patterns'] = [];
+    const lernaPath = path.join(dir, 'lerna.json');
+    const lernaJson = await WorkspaceDeclaration.readJsonIfExists(lernaPath);
+    if (lernaJson) {
+      const declared = Array.isArray(lernaJson.packages)
+        ? lernaJson.packages
+        : WorkspaceDeclaration.lernaDefaultPackages;
+      for (const pattern of declared) {
+        patterns.push({ pattern: WorkspaceDeclaration.assertPattern(pattern, lernaPath), source: lernaPath });
+      }
+    }
+    const packageJsonPath = path.join(dir, 'package.json');
+    const packageJson = await WorkspaceDeclaration.readJsonIfExists(packageJsonPath);
+    const extra = packageJson?.[WorkspaceDeclaration.EXTRA_PACKAGES_FIELD];
+    if (extra !== undefined) {
+      if (!Array.isArray(extra)) {
+        throw new WorkspaceDeclarationError(
+          `${packageJsonPath}: "${WorkspaceDeclaration.EXTRA_PACKAGES_FIELD}" must be an array of package globs`
+        );
+      }
+      for (const pattern of extra) {
+        patterns.push({
+          pattern: WorkspaceDeclaration.assertPattern(pattern, packageJsonPath),
+          source: packageJsonPath,
+        });
+      }
+    }
+    return patterns.length > 0 ? { rootDir: dir, patterns } : undefined;
+  }
+
+  /** A declared root: its own package.json (the container), then exactly its declared members. */
+  private static async discoverDeclared(declaration: Declaration, found: Map<string, DiscoveredPackage>) {
+    const own = path.join(declaration.rootDir, 'package.json');
+    if (await WorkspaceDeclaration.exists(own)) {
+      await WorkspaceDeclaration.add(found, own, 'declared', declaration.patterns[0].source);
+    }
+    for (const { pattern, source } of declaration.patterns) {
+      for (const memberDir of await WorkspaceDeclaration.expand(declaration.rootDir, pattern, source)) {
+        const nested = await WorkspaceDeclaration.read(memberDir);
+        if (nested) {
+          await WorkspaceDeclaration.discoverDeclared(nested, found); // a nested root owns its subtree
+        } else {
+          await WorkspaceDeclaration.add(found, path.join(memberDir, 'package.json'), 'declared', source);
+        }
+      }
+    }
+  }
+
+  /**
+   * The bounded walk of an UNDECLARED tree (the metarepo root): every package.json it meets is a
+   * member, and every declared root it meets is handed to that root's declaration instead of
+   * being walked. Never enters hidden directories, node_modules, or dist; never follows symlinks
+   * (`withFileTypes` reports a symlink as neither directory nor file).
+   */
+  private static async crawl(rootDir: string, found: Map<string, DiscoveredPackage>) {
+    const pending: string[] = [rootDir];
+    while (pending.length > 0) {
+      const currentDir = pending.pop()!;
+      for (const dirent of await fs.readdir(currentDir, { withFileTypes: true })) {
+        const entryPath = path.join(currentDir, dirent.name);
+        if (dirent.isDirectory()) {
+          if (WorkspaceDeclaration.isPrunedDirName(dirent.name)) {
+            continue;
+          }
+          const declaration = await WorkspaceDeclaration.read(entryPath);
+          if (declaration) {
+            await WorkspaceDeclaration.discoverDeclared(declaration, found);
+          } else {
+            pending.push(entryPath);
+          }
+        } else if (dirent.isFile() && dirent.name === 'package.json') {
+          await WorkspaceDeclaration.add(found, entryPath, 'crawled');
+        }
+      }
+    }
+  }
+
+  /**
+   * The directories a declared pattern names under `rootDir`, lerna's semantics: a literal path
+   * MUST hold a package.json (hard error otherwise — a declared package that does not exist is
+   * a broken declaration, never a silent skip); a glob (`*` within a segment, `**` for any depth)
+   * matches directories that hold one, walking with the same prune rules as the crawl. A declared
+   * root met inside a glob's walk is matched as a whole and not walked past — it owns its subtree.
+   */
+  private static async expand(rootDir: string, pattern: string, source: string): Promise<string[]> {
+    const segments = pattern.split('/').filter((segment) => segment.length > 0 && segment !== '.');
+    if (!segments.some((segment) => segment.includes('*'))) {
+      const dir = path.join(rootDir, ...segments);
+      if (!(await WorkspaceDeclaration.exists(path.join(dir, 'package.json')))) {
+        throw new WorkspaceDeclarationError(
+          `${source} declares "${pattern}" but ${path.join(dir, 'package.json')} does not exist — a declared package must exist (fix the declaration or restore the package)`
+        );
+      }
+      return [dir];
+    }
+    const matches = new Set<string>();
+    await WorkspaceDeclaration.matchSegments(rootDir, segments, 0, matches);
+    return Array.from(matches).sort();
+  }
+
+  private static async matchSegments(dir: string, segments: string[], index: number, matches: Set<string>) {
+    if (index === segments.length) {
+      if (await WorkspaceDeclaration.exists(path.join(dir, 'package.json'))) {
+        matches.add(dir);
+      }
+      return;
+    }
+    const segment = segments[index];
+    const remaining = segments.length - index - 1;
+    if (segment === '**') {
+      await WorkspaceDeclaration.matchSegments(dir, segments, index + 1, matches); // zero directories
+      for (const child of await WorkspaceDeclaration.childDirs(dir)) {
+        if (await WorkspaceDeclaration.read(child)) {
+          matches.add(child); // a nested root owns its subtree — matched whole, never walked past
+          continue;
+        }
+        await WorkspaceDeclaration.matchSegments(child, segments, index, matches); // one more directory under **
+      }
+      return;
+    }
+    const children = segment.includes('*')
+      ? (await WorkspaceDeclaration.childDirs(dir)).filter((child) =>
+          WorkspaceDeclaration.segmentMatcher(segment).test(path.basename(child))
+        )
+      : (await WorkspaceDeclaration.isRealDir(path.join(dir, segment)))
+        ? [path.join(dir, segment)]
+        : [];
+    for (const child of children) {
+      if (remaining > 0 && (await WorkspaceDeclaration.read(child))) {
+        matches.add(child);
+        continue;
+      }
+      await WorkspaceDeclaration.matchSegments(child, segments, index + 1, matches);
+    }
+  }
+
+  /** Leaf packages resolve by name; two leaves with one name is a broken workspace, not a tie to break. */
+  private static assertNoLeafNameCollisions(discovered: DiscoveredPackage[]) {
+    const dirs = discovered.map((entry) => path.dirname(entry.filePath));
+    const isContainer = (entry: DiscoveredPackage) => {
+      const prefix = path.dirname(entry.filePath) + path.sep;
+      return dirs.some((dir) => dir.startsWith(prefix));
+    };
+    const byName = new Map<string, DiscoveredPackage[]>();
+    for (const entry of discovered) {
+      const name = entry.packageJson?.name;
+      if (typeof name !== 'string' || name.length === 0) {
+        continue;
+      }
+      byName.set(name, (byName.get(name) ?? []).concat(entry));
+    }
+    const collisions: string[] = [];
+    for (const [name, entries] of Array.from(byName.entries())) {
+      const leaves = entries.filter((entry) => !isContainer(entry));
+      if (leaves.length < 2) {
+        continue;
+      }
+      collisions.push(
+        `"${name}" is claimed by\n` +
+          leaves
+            .map(
+              (entry) =>
+                `  - ${entry.filePath} (${entry.origin === 'declared' ? `declared by ${entry.declaredBy}` : 'crawled — no declaration names it'})`
+            )
+            .join('\n')
+      );
+    }
+    if (collisions.length > 0) {
+      throw new WorkspaceDeclarationError(
+        `Workspace package name collision — dependencies resolve to workspace members BY NAME, so two packages cannot share one:\n${collisions.join('\n')}\nRename the impostor (fixtures carry fixture names) or move it outside the workspace.`
+      );
+    }
+  }
+
+  private static async add(
+    found: Map<string, DiscoveredPackage>,
+    filePath: string,
+    origin: DiscoveredPackage['origin'],
+    declaredBy?: string
+  ) {
+    if (found.has(filePath)) {
+      return;
+    }
+    const packageJson = JSON.parse(await fs.readFile(filePath, 'utf8'));
+    found.set(filePath, { filePath, packageJson, origin, ...(declaredBy ? { declaredBy } : {}) });
+  }
+
+  private static assertPattern(pattern: unknown, source: string): string {
+    if (typeof pattern !== 'string' || pattern.trim().length === 0) {
+      throw new WorkspaceDeclarationError(
+        `${source}: package patterns must be non-empty strings, got ${JSON.stringify(pattern)}`
+      );
+    }
+    if (path.isAbsolute(pattern) || pattern.split('/').includes('..')) {
+      throw new WorkspaceDeclarationError(
+        `${source}: package pattern "${pattern}" must be relative to the root and stay inside it`
+      );
+    }
+    return pattern;
+  }
+
+  private static segmentMatcher(segment: string): RegExp {
+    const escaped = segment.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*');
+    return new RegExp(`^${escaped}$`);
+  }
+
+  private static isPrunedDirName(name: string): boolean {
+    return name.startsWith('.') || WorkspaceDeclaration.prunedDirNames.has(name);
+  }
+
+  /** Real (non-symlink, non-pruned) child directories of `dir`. */
+  private static async childDirs(dir: string): Promise<string[]> {
+    let dirents;
+    try {
+      dirents = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return dirents
+      .filter((dirent) => dirent.isDirectory() && !WorkspaceDeclaration.isPrunedDirName(dirent.name))
+      .map((dirent) => path.join(dir, dirent.name))
+      .sort();
+  }
+
+  private static async isRealDir(p: string): Promise<boolean> {
+    try {
+      return (await fs.lstat(p)).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  private static async exists(p: string): Promise<boolean> {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private static async readJsonIfExists(p: string): Promise<any | undefined> {
+    let text: string;
+    try {
+      text = await fs.readFile(p, 'utf8');
+    } catch {
+      return undefined;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new WorkspaceDeclarationError(
+        `${p} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+}

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

@@ -0,0 +1,35 @@
+import { parseArgsMap } from '../src/ArgsMap';
+
+describe('parseArgsMap', () => {
+  test('preserves the full value when it contains embedded = characters', () => {
+    // The estate CLI's --note values regularly carry '=' (e.g. env assignments, key=value notes).
+    // The parser must split on the FIRST '=' only and keep the remainder intact.
+    const args = parseArgsMap(['--note=emulator=spanner-x port=9040']);
+    expect(args['note']).toEqual('emulator=spanner-x port=9040');
+  });
+
+  test('parses a simple key=value pair', () => {
+    const args = parseArgsMap(['--name=my-estate']);
+    expect(args['name']).toEqual('my-estate');
+  });
+
+  test('parses a bare flag as boolean true', () => {
+    const args = parseArgsMap(['--pin']);
+    expect(args['pin']).toEqual(true);
+  });
+
+  test('parses an explicitly empty value as the empty string', () => {
+    const args = parseArgsMap(['--note=']);
+    expect(args['note']).toEqual('');
+  });
+
+  test('ignores args that do not start with --', () => {
+    const args = parseArgsMap(['positional', '-x', '--keep=yes']);
+    expect(args).toEqual({ keep: 'yes' });
+  });
+
+  test('parses multiple args together, preserving each full value', () => {
+    const args = parseArgsMap(['--containers=spanner-x', '--pids=123', '--pin', '--note=a=b=c']);
+    expect(args).toEqual({ containers: 'spanner-x', pids: '123', pin: true, note: 'a=b=c' });
+  });
+});