carveout 0.1.0 → 0.1.2

package/dist/src/pseudonyms/draft.js

@@ -0,0 +1,284 @@
+/**
+ * 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 { renameFile } from "./aliases.js";
+import { relativeSpecifier } from "../project/project.js";
+import { termMatches } from "./vocabulary.js";
+/**
+ * Placeholders, in the order tried: a term takes the first that no input
+ * contains, in any case.
+ */
+export const PSEUDONYM_PLACEHOLDERS = [
+    // Made-up words first: a word the code or a contributor uses for what it
+    // is (the ACME protocol, `acme-client`, an "Acme Corp" in test data) must
+    // never be read back as a hidden name.
+    "zorvex",
+    "velmira",
+    "quarnell",
+    "brixdor",
+    "tovlane",
+    "munquist",
+    "kelbrook",
+    "drovane",
+    "acme",
+    "globex",
+    "initech",
+    "hooli",
+    "vandelay",
+    "contoso",
+    "fabrikam",
+    "northwind",
+    "tailspin",
+    "wingtip",
+    "cyberdyne",
+    "tyrell",
+];
+/**
+ * Every placeholder in the order tried: the fictional companies first, then
+ * made-up words any source is unlikely to hold, so a corpus that holds the
+ * companies' names (a pseudonym tool of its own) still gets one per term.
+ */
+function* placeholderCandidates() {
+    yield* PSEUDONYM_PLACEHOLDERS;
+    const onsets = ["zor", "vel", "quar", "brix", "tov", "mun", "kel", "dro", "fen", "sav"];
+    const codas = ["vex", "lane", "dor", "mira", "tune", "quist", "brook", "nell"];
+    for (const onset of onsets)
+        for (const coda of codas)
+            yield `${onset}${coda}`;
+}
+/** The generator's words as a list, for `find`. */
+const placeholderList = [...placeholderCandidates()];
+const IDENTIFIER_CHAR = /[A-Za-z0-9_$]/;
+const IDENTIFIER_START = /^[A-Za-z_$]/;
+const IDENTIFIER_RUN = /^[A-Za-z0-9_$]+$/;
+const isIdentifierChar = (char) => char !== undefined && IDENTIFIER_CHAR.test(char);
+/** `word` in the case `surface` is written in: `ACME`, `Acme` or `acme`. */
+function styled(word, surface) {
+    if (!/\p{Ll}/u.test(surface))
+        return word.toUpperCase();
+    if (/^\P{L}*\p{Lu}/u.test(surface))
+        return `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+    return word;
+}
+/**
+ * The words a multi-word term's placeholder adds after its own: a term of
+ * two words (`sandbox-factory`) becomes two (`contoso-labs`), so every
+ * spelling of it (`sandboxFactory`, `SANDBOX_FACTORY`, `sandbox factory`)
+ * has a spelling of its own, and maps back.
+ */
+const PLACEHOLDER_TAILS = ["labs", "group", "works", "systems", "partners", "ventures"];
+/** A term's placeholder as words: its base, and a tail word for each word more the term has. */
+export function placeholderWords(term, base) {
+    const count = term.split("-").filter(Boolean).length;
+    return [base, ...PLACEHOLDER_TAILS.slice(0, Math.max(0, count - 1))];
+}
+/**
+ * `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 function restyle(words, surface) {
+    if (words.length <= 1)
+        return styled(words[0] ?? "", surface);
+    const segments = [];
+    const joins = [];
+    surface.split(/([\s_\-./]+)/).forEach((part, index) => {
+        if (index % 2 === 1) {
+            joins.push(part);
+            return;
+        }
+        const pieces = part
+            .replace(/(\p{Ll}|\p{N})(\p{Lu})/gu, "$1\u0000$2")
+            .replace(/(\p{Lu})(\p{Lu}\p{Ll})/gu, "$1\u0000$2")
+            .split("\u0000")
+            .filter(Boolean);
+        pieces.forEach((piece, at) => {
+            if (at > 0)
+                joins.push("");
+            segments.push(piece);
+        });
+    });
+    if (segments.length === words.length)
+        return words.map((word, index) => `${index === 0 ? "" : (joins[index - 1] ?? "")}${styled(word, segments[index] ?? surface)}`).join("");
+    const upper = !/\p{Ll}/u.test(surface);
+    return words.map((word, index) => (index === 0 ? styled(word, surface) : upper ? word.toUpperCase() : word)).join("");
+}
+/** A pseudo-file's leaves (`base#pointer`) have no path to rename. */
+const isRealPath = (path) => !path.includes("#");
+export function draftPseudonyms(input) {
+    // Longer terms first, so `lunox-work` is renamed whole before `lunox`.
+    const terms = [...input.vocabulary].sort((a, b) => b.length - a.length || (a < b ? -1 : a > b ? 1 : 0));
+    if (terms.length === 0)
+        return [];
+    const matchesIn = (text) => {
+        const found = [];
+        for (const term of terms)
+            for (const match of termMatches(text, term))
+                if (!found.some((other) => match.start < other.end && other.start < match.end))
+                    found.push({ ...match, term });
+        return found.sort((a, b) => a.start - b.start);
+    };
+    // One placeholder per term, found in no input.
+    const corpus = input.files
+        .map((file) => `${file.path}\n${file.text}`)
+        .join("\n")
+        .toLowerCase();
+    const placeholders = new Map();
+    const placeholderOf = (term) => {
+        const chosen = placeholders.get(term);
+        if (chosen !== undefined)
+            return chosen;
+        const taken = new Set(placeholders.values());
+        const earlier = input.preferred?.get(term);
+        if (earlier !== undefined && !taken.has(earlier) && !corpus.includes(earlier) && matchesIn(earlier).length === 0) {
+            placeholders.set(term, earlier);
+            return earlier;
+        }
+        // A word an earlier cut gave another term is not given to this one.
+        const reserved = new Set(input.preferred?.values() ?? []);
+        const word = placeholderList.find((candidate) => !taken.has(candidate) &&
+            !reserved.has(candidate) &&
+            !corpus.includes(candidate) &&
+            matchesIn(candidate).length === 0);
+        if (word !== undefined)
+            placeholders.set(term, word);
+        return word ?? null;
+    };
+    /** `text` with each term in it replaced, or null when one has no placeholder. */
+    const replaced = (text) => {
+        let out = "";
+        let at = 0;
+        for (const match of matchesIn(text)) {
+            const word = placeholderOf(match.term);
+            if (word === null)
+                return null;
+            out += text.slice(at, match.start);
+            out += restyle(placeholderWords(match.term, word), text.slice(match.start, match.end));
+            at = match.end;
+        }
+        return out + text.slice(at);
+    };
+    // Paths: each segment that carries a term, renamed from the root down.
+    const pathRules = [];
+    for (const file of input.files) {
+        if (!isRealPath(file.path))
+            continue;
+        const segments = renameFile({ path: file.path, text: "" }, pathRules).path.split("/");
+        for (const [index, segment] of segments.entries()) {
+            const after = replaced(segment);
+            if (after === null || after === segment)
+                continue;
+            const before = segments.slice(0, index + 1).join("/");
+            segments[index] = after;
+            if (!pathRules.some((rule) => rule.before === before))
+                pathRules.push({
+                    before,
+                    after: segments.slice(0, index + 1).join("/"),
+                    kind: "path",
+                    paths: [],
+                });
+        }
+    }
+    const aliasedPath = (path) => renameFile({ path, text: "" }, pathRules).path;
+    // Imports of the workspace's packages, as the relative path to the module:
+    // one rule per literal and path, scoped to the files that import it so.
+    const importers = new Map();
+    const byPath = new Map(input.files.map((file) => [file.path, file]));
+    for (const edge of input.imports) {
+        if (edge.specifier.startsWith(".") || edge.specifier.startsWith("/"))
+            continue;
+        if (matchesIn(edge.specifier).length === 0)
+            continue;
+        const text = byPath.get(edge.from)?.text;
+        if (text === undefined)
+            continue;
+        const to = relativeSpecifier(aliasedPath(edge.from), aliasedPath(edge.to));
+        for (const quote of ['"', "'"]) {
+            const before = `${quote}${edge.specifier}${quote}`;
+            if (!text.includes(before))
+                continue;
+            const after = `${quote}${to}${quote}`;
+            const key = `${before}\n${after}`;
+            const entry = importers.get(key) ?? { before, after, paths: new Set() };
+            entry.paths.add(edge.from);
+            importers.set(key, entry);
+        }
+    }
+    const importRules = [...importers.values()].map((entry) => ({
+        before: entry.before,
+        after: entry.after,
+        kind: "text",
+        paths: [...entry.paths].sort(),
+    }));
+    // What is left: each occurrence, as the identifier it is in or as text.
+    const settled = [...importRules, ...pathRules];
+    const identifiers = new Map();
+    const texts = new Map();
+    const foldedIdentifiers = new Set();
+    for (const file of input.files) {
+        const { text } = renameFile(file, settled);
+        for (const match of matchesIn(text)) {
+            const surface = text.slice(match.start, match.end);
+            let start = match.start;
+            let end = match.end;
+            if (IDENTIFIER_RUN.test(surface)) {
+                while (isIdentifierChar(text[start - 1]))
+                    start -= 1;
+                while (isIdentifierChar(text[end]))
+                    end += 1;
+                const token = text.slice(start, end);
+                const after = replaced(token);
+                if (after === null || after === token)
+                    continue;
+                if (identifiers.has(token))
+                    continue;
+                if (IDENTIFIER_START.test(token) &&
+                    !foldedIdentifiers.has(token.toLowerCase())) {
+                    foldedIdentifiers.add(token.toLowerCase());
+                    identifiers.set(token, {
+                        before: token,
+                        after,
+                        kind: "identifier",
+                        paths: [],
+                    });
+                    continue;
+                }
+            }
+            // Text, held in place by the characters around it, so it renames
+            // neither another spelling nor the inside of an identifier.
+            const from = Math.max(0, start - 1);
+            const to = Math.min(text.length, end + 1);
+            const before = `${isIdentifierChar(text[from]) ? "" : text.slice(from, start)}${text.slice(start, end)}${isIdentifierChar(text[end]) ? "" : text.slice(end, to)}`;
+            const after = replaced(before);
+            if (after === null || after === before || texts.has(before))
+                continue;
+            texts.set(before, { before, after, kind: "text", paths: [] });
+        }
+    }
+    for (const [term, word] of placeholders)
+        input.placeholders?.set(term, placeholderWords(term, word).join("-"));
+    return [...settled, ...identifiers.values(), ...texts.values()];
+}

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

@@ -0,0 +1,172 @@
+/**
+ * A public folder in pseudonyms, and the way back.
+ *
+ * A public cut writes the slice for someone who must not learn whose code
+ * it is. The names that say so (the organization, its handle and the
+ * account that owns the repository, the repository's and the workspace's
+ * package names, the maintainer's own name and address) are found by
+ * `workspaceNames`, and every file the folder holds is written under a
+ * table of renames that hides them: drafted by rule over the folder's own
+ * text (`draftPseudonyms`), after any renames the owner wrote, and proved
+ * to map back byte for byte (`applyAliases`). A name still in the folder
+ * after the table is a `vocabulary_leaked` blocker.
+ *
+ * The table never leaves the maintainer: it is kept in the cut's receipt.
+ * A folder that comes back is renamed back, path and text, into a scratch
+ * copy at the repository's own paths (`unaliasFolder`), and the patch is
+ * made from that copy as from any folder: the maintainer reads, and the
+ * hand-off policy judges, the change in the repository's own names.
+ *
+ * A package the folder installs from the public registry keeps its name,
+ * which npm needs: its occurrences are masked from the table both ways,
+ * and named to the maintainer when they carry a term (`kept`).
+ */
+import { type AliasRule, type AliasedFile } from "./aliases.js";
+import { type VocabularyLeak, type VocabularyName } from "./vocabulary.js";
+/** What the receipt keeps of a public folder's pseudonyms. */
+export interface FolderPseudonyms {
+    /** The table, in the order it was applied: the owner's rules first. */
+    readonly rules: readonly AliasRule[];
+    /** Package names the folder installs and keeps, which carry a term. */
+    readonly kept: readonly string[];
+    /** The terms the folder was scanned for. */
+    readonly vocabulary: readonly string[];
+    /**
+     * The placeholder each term was given. A placeholder occurs nowhere in
+     * the repository's own text, so one the folder's holder wrote (a new
+     * `AcmeDiscount`, a new `acme-totals.ts`) maps back to its term.
+     */
+    readonly words?: readonly {
+        readonly term: string;
+        readonly placeholder: string;
+    }[];
+}
+/**
+ * The names a repository goes by, for a public folder to hide: the owner's
+ * (`names` in the configuration, `--name`), the root's and the slice's
+ * packages' names, scopes, authors and repository URLs, the account and
+ * repository its `origin` remote names, the checkout's folder name, and the
+ * maintainer's own Git name and address. `workspaceVocabulary` drops what
+ * is too short or too generic to say whose code it is.
+ */
+export declare function workspaceNames(repo: string, packageDirs: readonly string[], owner?: readonly string[]): VocabularyName[];
+/**
+ * The names written after a name the repository goes by, the way its
+ * owner's other repositories are (`lunox-work/sandbox-factory` in a default
+ * list, a URL, a comment): each is the owner's too, and goes in the
+ * vocabulary. Only a name of two words or more (`sandbox-factory`): one
+ * word after a slash is as often a folder or a file (`lunox/README`), and
+ * a common word renamed everywhere hides nothing.
+ */
+export declare function ownedNames(texts: readonly {
+    readonly text: string;
+}[], vocabulary: readonly string[]): VocabularyName[];
+/**
+ * `text` with each kept name (longest first) behind a mask the table cannot
+ * match, where it is written as a package: in quotes, alone or before a
+ * subpath (`"@lunox/ui"`, `'@lunox/ui/button'`). Elsewhere it is a word
+ * like any other, renamed and scanned.
+ */
+export declare function maskKept(text: string, kept: readonly string[]): string;
+/** `maskKept` undone. */
+export declare function unmaskKept(text: string, kept: readonly string[]): string;
+/** The kept names among the packages: those that carry one of the terms. */
+export declare function keptNames(packages: readonly string[], vocabulary: readonly string[]): string[];
+/** A folder's files in pseudonyms, or why the table could not be made. */
+export type Pseudonymized = {
+    readonly ok: true;
+    readonly table: FolderPseudonyms;
+    /** The text files as the folder holds them, by repository path. */
+    readonly files: ReadonlyMap<string, AliasedFile>;
+    /** Each repository path's path in the folder, binaries included. */
+    readonly pathOf: (path: string) => string;
+    /** What the table left: a term still in a path or a text. */
+    readonly leaks: readonly VocabularyLeak[];
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/**
+ * The folder's files under a table that hides `vocabulary`: the owner's
+ * rules, then rules drafted over what they leave. `files` are the text
+ * files at their repository paths, `binaries` the paths of the rest (only
+ * their paths are renamed). Fails, writing nothing, when the table does
+ * not map back byte for byte.
+ */
+export declare function pseudonymize(input: {
+    readonly files: readonly AliasedFile[];
+    readonly binaries: readonly string[];
+    readonly vocabulary: readonly string[];
+    readonly owner: readonly AliasRule[];
+    readonly kept: readonly string[];
+    /** An earlier cut's pseudonyms, whose placeholders are kept where they fit. */
+    readonly earlier?: FolderPseudonyms;
+    /**
+     * The files a patch will read back (the slice's own): each must come
+     * back through `fromFolder` byte for byte, as `patch` reads it, or a
+     * patch of a folder no one edited would carry a change.
+     */
+    readonly readBack?: (path: string) => boolean;
+}): Pseudonymized;
+/**
+ * Each term found in the files by a looser reading than the table's: inside
+ * a longer word (`getlunox`, `lunoxes`), whatever joins its words, in any
+ * case, its accents stripped, and in binary files' bytes. The table renames
+ * a name on its word's edges; a name it could not reach still says whose
+ * code it is, and blocks the folder.
+ */
+export declare function looseLeaks(files: readonly {
+    readonly path: string;
+    readonly text: string;
+}[], vocabulary: readonly string[], kept?: readonly string[]): VocabularyLeak[];
+/**
+ * Each term the table's rules left in a path or a text, given its
+ * placeholder, spelled as the term was (`AcmeDiscount` → `ZorvexDiscount`,
+ * `acme-cases-v2.ts` → `zorvex-cases-v2.ts`): what the cut never saw, as
+ * `apply` writes it. The rules match what the cut found, file by file; a
+ * file the repository added since, or a line it wrote, may spell a term
+ * where no rule reaches. `fromFolder` puts each back by the same words. A
+ * kept package's name stays as it is, and a term the cut gave no
+ * placeholder (it found none) is left for the leak scan to name.
+ */
+export declare function wordsToFolder(table: FolderPseudonyms, text: string): string;
+/** The package names a text spells as module specifiers (`from "x"`, `import("x")`), relative ones aside. */
+export declare function specifierPackages(text: string): string[];
+/**
+ * A path or a text in the folder's names that maps back byte for byte: the
+ * table's rules with a placeholder for each term they left
+ * (`wordsToFolder`) when `fromFolder` takes that back to what it was, else
+ * the rules alone when those do; null when neither does (a mixed-case term
+ * `restyle` cannot keep, a package name the restore shields, a placeholder
+ * word the repository's own text holds). What `apply` writes, and only
+ * that: a text that maps back wrong would have `patch` rewrite the
+ * repository's.
+ */
+export declare function exactToFolder(table: FolderPseudonyms, path: string, text: string, ownPackage?: (name: string) => boolean, repositoryPackage?: (name: string) => boolean): {
+    readonly path: string;
+    readonly text: string;
+} | null;
+/** A path or text in the repository's names, put in the folder's. */
+export declare function toFolder(table: FolderPseudonyms, path: string, text: string): AliasedFile;
+/**
+ * A path or text in the folder's names, put back in the repository's: the
+ * table undone, then any placeholder still there (a name the folder's
+ * holder made) put back as its term. A package the contributor imports by
+ * its own name (`acme-client`) is shielded from both, unless it is one of
+ * the folder's own mock packages (`ownPackage`), whose names are the
+ * table's.
+ */
+export declare function fromFolder(table: FolderPseudonyms, path: string, text: string, ownPackage?: (name: string) => boolean, 
+/**
+ * A package the repository knows (a workspace package, a dependency it
+ * declares): a specifier the table's rules take back to one is the
+ * repository's own name the cut renamed (in an import, in a test's
+ * data), and goes back with the rest.
+ */
+repositoryPackage?: (name: string) => boolean): AliasedFile;
+/**
+ * A record's string leaves in the folder's names, its hashes and ids left
+ * as they are (a term made of hex letters could match inside one): the
+ * folder's own `carveout.json`, which its own commands read.
+ */
+export declare function recordToFolder<T>(table: FolderPseudonyms, value: T): T;