@warlock.js/web 5.0.0

package/esm/vite/gate-a-resolve.mjs

@@ -0,0 +1,834 @@
+import { builtinModules } from "node:module";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "@babel/parser";
+
+//#region ../web/src/vite/gate-a-resolve.ts
+/**
+* Gate A — `resolveId` refusal for the client build.
+*
+* Resolution fails for import PATHS that can never be client-safe:
+*   1. Node builtins (`fs`, `crypto`, `node:*`, ...) — see `isNodeBuiltin` for
+*      why the set is ASKED of Node rather than written down, and
+*      `externalizedBuiltins` for the one route that reaches a chunk
+*      without passing through `resolveId` at all. This rule is judged for
+*      EVERY importer, in or out of `GOVERNED_SCOPES` — see its note below.
+*   2. `@warlock.js/*` / `@mongez/*` packages whose `package.json` carries
+*      `"warlock": { "environment": "server" }`. An ABSENT marker is NOT a
+*      refusal — see the burden note on `createEnvironmentClassifier`. Judged
+*      only for imports whose importer is inside the app root — see
+*      `isInsideAppRoot` note below. An import statement carrying no VALUE
+*      binding is not refused but ERASED — see the type-only note on
+*      `recordImportKinds`.
+*   3. Server-only modules declared by FILE NAME: `*.server.ts` files,
+*      anything under a `.server/` directory, and — for the app's OWN source
+*      only — anything under a plain `server/` directory segment.
+*   4. Local modules outside a `$module/web/` (or `src/web/`) folder that are
+*      not a recognized universal surface (`*.page.tsx`, `layout.tsx`). The app
+*      root (`src/web/root.tsx`) is admitted by the `web/` FOLDER rule above,
+*      not by its name — see the note in `isRecognizedUniversalSurface`. A
+*      specifier that omits its file extension is judged on the file it will
+*      actually load, not on the extensionless string — see
+*      `completeLocalModulePath`.
+*   5. The `server-only` npm package — a module importing it has declared
+*      itself server-side and cannot reach the browser. Judged by NAME, right
+*      after rule 1 and ahead of rule 2's scope check; see
+*      `BOUNDARY_DECLARATION_PACKAGES`.
+*
+* Gate B (inline secrets), Gate C (output verification) and the SSR mirror
+* rule (`*.client.*` refusal / `clientOnly()`) are NOT this gate. Do not
+* extend this file to cover them; they are separate, later slices.
+*/
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+/**
+* Node's OWN list of its builtins, read at runtime from `node:module`, never
+* copied into this file. A deny-list of names would be correct on the day it
+* was written and wrong on the day Node ships the next builtin — `node:sqlite`
+* and `node:test` are both recent enough to have missed any list this repo
+* could have hand-typed — and a fence that fails open on names nobody has
+* added yet is a fence with an expiry date nobody is watching. Asking the
+* runtime costs one import and cannot drift: the process doing the bundling is
+* the same process whose builtins are at issue.
+*
+* The `node:`-prefixed forms are handled separately (see `isNodeBuiltin`), so
+* this set only needs the names as `builtinModules` reports them.
+*/
+const NODE_BUILTINS = new Set(builtinModules);
+/**
+* Every SPELLING of every builtin — bare and `node:`-prefixed — derived from
+* the set above rather than enumerated. Used only by
+* `externalizedBuiltins`, which has to interrogate a predicate it does
+* not control and therefore needs concrete strings to ask about. `node:test`,
+* `node:sea` and friends are reported by `builtinModules` ALREADY prefixed and
+* have no bare form at all, so they are passed through unchanged.
+*/
+const NODE_BUILTIN_SPELLINGS = [...NODE_BUILTINS].flatMap((name) => name.startsWith("node:") ? [name] : [name, `node:${name}`]);
+/**
+* Scopes whose `package.json` Gate A will read for a `warlock.environment`
+* marker. Third-party packages outside these two scopes (react, lodash, ...)
+* are never asked for this field — they are judged solely by Gate A's other,
+* import-based rules. Note that a governed package is only REFUSED when it
+* declares `"server"`; being in scope is not itself a refusal.
+*/
+const GOVERNED_SCOPES = ["@warlock.js/", "@mongez/"];
+function isGovernedScope(source) {
+	return GOVERNED_SCOPES.some((scope) => source.startsWith(scope));
+}
+/**
+* The package root of a scoped specifier, e.g. `@warlock.js/core/db` ->
+* `@warlock.js/core`, `@warlock.js/core` -> `@warlock.js/core`.
+*/
+function governedPackageNameOf(source) {
+	const [scope, name] = source.split("/");
+	return `${scope}/${name}`;
+}
+/**
+* Indexes every `@warlock.js/*` / `@mongez/*` workspace member's
+* `package.json` path from the monorepo root's `package.json` `workspaces`
+* array (`48cb4ae7` discipline — enumerated, never hand-typed). Walks up from
+* this file looking for the workspace root (identified by
+* `name: "warlock-workspace"`) so it works whether this module runs from
+* `web/src/vite/` (dev) or a compiled `web/esm/vite/` output. Returns
+* `undefined` when no monorepo root is reachable — e.g. this package
+* installed standalone in a consuming app — in which case governed packages
+* are located via `node_modules` instead (see `findNodeModulesPackageJson`).
+*/
+function findWorkspaceIndex(startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 6; depth++) {
+		const candidate = path.join(dir, "package.json");
+		if (existsSync(candidate)) try {
+			const pkg = JSON.parse(readFileSync(candidate, "utf-8"));
+			if (pkg?.name === "warlock-workspace" && Array.isArray(pkg.workspaces)) {
+				const packageJsonByName = /* @__PURE__ */ new Map();
+				for (const workspace of pkg.workspaces) {
+					const workspacePkgPath = path.join(dir, workspace, "package.json");
+					if (!existsSync(workspacePkgPath)) continue;
+					try {
+						const workspacePkg = JSON.parse(readFileSync(workspacePkgPath, "utf-8"));
+						if (typeof workspacePkg.name === "string" && isGovernedScope(`${workspacePkg.name}/`)) packageJsonByName.set(workspacePkg.name, workspacePkgPath);
+					} catch {}
+				}
+				return { packageJsonByName };
+			}
+		} catch {}
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+}
+/**
+* Locates a governed-scope package's `package.json` the ordinary Node
+* resolution way — walking up `node_modules` directories from `startDir` —
+* for packages that are not monorepo workspace members (published
+* dependencies, e.g. `@mongez/reinforcements`, or any governed package when
+* this module runs standalone outside the monorepo).
+*/
+function findNodeModulesPackageJson(pkgName, startDir) {
+	let dir = startDir;
+	for (let depth = 0; depth < 20; depth++) {
+		const candidate = path.join(dir, "node_modules", pkgName, "package.json");
+		if (existsSync(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+}
+/**
+* The governed-scope package name owning `normalized` (an already-`/`-
+* normalized absolute path), found by taking the LAST `node_modules/`
+* segment — nested `node_modules` (a dependency's own vendored copy) must
+* resolve to the nearest enclosing package, not the outermost one. Returns
+* `undefined` for paths with no `node_modules` segment, or whose owning
+* package isn't in a governed scope.
+*/
+function packageNameFromNodeModulesPath(normalized) {
+	const segments = normalized.split("node_modules/");
+	if (segments.length < 2) return void 0;
+	const afterLast = segments[segments.length - 1];
+	const parts = afterLast.split("/");
+	const name = afterLast.startsWith("@") ? `${parts[0]}/${parts[1]}` : parts[0];
+	return isGovernedScope(`${name}/`) ? name : void 0;
+}
+/**
+* The two npm packages whose entire published API is a declaration of which
+* side of the client/server boundary their importer belongs to: importing
+* `server-only` says "this module must never reach the browser", importing
+* `client-only` says the mirror. Mapped to the environment each one declares
+* of its IMPORTER.
+*
+* Recognized by NAME, ahead of rule 2's scope check, for a reason that is not
+* a special case: both sit outside `GOVERNED_SCOPES`, so `environmentOf` is
+* never consulted for them under ANY default — no marker resolution, current
+* or future, can ever classify them. Their name IS the marker, and reading it
+* is the same move rule 3 makes when it reads `.server.ts` off a file name.
+*
+* Only a `"server"` declaration is a violation HERE. `client-only` is
+* recognized and deliberately permitted: this is the client build, so a module
+* declaring itself client-side is exactly where it belongs. Judging it is the
+* SSR mirror rule's job, and that gate is not this file (see the header note).
+*/
+const BOUNDARY_DECLARATION_PACKAGES = {
+	"server-only": "server",
+	"client-only": "client"
+};
+/**
+* The boundary-declaration package a specifier reaches, if any — matching the
+* package itself or a subpath of it (`server-only/empty` is a real published
+* entry point), never a merely similar name like `server-only-utils`.
+*/
+function boundaryDeclarationOf(source) {
+	for (const [name, declares] of Object.entries(BOUNDARY_DECLARATION_PACKAGES)) if (source === name || source.startsWith(`${name}/`)) return {
+		name,
+		declares
+	};
+}
+/**
+* Whether a specifier names a Node builtin, in either spelling.
+*
+* The `node:` prefix is answered by SHAPE, not by membership: the prefix is
+* reserved by Node for builtins and nothing else can ever legally claim it, so
+* `node:anything` is refused even when `builtinModules` has never heard of it.
+* That covers the prefix-only builtins (`node:test`, `node:sqlite`, `node:sea`)
+* on Node versions whose `builtinModules` omits them, and every builtin Node
+* has not shipped yet, without this file knowing a single one of their names.
+*
+* Bare names fall through to Node's own set, which already carries the subpath
+* entries (`fs/promises`, `stream/web`, `timers/promises`, ...) as first-class
+* members — they need no prefix matching of their own.
+*/
+function isNodeBuiltin(source) {
+	if (source.startsWith("node:")) return true;
+	return NODE_BUILTINS.has(source);
+}
+function normalize(filePath) {
+	return filePath.replace(/\\/g, "/");
+}
+/**
+* A plain `server/` path segment, tested against a path ALREADY made relative
+* to the app root — never against the absolute path. An app checked out at
+* `D:/work/server/shop` would otherwise have every one of its own files match.
+*/
+const APP_SERVER_SEGMENT = /(^|\/)server(\/|$)/;
+function isServerFile(resolvedPath, appRoot) {
+	const normalized = normalize(resolvedPath);
+	if (/\.server(\.[jt]sx?)?$/.test(normalized)) return true;
+	if (/(^|\/)\.server(\/|$)/.test(normalized)) return true;
+	if (isAppSourcePath(resolvedPath, appRoot)) {
+		if (APP_SERVER_SEGMENT.test(normalize(path.relative(appRoot, resolvedPath)))) return true;
+	}
+	return false;
+}
+/**
+* Rule 4's subject set: local files that CARRY CODE. Deliberately the same
+* shape as `PARSEABLE_MODULE_EXTENSIONS` below — one notion of "this is a
+* JS/TS module" for the whole file — which also picks up `.mts`/`.cts`, absent
+* from the earlier hand-spelled `/\.(tsx?|jsx?|mjs|cjs)$/`. `.mts` is a real
+* module extension Vite resolves, so a file wearing it was walking past rule 4
+* with its extension written out in full.
+*
+* Every extension `IMPLICIT_MODULE_EXTENSIONS` can append MUST match this —
+* see the note there.
+*/
+const LOCAL_MODULE_EXTENSIONS = /\.([cm]?[jt]sx?)$/;
+/**
+* The extensions a local specifier may leave off, in Vite's own
+* `resolve.extensions` order.
+*
+* `.json` is deliberately absent: it is not code-carrying, so completing to it
+* would only hand rule 4 a path it exempts one line later, and the exemption is
+* the correct answer for a data file.
+*
+* The list and `LOCAL_MODULE_EXTENSIONS` have to agree in one direction: an
+* extension this list can PRODUCE but that regex does not RECOGNIZE is a fresh
+* escape hatch of exactly the shape this completion exists to close — the
+* judged path would gain a suffix and still be waved through. Pinned by case 32
+* in the spec. The order only decides which of two same-named files gets
+* judged, and every rule downstream (`isServerFile`, `isWithinModuleWebFolder`,
+* `isRecognizedUniversalSurface`) answers identically for `x.ts` and `x.js`, so
+* matching Vite is for least surprise rather than for correctness.
+*/
+const IMPLICIT_MODULE_EXTENSIONS = [
+	".mjs",
+	".js",
+	".mts",
+	".ts",
+	".jsx",
+	".tsx",
+	".cjs",
+	".cts"
+];
+function isFile(candidate) {
+	try {
+		return statSync(candidate).isFile();
+	} catch {
+		return false;
+	}
+}
+/**
+* The file a local specifier will ACTUALLY load, given the path `resolveId`
+* derived from it with a raw `path.resolve`.
+*
+* Without this, rule 4 was escapable by writing the import the ordinary way.
+* `resolveId` runs before anything appends an extension, so `./services/helper`
+* arrives as a path ending in `helper`; rule 4 asks for a code extension —
+* rightly, since it has no business judging `./logo.css` — finds none, and
+* declines to judge at all. `./x.middleware` slipped the same way while LOOKING
+* like it had an extension, and so did `./services` resolving to
+* `services/index.ts`. Measured: all three built clean (spec cases 25-28, 32).
+*
+* Asked of the FILESYSTEM rather than answered from the string, because the
+* string cannot tell an omitted extension from a real one: `.middleware` is not
+* a code extension and not an asset extension either, and only the disk knows
+* whether `thing.middleware.ts` is sitting there. Probing `<path><ext>` and
+* then `<path>/index<ext>` is what Vite is about to do anyway, so the rule
+* judges the file that will really be bundled.
+*
+* Deliberately NOT cached. A handful of `stat` calls per local specifier is
+* what every resolver in the pipeline already spends, and a cache would go
+* stale in watch mode exactly when a file is created or deleted — which is the
+* moment a fence must not be answering from memory.
+*
+* Three early exits, each a case where completion has nothing to add or no
+* business guessing:
+*   - a non-absolute path (a bare package specifier — rules 1/2's business)
+*     or a virtual `\0` id;
+*   - a query suffix (`./helper?raw`, `./thing?worker`). The query changes what
+*     the id MEANS to Vite, and inventing a file for it is a separate decision
+*     from this one. Rule 4 still does not judge these — a known gap, narrower
+*     than the one being closed here, and not widened by guesswork;
+*   - a path that already carries a code extension, or that already exists as a
+*     real non-code file (an asset — `./theme.css`), where the path on hand is
+*     the answer.
+*/
+function completeLocalModulePath(judgedPath) {
+	if (!path.isAbsolute(judgedPath)) return judgedPath;
+	if (judgedPath.includes("?") || judgedPath.includes("\0")) return judgedPath;
+	if (LOCAL_MODULE_EXTENSIONS.test(judgedPath)) return judgedPath;
+	if (path.extname(judgedPath) !== "" && isFile(judgedPath)) return judgedPath;
+	for (const extension of IMPLICIT_MODULE_EXTENSIONS) {
+		const candidate = `${judgedPath}${extension}`;
+		if (isFile(candidate)) return candidate;
+	}
+	for (const extension of IMPLICIT_MODULE_EXTENSIONS) {
+		const candidate = path.join(judgedPath, `index${extension}`);
+		if (isFile(candidate)) return candidate;
+	}
+	return judgedPath;
+}
+/**
+* Whether a judged path is the APP'S OWN SOURCE, as opposed to a dependency's
+* internals. This is Gate A's single definition of that boundary — rules 3
+* and 4 both call it, and `packageNameForFilePath` draws the same line for
+* Gate C. Two conditions, both already required by rule 4 before this was
+* extracted:
+*
+*   - inside `appRoot` (a monorepo sibling or any other path resolution has
+*     left the app root for is that package's own business), and
+*   - not under a `node_modules/` segment. Nested `node_modules` inside
+*     `appRoot` is the ORDINARY case for a dependency, and Vite's optimized
+*     dependency chunks (`<appRoot>/node_modules/.vite/deps`) even import one
+*     another relatively.
+*
+* Bare package specifiers never reach here as app source: for those the
+* "judged path" is still the specifier string itself (see `resolveId`), which
+* is not absolute. They are rule 2's business.
+*/
+function isAppSourcePath(resolvedPath, appRoot) {
+	if (!path.isAbsolute(resolvedPath)) return false;
+	if (!isInsideAppRoot(resolvedPath, appRoot)) return false;
+	return !normalize(resolvedPath).includes("/node_modules/");
+}
+function isInsideAppRoot(resolvedPath, appRoot) {
+	const relative = path.relative(appRoot, resolvedPath);
+	return !!relative && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+/** Files whose source Gate A will parse for import kinds. */
+const PARSEABLE_MODULE_EXTENSIONS = /\.([cm]?[jt]sx?)$/;
+/** Cheap pre-filter: no governed scope in the text, nothing to classify. */
+const GOVERNED_SCOPE_MENTION = /@warlock\.js\/|@mongez\//;
+/**
+* The id Gate A resolves a type-only edge into a server-only package to. `\0`
+* is the virtual-module convention, which also keeps Gate C from trying to
+* attribute this id to a package on disk (`packageNameForFilePath` returns
+* `undefined` for any id containing `\0` — see its note).
+*/
+const TYPE_ONLY_ERASED_ID = "\0warlock:type-only-erased";
+/**
+* Rollup module ids carry query suffixes (`?v=`, `?used`, ...) that differ
+* between the `transform` id and a later `importer`. Both sides key through
+* here so they agree.
+*/
+function moduleKey(id) {
+	return normalize(id.split("?")[0]);
+}
+function parserPluginsFor(id) {
+	return /\.[cm]?ts$/.test(moduleKey(id)) ? ["typescript"] : ["typescript", "jsx"];
+}
+/**
+* Whether an `ImportDeclaration`'s specifier list is entirely type-only.
+*
+* Both spellings count, because both are erased: the statement form
+* (`import type { X } from "P"`, `decl.importKind === "type"`) and the inline
+* form (`import { type X } from "P"`, every specifier's own `importKind`).
+* The inline form is the one that matters in practice — under
+* `verbatimModuleSyntax` TypeScript/esbuild emit it VERBATIM as
+* `import {} from "P"`, so it is the only one that survives to `resolveId` at
+* all.
+*
+* An EMPTY specifier list (`import "P"`) is deliberately `"value"`: a bare
+* side-effect import is a real runtime edge that the author wrote on purpose,
+* and it is indistinguishable — post-esbuild — from the erased form. Treating
+* it as type-only would turn this carve-out into a hole big enough to smuggle
+* a whole server package through.
+*/
+function importDeclarationKind(decl) {
+	if (decl.importKind === "type") return "type";
+	if (decl.specifiers.length === 0) return "value";
+	return decl.specifiers.every((spec) => spec.importKind === "type") ? "type" : "value";
+}
+function exportDeclarationKind(stmt) {
+	if (stmt.exportKind === "type") return "type";
+	const specifiers = stmt.specifiers ?? [];
+	if (specifiers.length === 0) return "value";
+	return specifiers.every((spec) => spec.exportKind === "type") ? "type" : "value";
+}
+/**
+* Every specifier reached by a RUNTIME expression rather than a static
+* import/export statement — `import("P")` and `require("P")` — found by a
+* duck-typed walk of the whole program, not just its top level, because both
+* are ordinary expressions and can sit anywhere.
+*
+* These are unconditionally `"value"`. A dynamic import of a server-only
+* package is exactly the edge rule 2 exists to refuse, and it reaches
+* `resolveId` with the same specifier string a static import would, so
+* without this walk a file could hold `import { type X } from "P"` beside
+* `await import("P")` and have the static statement's kind exempt the dynamic
+* one.
+*/
+function collectRuntimeSpecifiers(node, into) {
+	if (!node || typeof node !== "object") return;
+	if (Array.isArray(node)) {
+		for (const item of node) collectRuntimeSpecifiers(item, into);
+		return;
+	}
+	const record = node;
+	if (typeof record.type !== "string") return;
+	if (record.type === "CallExpression" || record.type === "ImportExpression") {
+		const callee = record.callee;
+		if (record.type === "ImportExpression" || callee?.type === "Import" || callee?.type === "Identifier" && callee.name === "require") {
+			const arg = record.source ?? record.arguments?.[0];
+			if (arg?.type === "StringLiteral" && typeof arg.value === "string") into.add(arg.value);
+		}
+	}
+	for (const key of Object.keys(record)) {
+		if (key === "type" || key === "start" || key === "end" || key === "loc" || key === "range") continue;
+		if (key === "leadingComments" || key === "trailingComments" || key === "innerComments" || key === "extra") continue;
+		collectRuntimeSpecifiers(record[key], into);
+	}
+}
+/**
+* Classifies every specifier `code` imports as `"value"` or `"type"`. Returns
+* `undefined` when the source could not be parsed — the caller reads that as
+* "no information", which leaves rule 2 refusing exactly as it does today.
+*/
+function classifyImportKinds(code, id) {
+	let ast;
+	try {
+		ast = parse(code, {
+			sourceType: "module",
+			plugins: parserPluginsFor(id),
+			errorRecovery: false
+		});
+	} catch {
+		return;
+	}
+	const kinds = /* @__PURE__ */ new Map();
+	const record = (source, kind) => {
+		if (kind === "value" || !kinds.has(source)) kinds.set(source, kind);
+	};
+	for (const stmt of ast.program.body) {
+		if (stmt.type === "ImportDeclaration") {
+			record(stmt.source.value, importDeclarationKind(stmt));
+			continue;
+		}
+		if ((stmt.type === "ExportNamedDeclaration" || stmt.type === "ExportAllDeclaration") && stmt.source) record(stmt.source.value, exportDeclarationKind(stmt));
+	}
+	const runtimeSpecifiers = /* @__PURE__ */ new Set();
+	collectRuntimeSpecifiers(ast.program.body, runtimeSpecifiers);
+	for (const source of runtimeSpecifiers) kinds.set(source, "value");
+	return kinds;
+}
+/**
+* Rule 2's predicate on its own, extracted so `resolveId` can ask the question
+* a SECOND time after `ruleViolation` has declined to refuse: a type-only edge
+* into a server-only package is not a violation, but it is not an ordinary
+* import either — it is erased (see `TYPE_ONLY_ERASED_ID`). Asking separately,
+* rather than short-circuiting inside `ruleViolation`, is what keeps rules 3
+* and 4 authoritative over a type-only specifier: `@warlock.js/core/db.server`
+* imported for its types alone is still refused, by rule 3, because
+* `ruleViolation` still runs to completion first.
+*/
+function isServerMarkedGovernedPackage(source, importer, environmentOf, appRoot) {
+	if (!isGovernedScope(source)) return false;
+	if (importer && !isInsideAppRoot(importer, appRoot)) return false;
+	return environmentOf(governedPackageNameOf(source)) === "server";
+}
+function ruleViolation(source, resolvedPath, importer, environmentOf, appRoot, isTypeOnlyEdge) {
+	if (isNodeBuiltin(source)) return {
+		cause: `"${source}" is a Node.js builtin module and cannot run in the browser.`,
+		fix: `Move the code that needs "${source}" into a *.server.ts file or a server-only loader/controller, and pass only serializable data to the client.`
+	};
+	const boundaryDeclaration = boundaryDeclarationOf(source);
+	if (boundaryDeclaration?.declares === "server") {
+		const declarer = importer ? displayName(importer) : source;
+		return {
+			cause: `"${declarer}" imports "${boundaryDeclaration.name}" — that package publishes no API at all, only a declaration: any module importing it is server-side and must never be bundled for the browser.`,
+			fix: `Move the server work in "${declarer}" into a *.server.ts file, a server/ folder, a loader, or a controller — the client only needs the serialized data it returns — or, if this module is genuinely browser-safe, remove its "${boundaryDeclaration.name}" import.`
+		};
+	}
+	if (!isTypeOnlyEdge && isServerMarkedGovernedPackage(source, importer, environmentOf, appRoot)) {
+		const pkgName = governedPackageNameOf(source);
+		return {
+			cause: `"${source}" resolves into ${pkgName}, a server-only ${pkgName.startsWith("@warlock.js/") ? "@warlock.js" : "@mongez"} package — it declares "warlock": { "environment": "server" } in its package.json.`,
+			fix: `Move this import behind a *.server.ts file, a server/ folder, a loader, or a controller — the client only needs the serialized data it returns — or, if ${pkgName} is genuinely universal/client-safe, change its marker to "warlock": { "environment": "universal" } (or "client").`
+		};
+	}
+	if (isServerFile(resolvedPath, appRoot)) return {
+		cause: `"${source}" is a server-only file — its name declares it: it matches *.server.ts, or it lives under a .server/ directory, or under a server/ folder in this app's source.`,
+		fix: `Import the data this file produces through a loader instead of importing the server file directly, or move the shared logic into a universal helper under $module/web/ — outside any server/ folder and without a .server suffix.`
+	};
+}
+/**
+* The label one hop of an import chain carries.
+*
+* A basename is enough for the app's own source, where file names are chosen
+* and distinct. It is not enough for a dependency: a large share of
+* node_modules resolves to a file literally called `index.js`, and a chain
+* reading `page.tsx → index.js → node:fs` names the culprit for nobody — which
+* is the failure mode where people switch the fence off instead of fixing the
+* import. Anything under a `node_modules/` segment is therefore labelled with
+* its path from the LAST such segment (`vendor-node-lib/index.js`), so a
+* vendored nested copy reports the package that actually holds the file rather
+* than the one at the top of the tree.
+*/
+function displayName(id) {
+	const normalized = normalize(id);
+	const segments = normalized.split("node_modules/");
+	if (segments.length < 2) return path.basename(normalized);
+	return segments[segments.length - 1];
+}
+/**
+* Every Node builtin the Rollup config would externalize — empty when none,
+* which is the only shape that lets a build proceed past `buildStart`.
+*
+* This is the one route a builtin can take into a browser chunk without ever
+* being offered to `resolveId`: Rollup consults `external` FIRST, and an
+* externalized specifier is emitted into the output verbatim — measured, on
+* this gate's own fixture, as a clean build whose chunk still opens with
+* `import { readFileSync } from "node:fs"`. No `resolveId` rule can close that,
+* because the hook is never called; the check has to happen against the config
+* itself, before any module is loaded.
+*
+* Asked as a QUESTION of the normalized predicate rather than by reading an
+* array, because `external` may legitimately be a string, a RegExp, an array of
+* either, or a function — Rollup normalizes all of them into the function
+* handed to `buildStart`, and asking it about each builtin spelling is the only
+* form of the check that covers every shape. A predicate that throws on an
+* unexpected shape of argument is read as "not external": this guard exists to
+* catch a config that says yes, and inventing a refusal out of someone else's
+* exception would be a false positive with no evidence behind it.
+*
+* This fires on CONFIGURATION, not on an actual import — nothing need import
+* `fs` for it to trip. That is on purpose: the config has already decided the
+* fence does not apply, and a build that would silently pass today only because
+* no import happens to exist yet is not a build anyone should trust tomorrow.
+*/
+function externalizedBuiltins(isExternal) {
+	if (typeof isExternal !== "function") return [];
+	const asks = isExternal;
+	return NODE_BUILTIN_SPELLINGS.filter((specifier) => {
+		try {
+			return asks(specifier, void 0, false) === true;
+		} catch {
+			return false;
+		}
+	});
+}
+/**
+* The `warlock.environment` marker classifier (rule 2). Extracted from
+* `gateAResolve` so Gate C can classify packages it finds in the EMITTED
+* bundle graph with the identical resolution logic — same workspace index,
+* same `node_modules` fallback, same default — rather than a second,
+* potentially-drifting implementation.
+*
+* An ABSENT marker classifies as `"universal"`, i.e. allowed. This is a
+* deliberate reversal of the earlier burden-inversion default. A marker is
+* shipped metadata: making silence mean "refuse" meant every browser-safe
+* package we own needed a marker AND a release before any app could boot, and
+* a package the app does not control (`@mongez/react-atom`) could not be
+* imported at all. Refusal is now driven by information that is PRESENT — an
+* explicit `"server"` marker, or a server-only file name (rule 3) — which the
+* app author can always supply themselves without waiting on a release. The
+* marker mechanism itself is untouched and still authoritative when set.
+*/
+function createEnvironmentClassifier(options = {}) {
+	const forcedServerPackages = options.serverPackages ? new Set(options.serverPackages) : void 0;
+	const appRoot = path.resolve(options.appRoot ?? process.cwd());
+	const workspaceIndex = findWorkspaceIndex(__dirname);
+	const environmentCache = /* @__PURE__ */ new Map();
+	function environmentOf(pkgName) {
+		if (forcedServerPackages?.has(pkgName)) return "server";
+		const cached = environmentCache.get(pkgName);
+		if (cached) return cached;
+		const packageJsonPath = workspaceIndex?.packageJsonByName.get(pkgName) ?? findNodeModulesPackageJson(pkgName, appRoot);
+		let environment = "universal";
+		if (packageJsonPath) try {
+			const marker = JSON.parse(readFileSync(packageJsonPath, "utf-8"))?.warlock?.environment;
+			if (marker === "server" || marker === "universal" || marker === "client") environment = marker;
+		} catch {}
+		environmentCache.set(pkgName, environment);
+		return environment;
+	}
+	function packageNameForFilePath(absPath) {
+		if (absPath.includes("\0")) return void 0;
+		const normalized = normalize(path.resolve(absPath));
+		const nodeModulesMatch = packageNameFromNodeModulesPath(normalized);
+		if (nodeModulesMatch) return nodeModulesMatch;
+		if (isInsideAppRoot(normalized, appRoot)) return void 0;
+		if (workspaceIndex) for (const [name, pkgJsonPath] of workspaceIndex.packageJsonByName) {
+			const root = `${normalize(path.dirname(pkgJsonPath))}/`;
+			if (normalized.startsWith(root)) return name;
+		}
+	}
+	return {
+		appRoot,
+		environmentOf,
+		packageNameForFilePath
+	};
+}
+/**
+* The client-build Vite plugin. `vite` is only imported for its types
+* (`import type`), so this module carries no runtime dependency on `vite`
+* being installed — it is a `peerDependenciesMeta.optional` peer.
+*/
+function gateAResolve(options = {}) {
+	const { appRoot, environmentOf } = createEnvironmentClassifier(options);
+	const importerOf = /* @__PURE__ */ new Map();
+	/**
+	* Module key -> that module's specifier classification, filled by the
+	* `transform` hook below and read by `resolveId`.
+	*
+	* This is the answer to the one structural problem rule 2 has: `resolveId`
+	* receives a specifier STRING and an importer path, never an AST, so it
+	* cannot see for itself whether an import was type-only. The information
+	* exists exactly once in the pipeline — in the module's PRE-esbuild
+	* TypeScript source — so it is captured there and carried forward.
+	*
+	* Three routes were available; this is why the other two lost:
+	*
+	*  - Recognizing the POST-esbuild shape (`import {} from "P"`) from inside
+	*    `resolveId`. Rejected as unsound, not merely awkward: esbuild emits the
+	*    identical `import {} from "P"` for a genuine bare side-effect import
+	*    under some settings, so the shape cannot separate "erased type import"
+	*    from "the author asked for this package's side effects". That is a
+	*    false NEGATIVE in a security fence — the one direction of error this
+	*    gate must never make — and it would additionally depend on
+	*    `getModuleInfo(importer).code` being populated during a dependency's
+	*    `resolveId`, which is undocumented Rollup ordering.
+	*  - Moving rule 2 wholesale into a `transform` pass. Rejected as too wide
+	*    for this change: `transform` never runs for entry, virtual or
+	*    externalized importers, so rule 2 would silently stop judging edges it
+	*    judges today, and the import-chain machinery (`importerOf`) is built
+	*    out of `resolveId`'s importer argument. Gate A is a `resolveId` fence
+	*    by identity; only the type-only QUESTION moves, never the refusal.
+	*  - Reusing `projection.ts`'s existing parse (`projectModule`). Rejected as
+	*    a coupling, though it is the right TECHNIQUE and is copied here:
+	*    projection parses only `*.page.tsx`/`layout`/`root`, records binding
+	*    READERS rather than import KINDS, and rewrites code. Gate A must work
+	*    standalone — every case in `gate-a-resolve.spec.ts` runs
+	*    `gateAResolve()` with no projection in the array — so it cannot depend
+	*    on another plugin having run.
+	*
+	* A module absent from this map (unparseable, never transformed, not JS/TS)
+	* yields no `"type"` answer, so rule 2 refuses exactly as it does today.
+	* Missing information fails CLOSED.
+	*/
+	const importKindsByModule = /* @__PURE__ */ new Map();
+	function recordImportKinds(code, id) {
+		const key = moduleKey(id);
+		if (key.includes("\0")) return;
+		if (!PARSEABLE_MODULE_EXTENSIONS.test(key)) return;
+		if (!GOVERNED_SCOPE_MENTION.test(code)) return;
+		const kinds = classifyImportKinds(code, key);
+		if (!kinds) return;
+		const existing = importKindsByModule.get(key);
+		if (!existing) {
+			importKindsByModule.set(key, kinds);
+			return;
+		}
+		for (const [source, kind] of kinds) if (kind === "value" || !existing.has(source)) existing.set(source, kind);
+	}
+	function isTypeOnlyEdge(source, importer) {
+		if (!importer) return false;
+		return importKindsByModule.get(moduleKey(importer))?.get(source) === "type";
+	}
+	/**
+	* How many `resolve.alias` entries this build declares, captured from the
+	* RESOLVED Vite config (`configResolved`) rather than guessed.
+	*
+	* Purely diagnostic, and it is the one thing the alias table can tell Gate A
+	* that the resolver cannot. The gate does not match aliases itself — see the
+	* note on the alias pass in `resolveId` for why asking Vite's own resolver
+	* beats re-deriving `@rollup/plugin-alias`'s find/replacement semantics. But
+	* when a specifier resolves to NOTHING, the count is the difference between
+	* "a dependency is missing" and "this build never installed the alias table
+	* its own tsconfig `paths` describe" — which is exactly the v5 production
+	* client build's state, and the actionable half of that warning.
+	*
+	* `undefined` when `configResolved` never fired (plain Rollup, or a unit
+	* harness), which the message reports as unknown rather than as zero.
+	*/
+	let declaredAliasCount;
+	function buildChain(importer) {
+		const chain = [];
+		let current = importer;
+		const seen = /* @__PURE__ */ new Set();
+		while (current && !seen.has(current)) {
+			seen.add(current);
+			chain.unshift(displayName(current));
+			current = importerOf.get(current);
+		}
+		return chain;
+	}
+	return {
+		name: "warlock:gate-a-resolve",
+		enforce: "pre",
+		/** Records the alias-table size; see `declaredAliasCount`. Judges nothing. */
+		configResolved(config) {
+			const alias = config.resolve?.alias;
+			if (Array.isArray(alias)) declaredAliasCount = alias.length;
+			else if (alias && typeof alias === "object") declaredAliasCount = Object.keys(alias).length;
+			else declaredAliasCount = 0;
+		},
+		/**
+		* The config-level half of rule 1 — see `externalizedBuiltins` for why a
+		* `resolveId` fence cannot cover it on its own. Runs once per build, before
+		* the first module is loaded, so the refusal lands before anything has been
+		* bundled.
+		*/
+		buildStart(inputOptions) {
+			const externalized = externalizedBuiltins(inputOptions.external);
+			if (externalized.length === 0) return;
+			const shown = externalized.slice(0, 5).join(", ");
+			const rest = externalized.length > 5 ? `, and ${externalized.length - 5} more` : "";
+			this.error([
+				`Gate A refused this build: its Rollup "external" config would let Node builtins through the fence.`,
+				``,
+				`Externalized builtins: ${shown}${rest}`,
+				`Cause: Rollup consults "external" BEFORE any resolveId hook, so an externalized builtin is never offered to Gate A and is emitted into the browser chunk verbatim (e.g. import { readFileSync } from "node:fs"). No import of one has to exist yet — the configuration alone has already disabled rule 1.`,
+				`Fix: remove the Node builtins from build.rollupOptions.external (keeping any non-builtin entries), and move the code that needs them into a *.server.ts file, a server/ folder, a loader, or a controller. If this build targets Node rather than the browser, it should not be running Gate A at all.`
+			].join("\n"));
+		},
+		/**
+		* Records import kinds; never rewrites a byte (`null` return). `enforce:
+		* "pre"` is what makes this correct as well as early — it puts this hook
+		* ahead of Vite's own `vite:esbuild` TypeScript transform, so `code` here
+		* is the ORIGINAL source with `type` modifiers still on it. After esbuild
+		* the distinction no longer exists in the text.
+		*
+		* Runs before `resolveId` fires for any of this module's own specifiers:
+		* Rollup must parse a module's post-transform source to discover what to
+		* resolve next. That ordering is an OBSERVED Rollup behaviour, pinned by
+		* `index.spec.ts`'s "D.3 hook ordering pin" and documented at length in
+		* `index.ts`. If it ever inverts, this map is simply empty when
+		* `resolveId` reads it and rule 2 goes back to refusing type-only imports
+		* — a loud false positive, never a silent leak.
+		*/
+		transform(code, id) {
+			recordImportKinds(code, id);
+			return null;
+		},
+		/**
+		* The erased stand-in a type-only edge into a server-only package resolves
+		* to. It must exist rather than the import simply being permitted, and the
+		* fixture measures why: `import { type Request } from "@warlock.js/core"`
+		* under `verbatimModuleSyntax` is emitted as `import {} from
+		* "@warlock.js/core"`, and Rollup honours that as a side-effect edge — the
+		* package's module-level code lands in the client chunk even though not one
+		* binding is read from it. Permitting the import would therefore trade a
+		* false positive for the exact silent leak the `server` marker exists to
+		* close. Resolving to an empty module gives both: a clean build, and
+		* nothing of the server package in the browser.
+		*/
+		load(id) {
+			return id === TYPE_ONLY_ERASED_ID ? "export {};" : null;
+		},
+		async resolveId(source, importer, resolveOptions) {
+			const isRelativeOrAbsolute = source.startsWith(".") || path.isAbsolute(source);
+			const judgedPath = completeLocalModulePath(isRelativeOrAbsolute && importer ? path.resolve(path.dirname(importer), source) : source);
+			if (source === TYPE_ONLY_ERASED_ID) return source;
+			const typeOnly = isTypeOnlyEdge(source, importer);
+			const violation = ruleViolation(source, judgedPath, importer, environmentOf, appRoot, typeOnly);
+			if (violation) {
+				const chain = [...buildChain(importer), source].join(" → ");
+				this.error([
+					`Gate A refused an import: forbidden dependency reaches the client bundle.`,
+					``,
+					`Import chain: ${chain}`,
+					`File: ${importer ?? source}`,
+					`Cause: ${violation.cause}`,
+					`Fix: ${violation.fix}`
+				].join("\n"));
+			}
+			if (typeOnly && isServerMarkedGovernedPackage(source, importer, environmentOf, appRoot)) return TYPE_ONLY_ERASED_ID;
+			const resolved = await this.resolve(source, importer, {
+				...resolveOptions,
+				skipSelf: true
+			});
+			if (resolved && importer) importerOf.set(resolved.id, importer);
+			const isBareSpecifier = !isRelativeOrAbsolute && !source.includes("\0");
+			if (isBareSpecifier && resolved && !resolved.external) {
+				const aliasPath = completeLocalModulePath(moduleKey(resolved.id));
+				if (isAppSourcePath(aliasPath, appRoot)) {
+					const aliasViolation = ruleViolation(source, aliasPath, importer, environmentOf, appRoot, typeOnly);
+					if (aliasViolation) this.warn({
+						message: [
+							`Gate A WOULD refuse this import — reported as a WARNING, not enforced yet.`,
+							``,
+							`Import chain: ${[...buildChain(importer), source].join(" → ")}`,
+							`File: ${importer ?? source}`,
+							`Specifier: "${source}"`,
+							`Resolves to: ${aliasPath}`,
+							`Cause: ${aliasViolation.cause}`,
+							`Fix: ${aliasViolation.fix}`,
+							`Why only a warning: this specifier is written in ALIAS form. The identical import spelled relatively or absolutely is REFUSED today — the spelling was the only difference — and rules 3 and 4 have only just started judging this form. Every line like this is either an import to fix or a rule to correct; when there are none left, this becomes a refusal.`
+						].join("\n"),
+						id: importer
+					});
+				}
+			}
+			if (isBareSpecifier && !resolved) {
+				const aliasTable = declaredAliasCount === void 0 ? `this build's resolve.alias was never reported to the gate` : `this build's resolve.alias declares ${declaredAliasCount} ${declaredAliasCount === 1 ? "entry" : "entries"}`;
+				this.warn({
+					message: [
+						`Gate A could not judge this import — and it is going into the browser chunk unjudged.`,
+						``,
+						`Import chain: ${[...buildChain(importer), source].join(" → ")}`,
+						`File: ${importer ?? source}`,
+						`Specifier: "${source}"`,
+						`Cause: nothing in this build resolves "${source}", so Rollup treats it as an external dependency and writes the import statement into the client chunk verbatim. Rules 3 and 4 judge a FILE; with no resolution there is no file, so this import crossed the fence unexamined rather than being allowed by it (${aliasTable}).`,
+						`Fix: if this is an app-convention alias specifier (a tsconfig "paths" entry such as app/* or web/*), give the CLIENT build the matching resolve.alias entry the dev server already installs, so the specifier resolves to a real file and Gate A can judge it. Otherwise install the missing package, or write the import relatively.`
+					].join("\n"),
+					id: importer
+				});
+			}
+			return resolved ?? null;
+		}
+	};
+}
+
+//#endregion
+export { createEnvironmentClassifier, gateAResolve };
+//# sourceMappingURL=gate-a-resolve.mjs.map