@venizia/dev-configs 0.4.3 → 0.4.4

package/dist/checks/purity/manifest.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildManifest = exports.assertBrowserEsmEntry = exports.deriveEntries = exports.assertNoWorkspaceExternal = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const DEFAULT_WORKSPACE_SCOPE = '@venizia/';
+/** The one place this engine builds an `Error`: `getError` would make dev-configs depend on inversion, which depends on dev-configs. */
+// eslint-disable-next-line venizia/no-new-error -- getError would be a dev-configs -> inversion cycle
+const purityError = (message) => new Error(message);
+/** `types` describes the entry, it is not a runtime target; `./package.json` is not code. */
+const NON_RUNTIME_CONDITION = 'types';
+const NON_CODE_SUBPATH = './package.json';
+/**
+ * A code-level guard, not just the JSDoc on `external`: it is an escape hatch from this gate, and a
+ * hatch with no lock is one bad edit away from hiding a real leak - `external: ['@venizia/ignis-helpers']`
+ * on a red entry would silently turn it green by removing the exact root-barrel import this gate
+ * exists to catch from the module graph, rather than proving it absent.
+ *
+ * A plain `Error`, not `getError`: the engine runs from the repository root through `devz`, outside
+ * every workspace package, and has no logger to resolve.
+ */
+const assertNoWorkspaceExternal = (manifest, workspaceScope = DEFAULT_WORKSPACE_SCOPE) => {
+    for (const row of manifest) {
+        const specifiers = row.external ?? [];
+        for (const specifier of specifiers) {
+            if (!specifier.startsWith(workspaceScope)) {
+                continue;
+            }
+            throw purityError(`[purity][manifest] Entry '${row.label}' externalises '${specifier}', a workspace package ` +
+                `| \`external\` may only exempt THIRD-PARTY packaging, never the repository's own code - doing so ` +
+                `would hide the exact leak this gate exists to catch`);
+        }
+    }
+    return manifest;
+};
+exports.assertNoWorkspaceExternal = assertNoWorkspaceExternal;
+const readExportsMap = (opts) => {
+    const manifestPath = (0, node_path_1.join)(opts.root, 'packages', opts.package, 'package.json');
+    const manifest = JSON.parse((0, node_fs_1.readFileSync)(manifestPath, 'utf8'));
+    if (!manifest.exports) {
+        throw purityError(`[purity][manifest] '${opts.package}' claims browser purity but publishes no \`exports\` map ` +
+            `| There is nothing to derive rows from - remove the claim or add the map`);
+    }
+    return manifest.exports;
+};
+/**
+ * `exports` may spell one sub-path as several conditions pointing at different builds - the dual
+ * CJS/ESM packages do exactly that - and each is a separately resolvable file that a consumer can
+ * end up importing, so each is probed. `default` normally repeats `require`, so files are deduped
+ * and the FIRST condition naming a file is the one that labels it.
+ */
+const listConditionTargets = (target) => {
+    if (typeof target === 'string') {
+        return [{ condition: 'default', file: target }];
+    }
+    const seen = new Set();
+    const targets = [];
+    const targetEntries = Object.entries(target);
+    for (const [condition, file] of targetEntries) {
+        if (condition === NON_RUNTIME_CONDITION || seen.has(file)) {
+            continue;
+        }
+        seen.add(file);
+        targets.push({ condition, file });
+    }
+    return targets;
+};
+const buildLabel = (opts) => {
+    const { package: packageName, subpath, condition, isSoleTarget } = opts;
+    const suffix = subpath === '.' ? '' : subpath.slice(1);
+    const base = `${packageName}${suffix}`;
+    return isSoleTarget ? base : `${base} [${condition}]`;
+};
+/**
+ * Exported for the tests, which have to drive a claim that no longer matches its package's
+ * `exports` map - the staleness guard is the whole point of deriving, and it cannot be asserted
+ * through a built manifest, which by construction is never stale.
+ */
+const deriveEntries = (opts) => {
+    const { claim, root } = opts;
+    const exportsMap = readExportsMap({ root, package: claim.package });
+    const published = Object.keys(exportsMap).filter((subpath) => subpath !== NON_CODE_SUBPATH);
+    const subpathsList = claim.subpaths ?? [];
+    for (const subpath of subpathsList) {
+        if (published.includes(subpath)) {
+            continue;
+        }
+        throw purityError(`[purity][manifest] '${claim.package}' claims '${subpath}', which its \`exports\` map no longer ` +
+            `publishes | Published: ${published.join(', ')} - a renamed sub-path must not silently drop its row`);
+    }
+    const claimExternalKeys = Object.keys(claim.external ?? {});
+    for (const subpath of claimExternalKeys) {
+        if (published.includes(subpath)) {
+            continue;
+        }
+        throw purityError(`[purity][manifest] '${claim.package}' declares \`external\` for '${subpath}', which its ` +
+            `\`exports\` map no longer publishes | An external that outlives its entry is a waiver ` +
+            `nobody is reading`);
+    }
+    const claimed = claim.subpaths ?? published;
+    const claimImpureKeys = Object.keys(claim.impure ?? {});
+    for (const subpath of claimImpureKeys) {
+        if (claimed.includes(subpath)) {
+            continue;
+        }
+        throw purityError(`[purity][manifest] '${claim.package}' waives '${subpath}' as impure, but that sub-path is not ` +
+            `claimed | Claimed: ${claimed.join(', ')} - a waiver against nothing is one nobody is reading`);
+    }
+    const entries = [];
+    for (const subpath of claimed) {
+        const targets = listConditionTargets(exportsMap[subpath]);
+        const conditions = claim.impure?.[subpath] ?? [];
+        for (const condition of conditions) {
+            if (targets.some((target) => target.condition === condition)) {
+                continue;
+            }
+            throw purityError(`[purity][manifest] '${claim.package}' waives '${subpath}' under condition '${condition}', ` +
+                `which its \`exports\` map does not publish | Published: ${targets.map((t) => t.condition).join(', ')}`);
+        }
+        for (const { condition, file } of targets) {
+            entries.push({
+                label: buildLabel({
+                    package: claim.package,
+                    subpath,
+                    condition,
+                    isSoleTarget: targets.length === 1,
+                }),
+                package: claim.package,
+                entry: (0, node_path_1.join)('packages', claim.package, file),
+                ...(claim.external?.[subpath] ? { external: claim.external[subpath] } : {}),
+                ...(claim.impure?.[subpath]?.includes(condition) ? { expectImpure: true } : {}),
+            });
+        }
+    }
+    return entries;
+};
+exports.deriveEntries = deriveEntries;
+/**
+ * A browser claim is only honest if a browser bundler can actually consume the entry. A CommonJS
+ * entry forces every consumer into a workaround, so the claim carries the obligation: every claimed
+ * sub-path must publish its runtime entries below `esmEntryPrefix`. Checked here rather than trusted
+ * to a comment, for the same reason as {@link assertNoWorkspaceExternal} - the failure is otherwise
+ * invisible until someone tries to bundle the package downstream.
+ */
+const assertBrowserEsmEntry = (opts) => {
+    const { claims, root, esmEntryPrefix } = opts;
+    for (const claim of claims) {
+        const exportsMap = readExportsMap({ root, package: claim.package });
+        const claimed = claim.subpaths ?? Object.keys(exportsMap).filter((s) => s !== NON_CODE_SUBPATH);
+        for (const subpath of claimed) {
+            const target = exportsMap[subpath];
+            const runtimeTargets = typeof target === 'object' && target !== null
+                ? Object.entries(target)
+                    .filter(([condition]) => condition !== NON_RUNTIME_CONDITION)
+                    .map(([, file]) => file)
+                : [];
+            if (runtimeTargets.length > 0 &&
+                runtimeTargets.every((file) => file.startsWith(esmEntryPrefix))) {
+                continue;
+            }
+            throw purityError(`[purity][manifest] '${claim.package}' claims browser purity for '${subpath}' but its runtime ` +
+                `entry is not in ${esmEntryPrefix.replace(/^\.\//, '')} | A browser bundler needs an ES module, so the claim ` +
+                `cannot be consumed - build the package as ES modules`);
+        }
+    }
+    return claims;
+};
+exports.assertBrowserEsmEntry = assertBrowserEsmEntry;
+/** The rows of a whole repository: every claim derived from its package's `exports`, then the guards. */
+const buildManifest = (opts) => {
+    const { claims, root, options = {} } = opts;
+    const { esmEntryPrefix, workspaceScope = DEFAULT_WORKSPACE_SCOPE } = options;
+    const checked = esmEntryPrefix === undefined ? claims : (0, exports.assertBrowserEsmEntry)({ claims, root, esmEntryPrefix });
+    return (0, exports.assertNoWorkspaceExternal)(checked.flatMap((claim) => (0, exports.deriveEntries)({ claim, root })), workspaceScope);
+};
+exports.buildManifest = buildManifest;
+//# sourceMappingURL=manifest.js.map

