@claudiu.ceia/astkit 0.1.0

package/dist/src/patch/patch.js

@@ -0,0 +1,345 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { stdin as processStdin, stdout as processStdout } from "node:process";
+import { createInterface } from "node:readline/promises";
+import { buildCommand } from "@stricli/core";
+import chalk, { Chalk } from "chalk";
+import { patchProject } from "../spatch/spatch.js";
+export async function runPatchCommand(patchInput, scope, flags, options = {}) {
+    const patchScope = scope ?? ".";
+    const patchCwd = flags.cwd;
+    if (flags.interactive ?? false) {
+        if (flags["dry-run"] ?? false) {
+            throw new Error("Cannot combine --interactive with --dry-run.");
+        }
+        return runInteractivePatchCommand(patchInput, patchScope, patchCwd, flags["no-color"] ?? false, options.interactiveDecider);
+    }
+    return patchProject(patchInput, {
+        cwd: patchCwd,
+        dryRun: flags["dry-run"] ?? false,
+        scope: patchScope,
+    });
+}
+export function formatPatchOutput(result, options = {}) {
+    const chalkInstance = buildChalk(options);
+    const useColor = chalkInstance.level > 0;
+    const lines = [];
+    const changedFiles = result.files.filter((file) => file.replacementCount > 0);
+    for (const file of changedFiles) {
+        const headerPrefix = useColor ? chalkInstance.bold : (value) => value;
+        lines.push(headerPrefix(`diff --git a/${file.file} b/${file.file}`));
+        lines.push(useColor ? chalkInstance.gray(`--- a/${file.file}`) : `--- a/${file.file}`);
+        lines.push(useColor ? chalkInstance.gray(`+++ b/${file.file}`) : `+++ b/${file.file}`);
+        for (const occurrence of file.occurrences) {
+            if (occurrence.matched === occurrence.replacement) {
+                continue;
+            }
+            const oldCount = countLines(occurrence.matched);
+            const newCount = countLines(occurrence.replacement);
+            const hunkHeader = `@@ -${occurrence.line},${oldCount} +${occurrence.line},${newCount} @@`;
+            lines.push(useColor ? chalkInstance.cyan(hunkHeader) : hunkHeader);
+            for (const oldLine of splitDiffLines(occurrence.matched)) {
+                const line = `-${oldLine}`;
+                lines.push(useColor ? chalkInstance.red(line) : line);
+            }
+            for (const newLine of splitDiffLines(occurrence.replacement)) {
+                const line = `+${newLine}`;
+                lines.push(useColor ? chalkInstance.green(line) : line);
+            }
+        }
+    }
+    if (changedFiles.length === 0) {
+        lines.push(useColor ? chalkInstance.gray("No changes.") : "No changes.");
+    }
+    const summary = [
+        `${result.filesChanged} ${pluralize("file", result.filesChanged)} changed`,
+        `${result.totalReplacements} ${pluralize("replacement", result.totalReplacements)}`,
+        result.dryRun ? "(dry-run)" : null,
+    ]
+        .filter((part) => part !== null)
+        .join(", ");
+    lines.push(useColor ? chalkInstance.gray(summary) : summary);
+    return lines.join("\n");
+}
+export const patchCommand = buildCommand({
+    async func(flags, patchInput, scope) {
+        const result = await runPatchCommand(patchInput, scope, flags);
+        if (flags.json ?? false) {
+            this.process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            return;
+        }
+        const output = formatPatchOutput(result, {
+            color: Boolean(processStdout.isTTY) && !(flags["no-color"] ?? false),
+        });
+        this.process.stdout.write(`${output}\n`);
+    },
+    parameters: {
+        flags: {
+            interactive: {
+                kind: "boolean",
+                optional: true,
+                brief: "Interactively select which matches to apply",
+            },
+            json: {
+                kind: "boolean",
+                optional: true,
+                brief: "Output structured JSON instead of compact diff-style text",
+            },
+            "no-color": {
+                kind: "boolean",
+                optional: true,
+                brief: "Disable colored output",
+            },
+            "dry-run": {
+                kind: "boolean",
+                optional: true,
+                brief: "Preview changes without writing files",
+            },
+            cwd: {
+                kind: "parsed",
+                optional: true,
+                brief: "Working directory for resolving patch file and scope",
+                placeholder: "path",
+                parse: (input) => input,
+            },
+        },
+        positional: {
+            kind: "tuple",
+            parameters: [
+                {
+                    brief: "Patch document text or path to patch document file",
+                    placeholder: "patch",
+                    parse: (input) => input,
+                },
+                {
+                    brief: "Scope file or directory (defaults to current directory)",
+                    placeholder: "scope",
+                    parse: (input) => input,
+                    optional: true,
+                },
+            ],
+        },
+    },
+    docs: {
+        brief: "Apply structural rewrite from a patch document",
+    },
+});
+function buildChalk(options) {
+    if (options.chalkInstance) {
+        return options.chalkInstance;
+    }
+    const shouldColor = options.color ?? false;
+    if (!shouldColor) {
+        return new Chalk({ level: 0 });
+    }
+    const level = chalk.level > 0 ? chalk.level : 1;
+    return new Chalk({ level });
+}
+function splitDiffLines(text) {
+    const normalized = text.replaceAll("\r\n", "\n");
+    if (normalized.length === 0) {
+        return [""];
+    }
+    return normalized.split("\n");
+}
+function countLines(text) {
+    const normalized = text.replaceAll("\r\n", "\n");
+    if (normalized.length === 0) {
+        return 0;
+    }
+    return normalized.split("\n").length;
+}
+function pluralize(word, count) {
+    return count === 1 ? word : `${word}s`;
+}
+async function runInteractivePatchCommand(patchInput, scope, cwd, noColor, interactiveDecider) {
+    if (!interactiveDecider && (!processStdin.isTTY || !processStdout.isTTY)) {
+        throw new Error("Interactive mode requires a TTY stdin/stdout.");
+    }
+    const startedAt = Date.now();
+    const dryResult = await patchProject(patchInput, {
+        cwd,
+        dryRun: true,
+        scope,
+    });
+    const totalChanges = dryResult.files.reduce((count, file) => count +
+        file.occurrences.filter((occurrence) => occurrence.matched !== occurrence.replacement).length, 0);
+    let interactivePrompt = null;
+    const decider = interactiveDecider ??
+        ((interactivePrompt = await createTerminalInteractiveDecider(noColor)),
+            interactivePrompt.decider);
+    const selectedByFile = new Map();
+    let applyAll = false;
+    let stop = false;
+    let changeNumber = 0;
+    try {
+        for (const file of dryResult.files) {
+            const selected = [];
+            for (const occurrence of file.occurrences) {
+                if (occurrence.matched === occurrence.replacement) {
+                    continue;
+                }
+                changeNumber += 1;
+                if (applyAll) {
+                    selected.push(occurrence);
+                    continue;
+                }
+                const choice = await decider({
+                    file: file.file,
+                    occurrence,
+                    changeNumber,
+                    totalChanges,
+                });
+                if (choice === "yes") {
+                    selected.push(occurrence);
+                    continue;
+                }
+                if (choice === "all") {
+                    applyAll = true;
+                    selected.push(occurrence);
+                    continue;
+                }
+                if (choice === "quit") {
+                    stop = true;
+                    break;
+                }
+            }
+            selectedByFile.set(file.file, selected);
+            if (stop) {
+                break;
+            }
+        }
+    }
+    finally {
+        interactivePrompt?.close();
+    }
+    const fileResults = [];
+    let filesChanged = 0;
+    let totalReplacements = 0;
+    for (const file of dryResult.files) {
+        const selected = selectedByFile.get(file.file) ?? [];
+        if (selected.length === 0) {
+            fileResults.push({
+                ...file,
+                replacementCount: 0,
+                changed: false,
+                byteDelta: 0,
+                occurrences: [],
+            });
+            continue;
+        }
+        const absolutePath = path.resolve(cwd ?? process.cwd(), file.file);
+        const originalText = await readFile(absolutePath, "utf8");
+        const rewrittenText = applySelectedOccurrences(originalText, selected);
+        const changed = rewrittenText !== originalText;
+        if (changed) {
+            await writeFile(absolutePath, rewrittenText, "utf8");
+        }
+        const replacementCount = selected.filter((occurrence) => occurrence.matched !== occurrence.replacement).length;
+        totalReplacements += replacementCount;
+        if (changed) {
+            filesChanged += 1;
+        }
+        fileResults.push({
+            ...file,
+            replacementCount,
+            changed,
+            byteDelta: changed
+                ? Buffer.byteLength(rewrittenText, "utf8") -
+                    Buffer.byteLength(originalText, "utf8")
+                : 0,
+            occurrences: selected,
+        });
+    }
+    return {
+        ...dryResult,
+        dryRun: false,
+        filesChanged,
+        totalReplacements,
+        elapsedMs: Date.now() - startedAt,
+        files: fileResults,
+    };
+}
+function applySelectedOccurrences(source, occurrences) {
+    if (occurrences.length === 0) {
+        return source;
+    }
+    const sorted = [...occurrences].sort((left, right) => left.start - right.start);
+    const parts = [];
+    let cursor = 0;
+    for (const occurrence of sorted) {
+        parts.push(source.slice(cursor, occurrence.start));
+        parts.push(occurrence.replacement);
+        cursor = occurrence.end;
+    }
+    parts.push(source.slice(cursor));
+    return parts.join("");
+}
+async function createTerminalInteractiveDecider(noColor) {
+    const chalkInstance = buildChalk({
+        color: processStdout.isTTY && !noColor,
+    });
+    const useColor = chalkInstance.level > 0;
+    const rl = createInterface({
+        input: processStdin,
+        output: processStdout,
+    });
+    return {
+        decider: async ({ file, occurrence, changeNumber, totalChanges }) => {
+            processStdout.write(`\n${formatInteractiveChangeBlock({ file, occurrence, changeNumber, totalChanges }, {
+                chalkInstance,
+                color: useColor,
+            })}\n`);
+            while (true) {
+                const answer = await rl.question(useColor
+                    ? chalkInstance.bold("Choice [y/n/a/q] (default: n): ")
+                    : "Choice [y/n/a/q] (default: n): ");
+                const parsed = parseInteractiveChoice(answer);
+                if (parsed) {
+                    return parsed;
+                }
+                processStdout.write(useColor
+                    ? `${chalkInstance.yellow("Invalid choice.")} Use y, n, a, or q.\n`
+                    : "Invalid choice. Use y, n, a, or q.\n");
+            }
+        },
+        close: () => rl.close(),
+    };
+}
+function formatInteractiveChangeBlock(ctx, options = {}) {
+    const chalkInstance = buildChalk(options);
+    const useColor = chalkInstance.level > 0;
+    const divider = "─".repeat(72);
+    const oldCount = countLines(ctx.occurrence.matched);
+    const newCount = countLines(ctx.occurrence.replacement);
+    const hunkHeader = `@@ -${ctx.occurrence.line},${oldCount} +${ctx.occurrence.line},${newCount} @@`;
+    const lines = [
+        useColor ? chalkInstance.gray(divider) : divider,
+        useColor
+            ? chalkInstance.bold(`Change ${ctx.changeNumber}/${ctx.totalChanges} · ${ctx.file}:${ctx.occurrence.line}:${ctx.occurrence.character}`)
+            : `Change ${ctx.changeNumber}/${ctx.totalChanges} · ${ctx.file}:${ctx.occurrence.line}:${ctx.occurrence.character}`,
+        useColor ? chalkInstance.cyan(hunkHeader) : hunkHeader,
+        ...splitDiffLines(ctx.occurrence.matched).map((line) => useColor ? chalkInstance.red(`-${line}`) : `-${line}`),
+        ...splitDiffLines(ctx.occurrence.replacement).map((line) => useColor ? chalkInstance.green(`+${line}`) : `+${line}`),
+        useColor
+            ? chalkInstance.gray("Actions: [y] apply · [n] skip · [a] apply remaining · [q] quit")
+            : "Actions: [y] apply · [n] skip · [a] apply remaining · [q] quit",
+    ];
+    return lines.join("\n");
+}
+function parseInteractiveChoice(answer) {
+    const normalized = answer.trim().toLowerCase();
+    if (normalized.length === 0 || normalized === "n" || normalized === "no") {
+        return "no";
+    }
+    if (normalized === "y" || normalized === "yes") {
+        return "yes";
+    }
+    if (normalized === "a" || normalized === "all") {
+        return "all";
+    }
+    if (normalized === "q" || normalized === "quit") {
+        return "quit";
+    }
+    return null;
+}

