@effected/workspaces 0.26.0 → 0.27.0

package/README.md

@@ -347,6 +347,7 @@ describe("source boundary", () => {
 | `"console"` | any reference to the global `console` |
 | `"console-stdout"` | a reference to the global `console`, except a member access to a method Node writes to stderr: `error`, `warn`, `trace`, `assert`. A bare or aliased reference (`const c = console`, `f(console)`, `console[m]`) is flagged, since it can reach `log` |
 | `{ forbidImports }` | an import equal to an entry, a subpath of one, or starting with an entry's text before a trailing `*` |
+| `{ forbidTokens }` | an entry's exact text in code (never in a comment, string, template text or regex), as whole text: not inside a longer identifier |
 
 Neither console rule flags core's `Console` service. `"console-stdout"` suits a stdio server that must keep stdout for its protocol but may log to stderr.
 
@@ -365,11 +366,30 @@ assert.deepStrictEqual([...new Set(scan.waived.map((offence) => offence.file))],
 
 Both kinds of glob compile with `@effected/glob` and match the scan's relative, `/`-separated path; an uncompilable one fails the scan with `GlobPatternError`.
 
+To confine a token to named files rather than forbid it everywhere, forbid it with `{ forbidTokens }` and waive that rule for those files. The `"process"` rule exempts the build-time version define everywhere; this holds it to `version.ts`, and `waived` proves the confinement still matches something:
+
+```ts
+const TOKEN = "process.env.__PACKAGE_VERSION__";
+const scan = yield* SourceBoundary.scan({
+  root: SRC,
+  rules: ["process", { forbidTokens: [TOKEN] }],
+  allowRules: { forbidTokens: ["version.ts"] },
+});
+assert.deepStrictEqual(scan.violations, []);
+assert.deepStrictEqual(
+  scan.waived.map((offence) => offence.file),
+  ["version.ts"],
+);
+```
+
+`version.ts` names the file at the root; `**/version.ts` names one at any depth. One `"forbidTokens"` key covers every `{ forbidTokens }` rule in a scan, so two tokens with different homes take two scans.
+
 The scanner is a lexer, not a type checker. Its known limits:
 
 - There is no scope analysis, so any local binding named `process` or `console` is flagged like the global: a parameter (`(process: Handle) => process.kill()`), a variable, a label, or an unannotated class field (`process = 1`). An annotated class field (`process: T`) reads as a type member and is spared. Prefer renaming the binding; failing that, waive that one rule for the file with `allowRules` and assert `scan.waived` names exactly it.
 - `globalThis["process"]` and `const { process: p } = globalThis` are not seen.
 - A regex literal directly after a block-closing `}` reads as a division.
+- A variable named `yield` or `await` in a sloppy-mode script reads as the keyword, so a `/` after it opens a regex. Module and strict code reserve both words, so a module never hits this.
 - JSX text reads as code, which is why `.tsx` and `.jsx` are not scanned by default.
 - `forbidImports: ["node:*"]` matches only the `node:` spelling, not a bare `"fs"`. To forbid both, spread Node's list in the test file: `{ forbidImports: ["node:*", ...builtinModules] }`, with `builtinModules` from `node:module`. That also forbids npm packages named like a built-in (`events`, `buffer`).
 
@@ -377,7 +397,7 @@ The scanner is a lexer, not a type checker. Its known limits:
 
 `PackedInstall.run` packs a carrier and every workspace package it needs, then installs the carrier into a fresh project outside the workspace under each package manager that answers `--version`, and checks every expected bin is linked and executable. It carries the traps each manager sets: the parent run's `npm_*` and `pnpm_config_*` context is scrubbed, pnpm's overrides go in `pnpm-workspace.yaml`, Yarn Berry gets the `node-modules` linker, `packageManager` is pinned to the probed version, and lifecycle scripts are skipped. By default it packs each package's built `dist/prod/npm/pkg`, the artifact a release publishes; build first.
 
-It does not run the bins; the test does, inside the same scope, because the scratch directory is removed when the scope closes. For an MCP server bin, `McpProbe` from `@effected/mcp/testing` is the proof:
+It does not run the bins; the test does, inside the same scope, because the scratch directory (`result.scratch`) is removed when the scope closes. `consumer.runBin(name, args, options?)` runs one to completion and returns `{ stdout, stderr, exitCode }`, with no direct `@effected/commands` dependency. `consumer.command(name, args?, options?)` returns the `ChildProcess` command `runBin` builds, same environment and working directory, with stdin left open, so a probe that writes to the bin can spawn it. `consumer.binProvenance(name)` names the package a `.bin` symlink resolves into. `PackedInstall.closure(carrier, options?)` names every package the run will pack before it runs, and `PackedInstall.timeoutBudget` sizes the outer timeout from those names and the run's own ceilings. For an MCP server bin, `McpProbe` from `@effected/mcp/testing` is the proof:
 
 ```ts
 // __test__/e2e/packed-install.e2e.test.ts, two levels below the workspace root
@@ -388,49 +408,78 @@ import { assert, describe, layer } from "@effect/vitest";
 import { McpProbe } from "@effected/mcp/testing";
 import { Workspaces } from "@effected/workspaces";
 import { PackedInstall } from "@effected/workspaces/testing";
-import { Effect, Layer } from "effect";
-import { ChildProcess } from "effect/unstable/process";
+import { Duration, Effect, Layer } from "effect";
 
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const Live = Workspaces.layer({ cwd: ROOT }).pipe(Layer.provideMerge(NodeServices.layer));
 
+const MANAGERS = ["npm", "pnpm", "yarn", "bun"] as const;
+const INSTALL_TIMEOUT = "2 minutes";
+const PACK_TIMEOUT = "1 minute";
+const BIN_TIMEOUT = "30 seconds";
+// The packages the run will pack, known before the test is declared.
+const PACKAGES = await Effect.runPromise(PackedInstall.closure("my-tool").pipe(Effect.provide(Live)));
+// Every ceiling the run sets, plus the two bin runs per consumer. The vitest
+// timeout sits above it, so a named PackedInstallError fires before either guard.
+const BUDGET = PackedInstall.timeoutBudget({
+  managers: MANAGERS,
+  installTimeout: INSTALL_TIMEOUT,
+  packTimeout: PACK_TIMEOUT,
+  packages: PACKAGES,
+  perConsumer: "1 minute",
+});
+
 describe("packed install", () => {
   // The real clock: installs and the probe are real processes.
   layer(Live, { excludeTestServices: true })((it) => {
     it.effect(
-      "my-tool's MCP bin boots from a packed install under every available manager",
+      "my-tool's bins work from a packed install under every available manager",
       () =>
         Effect.gen(function* () {
           const result = yield* PackedInstall.run({
             carrier: "my-tool",
             closure: "auto",
-            managers: ["npm", "pnpm", "yarn", "bun"],
-            bins: ["my-tool-mcp"],
+            managers: MANAGERS,
+            bins: ["my-tool", "my-tool-mcp"],
             env: process.env,
-            installTimeout: "2 minutes",
+            installTimeout: INSTALL_TIMEOUT,
+            packTimeout: PACK_TIMEOUT,
           });
+          assert.deepStrictEqual(Object.keys(result.tarballs), [...PACKAGES]);
           assert.isAbove(result.consumers.length, 0, `nothing installed; unavailable: ${result.unavailable.join(", ")}`);
-          const env = PackedInstall.scrubEnv(process.env);
+          // The tool's data lives inside the scratch root and is removed with it.
+          const env = { XDG_DATA_HOME: `${result.scratch}/xdg` };
           for (const consumer of result.consumers) {
-            const bin = ChildProcess.make(consumer.binPath("my-tool-mcp"), [], {
-              cwd: consumer.directory,
-              env,
-              extendEnv: false,
-            });
-            const { response, stderr, exitCode } = yield* McpProbe.initialize(bin).pipe(Effect.timeout("30 seconds"));
+            const version = yield* consumer.runBin("my-tool", ["--version"], { env, timeout: BIN_TIMEOUT });
+            assert.strictEqual(version.exitCode, 0, `${consumer.manager}: ${version.stderr}`);
+            // Only the carrier declares my-tool (the run fails BinConflict otherwise, unless
+            // allowSharedBins), so the .bin link is the carrier's. pnpm's shims are not read: undefined.
+            const provenance = yield* consumer.binProvenance("my-tool");
+            if (consumer.manager !== "pnpm") assert.strictEqual(provenance?.package, "my-tool", consumer.manager);
+            const probe = McpProbe.initialize(consumer.command("my-tool-mcp", [], { env }));
+            const { response, stderr, exitCode } = yield* probe.pipe(Effect.timeout(BIN_TIMEOUT));
             assert.isUndefined(response.error, `${consumer.manager}: initialize was refused`);
             assert.strictEqual(stderr, "", `${consumer.manager}: stderr`);
             assert.strictEqual(exitCode, 0, `${consumer.manager}: exit code`);
           }
-          // The installs run one after another: the guard covers 4 managers x installTimeout, plus pack and probes.
-        }).pipe(Effect.timeout("12 minutes")),
-      780_000,
+        }).pipe(Effect.timeout(BUDGET)),
+      Duration.toMillis(BUDGET) + 60_000,
     );
   });
 });
 ```
 
-Pass `process.env` in: nothing in the subpath reads `process` itself. Run the bins under `PackedInstall.scrubEnv(process.env)`, the same environment the installs ran under. A requested manager that is not installed lands in `result.unavailable`; pass `require: "all"` to make that a failure instead. Declare in `consumerDependencies` every package the consumer's own code imports besides the carrier: pnpm links only declared dependencies at a project's top level. An entry that names a packed package is written as its `file:` tarball whatever spec you pass, so any range will do; npm fails `EOVERRIDE` when a direct spec differs from its override. The installs run one after another, so an outer `Effect.timeout` must be at least the number of managers times `installTimeout` (four minutes by default), plus the pack and the probes; a tighter guard fires first, as a `TimeoutError` that names no manager. `PackedInstall` is POSIX-only and fails `UnsupportedPlatform` elsewhere.
+Pass `process.env` in: nothing in the subpath reads `process` itself. `runBin` and `command` run under the environment the install ran under, with `options.env` layered over it after the parent manager's context is stripped, so an explicit entry such as `CI: "true"` wins and a key set to `undefined` removes a variable; a non-zero exit is a result, and a bin that cannot spawn or outlives its ceiling (one minute by default) fails `BinFailed`. `PackedInstall.scrubEnv(...)` returns the same scrubbed environment for any other spawn. A requested manager that is not installed lands in `result.unavailable`; pass `require: "all"` to make that a failure instead. Declare in `consumerDependencies` every package the consumer's own code imports besides the carrier: pnpm links only declared dependencies at a project's top level. An entry that names a packed package is written as its `file:` tarball whatever spec you pass, so any range will do; npm fails `EOVERRIDE` when a direct spec differs from its override.
+
+By default only the carrier may declare its bins. If any other packed package declares one of the carrier's bin names, the run fails `BinConflict` before installing: under npm, bun and Yarn's flat layouts either package can take the `.bin` slot (npm and bun were observed to link the package whose name sorts first; Yarn 1 and 4 kept the carrier's, the consumer's direct dependency), so the bin that runs may carry no carrier identity, and the bin check and every bin run could pass on the wrong package. The check reads the `bin` field of the packed packages only (the carrier, the closure and `overrides`): it does not read `directories.bin`, and a registry dependency declaring the same name goes undetected.
+
+Sharing bin names is a supported choice for a carrier whose front ends are also installed on their own: pass `allowSharedBins: true`. The expected bins are still verified present, but `runBin` may then run a front end's bin. `consumer.runCarrierBin(name, args?, options?)` runs the carrier's own bin whichever package took the slot: it resolves `name` through the carrier's installed `package.json` `bin` map and runs that file with `node`, under the same environment as `runBin`. Running through `node` assumes a Node script, drops any shebang flags, and bypasses the executable bit, so it proves the carrier's shim runs, not that it is executable. `consumer.carrierCommand(name, args?, options?)` returns that command, stdin open, for `McpProbe`.
+
+When a closure member needs a dependency the registry does not have yet, for example a sibling checkout's unreleased build linked through a dogfood `file:` override, pass it in `overrides`: package name to a publish-ready package directory, which is `npm pack`ed, or to a `.tgz`, which is used as it is. A relative path resolves against the workspace root. Every consumer steers that package to its tarball through the same override field as the closure, so the carrier's transitive references install it whatever range they ask for, and it joins `result.tarballs`. `workspaceOverrides: true` also takes every `"<name>": "file:<path>"` entry of the root `pnpm-workspace.yaml`'s `overrides:`, which is the link shape a dogfood loop writes; an explicit `overrides` entry wins over one read there. An override naming the carrier or a closure member, a path that is neither a package directory nor a `.tgz`, or a tarball whose manifest has another name fails `InvalidOverride`.
+
+The installs run one after another. `timeoutBudget` adds each manager's `--version` probe (30 seconds), install (`installTimeout`, four minutes by default) and `perConsumer` (one minute by default, one `runBin` at its default ceiling; add a minute per further bin run, or pass `"0 seconds"` for a test that only installs), each package's pack (`packTimeout`, two minutes by default) and manifest read (30 seconds), 30 seconds for the untimed steps, and one minute for cleanup (removing the scratch root when the scope closes, and killing a child after its ceiling interrupts it); a tighter outer guard fires first, as a `TimeoutError` that names no manager. `packages` is a count or the names `PackedInstall.closure` returns for the run's options: pass the run's own options object as the second argument when it sets `closure`, `overrides` or `workspaceOverrides`, and the names equal `Object.keys(result.tarballs)` in order. `PackedInstall.timeoutBudgetFor(runOptions, { perConsumer? })` does both in one Effect, reading `managers`, `installTimeout` and `packTimeout` from the same object. A vitest test's timeout is fixed when it is declared, so await either at module evaluation, as the example above does.
+
+`binProvenance` reads the `.bin` entry as a symlink, which npm, bun and Yarn (under the `node-modules` linker the run configures) write, realpaths it, and walks up to the nearest `package.json` with a string `name`, inside the (realpath'd) consumer directory. `undefined` means only that the entry exists and is not a symlink, which is a pnpm shim. An entry that does not exist, or a link to nothing, fails `MissingBin`; a link into no named package inside the consumer fails `UnownedBin`; any other read failure fails `Io`. `PackedInstall` is POSIX-only and fails `UnsupportedPlatform` elsewhere.
 
 ## Error handling
 

package/SourceBoundary.js

@@ -22,9 +22,10 @@ var Offence = class extends Schema.Class("Offence")({
 		"stdout-write",
 		"console",
 		"console-stdout",
-		"forbidImports"
+		"forbidImports",
+		"forbidTokens"
 	]),
-	/** What matched: the identifier, the call, or the import specifier. */
+	/** What matched: the identifier, the call, the import specifier, or the token. */
 	detail: Schema.String
 }) {
 	/** `file:line:column rule detail`, the form an assertion message reads best in. */
@@ -112,6 +113,23 @@ const memberAfter = (code, at, name) => {
 	while (isIdentifierChar(code[end])) end++;
 	return end > j ? code.slice(j, end) : void 0;
 };
+/**
+* Every offset where `token` appears in `code` as whole text: a token that
+* starts with an identifier character must not continue one (nor follow `#`),
+* and one that ends with an identifier character must not run into another.
+*/
+const tokenOccurrences = (code, token) => {
+	if (token.length === 0) return [];
+	const guardStart = isIdentifierChar(token[0]);
+	const guardEnd = isIdentifierChar(token[token.length - 1]);
+	const found = [];
+	for (let at = code.indexOf(token); at !== -1; at = code.indexOf(token, at + 1)) {
+		if (guardStart && (isIdentifierChar(code[at - 1]) || code[at - 1] === "#")) continue;
+		if (guardEnd && isIdentifierChar(code[at + token.length])) continue;
+		found.push(at);
+	}
+	return found;
+};
 const forbids = (entry, specifier) => entry.endsWith("*") ? specifier.startsWith(entry.slice(0, -1)) : specifier === entry || specifier.startsWith(`${entry}/`);
 const isNodeModule = (specifier, module) => [module, `node:${module}`].some((name) => specifier === name || specifier.startsWith(`${name}/`));
 const FIXTURES = [
@@ -348,6 +366,48 @@ const FIXTURES = [
 		source: "// import { NodeServices } from \"@effect/platform-node\";",
 		rule: { forbidImports: ["@effect/platform*"] },
 		flagged: false
+	},
+	{
+		name: "forbidTokens: the build-time version constant",
+		source: "export const version = process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: the token reached through globalThis",
+		source: "const version = globalThis.process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: a string and a comment",
+		source: "const s = \"process.env.__PACKAGE_VERSION__\"; // process.env.__PACKAGE_VERSION__",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: a longer identifier",
+		source: "const v = process.env.__PACKAGE_VERSION__X;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: the tail of a longer identifier",
+		source: "const v = xprocess.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
+	},
+	{
+		name: "forbidTokens: after a variable named of, divided",
+		source: "const of = 8; const x = of / 2; const v = process.env.__PACKAGE_VERSION__; const y = 8 / 2;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: true
+	},
+	{
+		name: "forbidTokens: a private field",
+		source: "const v = this.#process.env.__PACKAGE_VERSION__;",
+		rule: { forbidTokens: ["process.env.__PACKAGE_VERSION__"] },
+		flagged: false
 	}
 ];
 /**
@@ -383,6 +443,10 @@ const FIXTURES = [
 *
 * - JSX text reads as code;
 *
+* - a variable named `yield` or `await` in a sloppy-mode script reads as the
+*   keyword, so a `/` after it opens a regex (module and strict code reserve
+*   both words);
+*
 * - `forbidImports: ["node:*"]` does not catch a bare built-in such as
 *   `"fs"` (see {@link BoundaryRule}).
 *
@@ -412,7 +476,22 @@ var SourceBoundary = class SourceBoundary {
 	static importSpecifiers = (text) => specifierLiterals(lex(text)).map((literal) => literal.value);
 	/** Whether `text` imports the Node built-in `module`, in either its `node:` or bare form. */
 	static importsNode = (text, module) => SourceBoundary.importSpecifiers(text).some((specifier) => isNodeModule(specifier, module));
-	/** Every place `text` breaks one of `rules`, in source order, attributed to `file`. */
+	/**
+	* Every place `text` breaks one of `rules`, in source order, attributed to `file`.
+	*
+	* @remarks
+	* A `{ forbidTokens }` entry matches its exact text in code only: comments,
+	* strings, template text and regex bodies are blanked first, so a token that
+	* itself contains a string literal never matches, and whitespace inside a
+	* token must match byte for byte. A token that starts with an identifier
+	* character does not match inside a longer identifier or after `#`, and one
+	* that ends with one does not match when an identifier character follows.
+	* A member access is still a match: `globalThis.process.env.X` contains the
+	* token `process.env.X`. A token listed twice is reported once. A token with
+	* no identifier character at either end (`"=>"`, `"?."`) has no edge guard,
+	* so it matches inside longer punctuation, and consecutive matches of it can
+	* overlap.
+	*/
 	static check = (file, text, rules, options) => {
 		const lexed = lex(text);
 		const at = locate(text);
@@ -448,6 +527,11 @@ var SourceBoundary = class SourceBoundary {
 				detail: member === void 0 ? "console" : `console.${member}`
 			});
 		}
+		else if ("forbidTokens" in rule) for (const token of new Set(rule.forbidTokens)) for (const offset of tokenOccurrences(lexed.code, token)) found.push({
+			offset,
+			rule: "forbidTokens",
+			detail: token
+		});
 		else for (const literal of specifiers) if (rule.forbidImports.some((entry) => forbids(entry, literal.value))) found.push({
 			offset: literal.start,
 			rule: "forbidImports",

package/internal/packedInstallPlan.js

@@ -1,5 +1,5 @@
 import { RUNTIME_DEPENDENCY_FIELDS } from "./dependencyFields.js";
-import { Result } from "effect";
+import { Predicate, Result } from "effect";
 
 //#region src/internal/packedInstallPlan.ts
 /** Variables that carry the PARENT run's context into a child package manager. */
@@ -153,22 +153,87 @@ const installArgs = (manager, version) => {
 * is left alone: it resolves wherever the file exists.
 */
 const UNRESOLVABLE = /^(?:workspace:|catalog:|link:|file:(?!\/))/;
-/** Every specifier in a packed manifest's runtime maps that only the workspace could resolve (see `UNRESOLVABLE`). */
-const unresolvedSpecifiers = (manifestJson) => {
+/** Parse a packed manifest into the facts the run checks; the failure is the parse error or a non-object. */
+const readPackedManifest = (manifestJson) => {
 	let manifest;
 	try {
 		manifest = JSON.parse(manifestJson);
 	} catch (cause) {
 		return Result.fail(cause);
 	}
-	if (typeof manifest !== "object" || manifest === null) return Result.fail(/* @__PURE__ */ new Error("package.json is not an object"));
+	if (typeof manifest !== "object" || manifest === null || Array.isArray(manifest)) return Result.fail(/* @__PURE__ */ new Error("package.json is not an object"));
 	const record = manifest;
-	return Result.succeed(RUNTIME_DEPENDENCY_FIELDS.flatMap((field) => {
+	const name = typeof record.name === "string" ? record.name : void 0;
+	const unresolved = RUNTIME_DEPENDENCY_FIELDS.flatMap((field) => {
 		const block = record[field];
 		if (typeof block !== "object" || block === null) return [];
-		return Object.entries(block).filter(([, spec]) => typeof spec === "string" && UNRESOLVABLE.test(spec)).map(([name, spec]) => `${field}.${name}: ${String(spec)}`);
-	}));
+		return Object.entries(block).filter(([, spec]) => typeof spec === "string" && UNRESOLVABLE.test(spec)).map(([dependency, spec]) => `${field}.${dependency}: ${String(spec)}`);
+	});
+	const bin = record.bin;
+	const bins = typeof bin === "string" ? name === void 0 ? [] : [name.replace(/^@[^/]+\//, "")] : typeof bin === "object" && bin !== null && !Array.isArray(bin) ? Object.keys(bin) : [];
+	return Result.succeed({
+		name,
+		unresolved,
+		bins
+	});
+};
+/**
+* The file a manifest's `bin` declares for `name`: a `bin` object's entry, or
+* a `bin` string when `name` is the unscoped package name. `undefined` when
+* the manifest is not a JSON object or declares no such bin.
+*/
+const binTargetOf = (manifestJson, name) => {
+	let manifest;
+	try {
+		manifest = JSON.parse(manifestJson);
+	} catch {
+		return;
+	}
+	if (!Predicate.isObject(manifest) || Array.isArray(manifest)) return void 0;
+	const bin = manifest.bin;
+	if (typeof bin === "string") return typeof manifest.name === "string" && manifest.name.replace(/^@[^/]+\//, "") === name ? bin : void 0;
+	if (!Predicate.isObject(bin) || Array.isArray(bin)) return void 0;
+	const target = bin[name];
+	return typeof target === "string" && Object.hasOwn(bin, name) ? target : void 0;
+};
+/**
+* The first bin the carrier declares that another packed package declares
+* too. Under a flat layout (npm, bun, Yarn's `node-modules` linker) either
+* package can take `node_modules/.bin/<bin>`, so a bin check or a bin run
+* could pass on the wrong package. `PackedInstall.run` refuses it unless the
+* caller shares bin names deliberately (`allowSharedBins`).
+*/
+const binConflict = (carrier, others) => {
+	for (const bin of carrier.bins) {
+		const other = others.find((pkg) => pkg.name !== carrier.name && pkg.bins.includes(bin));
+		if (other !== void 0) return {
+			bin,
+			package: other.name
+		};
+	}
+};
+/** A bare package name, scoped or not: an override key carrying a selector (`a>b`, `a@1`) is not one. */
+const BARE_NAME = /^(?:@[^/@\s>]+\/)?[^/@\s>]+$/;
+/**
+* The `file:` entries of a parsed `pnpm-workspace.yaml`'s `overrides:` map,
+* name to the path after `file:` (relative paths are the caller's to resolve,
+* against the workspace root, as pnpm does). Entries that are not strings,
+* not `file:`, or keyed by anything but a bare package name are skipped, and
+* so is `__proto__`, which no npm package can be named. The map has no
+* prototype, so a package named `constructor` or `prototype` is an ordinary
+* own entry and a missing name never resolves to an inherited member.
+*/
+const fileOverridesOf = (document) => {
+	const out = Object.create(null);
+	if (!Predicate.isObject(document) || !Predicate.isObject(document.overrides) || Array.isArray(document.overrides)) return out;
+	for (const [name, spec] of Object.entries(document.overrides)) {
+		if (name === "__proto__") continue;
+		if (typeof spec === "string" && spec.startsWith("file:") && BARE_NAME.test(name)) out[name] = spec.slice(5);
+	}
+	return out;
 };
+/** An `overrides` value without the `file:` prefix a caller may copy from a workspace file. */
+const overridePath = (spec) => spec.startsWith("file:") ? spec.slice(5) : spec;
 
 //#endregion
-export { closureOf, consumerFiles, installArgs, scrubEnv, unresolvedSpecifiers, versionOf };
+export { binConflict, binTargetOf, closureOf, consumerFiles, fileOverridesOf, installArgs, overridePath, readPackedManifest, scrubEnv, versionOf };

package/internal/sourceText.js

@@ -19,6 +19,13 @@ const REGEX_AFTER = /* @__PURE__ */ new Set([
 	"yield",
 	"await"
 ]);
+/** Declaration keywords: the word after one is a binding name, so a `for (const of of xs)` binding named `of` is not the keyword. */
+const DECLARATIONS = /* @__PURE__ */ new Set([
+	"const",
+	"let",
+	"var",
+	"using"
+]);
 /** Keywords whose parenthesized condition may be followed directly by a statement, so a `/` after its `)` opens a regex. */
 const CONTROL = /* @__PURE__ */ new Set([
 	"if",
@@ -63,26 +70,45 @@ const lex = (text) => {
 		while (start >= 0 && isIdentifierChar(code[start])) start--;
 		return code.slice(start + 1, end + 1).join("");
 	};
+	/**
+	* Whether the code at offset `j` ends a binding a `for...of` head iterates
+	* into: a destructuring pattern, or a name that is neither a declaration
+	* keyword nor itself a keyword (`for (x in of / 2)` divides).
+	*/
+	const endsBinding = (j) => {
+		const char = code[j] ?? "";
+		if (char === "]" || char === "}") return true;
+		return isIdentifierChar(char) && !DECLARATIONS.has(wordAt(j)) && !isRegexKeyword(j);
+	};
+	/** Whether the identifier ending at code offset `j` is a keyword after which a `/` opens a regex. */
+	const isRegexKeyword = (j) => {
+		const word = wordAt(j);
+		if (!REGEX_AFTER.has(word)) return false;
+		const before = lastCode(j - word.length);
+		if (code[before] === "." && !(code[before - 1] === "." && code[before - 2] === ".")) return false;
+		if (word === "of") return parens.at(-1) === "for" && before >= 0 && endsBinding(before);
+		return true;
+	};
 	/** Whether the code at offset `j` ends an operand (a value a postfix operator or a `/` division can follow). */
 	const endsOperand = (j) => {
 		const char = code[j] ?? "";
-		return char === ")" || char === "]" || isIdentifierChar(char) && !REGEX_AFTER.has(wordAt(j));
+		return char === ")" || char === "]" || isIdentifierChar(char) && !isRegexKeyword(j);
 	};
 	/** Whether a `/` here opens a regex, judged by the last code token. */
 	const regexAllowed = () => {
 		const j = lastCode(code.length - 1);
 		if (j < 0) return true;
 		const last = code[j] ?? "";
-		if (isIdentifierChar(last)) return REGEX_AFTER.has(wordAt(j));
+		if (isIdentifierChar(last)) return isRegexKeyword(j);
 		if (last === "!") return !endsOperand(j - 1);
 		if ((last === "+" || last === "-") && code[j - 1] === last) return !endsOperand(lastCode(j - 2));
 		if (last === ")") return controlCloses.has(j);
 		return !"]}\"'`".includes(last);
 	};
-	/** Whether the `(` about to be emitted opens an if/while/for/with condition. */
+	/** The if/while/for/with keyword whose condition the `(` about to be emitted opens, if any. */
 	const opensCondition = () => {
 		const j = lastCode(code.length - 1);
-		if (j < 0 || !isIdentifierChar(code[j])) return false;
+		if (j < 0 || !isIdentifierChar(code[j])) return void 0;
 		let word = wordAt(j);
 		let end = j - word.length;
 		if (word === "await") {
@@ -90,7 +116,7 @@ const lex = (text) => {
 			word = end < 0 ? "" : wordAt(end);
 			end -= word.length;
 		}
-		return CONTROL.has(word) && code[lastCode(end)] !== ".";
+		return CONTROL.has(word) && code[lastCode(end)] !== "." ? word : void 0;
 	};
 	/** Consume a regex literal at `i` if one closes on this line; `false` leaves `i` untouched. */
 	const regex = () => {
@@ -212,7 +238,7 @@ const lex = (text) => {
 			emit(char, true, true);
 			i++;
 		} else if (char === ")") {
-			if (parens.pop() === true) controlCloses.add(code.length);
+			if (parens.pop() !== void 0) controlCloses.add(code.length);
 			emit(char, true, true);
 			i++;
 		} else if (char === "{") {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/workspaces",
-	"version": "0.26.0",
+	"version": "0.27.0",
 	"private": false,
 	"description": "Monorepo workspace tooling as Effect services — root discovery, package enumeration, the dependency graph, package-manager detection, pnpm catalog resolution, lockfile IO and git-based change detection.",
 	"keywords": [