carveout 0.1.0 → 0.1.2

package/dist/src/project/provenance.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How every dependency of a cut is satisfied: the cut modules become
+ * runtime mocks generated from their declarations, service packages and
+ * packages no lockfile shows come from the public registry become mock
+ * packages, and the rest install at the version the source pins.
+ *
+ * The slice manifest and boundary contract are the inputs; this module
+ * reads them and never the source.
+ */
+import type { SliceManifest, BoundaryContract } from "../slice/manifest.js";
+export declare const DEPENDENCY_RESOLUTIONS: readonly ["included-code", "runtime-mock", "approved-package", "unresolved"];
+export type DependencyResolution = (typeof DEPENDENCY_RESOLUTIONS)[number];
+/** Whether the registry resolves a pin, directly or through an alias. */
+export declare function isRegistryVersion(version: string): boolean;
+export interface ResolvedDependency {
+    /** A package name, or a repository path for a cut module. */
+    readonly name: string;
+    readonly kind: "package" | "module";
+    readonly version: string | null;
+    readonly resolution: DependencyResolution;
+    readonly detail: string;
+}
+/** What the owner may decide per dependency; the rest is derived. */
+export type DependencyChoice = "runtime-mock" | "approved-package";
+export interface ProvenanceBlocker {
+    readonly code: "slice_not_ready" | "dependency_unresolved" | "partial_signature_coverage" | "alias_rules_invalid" | "operation_unapproved";
+    readonly detail: string;
+}
+/**
+ * The classification a cut gives every path. Copied source keeps its
+ * structure; generated files live apart from it and are never editable.
+ */
+export declare const PATH_CLASSES: readonly ["source", "stub", "mock", "test-public", "config", "harness"];
+export type PathClass = (typeof PATH_CLASSES)[number];
+export interface ScopeRecord {
+    /** Repository paths a contribution may edit, sorted. */
+    readonly editablePaths: readonly string[];
+    /** Repository paths whose content is generated, sorted, never editable. */
+    readonly generatedPaths: readonly string[];
+    readonly permittedOperations: readonly ("edit" | "add" | "delete" | "rename")[];
+    readonly dependencies: readonly ResolvedDependency[];
+    readonly blockers: readonly ProvenanceBlocker[];
+}
+export interface ScopeInput {
+    readonly manifest: SliceManifest;
+    readonly contract: BoundaryContract;
+    /** Owner choices by package name; unspecified names take the default. */
+    readonly choices?: Readonly<Record<string, DependencyChoice>>;
+}
+/** Choices naming a package the slice does not require: a typo, never applied. */
+export declare function unknownDependencyChoices(manifest: Pick<SliceManifest, "requiredBuildInputs">, choices: Readonly<Record<string, DependencyChoice>>): string[];
+/**
+ * Resolves every dependency of the slice. Cut modules with full declaration
+ * coverage become runtime mocks generated from their declarations; service
+ * packages the externals pass named default to runtime mocks; a pinned
+ * package the repository shows comes from the public registry is approved
+ * for installation, and any other defaults to a runtime mock, since a
+ * private registry's name is anyone's on the public one. An owner may
+ * approve a package the repository says nothing of, never one it fetches
+ * from another registry or its own workspace's. An unpinned package blocks
+ * unless it is mocked, by default or by choice. Dynamic and unresolved
+ * imports are blockers the slice already carries, and they stay blockers
+ * here.
+ */
+export declare function resolveScope(input: ScopeInput): ScopeRecord;
+/**
+ * Whether a name is one npm installs a package by: `zod`, `@scope/name`.
+ * A Vite virtual module (`virtual:build-info`), an alias that resolved
+ * nowhere (`@/api`) or any other scheme is not; a slice mocks it as a
+ * module of its own, never as a package.
+ */
+export declare function isPackageName(name: string): boolean;
+export declare function packageNameOf(specifier: string): string;

package/dist/src/project/provenance.js

@@ -206,6 +206,18 @@ export function resolveScope(input) {
         blockers,
     };
 }
