carveout 0.1.1 → 0.2.0

package/dist/src/pseudonyms/aliases.js

@@ -0,0 +1,394 @@
+/**
+ * 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_$]*$/;
+// Any character a file name may hold but a NUL, a backslash or a quote:
+// a framework's `app/[lunoxId]` or an `assets/Lunox Logo.png` is a path.
+const PATH = /^[^\0\\"'`\n]+$/;
+/** 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");
+// A path's rule matches after a `/` too: `../../packages/lunox-money/x`
+// is the same folder, from another file.
+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 in the file as it was, or the
+                // inverse table could not tell a renamed occurrence from a natural
+                // one. An occurrence an earlier rule made is not natural: two rules
+                // that give one term the same placeholder (a path and an
+                // identifier) make it on purpose, and the round trip below proves
+                // the table maps back.
+                const existing = file.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/draft.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Pseudonyms drafted by rule: the name table a sliced version needs to keep
+ * the workspace's vocabulary out of its public files, written without a
+ * model wherever the vocabulary is where rules can find it.
+ *
+ * An import of one of the workspace's own packages (`@acme/db`) resolves to
+ * a module the slice copies or stubs, so it becomes the relative path the
+ * generator would give it, scoped to the files that import it: a renamed
+ * package would no longer resolve. Every other occurrence of a vocabulary
+ * term becomes a placeholder of the same case, one placeholder per term
+ * that no input already uses: a path segment by a path rule, an identifier
+ * that contains it renamed whole (`acmeOrders` becomes `globexOrders`), and
+ * anything else as text, held in place by the characters around it. One
+ * identifier rule covers each spelling up to case; a second spelling that
+ * differs from it only by case (`LUNOX` beside `Lunox`) is text too, and
+ * several casings may each get a text rule of their own, since a text rule
+ * matches and inverts its exact characters.
+ *
+ * The draft is a candidate, not a guarantee: the caller checks it as the
+ * build applies it, and one that does not hold is where the pseudonyms agent
+ * starts. Only the vocabulary is covered; a name that says whose code it is
+ * without being in it (a customer, a product's feature) is the agent's to
+ * find.
+ */
+import type { AliasRule, AliasedFile } from "./aliases.js";
+/** An import the slice resolved: from a file, as written, to a module. */
+export interface PseudonymImport {
+    readonly from: string;
+    readonly specifier: string;
+    readonly to: string;
+}
+/**
+ * Placeholders, in the order tried: a term takes the first that no input
+ * contains, in any case.
+ */
+export declare const PSEUDONYM_PLACEHOLDERS: readonly string[];
+/** A term's placeholder as words: its base, and a tail word for each word more the term has. */
+export declare function placeholderWords(term: string, base: string): string[];
+/**
+ * `words` spelled as `surface` spells its own: each word in the case of the
+ * surface's word in its place, joined as they are (`contosoLabs` for
+ * `sandboxFactory`, `CONTOSO_LABS` for `SANDBOX_FACTORY`, `contoso-labs`
+ * for `sandbox-factory`). A surface whose words run together with no mark
+ * between them (`sandboxfactory`) gets the words run together too.
+ */
+export declare function restyle(words: readonly string[], surface: string): string;
+export declare function draftPseudonyms(input: {
+    /** Everything the table is applied to, as `applyAliases` is given it. */
+    readonly files: readonly AliasedFile[];
+    readonly vocabulary: readonly string[];
+    /** The slice's resolved imports, inside it and across its cuts. */
+    readonly imports: readonly PseudonymImport[];
+    /**
+     * Filled with the placeholder each term was given: how a name the
+     * folder's holder writes in the placeholder's spelling maps back.
+     */
+    readonly placeholders?: Map<string, string>;
+    /**
+     * The placeholder each term had in an earlier cut of the repository, by
+     * its base word (`zorvex` of `zorvex-labs`): kept where it still fits, so
+     * a folder cut again (wider, or later) reads as the one before did.
+     */
+    readonly preferred?: ReadonlyMap<string, string>;
+}): AliasRule[];