carveout 0.2.0 → 0.3.0

package/dist/src/pseudonyms/legacy/aliases-v1.js

@@ -0,0 +1,391 @@
+// Frozen: sandbox-factory's packages/core/src/sandbox/aliases.ts as of its
+// commit f31d780, the renaming every platform version built before carveout
+// 0.3.0 was made with. Never edited: a version carries back only under the
+// renaming it was built with. carveout's own is ../aliases.ts. Exported, with a
+// V1 suffix, from ../legacy.ts.
+/**
+ * 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 const ALIAS_KINDS = ["identifier", "path", "text"];
+export const ALIAS_PROBLEM_CODES = [
+    "empty",
+    "identity",
+    "invalid_identifier",
+    "invalid_path",
+    "duplicate_source",
+    "duplicate_target",
+    "chained",
+    "casing_variant",
+    "target_collision",
+    "irreversible",
+    "too_many",
+    "unsupported_kind",
+];
+export const ALIAS_RULES_MAX = 500;
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const PATH = /^[A-Za-z0-9_.\-/@]+$/;
+/** Whether the set is well formed and free of interactions. */
+export function validateAliasRules(rules) {
+    const problems = [];
+    if (rules.length > ALIAS_RULES_MAX)
+        problems.push({
+            code: "too_many",
+            rule: null,
+            file: null,
+            detail: `${rules.length} rules exceed the limit of ${ALIAS_RULES_MAX}.`,
+        });
+    const sources = new Map();
+    const targets = new Map();
+    const folded = new Map();
+    rules.forEach((rule, index) => {
+        if (!ALIAS_KINDS.includes(rule.kind)) {
+            problems.push({
+                code: "unsupported_kind",
+                rule: index,
+                file: null,
+                detail: `Kind ${String(rule.kind)} is not supported.`,
+            });
+            return;
+        }
+        if (rule.before === "" || rule.after === "") {
+            problems.push({
+                code: "empty",
+                rule: index,
+                file: null,
+                detail: "Both sides of a rule must be non-empty.",
+            });
+            return;
+        }
+        if (rule.before === rule.after)
+            problems.push({
+                code: "identity",
+                rule: index,
+                file: null,
+                detail: `${rule.before} maps to itself.`,
+            });
+        if (rule.kind === "identifier" &&
+            (!IDENTIFIER.test(rule.before) || !IDENTIFIER.test(rule.after)))
+            problems.push({
+                code: "invalid_identifier",
+                rule: index,
+                file: null,
+                detail: `${rule.before} → ${rule.after} is not an identifier pair.`,
+            });
+        if (rule.kind === "path" &&
+            (!PATH.test(rule.before) ||
+                !PATH.test(rule.after) ||
+                rule.before.startsWith("/") ||
+                rule.after.startsWith("/") ||
+                rule.before.split("/").includes("..") ||
+                rule.after.split("/").includes("..")))
+            problems.push({
+                code: "invalid_path",
+                rule: index,
+                file: null,
+                detail: `${rule.before} → ${rule.after} is not a repository path pair.`,
+            });
+        const scope = rule.paths.length === 0 ? "" : [...rule.paths].sort().join("\n");
+        const sourceKey = `${rule.kind}\n${scope}\n${rule.before}`;
+        const targetKey = `${rule.kind}\n${scope}\n${rule.after}`;
+        const earlier = sources.get(sourceKey);
+        if (earlier !== undefined)
+            problems.push({
+                code: "duplicate_source",
+                rule: index,
+                file: null,
+                detail: `${rule.before} is already renamed by rule ${earlier}.`,
+            });
+        else
+            sources.set(sourceKey, index);
+        const shared = targets.get(targetKey);
+        if (shared !== undefined)
+            problems.push({
+                code: "duplicate_target",
+                rule: index,
+                file: null,
+                detail: `${rule.after} is already the target of rule ${shared}.`,
+            });
+        else
+            targets.set(targetKey, index);
+        // Identifier and path names that differ only by case are refused. Text
+        // is exempt: a text rule is applied with an exact, case-sensitive
+        // pattern and inverted exactly, so ` lunox ` → ` acme ` beside
+        // ` LUNOX ` → ` ACME ` is unambiguous both ways, and it is how a
+        // spelling no identifier rule can reach is covered.
+        if (rule.kind === "text")
+            return;
+        for (const [name, side] of [
+            [rule.before, "source"],
+            [rule.after, "target"],
+        ]) {
+            const key = `${rule.kind}\n${name.toLowerCase()}`;
+            const seen = folded.get(key);
+            if (seen !== undefined && seen !== index) {
+                const other = rules[seen];
+                if (other !== undefined &&
+                    other.before !== name &&
+                    other.after !== name)
+                    problems.push({
+                        code: "casing_variant",
+                        rule: index,
+                        file: null,
+                        detail: `${name} (${side}) differs only by case from a name in rule ${seen}.`,
+                    });
+            }
+            else
+                folded.set(key, index);
+        }
+    });
+    // A target that is another rule's source would be renamed again by a
+    // later rule, or would make the inverse table ambiguous.
+    rules.forEach((rule, index) => {
+        rules.forEach((other, otherIndex) => {
+            if (index !== otherIndex &&
+                rule.kind === other.kind &&
+                rule.after === other.before &&
+                scopesOverlap(rule.paths, other.paths))
+                problems.push({
+                    code: "chained",
+                    rule: index,
+                    file: null,
+                    detail: `${rule.after} is produced by rule ${index} and consumed by rule ${otherIndex}.`,
+                });
+        });
+    });
+    return { ok: problems.length === 0, problems: dedupe(problems) };
+}
+function dedupe(problems) {
+    const seen = new Set();
+    const result = [];
+    for (const problem of problems) {
+        const key = `${problem.code}\n${problem.rule ?? ""}\n${problem.file ?? ""}\n${problem.detail}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(problem);
+    }
+    return result;
+}
+function inScope(path, scopes) {
+    if (scopes.length === 0)
+        return true;
+    return scopes.some((scope) => path === scope || path.startsWith(`${scope.replace(/\/$/, "")}/`));
+}
+function scopesOverlap(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return true;
+    return a.some((x) => b.some((y) => inScope(x, [y]) || inScope(y, [x])));
+}
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const identifierPattern = (name) => new RegExp(`(?<![A-Za-z0-9_$])${escape(name)}(?![A-Za-z0-9_$])`, "g");
+const pathPattern = (name) => new RegExp(`(?<![A-Za-z0-9_.\\-/@])${escape(name)}(?![A-Za-z0-9_\\-@])`, "g");
+const textPattern = (name) => new RegExp(escape(name), "g");
+const patternFor = (rule, name) => rule.kind === "identifier"
+    ? identifierPattern(name)
+    : rule.kind === "path"
+        ? pathPattern(name)
+        : textPattern(name);
+/**
+ * A path renamed by the table, renamed back: the path rules undone in
+ * reverse order, each scoped by the original path as the forward pass was.
+ */
+function invertPath(path, original, reversed) {
+    let back = path;
+    for (const rule of reversed)
+        if (rule.kind === "path" && inScope(original, rule.paths))
+            back = back.replace(patternFor(rule, rule.after), rule.before);
+    return back;
+}
+function rewrite(files, rules, direction, counts, problems) {
+    const renames = [];
+    const result = files.map((file) => {
+        let text = file.text;
+        let path = file.path;
+        rules.forEach((rule, index) => {
+            if (!inScope(file.path, rule.paths))
+                return;
+            const from = direction === "forward" ? rule.before : rule.after;
+            const to = direction === "forward" ? rule.after : rule.before;
+            if (problems !== null) {
+                // The target must not already occur, or the inverse table could not
+                // tell a renamed occurrence from a natural one.
+                const existing = text.match(patternFor(rule, to));
+                if (existing !== null && existing.length > 0)
+                    problems.push({
+                        code: "target_collision",
+                        rule: index,
+                        file: file.path,
+                        detail: `${to} already occurs ${existing.length} time(s) in ${file.path}.`,
+                    });
+            }
+            const pattern = patternFor(rule, from);
+            let made = 0;
+            text = text.replace(pattern, () => {
+                made += 1;
+                return to;
+            });
+            if (counts !== null)
+                counts[index] = (counts[index] ?? 0) + made;
+            if (rule.kind === "path") {
+                const renamed = path.replace(patternFor(rule, from), to);
+                if (renamed !== path) {
+                    path = renamed;
+                    if (counts !== null)
+                        counts[index] = (counts[index] ?? 0) + 1;
+                }
+            }
+        });
+        if (path !== file.path)
+            renames.push({ from: file.path, to: path });
+        return { path, text };
+    });
+    return { files: result, renames };
+}
+/**
+ * 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 function applyAliases(files, rules) {
+    const validation = validateAliasRules(rules);
+    if (!validation.ok)
+        return {
+            ok: false,
+            files: [],
+            renames: [],
+            problems: validation.problems,
+            applied: [],
+        };
+    const problems = [];
+    const counts = rules.map(() => 0);
+    const forward = rewrite(files, rules, "forward", counts, problems);
+    // The inverse walks the rules backwards, undoing the last rename first.
+    const reversed = [...rules].reverse();
+    const inverse = rewrite(forward.files.map((file, index) => ({
+        // Scope checks use the original path: the inverse must see what the
+        // forward pass saw.
+        path: files[index]?.path ?? file.path,
+        text: file.text,
+    })), reversed, "inverse", null, null);
+    files.forEach((file, index) => {
+        const back = inverse.files[index];
+        if (back === undefined || back.text !== file.text)
+            problems.push({
+                code: "irreversible",
+                rule: null,
+                file: file.path,
+                detail: `Applying the inverse table to ${file.path} does not give the original back.`,
+            });
+        // Paths too: with `src → lib` beside a `lib/` the repository already
+        // has, `lib/x.ts` would map back to `src/x.ts`, and the table alone
+        // could not say where a public file came from.
+        const aliased = forward.files[index]?.path ?? file.path;
+        if (invertPath(aliased, file.path, reversed) !== file.path)
+            problems.push({
+                code: "irreversible",
+                rule: null,
+                file: file.path,
+                detail: `${aliased} does not map back to ${file.path}.`,
+            });
+    });
+    const renamedPaths = new Set(forward.files.map((file) => file.path));
+    if (renamedPaths.size !== files.length)
+        problems.push({
+            code: "target_collision",
+            rule: null,
+            file: null,
+            detail: "Two files would share one aliased path.",
+        });
+    const unique = dedupe(problems);
+    return unique.length > 0
+        ? { ok: false, files: [], renames: [], problems: unique, applied: counts }
+        : {
+            ok: true,
+            files: forward.files,
+            renames: forward.renames,
+            problems: [],
+            applied: counts,
+        };
+}
+/**
+ * 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 function jsonLeaves(base, value) {
+    const leaves = [];
+    const walk = (node, pointer) => {
+        if (typeof node === "string") {
+            leaves.push({ path: `${base}#${pointer}`, text: node });
+        }
+        else if (Array.isArray(node)) {
+            node.forEach((item, index) => walk(item, `${pointer}/${index}`));
+        }
+        else if (node !== null && typeof node === "object") {
+            for (const [key, item] of Object.entries(node))
+                walk(item, `${pointer}/${key.replace(/~/g, "~0").replace(/\//g, "~1")}`);
+        }
+    };
+    walk(value, "");
+    return leaves;
+}
+/**
+ * `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 function withJsonLeaves(value, texts) {
+    let at = 0;
+    const walk = (node) => {
+        if (typeof node === "string")
+            return texts[at++] ?? node;
+        if (Array.isArray(node))
+            return node.map(walk);
+        if (node !== null && typeof node === "object")
+            return Object.fromEntries(Object.entries(node).map(([key, item]) => [key, walk(item)]));
+        return node;
+    };
+    return walk(value);
+}
+/**
+ * The name a build gives its alias table among the private files it writes:
+ * `private/pseudonym.lunox`, beside the hidden tests.
+ */
+export const PSEUDONYMS_FILE = "pseudonym.lunox";
+export const PSEUDONYMS_SCHEMA_VERSION = 1;
+/**
+ * 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 function renameFile(file, rules) {
+    return rewrite([file], rules, "forward", null, null).files[0] ?? file;
+}
+/** The inverse table, as a contribution's import applies it. */
+export function invertAliasRules(rules) {
+    return [...rules]
+        .reverse()
+        .map((rule) => ({ ...rule, before: rule.after, after: rule.before }));
+}