package/dist/checks/purity/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/checks/purity/manifest.ts"],"names":[],"mappings":"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","sourcesContent":["import { readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nexport interface IPurityEntry {\n  label: string;\n  package: string;\n  /** Repository-relative path to the built file the `exports` map points at. */\n  entry: string;\n  /**\n   * Specifiers to pass through as `bun build --external`. Only for a third-party dependency whose\n   * OWN packaging is out of this gate's remit - e.g. one that relies on its `package.json` `browser`\n   * field remap, which the downstream app's bundler (Vite, ...) honours and `bun build` does not.\n   * Never for the repository's own source: an external hides that file from the module graph\n   * entirely, so using it on our own code would let a real leak through unseen rather than prove\n   * anything pure. Enforced by {@link assertNoWorkspaceExternal}, not left to this comment alone.\n   */\n  external?: string[];\n  /**\n   * This row is EXPECTED to be impure, so failing is its passing state. Derived from\n   * {@link IPurityClaim.impure} - never authored on a row directly.\n   */\n  expectImpure?: boolean;\n}\n\n/**\n * A package whose published entry points carry a browser-purity claim.\n *\n * The ROW SET IS NEVER AUTHORED. It is read from the package's own `exports` map, so a sub-path\n * added to a manifest is probed the moment it is published.\n */\nexport interface IPurityClaim {\n  /** Directory under `packages/`, and the token `devz check purity <token>` filters on. */\n  package: string;\n  /**\n   * Sub-paths (as spelled in `exports`) when the claim covers only PART of the published surface.\n   * Omit it and the whole surface is claimed. Every sub-path named here must still exist in\n   * `exports`; a rename fails the derivation loudly rather than quietly dropping a row.\n   */\n  subpaths?: string[];\n  /** `external` for one sub-path - see {@link IPurityEntry.external}. Keyed as spelled in `exports`. */\n  external?: Record<string, string[]>;\n  /**\n   * Entries that CANNOT be browser-pure, keyed as spelled in `exports`, valued by the conditions\n   * that are impure. The waiver is exact in BOTH directions: a listed entry that turns out to be\n   * pure fails as loudly as an unlisted one that is not. Deriving still owns the ROW SET, so a\n   * sub-path added later is claimed pure by default and has to earn its line here.\n   */\n  impure?: Record<string, string[]>;\n}\n\n/** What a repository may tune about the engine; everything else is the engine's contract. */\nexport interface IPurityOptions {\n  /**\n   * When set, every claimed sub-path must publish its runtime entries below this prefix (for\n   * example `./dist/esm/`): a browser bundler needs an ES module, so a CommonJS-only entry makes\n   * the claim unconsumable. Omit it for a repository that publishes a single build.\n   */\n  esmEntryPrefix?: string;\n\n  /** Package-name prefix of this repository's own packages; an `external` may never start with it. Default `@venizia/`. */\n  workspaceScope?: string;\n}\n\nconst DEFAULT_WORKSPACE_SCOPE = '@venizia/';\n\n/** The one place this engine builds an `Error`: `getError` would make dev-configs depend on inversion, which depends on dev-configs. */\n// eslint-disable-next-line venizia/no-new-error -- getError would be a dev-configs -> inversion cycle\nconst purityError = (message: string): Error => new Error(message);\n\n/** `types` describes the entry, it is not a runtime target; `./package.json` is not code. */\nconst NON_RUNTIME_CONDITION = 'types';\nconst NON_CODE_SUBPATH = './package.json';\n\n/**\n * A code-level guard, not just the JSDoc on `external`: it is an escape hatch from this gate, and a\n * hatch with no lock is one bad edit away from hiding a real leak - `external: ['@venizia/ignis-helpers']`\n * on a red entry would silently turn it green by removing the exact root-barrel import this gate\n * exists to catch from the module graph, rather than proving it absent.\n *\n * A plain `Error`, not `getError`: the engine runs from the repository root through `devz`, outside\n * every workspace package, and has no logger to resolve.\n */\nexport const assertNoWorkspaceExternal = (\n  manifest: IPurityEntry[],\n  workspaceScope: string = DEFAULT_WORKSPACE_SCOPE,\n): IPurityEntry[] => {\n  for (const row of manifest) {\n    const specifiers = row.external ?? [];\n    for (const specifier of specifiers) {\n      if (!specifier.startsWith(workspaceScope)) {\n        continue;\n      }\n\n      throw purityError(\n        `[purity][manifest] Entry '${row.label}' externalises '${specifier}', a workspace package ` +\n          `| \\`external\\` may only exempt THIRD-PARTY packaging, never the repository's own code - doing so ` +\n          `would hide the exact leak this gate exists to catch`,\n      );\n    }\n  }\n\n  return manifest;\n};\n\ntype TExportsTarget = string | Record<string, string>;\n\nconst readExportsMap = (opts: {\n  root: string;\n  package: string;\n}): Record<string, TExportsTarget> => {\n  const manifestPath = join(opts.root, 'packages', opts.package, 'package.json');\n  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as {\n    exports?: Record<string, TExportsTarget>;\n  };\n\n  if (!manifest.exports) {\n    throw purityError(\n      `[purity][manifest] '${opts.package}' claims browser purity but publishes no \\`exports\\` map ` +\n        `| There is nothing to derive rows from - remove the claim or add the map`,\n    );\n  }\n\n  return manifest.exports;\n};\n\n/**\n * `exports` may spell one sub-path as several conditions pointing at different builds - the dual\n * CJS/ESM packages do exactly that - and each is a separately resolvable file that a consumer can\n * end up importing, so each is probed. `default` normally repeats `require`, so files are deduped\n * and the FIRST condition naming a file is the one that labels it.\n */\nconst listConditionTargets = (\n  target: TExportsTarget,\n): Array<{ condition: string; file: string }> => {\n  if (typeof target === 'string') {\n    return [{ condition: 'default', file: target }];\n  }\n\n  const seen = new Set<string>();\n  const targets: Array<{ condition: string; file: string }> = [];\n\n  const targetEntries = Object.entries(target);\n  for (const [condition, file] of targetEntries) {\n    if (condition === NON_RUNTIME_CONDITION || seen.has(file)) {\n      continue;\n    }\n\n    seen.add(file);\n    targets.push({ condition, file });\n  }\n\n  return targets;\n};\n\nconst buildLabel = (opts: {\n  package: string;\n  subpath: string;\n  condition: string;\n  isSoleTarget: boolean;\n}): string => {\n  const { package: packageName, subpath, condition, isSoleTarget } = opts;\n  const suffix = subpath === '.' ? '' : subpath.slice(1);\n  const base = `${packageName}${suffix}`;\n\n  return isSoleTarget ? base : `${base} [${condition}]`;\n};\n\n/**\n * Exported for the tests, which have to drive a claim that no longer matches its package's\n * `exports` map - the staleness guard is the whole point of deriving, and it cannot be asserted\n * through a built manifest, which by construction is never stale.\n */\nexport const deriveEntries = (opts: { claim: IPurityClaim; root: string }): IPurityEntry[] => {\n  const { claim, root } = opts;\n  const exportsMap = readExportsMap({ root, package: claim.package });\n  const published = Object.keys(exportsMap).filter((subpath) => subpath !== NON_CODE_SUBPATH);\n\n  const subpathsList = claim.subpaths ?? [];\n  for (const subpath of subpathsList) {\n    if (published.includes(subpath)) {\n      continue;\n    }\n\n    throw purityError(\n      `[purity][manifest] '${claim.package}' claims '${subpath}', which its \\`exports\\` map no longer ` +\n        `publishes | Published: ${published.join(', ')} - a renamed sub-path must not silently drop its row`,\n    );\n  }\n\n  const claimExternalKeys = Object.keys(claim.external ?? {});\n  for (const subpath of claimExternalKeys) {\n    if (published.includes(subpath)) {\n      continue;\n    }\n\n    throw purityError(\n      `[purity][manifest] '${claim.package}' declares \\`external\\` for '${subpath}', which its ` +\n        `\\`exports\\` map no longer publishes | An external that outlives its entry is a waiver ` +\n        `nobody is reading`,\n    );\n  }\n\n  const claimed = claim.subpaths ?? published;\n\n  const claimImpureKeys = Object.keys(claim.impure ?? {});\n  for (const subpath of claimImpureKeys) {\n    if (claimed.includes(subpath)) {\n      continue;\n    }\n\n    throw purityError(\n      `[purity][manifest] '${claim.package}' waives '${subpath}' as impure, but that sub-path is not ` +\n        `claimed | Claimed: ${claimed.join(', ')} - a waiver against nothing is one nobody is reading`,\n    );\n  }\n\n  const entries: IPurityEntry[] = [];\n\n  for (const subpath of claimed) {\n    const targets = listConditionTargets(exportsMap[subpath]!);\n\n    const conditions = claim.impure?.[subpath] ?? [];\n    for (const condition of conditions) {\n      if (targets.some((target) => target.condition === condition)) {\n        continue;\n      }\n\n      throw purityError(\n        `[purity][manifest] '${claim.package}' waives '${subpath}' under condition '${condition}', ` +\n          `which its \\`exports\\` map does not publish | Published: ${targets.map((t) => t.condition).join(', ')}`,\n      );\n    }\n\n    for (const { condition, file } of targets) {\n      entries.push({\n        label: buildLabel({\n          package: claim.package,\n          subpath,\n          condition,\n          isSoleTarget: targets.length === 1,\n        }),\n        package: claim.package,\n        entry: join('packages', claim.package, file),\n        ...(claim.external?.[subpath] ? { external: claim.external[subpath] } : {}),\n        ...(claim.impure?.[subpath]?.includes(condition) ? { expectImpure: true } : {}),\n      });\n    }\n  }\n\n  return entries;\n};\n\n/**\n * A browser claim is only honest if a browser bundler can actually consume the entry. A CommonJS\n * entry forces every consumer into a workaround, so the claim carries the obligation: every claimed\n * sub-path must publish its runtime entries below `esmEntryPrefix`. Checked here rather than trusted\n * to a comment, for the same reason as {@link assertNoWorkspaceExternal} - the failure is otherwise\n * invisible until someone tries to bundle the package downstream.\n */\nexport const assertBrowserEsmEntry = (opts: {\n  claims: IPurityClaim[];\n  root: string;\n  esmEntryPrefix: string;\n}): IPurityClaim[] => {\n  const { claims, root, esmEntryPrefix } = opts;\n\n  for (const claim of claims) {\n    const exportsMap = readExportsMap({ root, package: claim.package });\n    const claimed = claim.subpaths ?? Object.keys(exportsMap).filter((s) => s !== NON_CODE_SUBPATH);\n\n    for (const subpath of claimed) {\n      const target = exportsMap[subpath];\n\n      const runtimeTargets =\n        typeof target === 'object' && target !== null\n          ? Object.entries(target)\n              .filter(([condition]) => condition !== NON_RUNTIME_CONDITION)\n              .map(([, file]) => file)\n          : [];\n\n      if (\n        runtimeTargets.length > 0 &&\n        runtimeTargets.every((file) => file.startsWith(esmEntryPrefix))\n      ) {\n        continue;\n      }\n\n      throw purityError(\n        `[purity][manifest] '${claim.package}' claims browser purity for '${subpath}' but its runtime ` +\n          `entry is not in ${esmEntryPrefix.replace(/^\\.\\//, '')} | A browser bundler needs an ES module, so the claim ` +\n          `cannot be consumed - build the package as ES modules`,\n      );\n    }\n  }\n\n  return claims;\n};\n\n/** The rows of a whole repository: every claim derived from its package's `exports`, then the guards. */\nexport const buildManifest = (opts: {\n  claims: IPurityClaim[];\n  root: string;\n  options?: IPurityOptions;\n}): IPurityEntry[] => {\n  const { claims, root, options = {} } = opts;\n  const { esmEntryPrefix, workspaceScope = DEFAULT_WORKSPACE_SCOPE } = options;\n\n  const checked =\n    esmEntryPrefix === undefined ? claims : assertBrowserEsmEntry({ claims, root, esmEntryPrefix });\n\n  return assertNoWorkspaceExternal(\n    checked.flatMap((claim) => deriveEntries({ claim, root })),\n    workspaceScope,\n  );\n};\n"]}

package/dist/checks/purity/probe.d.ts

@@ -0,0 +1,68 @@
+export interface IPurityResult {
+    entry: string;
+    ok: boolean;
+    sizeBytes: number;
+    builtins: string[];
+    globals: string[];
+    /** Node-global reads that cannot throw in a browser. Reported, never fatal. */
+    guardedGlobals: string[];
+    /**
+     * Specifiers this probe run excluded from its own module graph. Always echoed back, on both the
+     * passing and failing path - an entry that externalises something is measuring less than an entry
+     * that does not, and that must stay visible next to the result, not be a silent input.
+     */
+    external: string[];
+    buildError?: string;
+}
+/** Where the probe keeps its metafile, relative to the `cwd` it is given: the repository's own scratch, never the system temp. */
+export declare const PURITY_SCRATCH_DIR = ".agents/local/tmp";
+/** What a matched global means: ERROR is fatal, GUARDED is reported and never fatal. */
+export declare class ProbeSeverities {
+    static readonly ERROR = "error";
+    static readonly GUARDED = "guarded";
+    static readonly SCHEME_SET: Set<string>;
+    static isValid(value: string): value is TProbeSeverity;
+}
+export type TProbeSeverity = Extract<(typeof ProbeSeverities)[keyof typeof ProbeSeverities], string>;
+/**
+ * Node globals survive verbatim into a `target: 'browser'` bundle, so a gate reading only module
+ * specifiers reports clean on `process.env.NODE_ENV`. Each pattern must be anchored: a bundle
+ * legitimately contains identifiers like `processQueue`. A lookbehind that rejects a preceding dot
+ * also rejects `globalThis.process`, so every access path needs its own pattern.
+ *
+ * `severity` separates a read that throws from one that cannot. Optional chaining is not itself the
+ * difference: `process?.env` throws a ReferenceError when `process` is a free identifier, while
+ * `globalThis.process?.env` is an ordinary property read on an object that always exists.
+ *
+ * `guarded` means "reported, never fatal". Bare `process?.` sits there because this probe matches
+ * bundled text and has no scope information: hono's `getColorEnabled` writes
+ * `const { process, Deno } = globalThis;` and then `process?.env`, which is a local binding and
+ * perfectly safe, and no regex can tell that apart from a free global. Failing on it would make the
+ * gate cry wolf on a dependency; the unguarded `process.` and `globalThis.process.` forms stay
+ * fatal, and those are the ones that are unambiguously browser-breaking.
+ *
+ * Exported for `probe.test.ts` to assert against directly, alongside {@link stripBundlerPathComments}.
+ */
+export declare const GLOBAL_PATTERNS: Array<{
+    name: string;
+    pattern: RegExp;
+    severity: TProbeSeverity;
+}>;
+/**
+ * Exported so `probe.test.ts` can assert against the literal collision string directly, without
+ * spawning `bun build` - a fixture whose OWN entry-path comment happens to reproduce the collision
+ * is not something a filename choice can be relied on to keep reproducing.
+ */
+export declare const stripBundlerPathComments: (text: string) => string;
+/**
+ * The CLI, not `Bun.build()`: the in-process bundler resolves this workspace's symlinked
+ * dependencies to directories and dies on them.
+ */
+export declare const probeEntry: (opts: {
+    entry: string;
+    cwd: string;
+    external?: string[];
+    /** Defaults to {@link PURITY_SCRATCH_DIR} under `cwd`. */
+    scratchDir?: string;
+}) => Promise<IPurityResult>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/checks/purity/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../../../src/checks/purity/probe.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,OAAO,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kIAAkI;AAClI,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAStD,wFAAwF;AACxF,qBAAa,eAAe;IAC1B,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW;IAChC,MAAM,CAAC,QAAQ,CAAC,OAAO,aAAa;IAEpC,MAAM,CAAC,QAAQ,CAAC,UAAU,cAA+C;IAEzE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,cAAc;CAGvD;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,CAClC,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,EACtD,MAAM,CACP,CAAC;AAEF;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,cAAc,CAAC;CAC1B,CAgCA,CAAC;AAaF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,MAAM,MAAM,KAAG,MAEvD,CAAC;AAqIF;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAU,MAAM;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,KAAG,OAAO,CAAC,aAAa,CA6GxB,CAAC"}

package/dist/checks/purity/probe.js

@@ -0,0 +1,295 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.probeEntry = exports.stripBundlerPathComments = exports.GLOBAL_PATTERNS = exports.ProbeSeverities = exports.PURITY_SCRATCH_DIR = void 0;
+const node_crypto_1 = require("node:crypto");
+const promises_1 = require("node:fs/promises");
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+/** Where the probe keeps its metafile, relative to the `cwd` it is given: the repository's own scratch, never the system temp. */
+exports.PURITY_SCRATCH_DIR = '.agents/local/tmp';
+/**
+ * A browser entry must never reach `@venizia/dev-configs`: it is the Bun-only tooling package (its
+ * `./testing` entry imports `bun:test`). Matches the workspace folder (not its own test fixtures) and the installed copy.
+ */
+const DEV_CONFIGS_PATH = /(^|\/)(packages\/dev-configs\/(?!src\/__tests__\/)|node_modules\/@venizia\/dev-configs\/)/;
+/** What a matched global means: ERROR is fatal, GUARDED is reported and never fatal. */
+class ProbeSeverities {
+    static { this.ERROR = 'error'; }
+    static { this.GUARDED = 'guarded'; }
+    static { this.SCHEME_SET = new Set([this.ERROR, this.GUARDED]); }
+    static isValid(value) {
+        return this.SCHEME_SET.has(value);
+    }
+}
+exports.ProbeSeverities = ProbeSeverities;
+/**
+ * Node globals survive verbatim into a `target: 'browser'` bundle, so a gate reading only module
+ * specifiers reports clean on `process.env.NODE_ENV`. Each pattern must be anchored: a bundle
+ * legitimately contains identifiers like `processQueue`. A lookbehind that rejects a preceding dot
+ * also rejects `globalThis.process`, so every access path needs its own pattern.
+ *
+ * `severity` separates a read that throws from one that cannot. Optional chaining is not itself the
+ * difference: `process?.env` throws a ReferenceError when `process` is a free identifier, while
+ * `globalThis.process?.env` is an ordinary property read on an object that always exists.
+ *
+ * `guarded` means "reported, never fatal". Bare `process?.` sits there because this probe matches
+ * bundled text and has no scope information: hono's `getColorEnabled` writes
+ * `const { process, Deno } = globalThis;` and then `process?.env`, which is a local binding and
+ * perfectly safe, and no regex can tell that apart from a free global. Failing on it would make the
+ * gate cry wolf on a dependency; the unguarded `process.` and `globalThis.process.` forms stay
+ * fatal, and those are the ones that are unambiguously browser-breaking.
+ *
+ * Exported for `probe.test.ts` to assert against directly, alongside {@link stripBundlerPathComments}.
+ */
+exports.GLOBAL_PATTERNS = [
+    { name: 'process', pattern: /(?<![A-Za-z0-9_$.])process\s*\./, severity: 'error' },
+    { name: 'process?.', pattern: /(?<![A-Za-z0-9_$.])process\s*\?\./, severity: 'guarded' },
+    {
+        name: 'globalThis.process',
+        pattern: /(?<![A-Za-z0-9_$.])globalThis\s*\.\s*process\s*\./,
+        severity: 'error',
+    },
+    {
+        name: 'globalThis.process?.',
+        pattern: /(?<![A-Za-z0-9_$.])globalThis\s*\.\s*process\s*\?\./,
+        severity: 'guarded',
+    },
+    {
+        name: '__dirname',
+        pattern: /(?<![A-Za-z0-9_$.])__dirname(?![A-Za-z0-9_$])/,
+        severity: 'error',
+    },
+    {
+        name: '__filename',
+        pattern: /(?<![A-Za-z0-9_$.])__filename(?![A-Za-z0-9_$])/,
+        severity: 'error',
+    },
+    {
+        name: 'createRequire',
+        pattern: /(?<![A-Za-z0-9_$.])createRequire\s*\(/,
+        severity: 'error',
+    },
+    { name: 'require(', pattern: /(?<![A-Za-z0-9_$.])require\s*\(/, severity: 'error' },
+    // Member access only. `typeof Bun !== 'undefined'` is the legitimate runtime probe and never
+    // throws; `Bun.serve(...)` in a browser does.
+    { name: 'Bun', pattern: /(?<![A-Za-z0-9_$.])Bun\s*\./, severity: 'error' },
+];
+/**
+ * Bun's bundler prefixes every CommonJS-wrapped module with a full-line `// <path>.js` header (this
+ * whole workspace emits CJS `dist/*.js` - no package declares `"type": "module"`). A source path is
+ * free-form and can legitimately contain `process` as a substring with no identifier boundary on
+ * its left, e.g. this gate's own `transport/in-process.js`: the header reads
+ * `// packages/core-worker/dist/transport/in-process.js`, and `process.` there is a filename
+ * fragment, not a read of the global. `GLOBAL_PATTERNS` matches bundled TEXT with no scope
+ * information, so it cannot tell a path comment from code - stripped before matching.
+ */
+const BUNDLER_PATH_COMMENT = /^\/\/ [\w@./-]+\.(?:c|m)?js$/gm;
+/**
+ * Exported so `probe.test.ts` can assert against the literal collision string directly, without
+ * spawning `bun build` - a fixture whose OWN entry-path comment happens to reproduce the collision
+ * is not something a filename choice can be relied on to keep reproducing.
+ */
+const stripBundlerPathComments = (text) => {
+    return text.replace(BUNDLER_PATH_COMMENT, '');
+};
+exports.stripBundlerPathComments = stripBundlerPathComments;
+/**
+ * `node:module`'s own list, not a hand-maintained one: a bare `import ... from 'fs'` bundles
+ * identically to `'node:fs'` (Bun stubs both to an empty object), and the metafile records
+ * whichever spelling the source used. Matching by prefix alone misses the bare form entirely.
+ */
+const BUILTIN_MODULE_NAMES = new Set(node_module_1.builtinModules);
+const isBuiltinSpecifier = (specifier) => {
+    const bareName = specifier.startsWith('node:') ? specifier.slice('node:'.length) : specifier;
+    return BUILTIN_MODULE_NAMES.has(bareName);
+};
+/**
+ * Measured against Bun 1.3.14: `--target=browser` never fails on a `node:` import and never leaves
+ * the specifier in the bundled text. An unpolyfillable builtin (`fs`, `child_process`, ...) is
+ * stubbed to an empty object; a polyfillable one (`crypto`, `path`, ...) is inlined in full under a
+ * `/bun-vfs$$/` virtual path. Either way `exitCode` stays 0 and the specifier never survives into
+ * stdout. The `--metafile` module graph is the only place it is preserved.
+ */
+const findBuiltinSpecifiers = (metafile) => {
+    const builtins = new Set();
+    const metafileInputsEntries = Object.entries(metafile.inputs);
+    for (const [inputPath, input] of metafileInputsEntries) {
+        if (isBuiltinSpecifier(inputPath)) {
+            builtins.add(inputPath);
+        }
+        for (const dependency of input.imports) {
+            const specifier = dependency.original ?? dependency.path;
+            if (isBuiltinSpecifier(specifier)) {
+                builtins.add(specifier);
+            }
+        }
+    }
+    return [...builtins].sort();
+};
+/**
+ * A real npm dependency bundles in full under this target (measured: `zod` produces zero
+ * `external` entries) and a genuinely missing package fails the build outright (nonzero exit,
+ * caught before this runs). But a package's own `browser` field can remap a dependency to `false` -
+ * the standard convention for disabling a Node-only dependency in browser builds - and Bun honours
+ * that remap by leaving the import external with exit 0, whether or not the remapped name is a
+ * builtin. An unresolved import in a browser bundle is not safe to wave through either way -
+ * UNLESS the manifest entry asked for exactly this specifier via `external`, in which case its
+ * presence here is the requested exclusion working, not a leak.
+ */
+/**
+ * A relative specifier is the package's own file, and a truly unreachable one fails the build with a
+ * nonzero exit, which is caught before this runs. Bun's METAFILE nonetheless marks a re-export of the
+ * form `export { name } from './x.js'` as `external` while inlining it - measured on
+ * `helpers/dist/esm/core.js`: six such specifiers reported external, `Bundled 192 modules`, and the
+ * output contains `class BaseHelper` with no bare relative import left in it. Reading the metafile
+ * literally there reports a leak the bundle does not have.
+ */
+const isRelativeSpecifier = (specifier) => {
+    return specifier.startsWith('./') || specifier.startsWith('../');
+};
+const findUnresolvedExternalSpecifiers = (opts) => {
+    const { metafile, builtins, requestedExternal } = opts;
+    const unresolved = new Set();
+    const isRequestedExternal = (specifier) => {
+        for (const requested of requestedExternal) {
+            if (specifier === requested || specifier.startsWith(`${requested}/`)) {
+                return true;
+            }
+        }
+        return false;
+    };
+    const metafileInputsValues = Object.values(metafile.inputs);
+    for (const input of metafileInputsValues) {
+        for (const dependency of input.imports) {
+            if (!dependency.external) {
+                continue;
+            }
+            const specifier = dependency.original ?? dependency.path;
+            if (isRelativeSpecifier(specifier) ||
+                builtins.has(specifier) ||
+                isRequestedExternal(specifier)) {
+                continue;
+            }
+            unresolved.add(specifier);
+        }
+    }
+    return [...unresolved].sort();
+};
+/**
+ * Reads and removes the metafile unconditionally. Returns `undefined` rather than throwing -
+ * `probeEntry` reports on every entry it is given rather than aborting the run of the other five.
+ */
+const readMetafile = async (path) => {
+    try {
+        return JSON.parse(await Bun.file(path).text());
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        console.error(`[purity] Failed to read the build metafile at ${path}: ${reason}`);
+        return undefined;
+    }
+    finally {
+        await (0, promises_1.rm)(path, { force: true });
+    }
+};
+/**
+ * The CLI, not `Bun.build()`: the in-process bundler resolves this workspace's symlinked
+ * dependencies to directories and dies on them.
+ */
+const probeEntry = async (opts) => {
+    const { entry, cwd, external = [], scratchDir = (0, node_path_1.join)(cwd, exports.PURITY_SCRATCH_DIR) } = opts;
+    await (0, promises_1.mkdir)(scratchDir, { recursive: true });
+    const metafilePath = (0, node_path_1.join)(scratchDir, `purity-${(0, node_crypto_1.randomUUID)()}.json`);
+    // `--env=disable`: Bun inlines `process.env.NODE_ENV` as a compile-time string constant by
+    // default, regardless of whether the read is reachable. That erases the very read this probe
+    // exists to catch, and the erasure depends on the ambient `NODE_ENV` the probe happens to run
+    // under - the same failure shape as the undetected leak this gate was built to prevent.
+    const externalArgs = external.flatMap((specifier) => ['--external', specifier]);
+    const proc = Bun.spawn([
+        'bun',
+        'build',
+        entry,
+        '--target=browser',
+        '--format=esm',
+        '--env=disable',
+        `--metafile=${metafilePath}`,
+        ...externalArgs,
+    ], { cwd, stdout: 'pipe', stderr: 'pipe' });
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ]);
+    if (exitCode !== 0) {
+        await (0, promises_1.rm)(metafilePath, { force: true });
+        return {
+            entry,
+            ok: false,
+            sizeBytes: 0,
+            builtins: [],
+            globals: [],
+            guardedGlobals: [],
+            external,
+            buildError: stderr.trim(),
+        };
+    }
+    const metafile = await readMetafile(metafilePath);
+    if (!metafile) {
+        return {
+            entry,
+            ok: false,
+            sizeBytes: stdout.length,
+            builtins: [],
+            globals: [],
+            guardedGlobals: [],
+            external,
+            buildError: 'Could not read the bun build metafile - the probe result is not trustworthy',
+        };
+    }
+    const builtins = findBuiltinSpecifiers(metafile);
+    const reachesDevConfigs = Object.keys(metafile.inputs).some((inputPath) => DEV_CONFIGS_PATH.test(inputPath));
+    const unresolvedExternals = findUnresolvedExternalSpecifiers({
+        metafile,
+        builtins: new Set(builtins),
+        requestedExternal: new Set(external),
+    });
+    const scannableText = (0, exports.stripBundlerPathComments)(stdout);
+    const matched = exports.GLOBAL_PATTERNS.filter((g) => g.pattern.test(scannableText));
+    const globals = matched.filter((g) => g.severity === ProbeSeverities.ERROR).map((g) => g.name);
+    const guardedGlobals = matched
+        .filter((g) => g.severity === ProbeSeverities.GUARDED)
+        .map((g) => g.name);
+    if (builtins.length > 0 || unresolvedExternals.length > 0 || reachesDevConfigs) {
+        const reasons = [];
+        if (reachesDevConfigs) {
+            reasons.push('reaches @venizia/dev-configs, which is Bun-only tooling and never a browser dependency');
+        }
+        if (builtins.length > 0) {
+            reasons.push(`node builtin import(s): ${builtins.join(', ')}`);
+        }
+        if (unresolvedExternals.length > 0) {
+            reasons.push(`unresolved external import(s): ${unresolvedExternals.join(', ')}`);
+        }
+        return {
+            entry,
+            ok: false,
+            sizeBytes: stdout.length,
+            builtins,
+            globals,
+            guardedGlobals,
+            external,
+            buildError: reasons.join(' | '),
+        };
+    }
+    return {
+        entry,
+        ok: globals.length === 0,
+        sizeBytes: stdout.length,
+        builtins,
+        globals,
+        guardedGlobals,
+        external,
+    };
+};
+exports.probeEntry = probeEntry;
+//# sourceMappingURL=probe.js.map

package/dist/checks/purity/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../../../src/checks/purity/probe.ts"],"names":[],"mappings":";;;AAAA,6CAAyC;AACzC,+CAA6C;AAC7C,6CAA6C;AAC7C,yCAAiC;AAmBjC,kIAAkI;AACrH,QAAA,kBAAkB,GAAG,mBAAmB,CAAC;AAEtD;;;GAGG;AACH,MAAM,gBAAgB,GACpB,2FAA2F,CAAC;AAE9F,wFAAwF;AACxF,MAAa,eAAe;aACV,UAAK,GAAG,OAAO,CAAC;aAChB,YAAO,GAAG,SAAS,CAAC;aAEpB,eAAU,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;IAEzE,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AARH,0CASC;AAOD;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,eAAe,GAIvB;IACH,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,iCAAiC,EAAE,QAAQ,EAAE,OAAO,EAAE;IAClF,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,mCAAmC,EAAE,QAAQ,EAAE,SAAS,EAAE;IACxF;QACE,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,mDAAmD;QAC5D,QAAQ,EAAE,OAAO;KAClB;IACD;QACE,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,qDAAqD;QAC9D,QAAQ,EAAE,SAAS;KACpB;IACD;QACE,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,+CAA+C;QACxD,QAAQ,EAAE,OAAO;KAClB;IACD;QACE,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,gDAAgD;QACzD,QAAQ,EAAE,OAAO;KAClB;IACD;QACE,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,uCAAuC;QAChD,QAAQ,EAAE,OAAO;KAClB;IACD,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,iCAAiC,EAAE,QAAQ,EAAE,OAAO,EAAE;IACnF,6FAA6F;IAC7F,8CAA8C;IAC9C,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,6BAA6B,EAAE,QAAQ,EAAE,OAAO,EAAE;CAC3E,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,oBAAoB,GAAG,gCAAgC,CAAC;AAE9D;;;;GAIG;AACI,MAAM,wBAAwB,GAAG,CAAC,IAAY,EAAU,EAAE;IAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC,CAAC;AAFW,QAAA,wBAAwB,4BAEnC;AAgBF;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,4BAAc,CAAC,CAAC;AAErD,MAAM,kBAAkB,GAAG,CAAC,SAAiB,EAAW,EAAE;IACxD,MAAM,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC7F,OAAO,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAC5C,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,qBAAqB,GAAG,CAAC,QAAmB,EAAY,EAAE;IAC9D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAEnC,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,qBAAqB,EAAE,CAAC;QACvD,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC1B,CAAC;QAED,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACvC,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC;YACzD,IAAI,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC;gBAClC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9B,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH;;;;;;;GAOG;AACH,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAW,EAAE;IACzD,OAAO,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF,MAAM,gCAAgC,GAAG,CAAC,IAIzC,EAAY,EAAE;IACb,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,IAAI,CAAC;IACvD,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IAErC,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAW,EAAE;QACzD,KAAK,MAAM,SAAS,IAAI,iBAAiB,EAAE,CAAC;YAC1C,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;gBACrE,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5D,KAAK,MAAM,KAAK,IAAI,oBAAoB,EAAE,CAAC;QACzC,KAAK,MAAM,UAAU,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACvC,IAAI,CAAC,UAAU,CAAC,QAAQ,EAAE,CAAC;gBACzB,SAAS;YACX,CAAC;YAED,MAAM,SAAS,GAAG,UAAU,CAAC,QAAQ,IAAI,UAAU,CAAC,IAAI,CAAC;YACzD,IACE,mBAAmB,CAAC,SAAS,CAAC;gBAC9B,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;gBACvB,mBAAmB,CAAC,SAAS,CAAC,EAC9B,CAAC;gBACD,SAAS;YACX,CAAC;YAED,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;AAChC,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,YAAY,GAAG,KAAK,EAAE,IAAY,EAAkC,EAAE;IAC1E,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAc,CAAC;IAC9D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO,CAAC,KAAK,CAAC,iDAAiD,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QAClF,OAAO,SAAS,CAAC;IACnB,CAAC;YAAS,CAAC;QACT,MAAM,IAAA,aAAE,EAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAClC,CAAC;AACH,CAAC,CAAC;AAEF;;;GAGG;AACI,MAAM,UAAU,GAAG,KAAK,EAAE,IAMhC,EAA0B,EAAE;IAC3B,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,GAAG,EAAE,EAAE,UAAU,GAAG,IAAA,gBAAI,EAAC,GAAG,EAAE,0BAAkB,CAAC,EAAE,GAAG,IAAI,CAAC;IACvF,MAAM,IAAA,gBAAK,EAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,YAAY,GAAG,IAAA,gBAAI,EAAC,UAAU,EAAE,UAAU,IAAA,wBAAU,GAAE,OAAO,CAAC,CAAC;IAErE,2FAA2F;IAC3F,6FAA6F;IAC7F,8FAA8F;IAC9F,wFAAwF;IACxF,MAAM,YAAY,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC,CAAC;IAChF,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CACpB;QACE,KAAK;QACL,OAAO;QACP,KAAK;QACL,kBAAkB;QAClB,cAAc;QACd,eAAe;QACf,cAAc,YAAY,EAAE;QAC5B,GAAG,YAAY;KAChB,EACD,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,CACxC,CAAC;IAEF,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QAChC,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE;QAChC,IAAI,CAAC,MAAM;KACZ,CAAC,CAAC;IAEH,IAAI,QAAQ,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,IAAA,aAAE,EAAC,YAAY,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACxC,OAAO;YACL,KAAK;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,EAAE;YACX,cAAc,EAAE,EAAE;YAClB,QAAQ;YACR,UAAU,EAAE,MAAM,CAAC,IAAI,EAAE;SAC1B,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,KAAK;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,MAAM,CAAC,MAAM;YACxB,QAAQ,EAAE,EAAE;YACZ,OAAO,EAAE,EAAE;YACX,cAAc,EAAE,EAAE;YAClB,QAAQ;YACR,UAAU,EAAE,6EAA6E;SAC1F,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACjD,MAAM,iBAAiB,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CACxE,gBAAgB,CAAC,IAAI,CAAC,SAAS,CAAC,CACjC,CAAC;IACF,MAAM,mBAAmB,GAAG,gCAAgC,CAAC;QAC3D,QAAQ;QACR,QAAQ,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC;QAC3B,iBAAiB,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC;KACrC,CAAC,CAAC;IACH,MAAM,aAAa,GAAG,IAAA,gCAAwB,EAAC,MAAM,CAAC,CAAC;IACvD,MAAM,OAAO,GAAG,uBAAe,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IAC7E,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,eAAe,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC/F,MAAM,cAAc,GAAG,OAAO;SAC3B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,eAAe,CAAC,OAAO,CAAC;SACrD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAEtB,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,IAAI,iBAAiB,EAAE,CAAC;QAC/E,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,iBAAiB,EAAE,CAAC;YACtB,OAAO,CAAC,IAAI,CACV,wFAAwF,CACzF,CAAC;QACJ,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,2BAA2B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnC,OAAO,CAAC,IAAI,CAAC,kCAAkC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACnF,CAAC;QAED,OAAO;YACL,KAAK;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,MAAM,CAAC,MAAM;YACxB,QAAQ;YACR,OAAO;YACP,cAAc;YACd,QAAQ;YACR,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC;SAChC,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK;QACL,EAAE,EAAE,OAAO,CAAC,MAAM,KAAK,CAAC;QACxB,SAAS,EAAE,MAAM,CAAC,MAAM;QACxB,QAAQ;QACR,OAAO;QACP,cAAc;QACd,QAAQ;KACT,CAAC;AACJ,CAAC,CAAC;AAnHW,QAAA,UAAU,cAmHrB","sourcesContent":["import { randomUUID } from 'node:crypto';\nimport { mkdir, rm } from 'node:fs/promises';\nimport { builtinModules } from 'node:module';\nimport { join } from 'node:path';\n\nexport interface IPurityResult {\n  entry: string;\n  ok: boolean;\n  sizeBytes: number;\n  builtins: string[];\n  globals: string[];\n  /** Node-global reads that cannot throw in a browser. Reported, never fatal. */\n  guardedGlobals: string[];\n  /**\n   * Specifiers this probe run excluded from its own module graph. Always echoed back, on both the\n   * passing and failing path - an entry that externalises something is measuring less than an entry\n   * that does not, and that must stay visible next to the result, not be a silent input.\n   */\n  external: string[];\n  buildError?: string;\n}\n\n/** Where the probe keeps its metafile, relative to the `cwd` it is given: the repository's own scratch, never the system temp. */\nexport const PURITY_SCRATCH_DIR = '.agents/local/tmp';\n\n/**\n * A browser entry must never reach `@venizia/dev-configs`: it is the Bun-only tooling package (its\n * `./testing` entry imports `bun:test`). Matches the workspace folder (not its own test fixtures) and the installed copy.\n */\nconst DEV_CONFIGS_PATH =\n  /(^|\\/)(packages\\/dev-configs\\/(?!src\\/__tests__\\/)|node_modules\\/@venizia\\/dev-configs\\/)/;\n\n/** What a matched global means: ERROR is fatal, GUARDED is reported and never fatal. */\nexport class ProbeSeverities {\n  static readonly ERROR = 'error';\n  static readonly GUARDED = 'guarded';\n\n  static readonly SCHEME_SET = new Set<string>([this.ERROR, this.GUARDED]);\n\n  static isValid(value: string): value is TProbeSeverity {\n    return this.SCHEME_SET.has(value);\n  }\n}\n\nexport type TProbeSeverity = Extract<\n  (typeof ProbeSeverities)[keyof typeof ProbeSeverities],\n  string\n>;\n\n/**\n * Node globals survive verbatim into a `target: 'browser'` bundle, so a gate reading only module\n * specifiers reports clean on `process.env.NODE_ENV`. Each pattern must be anchored: a bundle\n * legitimately contains identifiers like `processQueue`. A lookbehind that rejects a preceding dot\n * also rejects `globalThis.process`, so every access path needs its own pattern.\n *\n * `severity` separates a read that throws from one that cannot. Optional chaining is not itself the\n * difference: `process?.env` throws a ReferenceError when `process` is a free identifier, while\n * `globalThis.process?.env` is an ordinary property read on an object that always exists.\n *\n * `guarded` means \"reported, never fatal\". Bare `process?.` sits there because this probe matches\n * bundled text and has no scope information: hono's `getColorEnabled` writes\n * `const { process, Deno } = globalThis;` and then `process?.env`, which is a local binding and\n * perfectly safe, and no regex can tell that apart from a free global. Failing on it would make the\n * gate cry wolf on a dependency; the unguarded `process.` and `globalThis.process.` forms stay\n * fatal, and those are the ones that are unambiguously browser-breaking.\n *\n * Exported for `probe.test.ts` to assert against directly, alongside {@link stripBundlerPathComments}.\n */\nexport const GLOBAL_PATTERNS: Array<{\n  name: string;\n  pattern: RegExp;\n  severity: TProbeSeverity;\n}> = [\n  { name: 'process', pattern: /(?<![A-Za-z0-9_$.])process\\s*\\./, severity: 'error' },\n  { name: 'process?.', pattern: /(?<![A-Za-z0-9_$.])process\\s*\\?\\./, severity: 'guarded' },\n  {\n    name: 'globalThis.process',\n    pattern: /(?<![A-Za-z0-9_$.])globalThis\\s*\\.\\s*process\\s*\\./,\n    severity: 'error',\n  },\n  {\n    name: 'globalThis.process?.',\n    pattern: /(?<![A-Za-z0-9_$.])globalThis\\s*\\.\\s*process\\s*\\?\\./,\n    severity: 'guarded',\n  },\n  {\n    name: '__dirname',\n    pattern: /(?<![A-Za-z0-9_$.])__dirname(?![A-Za-z0-9_$])/,\n    severity: 'error',\n  },\n  {\n    name: '__filename',\n    pattern: /(?<![A-Za-z0-9_$.])__filename(?![A-Za-z0-9_$])/,\n    severity: 'error',\n  },\n  {\n    name: 'createRequire',\n    pattern: /(?<![A-Za-z0-9_$.])createRequire\\s*\\(/,\n    severity: 'error',\n  },\n  { name: 'require(', pattern: /(?<![A-Za-z0-9_$.])require\\s*\\(/, severity: 'error' },\n  // Member access only. `typeof Bun !== 'undefined'` is the legitimate runtime probe and never\n  // throws; `Bun.serve(...)` in a browser does.\n  { name: 'Bun', pattern: /(?<![A-Za-z0-9_$.])Bun\\s*\\./, severity: 'error' },\n];\n\n/**\n * Bun's bundler prefixes every CommonJS-wrapped module with a full-line `// <path>.js` header (this\n * whole workspace emits CJS `dist/*.js` - no package declares `\"type\": \"module\"`). A source path is\n * free-form and can legitimately contain `process` as a substring with no identifier boundary on\n * its left, e.g. this gate's own `transport/in-process.js`: the header reads\n * `// packages/core-worker/dist/transport/in-process.js`, and `process.` there is a filename\n * fragment, not a read of the global. `GLOBAL_PATTERNS` matches bundled TEXT with no scope\n * information, so it cannot tell a path comment from code - stripped before matching.\n */\nconst BUNDLER_PATH_COMMENT = /^\\/\\/ [\\w@./-]+\\.(?:c|m)?js$/gm;\n\n/**\n * Exported so `probe.test.ts` can assert against the literal collision string directly, without\n * spawning `bun build` - a fixture whose OWN entry-path comment happens to reproduce the collision\n * is not something a filename choice can be relied on to keep reproducing.\n */\nexport const stripBundlerPathComments = (text: string): string => {\n  return text.replace(BUNDLER_PATH_COMMENT, '');\n};\n\ninterface IMetafileImport {\n  path: string;\n  original?: string;\n  external?: boolean;\n}\n\ninterface IMetafileInput {\n  imports: IMetafileImport[];\n}\n\ninterface IMetafile {\n  inputs: Record<string, IMetafileInput>;\n}\n\n/**\n * `node:module`'s own list, not a hand-maintained one: a bare `import ... from 'fs'` bundles\n * identically to `'node:fs'` (Bun stubs both to an empty object), and the metafile records\n * whichever spelling the source used. Matching by prefix alone misses the bare form entirely.\n */\nconst BUILTIN_MODULE_NAMES = new Set(builtinModules);\n\nconst isBuiltinSpecifier = (specifier: string): boolean => {\n  const bareName = specifier.startsWith('node:') ? specifier.slice('node:'.length) : specifier;\n  return BUILTIN_MODULE_NAMES.has(bareName);\n};\n\n/**\n * Measured against Bun 1.3.14: `--target=browser` never fails on a `node:` import and never leaves\n * the specifier in the bundled text. An unpolyfillable builtin (`fs`, `child_process`, ...) is\n * stubbed to an empty object; a polyfillable one (`crypto`, `path`, ...) is inlined in full under a\n * `/bun-vfs$$/` virtual path. Either way `exitCode` stays 0 and the specifier never survives into\n * stdout. The `--metafile` module graph is the only place it is preserved.\n */\nconst findBuiltinSpecifiers = (metafile: IMetafile): string[] => {\n  const builtins = new Set<string>();\n\n  const metafileInputsEntries = Object.entries(metafile.inputs);\n  for (const [inputPath, input] of metafileInputsEntries) {\n    if (isBuiltinSpecifier(inputPath)) {\n      builtins.add(inputPath);\n    }\n\n    for (const dependency of input.imports) {\n      const specifier = dependency.original ?? dependency.path;\n      if (isBuiltinSpecifier(specifier)) {\n        builtins.add(specifier);\n      }\n    }\n  }\n\n  return [...builtins].sort();\n};\n\n/**\n * A real npm dependency bundles in full under this target (measured: `zod` produces zero\n * `external` entries) and a genuinely missing package fails the build outright (nonzero exit,\n * caught before this runs). But a package's own `browser` field can remap a dependency to `false` -\n * the standard convention for disabling a Node-only dependency in browser builds - and Bun honours\n * that remap by leaving the import external with exit 0, whether or not the remapped name is a\n * builtin. An unresolved import in a browser bundle is not safe to wave through either way -\n * UNLESS the manifest entry asked for exactly this specifier via `external`, in which case its\n * presence here is the requested exclusion working, not a leak.\n */\n/**\n * A relative specifier is the package's own file, and a truly unreachable one fails the build with a\n * nonzero exit, which is caught before this runs. Bun's METAFILE nonetheless marks a re-export of the\n * form `export { name } from './x.js'` as `external` while inlining it - measured on\n * `helpers/dist/esm/core.js`: six such specifiers reported external, `Bundled 192 modules`, and the\n * output contains `class BaseHelper` with no bare relative import left in it. Reading the metafile\n * literally there reports a leak the bundle does not have.\n */\nconst isRelativeSpecifier = (specifier: string): boolean => {\n  return specifier.startsWith('./') || specifier.startsWith('../');\n};\n\nconst findUnresolvedExternalSpecifiers = (opts: {\n  metafile: IMetafile;\n  builtins: Set<string>;\n  requestedExternal: Set<string>;\n}): string[] => {\n  const { metafile, builtins, requestedExternal } = opts;\n  const unresolved = new Set<string>();\n\n  const isRequestedExternal = (specifier: string): boolean => {\n    for (const requested of requestedExternal) {\n      if (specifier === requested || specifier.startsWith(`${requested}/`)) {\n        return true;\n      }\n    }\n    return false;\n  };\n\n  const metafileInputsValues = Object.values(metafile.inputs);\n  for (const input of metafileInputsValues) {\n    for (const dependency of input.imports) {\n      if (!dependency.external) {\n        continue;\n      }\n\n      const specifier = dependency.original ?? dependency.path;\n      if (\n        isRelativeSpecifier(specifier) ||\n        builtins.has(specifier) ||\n        isRequestedExternal(specifier)\n      ) {\n        continue;\n      }\n\n      unresolved.add(specifier);\n    }\n  }\n\n  return [...unresolved].sort();\n};\n\n/**\n * Reads and removes the metafile unconditionally. Returns `undefined` rather than throwing -\n * `probeEntry` reports on every entry it is given rather than aborting the run of the other five.\n */\nconst readMetafile = async (path: string): Promise<IMetafile | undefined> => {\n  try {\n    return JSON.parse(await Bun.file(path).text()) as IMetafile;\n  } catch (error) {\n    const reason = error instanceof Error ? error.message : String(error);\n    console.error(`[purity] Failed to read the build metafile at ${path}: ${reason}`);\n    return undefined;\n  } finally {\n    await rm(path, { force: true });\n  }\n};\n\n/**\n * The CLI, not `Bun.build()`: the in-process bundler resolves this workspace's symlinked\n * dependencies to directories and dies on them.\n */\nexport const probeEntry = async (opts: {\n  entry: string;\n  cwd: string;\n  external?: string[];\n  /** Defaults to {@link PURITY_SCRATCH_DIR} under `cwd`. */\n  scratchDir?: string;\n}): Promise<IPurityResult> => {\n  const { entry, cwd, external = [], scratchDir = join(cwd, PURITY_SCRATCH_DIR) } = opts;\n  await mkdir(scratchDir, { recursive: true });\n  const metafilePath = join(scratchDir, `purity-${randomUUID()}.json`);\n\n  // `--env=disable`: Bun inlines `process.env.NODE_ENV` as a compile-time string constant by\n  // default, regardless of whether the read is reachable. That erases the very read this probe\n  // exists to catch, and the erasure depends on the ambient `NODE_ENV` the probe happens to run\n  // under - the same failure shape as the undetected leak this gate was built to prevent.\n  const externalArgs = external.flatMap((specifier) => ['--external', specifier]);\n  const proc = Bun.spawn(\n    [\n      'bun',\n      'build',\n      entry,\n      '--target=browser',\n      '--format=esm',\n      '--env=disable',\n      `--metafile=${metafilePath}`,\n      ...externalArgs,\n    ],\n    { cwd, stdout: 'pipe', stderr: 'pipe' },\n  );\n\n  const [stdout, stderr, exitCode] = await Promise.all([\n    new Response(proc.stdout).text(),\n    new Response(proc.stderr).text(),\n    proc.exited,\n  ]);\n\n  if (exitCode !== 0) {\n    await rm(metafilePath, { force: true });\n    return {\n      entry,\n      ok: false,\n      sizeBytes: 0,\n      builtins: [],\n      globals: [],\n      guardedGlobals: [],\n      external,\n      buildError: stderr.trim(),\n    };\n  }\n\n  const metafile = await readMetafile(metafilePath);\n  if (!metafile) {\n    return {\n      entry,\n      ok: false,\n      sizeBytes: stdout.length,\n      builtins: [],\n      globals: [],\n      guardedGlobals: [],\n      external,\n      buildError: 'Could not read the bun build metafile - the probe result is not trustworthy',\n    };\n  }\n\n  const builtins = findBuiltinSpecifiers(metafile);\n  const reachesDevConfigs = Object.keys(metafile.inputs).some((inputPath) =>\n    DEV_CONFIGS_PATH.test(inputPath),\n  );\n  const unresolvedExternals = findUnresolvedExternalSpecifiers({\n    metafile,\n    builtins: new Set(builtins),\n    requestedExternal: new Set(external),\n  });\n  const scannableText = stripBundlerPathComments(stdout);\n  const matched = GLOBAL_PATTERNS.filter((g) => g.pattern.test(scannableText));\n  const globals = matched.filter((g) => g.severity === ProbeSeverities.ERROR).map((g) => g.name);\n  const guardedGlobals = matched\n    .filter((g) => g.severity === ProbeSeverities.GUARDED)\n    .map((g) => g.name);\n\n  if (builtins.length > 0 || unresolvedExternals.length > 0 || reachesDevConfigs) {\n    const reasons: string[] = [];\n    if (reachesDevConfigs) {\n      reasons.push(\n        'reaches @venizia/dev-configs, which is Bun-only tooling and never a browser dependency',\n      );\n    }\n    if (builtins.length > 0) {\n      reasons.push(`node builtin import(s): ${builtins.join(', ')}`);\n    }\n    if (unresolvedExternals.length > 0) {\n      reasons.push(`unresolved external import(s): ${unresolvedExternals.join(', ')}`);\n    }\n\n    return {\n      entry,\n      ok: false,\n      sizeBytes: stdout.length,\n      builtins,\n      globals,\n      guardedGlobals,\n      external,\n      buildError: reasons.join(' | '),\n    };\n  }\n\n  return {\n    entry,\n    ok: globals.length === 0,\n    sizeBytes: stdout.length,\n    builtins,\n    globals,\n    guardedGlobals,\n    external,\n  };\n};\n"]}