+/**
+ * Whether a name is one npm installs a package by: `zod`, `@scope/name`.
+ * A Vite virtual module (`virtual:build-info`), an alias that resolved
+ * nowhere (`@/api`) or any other scheme is not; a slice mocks it as a
+ * module of its own, never as a package.
+ */
+export function isPackageName(name) {
+    // npm's rule, but a leading `~`: `~/lib/errors` is the common alias for a
+    // source folder, and `~icons/…` a bundler's virtual module, never a
+    // package anyone installs.
+    return name.length <= 214 && /^(@[a-z0-9-][a-z0-9._~-]*\/)?[a-z0-9-][a-z0-9._~-]*$/i.test(name);
+}
 export function packageNameOf(specifier) {
     const parts = specifier.split("/");
     return specifier.startsWith("@") && parts.length > 1

package/dist/src/project/runner.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The test runner of a test file that imports none: Vitest with `globals`
+ * (`describe`, `it`, `expect` as globals) in a package that depends on
+ * Vitest and not on Jest. A test that imports `node:test` or `vitest` says
+ * its runner itself (`testRunnerOf`). Without this, every test of a package
+ * on Vitest's globals was left behind as running on no known runner (E8g:
+ * all 11 tests of an n8n module).
+ */
+import { type TestRunner } from "../slice/reach.js";
+/** The pattern's source, for the folder's own test runner to use. */
+export declare const GLOBAL_CALL_SOURCE: string;
+/** Whether a test file calls a runner's globals without importing one. */
+export declare function usesTestGlobals(text: string): boolean;
+/**
+ * The runner of each test file: its imports first, then a package on
+ * Vitest's globals (the file's package, else the repository's root). Jest
+ * is not run by a slice, so a package on Jest gives null.
+ */
+export declare function testRunnerResolver(repo: string, packageOf: (file: string) => string): (file: string, specifiers: readonly string[]) => TestRunner | null;