package/dist/src/pseudonyms/legacy/vocabulary-v1.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Workspace vocabulary: the names that say whose code a sandbox was cut
+ * from (the organization, its repository, its package scope, its author)
+ * and the check that none of them reaches a public file.
+ *
+ * Pseudonyms are what hide those names, but a table can be empty or miss
+ * one, and a sliced version is the workspace's own code. So a build scans
+ * what contributors would read, paths and text, for every name the
+ * workspace goes by, and a name still there blocks the build until the
+ * table renames it.
+ *
+ * A name is matched by its words, whatever joins them: `sandbox-factory`
+ * is found as `sandboxFactory`, `SANDBOX_FACTORY` and `sandbox factory`.
+ * A match must start and end on a word boundary, where a case change in an
+ * identifier counts as one: `acme` is found in `acmeOrders`, `MyAcme` and
+ * `ACMEOrders`, not in `acmes`. A name too short or too generic to say
+ * whose code it is (`api`, `web`, `monorepo`) is not scanned for.
+ *
+ * An organization's names are scanned word by word as well: `Acme Corp`
+ * writes its packages `@acme/ledger` and its code `acmeOrders`, never
+ * `acme-corp`. Only its distinctive words, though: one of at least
+ * `VOCABULARY_TERM_MIN` letters that is not a legal form or trade
+ * (`ORGANIZATION_WORDS`) nor an everyday word (`COMMON_WORDS`), whatever its
+ * length. `First Choice Logistics` is scanned whole, never as `first`, or
+ * every `firstName` would block; `acme` and `payflow` are scanned alone.
+ * Other names (a repository's, a package's) are matched only whole, since
+ * `billing-service` names one product but `billing` is everyone's word. A
+ * name or word without a letter (`12345`) names nothing and is dropped.
+ *
+ * A package the slice imports from the workspace itself or from a private
+ * registry is mocked under its own name unless the table renames it, so its
+ * scope is scanned as an organization's name (`@acme/ledger` gives `acme`)
+ * and an unscoped one by its whole name (`payflow-sdk`). A package's own
+ * one word (`ledger`, `logger`) is the code's vocabulary, not whose code it
+ * is, and a public package mocked by default (`lodash`) names no one.
+ */
+import type { RequiredBuildInputs } from "../../slice/manifest.js";
+import type { ProjectBlocker } from "../../project/project.js";
+/** Shorter names, separators aside, match too much to block on. */
+export declare const VOCABULARY_TERM_MIN = 4;
+/**
+ * A name the workspace goes by. A bare string is `kind: "name"`: matched
+ * only as a whole. An `organization` name (its name, its handle, the
+ * account that owns its repositories, its mail domain) is matched whole and
+ * by each of its distinctive words.
+ */
+export interface VocabularyName {
+    readonly name: string;
+    readonly kind: "organization" | "name";
+}
+/** Names that say who the organization is, to be scanned word by word too. */
+export declare function organizationNames(names: readonly string[]): VocabularyName[];
+/**
+ * The names the slice's privately hosted packages give (see the module
+ * comment): one of the workspace's own, or one a lockfile or `.npmrc` says
+ * comes from another registry. A package nothing says is public is mocked
+ * too, but by default, so it is not one.
+ */
+export declare function privatePackageNames(packages: RequiredBuildInputs["packages"]): VocabularyName[];
+/**
+ * The names a package author's address gives: its local part unless a role
+ * mailbox's (`support@`) or without a letter, and its domain as the
+ * organization's unless it is a public mail provider's. A GitHub noreply
+ * address (`12345+octocat@users.noreply.github.com`) gives the login after
+ * the `+`; any other drops its `+tag`.
+ */
+export declare function emailNames(email: string): VocabularyName[];
+/**
+ * A name's words, lowercased: split at anything not a letter or digit, and
+ * at each case change an identifier marks (`acmeOrders`, `XMLParser`).
+ */
+export declare function termWords(name: string): string[];
+/**
+ * The names worth scanning for, each as its words joined by `-`, in the
+ * order first given; an organization's name is followed by each of its
+ * distinctive words (see the module comment). Repeats, names under
+ * `VOCABULARY_TERM_MIN`, names without a letter and names made only of
+ * generic words are dropped.
+ */
+export declare function workspaceVocabulary(names: readonly (string | VocabularyName)[]): string[];
+export interface VocabularyLeak {
+    readonly term: string;
+    readonly occurrences: number;
+    /** The files it was found in, path or text, in the order given. */
+    readonly files: readonly string[];
+}
+/** Where a term was found in a text: `text.slice(start, end)`. */
+export interface TermMatch {
+    readonly start: number;
+    readonly end: number;
+}
+/**
+ * Every match of `term` in `text` that starts and ends on a word boundary:
+ * not a letter, or a case change an identifier marks (`myAcme`, `acmeOrders`,
+ * and in a run of capitals the last one before a lowercase, `XMLAcme`,
+ * `ACMEOrders`), or a capital after a digit (`web3Labs`). A term that starts
+ * or ends on a digit (`web3`) needs a non-digit there too, so `web3` is not
+ * found in `web30`.
+ */
+export declare function termMatches(text: string, term: string): TermMatch[];
+/** Each term found in the files' paths or text, in the vocabulary's order. */
+export declare function vocabularyLeaks(files: readonly {
+    readonly path: string;
+    readonly text: string;
+}[], vocabulary: readonly string[]): VocabularyLeak[];
+/** A blocker for each leak, naming where it was found and what clears it. */
+export declare function vocabularyBlockers(leaks: readonly VocabularyLeak[]): ProjectBlocker[];