package/dist/src/pattern/balance.d.ts

@@ -0,0 +1 @@
+export declare function isBalancedChunk(chunk: string): boolean;

package/dist/src/pattern/balance.js

@@ -0,0 +1,25 @@
+import { any, anyChar, createLanguage, eof, many, manyTill, map, minus, optional, regex as parseRegex, seq, str, } from "@claudiu-ceia/combine";
+const escapedCharacterParser = map(seq(str("\\"), anyChar()), () => null);
+const singleQuotedParser = map(seq(str("'"), many(any(escapedCharacterParser, map(parseRegex(/[^'\\]+/, "single quoted text"), () => null))), str("'")), () => null);
+const doubleQuotedParser = map(seq(str('"'), many(any(escapedCharacterParser, map(parseRegex(/[^"\\]+/, "double quoted text"), () => null))), str('"')), () => null);
+const templateQuotedParser = map(seq(str("`"), many(any(escapedCharacterParser, map(parseRegex(/[^`\\]+/, "template text"), () => null))), str("`")), () => null);
+const lineCommentParser = map(seq(str("//"), many(minus(anyChar(), str("\n"))), optional(str("\n"))), () => null);
+const blockCommentParser = map(seq(str("/*"), manyTill(anyChar(), str("*/"))), () => null);
+const balancedChunkLanguage = createLanguage({
+    piece: (self) => any(self.paren, self.bracket, self.brace, self.singleQuote, self.doubleQuote, self.templateQuote, self.lineComment, self.blockComment, self.plain, self.slash),
+    paren: (self) => map(seq(str("("), many(self.piece), str(")")), () => null),
+    bracket: (self) => map(seq(str("["), many(self.piece), str("]")), () => null),
+    brace: (self) => map(seq(str("{"), many(self.piece), str("}")), () => null),
+    singleQuote: () => singleQuotedParser,
+    doubleQuote: () => doubleQuotedParser,
+    templateQuote: () => templateQuotedParser,
+    lineComment: () => lineCommentParser,
+    blockComment: () => blockCommentParser,
+    plain: () => map(parseRegex(/[^()[\]{}'"`/]+/, "plain text"), () => null),
+    slash: () => map(str("/"), () => null),
+});
+const balancedChunkParser = map(seq(many(balancedChunkLanguage.piece), eof()), () => true);
+export function isBalancedChunk(chunk) {
+    const result = balancedChunkParser({ text: chunk, index: 0 });
+    return result.success;
+}

package/dist/src/pattern/index.d.ts

@@ -0,0 +1,5 @@
+export { compileTemplate, tokenizeTemplate } from "./syntax.ts";
+export { findTemplateMatches } from "./match.ts";
+export { renderTemplate } from "./render.ts";
+export type { CompiledTemplate, TemplateMatch } from "./types.ts";
+export { ELLIPSIS_CAPTURE_PREFIX } from "./types.ts";

package/dist/src/pattern/index.js

@@ -0,0 +1,4 @@
+export { compileTemplate, tokenizeTemplate } from "./syntax.js";
+export { findTemplateMatches } from "./match.js";
+export { renderTemplate } from "./render.js";
+export { ELLIPSIS_CAPTURE_PREFIX } from "./types.js";

package/dist/src/pattern/match.d.ts

@@ -0,0 +1,2 @@
+import type { CompiledTemplate, TemplateMatch } from "./types.ts";
+export declare function findTemplateMatches(text: string, template: CompiledTemplate): TemplateMatch[];

package/dist/src/pattern/match.js

@@ -0,0 +1,141 @@
+import { isBalancedChunk } from "./balance.js";
+import { ELLIPSIS_CAPTURE_PREFIX } from "./types.js";
+export function findTemplateMatches(text, template) {
+    const matches = [];
+    const firstToken = template.tokens[0];
+    const anchor = firstToken?.kind === "text" ? firstToken.value : null;
+    let cursor = 0;
+    while (cursor <= text.length) {
+        const start = anchor ? text.indexOf(anchor, cursor) : cursor;
+        if (start < 0) {
+            break;
+        }
+        const result = matchTokens(text, template.tokens, 0, start, new Map());
+        if (!result || result.end <= start) {
+            cursor = start + 1;
+            continue;
+        }
+        matches.push({
+            start,
+            end: result.end,
+            text: text.slice(start, result.end),
+            captures: Object.fromEntries(result.captures),
+        });
+        cursor = result.end;
+    }
+    return matches;
+}
+function matchTokens(text, tokens, tokenIndex, cursor, captures) {
+    const token = tokens[tokenIndex];
+    if (!token) {
+        return { end: cursor, captures: new Map(captures) };
+    }
+    if (token.kind === "text") {
+        if (!text.startsWith(token.value, cursor)) {
+            return null;
+        }
+        return matchTokens(text, tokens, tokenIndex + 1, cursor + token.value.length, captures);
+    }
+    if (token.kind === "ellipsis") {
+        const nextLiteral = findNextLiteral(tokens, tokenIndex + 1);
+        if (!nextLiteral) {
+            const chunk = text.slice(cursor);
+            if (!isBalancedChunk(chunk)) {
+                return null;
+            }
+            const nextCaptures = captureEllipsis(captures, token.index, chunk);
+            return matchTokens(text, tokens, tokenIndex + 1, text.length, nextCaptures);
+        }
+        const nextIndexes = findLiteralIndexes(text, nextLiteral.value, cursor);
+        for (let index = nextIndexes.length - 1; index >= 0; index -= 1) {
+            const nextIndex = nextIndexes[index];
+            if (nextIndex === undefined) {
+                continue;
+            }
+            const chunk = text.slice(cursor, nextIndex);
+            if (isBalancedChunk(chunk)) {
+                const nextCaptures = captureEllipsis(captures, token.index, chunk);
+                const nested = matchTokens(text, tokens, tokenIndex + 1, nextIndex, nextCaptures);
+                if (nested) {
+                    return nested;
+                }
+            }
+        }
+        return null;
+    }
+    const nextLiteral = findNextLiteral(tokens, tokenIndex + 1);
+    if (!nextLiteral) {
+        const chunk = text.slice(cursor);
+        if (!isBalancedChunk(chunk)) {
+            return null;
+        }
+        const nextCaptures = captureHole(captures, token, chunk);
+        if (!nextCaptures) {
+            return null;
+        }
+        return matchTokens(text, tokens, tokenIndex + 1, text.length, nextCaptures);
+    }
+    let probe = cursor;
+    while (probe <= text.length) {
+        const nextIndex = text.indexOf(nextLiteral.value, probe);
+        if (nextIndex < 0) {
+            return null;
+        }
+        const chunk = text.slice(cursor, nextIndex);
+        if (isBalancedChunk(chunk)) {
+            const nextCaptures = captureHole(captures, token, chunk);
+            if (nextCaptures) {
+                const nested = matchTokens(text, tokens, tokenIndex + 1, nextIndex, nextCaptures);
+                if (nested) {
+                    return nested;
+                }
+            }
+        }
+        probe = nextIndex + 1;
+    }
+    return null;
+}
+function findNextLiteral(tokens, fromIndex) {
+    for (let index = fromIndex; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token && token.kind === "text") {
+            return token;
+        }
+    }
+    return null;
+}
+function captureHole(captures, hole, value) {
+    if (hole.constraintRegex && !hole.constraintRegex.test(value)) {
+        return null;
+    }
+    const next = new Map(captures);
+    if (hole.anonymous) {
+        return next;
+    }
+    const current = next.get(hole.name);
+    if (current !== undefined && current !== value) {
+        return null;
+    }
+    if (current === undefined) {
+        next.set(hole.name, value);
+    }
+    return next;
+}
+function captureEllipsis(captures, index, value) {
+    const next = new Map(captures);
+    next.set(`${ELLIPSIS_CAPTURE_PREFIX}${index}`, value);
+    return next;
+}
+function findLiteralIndexes(text, literal, fromIndex) {
+    const indexes = [];
+    let probe = fromIndex;
+    while (probe <= text.length) {
+        const matchIndex = text.indexOf(literal, probe);
+        if (matchIndex < 0) {
+            break;
+        }
+        indexes.push(matchIndex);
+        probe = matchIndex + 1;
+    }
+    return indexes;
+}

package/dist/src/pattern/render.d.ts

@@ -0,0 +1 @@
+export declare function renderTemplate(source: string, captures: Record<string, string>): string;

package/dist/src/pattern/render.js

@@ -0,0 +1,32 @@
+import { tokenizeTemplate } from "./syntax.js";
+import { ELLIPSIS_CAPTURE_PREFIX } from "./types.js";
+export function renderTemplate(source, captures) {
+    if (source.length === 0) {
+        return "";
+    }
+    const tokens = tokenizeTemplate(source);
+    let rendered = "";
+    for (const token of tokens) {
+        if (token.kind === "text") {
+            rendered += token.value;
+            continue;
+        }
+        if (token.kind === "ellipsis") {
+            const value = captures[`${ELLIPSIS_CAPTURE_PREFIX}${token.index}`];
+            if (value === undefined) {
+                throw new Error(`Replacement uses ellipsis #${token.index + 1} but pattern did not capture it.`);
+            }
+            rendered += value;
+            continue;
+        }
+        if (token.anonymous) {
+            continue;
+        }
+        const value = captures[token.name];
+        if (value === undefined) {
+            throw new Error(`Replacement uses unknown hole "${token.name}".`);
+        }
+        rendered += value;
+    }
+    return rendered;
+}

package/dist/src/pattern/syntax.d.ts

@@ -0,0 +1,3 @@
+import type { CompiledTemplate, TemplateToken } from "./types.ts";
+export declare function tokenizeTemplate(source: string): TemplateToken[];
+export declare function compileTemplate(source: string): CompiledTemplate;

package/dist/src/pattern/syntax.js

@@ -0,0 +1,87 @@
+import { any, anyChar, cut, eof, formatErrorCompact, many, many1, map, mapJoin, minus, optional, regex as parseRegex, seq, str, } from "@claudiu-ceia/combine";
+const HOLE_INNER_NAME_PATTERN = /(?:[A-Za-z_][A-Za-z0-9_]*|_)/;
+const holeNameParser = parseRegex(HOLE_INNER_NAME_PATTERN, "hole name");
+const escapedConstraintCharacterParser = map(seq(str("\\"), anyChar()), ([slash, character]) => `${slash}${character}`);
+const charClassCharacterParser = any(escapedConstraintCharacterParser, parseRegex(/[^\]]/, "character class character"));
+const charClassParser = map(seq(str("["), mapJoin(many(charClassCharacterParser)), str("]")), ([open, body, close]) => `${open}${body}${close}`);
+const regexConstraintCharacterParser = any(escapedConstraintCharacterParser, charClassParser, parseRegex(/[^\]]/, "regex constraint character"));
+const regexConstraintParser = mapJoin(many1(regexConstraintCharacterParser));
+const holeTokenParser = map(seq(str(":["), cut(holeNameParser, "hole name"), optional(seq(str("~"), cut(regexConstraintParser, "regex constraint"))), cut(str("]"), "closing ']'")), ([, name, constraint]) => {
+    const constraintSource = constraint ? constraint[1] : null;
+    return {
+        kind: "hole",
+        name,
+        anonymous: name === "_",
+        constraintSource,
+    };
+});
+const ellipsisTokenParser = map(str("..."), () => ({
+    kind: "ellipsis",
+}));
+const textTokenParser = map(mapJoin(many1(minus(anyChar(), any(str("..."), str(":["))))), (value) => ({ kind: "text", value }));
+const templateTokensParser = map(seq(many(any(holeTokenParser, ellipsisTokenParser, textTokenParser)), eof()), ([tokens]) => tokens);
+export function tokenizeTemplate(source) {
+    const parsed = templateTokensParser({ text: source, index: 0 });
+    if (!parsed.success) {
+        throw new Error(`Invalid template: ${formatErrorCompact(parsed)}`);
+    }
+    let ellipsisIndex = 0;
+    return parsed.value.map((token) => resolveRawToken(token, () => ellipsisIndex++));
+}
+export function compileTemplate(source) {
+    if (source.length === 0) {
+        throw new Error("Template cannot be empty.");
+    }
+    const tokens = tokenizeTemplate(source);
+    if (tokens.length === 0) {
+        throw new Error("Template did not produce any tokens.");
+    }
+    for (let index = 0; index < tokens.length - 1; index += 1) {
+        const current = tokens[index];
+        const next = tokens[index + 1];
+        if (current &&
+            next &&
+            current.kind !== "text" &&
+            next.kind !== "text") {
+            throw new Error("Adjacent holes are ambiguous. Add a literal delimiter between them.");
+        }
+    }
+    const literalLength = tokens.reduce((total, token) => total + (token.kind === "text" ? token.value.length : 0), 0);
+    if (literalLength === 0) {
+        throw new Error("Template must include at least one literal character to avoid empty matches.");
+    }
+    return { source, tokens };
+}
+function resolveRawToken(token, nextEllipsisIndex) {
+    if (token.kind === "text") {
+        return token;
+    }
+    if (token.kind === "ellipsis") {
+        return {
+            kind: "ellipsis",
+            index: nextEllipsisIndex(),
+        };
+    }
+    if (token.constraintSource === null) {
+        return {
+            kind: "hole",
+            name: token.name,
+            anonymous: token.anonymous,
+            constraintSource: token.constraintSource,
+            constraintRegex: null,
+        };
+    }
+    try {
+        return {
+            kind: "hole",
+            name: token.name,
+            anonymous: token.anonymous,
+            constraintSource: token.constraintSource,
+            constraintRegex: new RegExp(`^(?:${token.constraintSource})$`, "s"),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid regex constraint for hole "${token.name}": ${message}`);
+    }
+}