package/dist/src/project/secrets.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Secrets: the credentials a source repository can hold in its text (a
+ * private key, a cloud or API token, a password assigned in code) and the
+ * files that exist to hold them (`.env`, `*.pem`, a service-account JSON).
+ *
+ * A sandbox is cut from a private repository, so a slice that reaches a
+ * secret-named file is refused, and a build scans every public file it
+ * generates and blocks on what it finds. A finding names its rule, file and
+ * line, never the value: a blocker is shown to the people and agents the
+ * value must not reach.
+ *
+ * Provider rules match a token's own shape (an `Authorization: Bearer`
+ * header's and an `.npmrc` `_authToken`'s too), and skip one only when what
+ * follows its prefix is a placeholder as a whole (`ghp_xxxx…`, `${TOKEN}`,
+ * `<token>`, `your-token-here`, AWS's documented `…EXAMPLE` keys): a real
+ * token can hold `Test` by chance or by its owner's choice. A URL's password
+ * (`postgres://app:…@db`) counts unless it is empty, a template or such a
+ * placeholder (`user:password@`).
+ *
+ * The generic rule needs a name whose last word says secret (`apiKey`,
+ * `DB_PASSWORD`, `client_secret`, not `tokenizerModel` or
+ * `passwordResetPath`) assigned a long literal of high entropy with letters
+ * and digits, and skips values with a placeholder word in them (`fixture`,
+ * `test`, `your`) and values that read as a path, an ARN or words joined
+ * (`token-refresh-queue-v2`, `gpt-4o-mini-2024-07-18`). A password-named
+ * literal of letters alone (`correcthorsebatterystaple`) counts too unless
+ * it is shaped like an identifier. An environment read is not a literal, so
+ * it never matches, but its fallback (`process.env.API_KEY ?? "…"`) is. A
+ * hex value under a name that says it is a hash (`tokenHash`,
+ * `secretDigest`) is a digest, not a credential.
+ */
+import type { ProjectBlocker } from "./project.js";
+export declare const SECRET_RULES: readonly ["private-key", "aws-access-key-id", "github-token", "gitlab-token", "npm-token", "slack-token", "stripe-live-key", "google-api-key", "google-service-account", "sendgrid-key", "huggingface-token", "jwt", "anthropic-key", "openai-key", "bearer-token", "url-credentials", "generic-secret"];
+export type SecretRule = (typeof SECRET_RULES)[number];
+export interface SecretFinding {
+    readonly rule: SecretRule;
+    readonly file: string;
+    /** 1-based. */
+    readonly line: number;
+}
+/** Shannon entropy of a string, in bits per character. */
+export declare function entropy(text: string): number;
+/** Each secret found in each file's text, by file, line and rule. */
+export declare function scanSecrets(files: readonly {
+    readonly path: string;
+    readonly text: string;
+}[]): SecretFinding[];
+/**
+ * Files that exist to hold credentials: environment files (`.env`,
+ * `.env.local`, `.env-prod`, `prod.env`, direnv's `.envrc`), keys and
+ * keystores, SSH identities, credential, service-account, admin SDK and
+ * key JSON, secrets files (`secrets.yml`, `app.secrets.json`), Terraform
+ * variables, kubeconfigs, AWS shared credentials and Docker's and Kubernetes'
+ * client configuration, and npm, PyPI, Git, Postgres and netrc credential
+ * files (which carry registry, host and database passwords). Matched on the
+ * basename, case-insensitively, except `.aws/credentials`,
+ * `.docker/config.json` and `.kube/config`, path suffixes. An environment
+ * template (`.env.example`, `.env.local.sample`, `.env-template`) documents
+ * keys, not values, so it is not one; its text is scanned like any other.
+ * No slice may include one, and no agent tool reads one.
+ */
+export declare function isSecretPath(path: string): boolean;
+/** A blocker for each file with findings, naming lines and rules, never values. */
+export declare function secretBlockers(findings: readonly SecretFinding[]): ProjectBlocker[];

package/dist/src/project/vitest-config.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The Vitest settings a package's tests run under, read from its config's
+ * syntax and never run: the environment (`jsdom` for a component's tests,
+ * which otherwise fail on `document is not defined`), the setup files that
+ * run before them, the test timeout and the globals. A slice that carries
+ * the package's Vitest tests runs them under the same settings: the setup
+ * files come along as entry points, the environment's package is installed
+ * as the repository locks it, and the folder gets a `vitest.config.mjs`.
+ */
+/** What a package's Vitest config sets for its tests, as far as the slice needs. */
+export interface VitestSettings {
+    /** `jsdom`, `happy-dom`, `node`, or another environment's name. */
+    readonly environment?: string;
+    /** Setup files, as paths from the repository's root. */
+    readonly setupFiles: readonly string[];
+    /**
+     * Setup files named by a package's specifier
+     * (`@testing-library/jest-dom/vitest`): installed, and run as named.
+     */
+    readonly setupPackages?: readonly string[];
+    readonly testTimeout?: number;
+    readonly globals?: boolean;
+    /** The test files it runs (`test.include`), as globs from the repository's root. */
+    readonly include?: readonly string[];
+    /**
+     * The config's inline projects (`test.projects`), each with what it
+     * sets: Vitest runs a test under the project whose `include` matches it.
+     */
+    readonly projects?: readonly VitestProject[];
+}
+/** One inline project of a Vitest config, its paths from the repository's root. */
+export interface VitestProject {
+    readonly name?: string;
+    /** Globs from the repository's root. */
+    readonly include?: readonly string[];
+    readonly environment?: string;
+    readonly setupFiles: readonly string[];
+    readonly setupPackages?: readonly string[];
+    readonly testTimeout?: number;
+    readonly globals?: boolean;
+}
+/** The packages each environment runs on. */
+export declare const ENVIRONMENT_PACKAGES: Readonly<Record<string, readonly string[]>>;
+/**
+ * The environments a test file asks for itself, in a docblock comment
+ * (`// @vitest-environment happy-dom`), which run whatever the config says.
+ */
+export declare function fileEnvironments(text: string): string[];
+/**
+ * The settings of the first Vitest config in `dir` (`vitest.config.*`,
+ * then `vite.config.*`), else at the repository's root, or null when there
+ * is none or it sets nothing the slice can carry. The `test` object is the
+ * default export's (through `defineConfig`, a function, a name), else the
+ * first `test: {…}` in the file. Only literal values are read: a computed
+ * one is left to Vitest's default.
+ */
+export declare function vitestSettings(repo: string, dir: string): VitestSettings | null;
+/**
+ * The folder's `vitest.config.mjs`: the settings, with the setup files at
+ * their folder paths; an alias for each module that is no package
+ * (`virtual:build-info`, and its subpaths) to its mock under `carveout/`;
+ * and a resolver that reads the source beside a built `.js`. The folder's
+ * build writes a `.js` beside each `.ts` for node:test, and a relative
+ * `./x.js` would otherwise be that file to Vitest: `vitest` run on its own
+ * after an edit tested the code as it was at the last build, where the
+ * repository's Vitest reads the source.
+ */
+export declare function vitestConfigText(settings: VitestSettings, folderPath?: (path: string) => string, 
+/** Module name → the folder of its mock, from the folder's root. */
+virtualModules?: Readonly<Record<string, string>>): string;

package/dist/src/project/vitest-config.js

@@ -0,0 +1,291 @@
+/**
+ * The Vitest settings a package's tests run under, read from its config's
+ * syntax and never run: the environment (`jsdom` for a component's tests,
+ * which otherwise fail on `document is not defined`), the setup files that
+ * run before them, the test timeout and the globals. A slice that carries
+ * the package's Vitest tests runs them under the same settings: the setup
+ * files come along as entry points, the environment's package is installed
+ * as the repository locks it, and the folder gets a `vitest.config.mjs`.
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, posix } from "node:path";
+import ts from "typescript";
+const CONFIG_NAMES = ["vitest.config", "vite.config"].flatMap((name) => ["ts", "mts", "cts", "js", "mjs", "cjs"].map((ext) => `${name}.${ext}`));
+/** The packages each environment runs on. */
+export const ENVIRONMENT_PACKAGES = {
+    jsdom: ["jsdom"],
+    "happy-dom": ["happy-dom"],
+    "edge-runtime": ["@edge-runtime/vm"],
+};
+/**
+ * The environments a test file asks for itself, in a docblock comment
+ * (`// @vitest-environment happy-dom`), which run whatever the config says.
+ */
+export function fileEnvironments(text) {
+    return [...new Set([...text.matchAll(/@vitest-environment\s+([\w-]+)/g)].map((match) => match[1] ?? ""))].filter(Boolean);
+}
+/** An expression with what only types it taken away: `(x)`, `x as T`, `x satisfies T`, `<T>x`. */
+function bare(node) {
+    let at = node;
+    for (;;) {
+        if (ts.isParenthesizedExpression(at) || ts.isAsExpression(at) || ts.isSatisfiesExpression(at) || ts.isTypeAssertionExpression(at))
+            at = at.expression;
+        else
+            return at;
+    }
+}
+/**
+ * The object an expression of the config comes to, read and never run: an
+ * object literal; a call's (`defineConfig({…})`, `mergeConfig(a, b)`, the
+ * last that is one); a function's result (`defineConfig(() => ({…}))`, or
+ * its block's last `return`); a name declared in the file with one.
+ */
+function objectOf(node, source, depth = 0) {
+    if (node === undefined || depth > 8)
+        return null;
+    const at = bare(node);
+    if (ts.isObjectLiteralExpression(at))
+        return at;
+    if (ts.isCallExpression(at)) {
+        for (const argument of [...at.arguments].reverse()) {
+            const found = objectOf(argument, source, depth + 1);
+            if (found !== null)
+                return found;
+        }
+        return null;
+    }
+    if (ts.isArrowFunction(at) || ts.isFunctionExpression(at)) {
+        if (!ts.isBlock(at.body))
+            return objectOf(at.body, source, depth + 1);
+        const returns = [];
+        const visit = (child) => {
+            if (ts.isFunctionLike(child) && child !== at)
+                return;
+            if (ts.isReturnStatement(child) && child.expression !== undefined)
+                returns.push(child.expression);
+            ts.forEachChild(child, visit);
+        };
+        visit(at.body);
+        return objectOf(returns.at(-1), source, depth + 1);
+    }
+    if (ts.isIdentifier(at)) {
+        for (const statement of source.statements)
+            if (ts.isVariableStatement(statement))
+                for (const declaration of statement.declarationList.declarations)
+                    if (ts.isIdentifier(declaration.name) && declaration.name.text === at.text)
+                        return objectOf(declaration.initializer, source, depth + 1);
+    }
+    return null;
+}
+/** An object literal's property's value by its key: `key: value`, or `key` alone (shorthand). */
+function propertyOf(object, key) {
+    for (const each of object.properties) {
+        if (ts.isPropertyAssignment(each) && (ts.isIdentifier(each.name) || ts.isStringLiteral(each.name)) && each.name.text === key)
+            return each.initializer;
+        if (ts.isShorthandPropertyAssignment(each) && each.name.text === key)
+            return each.name;
+    }
+    return undefined;
+}
+/**
+ * The settings of the first Vitest config in `dir` (`vitest.config.*`,
+ * then `vite.config.*`), else at the repository's root, or null when there
+ * is none or it sets nothing the slice can carry. The `test` object is the
+ * default export's (through `defineConfig`, a function, a name), else the
+ * first `test: {…}` in the file. Only literal values are read: a computed
+ * one is left to Vitest's default.
+ */
+export function vitestSettings(repo, dir) {
+    const at = [dir, ...(dir === "" ? [] : [""])].flatMap((folder) => CONFIG_NAMES.filter((candidate) => existsSync(join(repo, folder, candidate))).map((name) => ({ folder, name })))[0];
+    if (at === undefined)
+        return null;
+    const { folder, name } = at;
+    const text = readFileSync(join(repo, folder, name), "utf8");
+    const source = ts.createSourceFile(name, text, ts.ScriptTarget.Latest, true);
+    let test = null;
+    for (const statement of source.statements)
+        if (ts.isExportAssignment(statement)) {
+            const config = objectOf(statement.expression, source);
+            const value = config === null ? undefined : propertyOf(config, "test");
+            test = objectOf(value, source);
+        }
+    if (test === null) {
+        const visit = (node) => {
+            if (test !== null)
+                return;
+            if (ts.isPropertyAssignment(node) && (ts.isIdentifier(node.name) || ts.isStringLiteral(node.name)) && node.name.text === "test") {
+                const found = objectOf(node.initializer, source);
+                if (found !== null) {
+                    test = found;
+                    return;
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(source);
+    }
+    if (test === null)
+        return null;
+    const found = test;
+    const read = (object, base) => {
+        const property = (key) => {
+            const value = propertyOf(object, key);
+            return value === undefined ? undefined : bare(value);
+        };
+        const strings = (node) => node === undefined
+            ? []
+            : ts.isStringLiteralLike(node)
+                ? [node.text]
+                : ts.isArrayLiteralExpression(node)
+                    ? node.elements.flatMap((element) => (ts.isStringLiteralLike(element) ? [element.text] : []))
+                    : [];
+        const root = property("root");
+        // Relative to the config's folder, or to the `root` it sets.
+        const from = root !== undefined && ts.isStringLiteralLike(root) ? posix.normalize(posix.join(base, root.text)) : base;
+        const named = strings(property("setupFiles"));
+        const setupFiles = named
+            .filter((file) => !isBareSpecifier(file))
+            .map((file) => posix.normalize(posix.join(from, file.replace(/^\.\//, ""))))
+            // As Vitest finds one: as written, or with a script's extension.
+            .flatMap((file) => ["", ".ts", ".tsx", ".mts", ".js", ".mjs"].map((ext) => `${file}${ext}`).find((path) => existsSync(join(repo, path)) && statSync(join(repo, path)).isFile()) ?? [])
+            .filter((file) => !file.startsWith(".."));
+        const setupPackages = named.filter(isBareSpecifier);
+        const include = strings(property("include")).map((glob) => (from === "" ? glob.replace(/^\.\//, "") : posix.join(from, glob.replace(/^\.\//, ""))));
+        const environment = property("environment");
+        const name = property("name");
+        const timeout = property("testTimeout");
+        const timeoutText = timeout !== undefined ? timeout.getText(source).replace(/_/g, "") : "";
+        const globals = property("globals");
+        return {
+            ...(name !== undefined && ts.isStringLiteralLike(name) ? { name: name.text } : {}),
+            ...(include.length === 0 ? {} : { include }),
+            ...(environment !== undefined && ts.isStringLiteralLike(environment) ? { environment: environment.text } : {}),
+            setupFiles,
+            ...(setupPackages.length === 0 ? {} : { setupPackages }),
+            ...(/^\d+$/.test(timeoutText) ? { testTimeout: Number(timeoutText) } : {}),
+            ...(globals?.kind === ts.SyntaxKind.TrueKeyword ? { globals: true } : {}),
+        };
+    };
+    const top = read(found, folder);
+    // Inline projects: each its own `test`, under its own `root` if it sets one.
+    const listed = propertyOf(found, "projects");
+    const projects = listed !== undefined && ts.isArrayLiteralExpression(bare(listed))
+        ? bare(listed).elements.flatMap((element) => {
+            if (!ts.isExpression(element))
+                return [];
+            const project = objectOf(element, source);
+            const projectTest = project === null ? null : objectOf(propertyOf(project, "test"), source);
+            return projectTest === null ? [] : [read(projectTest, folder)];
+        })
+        : [];
+    const settings = {
+        ...(top.environment === undefined ? {} : { environment: top.environment }),
+        setupFiles: top.setupFiles,
+        ...(top.setupPackages === undefined ? {} : { setupPackages: top.setupPackages }),
+        ...(top.testTimeout === undefined ? {} : { testTimeout: top.testTimeout }),
+        ...(top.globals === true ? { globals: true } : {}),
+        ...(top.include === undefined ? {} : { include: top.include }),
+        ...(projects.length === 0 ? {} : { projects }),
+    };
+    return settings.environment === undefined &&
+        settings.setupFiles.length === 0 &&
+        (settings.setupPackages ?? []).length === 0 &&
+        settings.testTimeout === undefined &&
+        settings.globals !== true &&
+        projects.length === 0
+        ? null
+        : settings;
+}
+/** A specifier that names a package (`@testing-library/jest-dom/vitest`, `vitest-canvas-mock`), not a file. */
+function isBareSpecifier(name) {
+    return !name.startsWith(".") && !name.startsWith("/") && !/^[A-Za-z]:/.test(name) && /^(@[\w.-]+\/)?[\w.-]+(\/[\w./-]*)?$/.test(name) && !/\.[cm]?[jt]sx?$/.test(name.split("/").pop() ?? "");
+}
+/**
+ * The folder's `vitest.config.mjs`: the settings, with the setup files at
+ * their folder paths; an alias for each module that is no package
+ * (`virtual:build-info`, and its subpaths) to its mock under `carveout/`;
+ * and a resolver that reads the source beside a built `.js`. The folder's
+ * build writes a `.js` beside each `.ts` for node:test, and a relative
+ * `./x.js` would otherwise be that file to Vitest: `vitest` run on its own
+ * after an edit tested the code as it was at the last build, where the
+ * repository's Vitest reads the source.
+ */
+export function vitestConfigText(settings, folderPath = (path) => path, 
+/** Module name → the folder of its mock, from the folder's root. */
+virtualModules = {}) {
+    const test = {
+        ...(settings.environment === undefined ? {} : { environment: settings.environment }),
+        ...(settings.setupFiles.length === 0 && (settings.setupPackages ?? []).length === 0
+            ? {}
+            : { setupFiles: [...(settings.setupPackages ?? []), ...settings.setupFiles.map((file) => `./${folderPath(file)}`)] }),
+        ...(settings.testTimeout === undefined ? {} : { testTimeout: settings.testTimeout }),
+        ...(settings.globals === true ? { globals: true } : {}),
+    };
+    const aliases = Object.entries(virtualModules).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const escape = (text) => text.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+    return [
+        "// The repository's Vitest settings for the tests this folder carries, as the cut read them,",
+        "// the modules that are no package found at their mocks, and the source read beside a built .js.",
+        'import { existsSync } from "node:fs";',
+        'import { dirname, resolve } from "node:path";',
+        'import { fileURLToPath } from "node:url";',
+        "",
+        "const SOURCES = { js: [\".ts\", \".tsx\"], mjs: [\".mts\"], cjs: [\".cts\"] };",
+        "/** `./x.js` from the folder's own code is `./x.ts` when that is there, as in the repository. */",
+        "const sourceFirst = {",
+        '  name: "carveout-source-first",',
+        '  enforce: "pre",',
+        "  resolveId(source, importer) {",
+        '    if (importer === undefined || importer.includes("/node_modules/") || !/^\\.{1,2}\\//.test(source)) return null;',
+        "    const match = /^(.*)\\.([cm]?js)$/.exec(source);",
+        '    const from = dirname(importer.split("?")[0]);',
+        "    if (match !== null) {",
+        "      const stem = resolve(from, match[1]);",
+        "      for (const ext of SOURCES[match[2]]) if (existsSync(stem + ext)) return stem + ext;",
+        "      return null;",
+        "    }",
+        "    // No extension (`./sum`): the source, ahead of any `.mjs` or `.js` beside it.",
+        "    if (/\\.[^/.]+$/.test(source)) return null;",
+        "    const bare = resolve(from, source);",
+        '    for (const candidate of [".ts", ".tsx", ".mts", ".cts", "/index.ts", "/index.tsx"]) if (existsSync(bare + candidate)) return bare + candidate;',
+        "    return null;",
+        "  },",
+        "};",
+        "",
+        "export default {",
+        "  plugins: [sourceFirst],",
+        `  test: ${JSON.stringify({
+            ...test,
+            // Each inline project as the repository's config sets it, extending
+            // this one (its resolver and aliases) with its paths at the folder's.
+            ...(settings.projects === undefined || settings.projects.length === 0
+                ? {}
+                : {
+                    projects: settings.projects.map((project) => ({
+                        extends: true,
+                        test: {
+                            ...(project.name === undefined ? {} : { name: project.name }),
+                            ...(project.include === undefined ? {} : { include: project.include.map(folderPath) }),
+                            ...(project.environment === undefined ? {} : { environment: project.environment }),
+                            ...(project.setupFiles.length === 0 && (project.setupPackages ?? []).length === 0
+                                ? {}
+                                : { setupFiles: [...(project.setupPackages ?? []), ...project.setupFiles.map((file) => `./${folderPath(file)}`)] }),
+                            ...(project.testTimeout === undefined ? {} : { testTimeout: project.testTimeout }),
+                            ...(project.globals === true ? { globals: true } : {}),
+                        },
+                    })),
+                }),
+        }, null, 2).replace(/\n/g, "\n  ")},`,
+        ...(aliases.length === 0
+            ? []
+            : [
+                "  resolve: {",
+                "    alias: [",
+                ...aliases.map(([name, dir]) => `      { find: /^${escape(name)}(?:\\/.*)?$/, replacement: fileURLToPath(new URL(${JSON.stringify(`./${dir}/index.js`)}, import.meta.url)) },`),
+                "    ],",
+                "  },",
+            ]),
+        "};",
+        "",
+    ].join("\n");
+}

package/dist/src/pseudonyms/aliases.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Alias rules: the private, bidirectional name table a sandbox version
+ * applies to copied source before it can leave the organization.
+ *
+ * A rule is an explicit pair with a kind and a scope. Rules are ordered,
+ * and applied in that order; they are validated as a set before any text
+ * is touched, because two rules that look harmless alone can interact (one
+ * rule's output is another's input, two rules share a target, two
+ * identifier or path names differ only by case). Application is
+ * deterministic and textual, bounded to identifier or path tokens so a name
+ * inside a longer identifier is never touched, and it is checked to be
+ * reversible: applying the inverse table to the output must give the input
+ * back byte for byte. A text rule matches its exact, case-sensitive
+ * characters and is inverted the same way, so two text rules that differ
+ * only by case are distinct and both hold. A
+ * transformation that cannot be mapped back is refused, never silently
+ * dropped. Redaction of implementation is not a rename and has no place
+ * here.
+ */
+export declare const ALIAS_KINDS: readonly ["identifier", "path", "text"];
+export type AliasKind = (typeof ALIAS_KINDS)[number];
+export interface AliasRule {
+    readonly before: string;
+    readonly after: string;
+    readonly kind: AliasKind;
+    /**
+     * Repository paths the rule applies to: a file, or a directory prefix.
+     * Empty means every file. Scoped rules let one name mean different
+     * things in different modules without a symbol table.
+     */
+    readonly paths: readonly string[];
+}
+export declare const ALIAS_PROBLEM_CODES: readonly ["empty", "identity", "invalid_identifier", "invalid_path", "duplicate_source", "duplicate_target", "chained", "casing_variant", "target_collision", "irreversible", "too_many", "unsupported_kind"];
+export type AliasProblemCode = (typeof ALIAS_PROBLEM_CODES)[number];
+export interface AliasProblem {
+    readonly code: AliasProblemCode;
+    /** Index into the rule list; null for a problem of the whole set. */
+    readonly rule: number | null;
+    readonly file: string | null;
+    readonly detail: string;
+}
+export declare const ALIAS_RULES_MAX = 500;
+export interface AliasValidation {
+    readonly ok: boolean;
+    readonly problems: readonly AliasProblem[];
+}
+/** Whether the set is well formed and free of interactions. */
+export declare function validateAliasRules(rules: readonly AliasRule[]): AliasValidation;
+export interface AliasedFile {
+    readonly path: string;
+    readonly text: string;
+}
+export interface AliasApplication {
+    readonly ok: boolean;
+    readonly files: readonly AliasedFile[];
+    /** Original path to aliased path, for every file whose path changed. */
+    readonly renames: readonly {
+        readonly from: string;
+        readonly to: string;
+    }[];
+    readonly problems: readonly AliasProblem[];
+    /** Rule index to the number of replacements it made, for the record. */
+    readonly applied: readonly number[];
+}
+/**
+ * Applies the rules to the files and proves the result maps back. Problems
+ * refuse the whole application: a partially aliased candidate is worse
+ * than none, because it looks finished.
+ */
+export declare function applyAliases(files: readonly AliasedFile[], rules: readonly AliasRule[]): AliasApplication;
+/**
+ * A JSON value's string leaves, each as a file of its own, for aliasing a
+ * structure without touching its shape.
+ *
+ * Aliasing a serialized object as one text renames its keys too: a quote is
+ * a word boundary, so a rule `name → label` turned `"name":` into
+ * `"label":` and the object lost the field. Leaves alone keep every key,
+ * number and boolean as they were. Each is named `base#pointer`, and
+ * `withJsonLeaves` puts them back in the same order.
+ */
+export declare function jsonLeaves(base: string, value: unknown): AliasedFile[];
+/**
+ * `value` with its string leaves replaced by `texts`, in `jsonLeaves`'s
+ * order; a leaf with no text left keeps its own. A fresh value: the one
+ * given is not changed.
+ */
+export declare function withJsonLeaves<T>(value: T, texts: readonly string[]): T;
+/**
+ * The name a build gives its alias table among the private files it writes:
+ * `private/pseudonym.lunox`, beside the hidden tests.
+ */
+export declare const PSEUDONYMS_FILE = "pseudonym.lunox";
+export declare const PSEUDONYMS_SCHEMA_VERSION = 1;
+/** `pseudonym.lunox`: the table a version's public files were renamed by. */
+export interface PseudonymTable {
+    readonly schemaVersion: typeof PSEUDONYMS_SCHEMA_VERSION;
+    readonly rules: readonly AliasRule[];
+}
+/**
+ * One file renamed by the rules, without the checks `applyAliases` makes:
+ * for reading back a file already proved to map back, such as a public
+ * file in its private names under the inverse table. `file.path` is its
+ * repository path, which scoped rules are matched against.
+ */
+export declare function renameFile(file: AliasedFile, rules: readonly AliasRule[]): AliasedFile;
+/** The inverse table, as a contribution's import applies it. */
+export declare function invertAliasRules(rules: readonly AliasRule[]): AliasRule[];