@crewhaus/tool-text 0.7.0

package/dist/lib/format.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shaping text to fit somewhere: a token budget, a column width, or another
+ * language's syntax.
+ */
+export type TruncateStrategy = "head" | "tail" | "middle";
+/**
+ * Cut text to at most `maxChars`, keeping the end that matters for the
+ * chosen strategy and marking where bytes were dropped. Returns the input
+ * untouched when it already fits, so a caller can pipe everything through
+ * this without a size check first.
+ */
+export declare function truncateToChars(text: string, maxChars: number, strategy: TruncateStrategy, marker: string): {
+    text: string;
+    truncated: boolean;
+    droppedChars: number;
+};
+/**
+ * Greedy word wrap at `width`, preserving blank-line paragraph breaks and
+ * prefixing every line (for quoting, comment blocks, commit bodies). A word
+ * longer than the width is left whole rather than split, because splitting a
+ * URL or an identifier makes it wrong, not merely ugly.
+ */
+export declare function wrapText(text: string, width: number, prefix: string, hangingIndent: string): string;
+export type EscapeTarget = "regex" | "shellSingle" | "shellDouble" | "json" | "url" | "urlComponent" | "html" | "markdown" | "csv" | "sqlLike";
+/**
+ * Escape text for embedding in another syntax.
+ *
+ * This is the function that stops a harness building an injection into its
+ * own next command: a scraped string going into a regex, a filename going
+ * into a shell word, a customer's text going into a CSV cell. It performs no
+ * execution of any kind — it only quotes.
+ */
+export declare function escapeFor(text: string, target: EscapeTarget): string;

package/dist/lib/format.js

@@ -0,0 +1,107 @@
+/**
+ * Shaping text to fit somewhere: a token budget, a column width, or another
+ * language's syntax.
+ */
+/**
+ * Cut text to at most `maxChars`, keeping the end that matters for the
+ * chosen strategy and marking where bytes were dropped. Returns the input
+ * untouched when it already fits, so a caller can pipe everything through
+ * this without a size check first.
+ */
+export function truncateToChars(text, maxChars, strategy, marker) {
+    if (text.length <= maxChars)
+        return { text, truncated: false, droppedChars: 0 };
+    if (maxChars <= marker.length) {
+        return {
+            text: marker.slice(0, maxChars),
+            truncated: true,
+            droppedChars: text.length - maxChars,
+        };
+    }
+    const budget = maxChars - marker.length;
+    let out;
+    if (strategy === "head") {
+        out = text.slice(0, budget) + marker;
+    }
+    else if (strategy === "tail") {
+        out = marker + text.slice(text.length - budget);
+    }
+    else {
+        const half = Math.floor(budget / 2);
+        out = text.slice(0, half) + marker + text.slice(text.length - (budget - half));
+    }
+    return { text: out, truncated: true, droppedChars: text.length - budget };
+}
+/**
+ * Greedy word wrap at `width`, preserving blank-line paragraph breaks and
+ * prefixing every line (for quoting, comment blocks, commit bodies). A word
+ * longer than the width is left whole rather than split, because splitting a
+ * URL or an identifier makes it wrong, not merely ugly.
+ */
+export function wrapText(text, width, prefix, hangingIndent) {
+    const usable = Math.max(1, width - prefix.length);
+    const out = [];
+    for (const paragraph of text.split(/\n{2,}/)) {
+        const words = paragraph.split(/\s+/).filter((w) => w !== "");
+        if (words.length === 0)
+            continue;
+        let line = "";
+        const lines = [];
+        for (const word of words) {
+            if (line === "") {
+                line = (lines.length === 0 ? "" : hangingIndent) + word;
+                continue;
+            }
+            if (line.length + 1 + word.length <= usable) {
+                line += ` ${word}`;
+                continue;
+            }
+            lines.push(line);
+            line = hangingIndent + word;
+        }
+        if (line !== "")
+            lines.push(line);
+        out.push(lines.map((l) => prefix + l).join("\n"));
+    }
+    return out.join("\n\n");
+}
+/**
+ * Escape text for embedding in another syntax.
+ *
+ * This is the function that stops a harness building an injection into its
+ * own next command: a scraped string going into a regex, a filename going
+ * into a shell word, a customer's text going into a CSV cell. It performs no
+ * execution of any kind — it only quotes.
+ */
+export function escapeFor(text, target) {
+    switch (target) {
+        case "regex":
+            return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        case "shellSingle":
+            // POSIX single-quoting: close the quote, emit an escaped quote, reopen.
+            return `'${text.replace(/'/g, `'\\''`)}'`;
+        case "shellDouble":
+            return `"${text.replace(/(["$`\\])/g, "\\$1")}"`;
+        case "json":
+            return JSON.stringify(text);
+        case "url":
+            return encodeURI(text);
+        case "urlComponent":
+            return encodeURIComponent(text);
+        case "html":
+            return text
+                .replace(/&/g, "&amp;")
+                .replace(/</g, "&lt;")
+                .replace(/>/g, "&gt;")
+                .replace(/"/g, "&quot;")
+                .replace(/'/g, "&#39;");
+        case "markdown":
+            return text.replace(/([\\`*_{}[\]()#+\-.!|>~])/g, "\\$1");
+        case "csv":
+            return /[",\n\r]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+        case "sqlLike":
+            return text.replace(/([\\%_])/g, "\\$1");
+        default:
+            return text;
+    }
+}

package/dist/lib/locate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Offset bookkeeping shared by every tool that reports where something was
+ * found. Kept in one place so "line 12, column 3" means the same thing
+ * whether it came from a regex match or an entity scan.
+ */
+/** Byte offsets at which each line starts, so an offset maps to a line. */
+export declare function lineStarts(text: string): number[];
+/** Turn a 0-based offset into a 1-based {line, column} by binary search. */
+export declare function offsetToLineCol(starts: ReadonlyArray<number>, offset: number): {
+    line: number;
+    column: number;
+};
+/**
+ * The token estimate used across this package.
+ *
+ * Four characters per token is the well-worn heuristic for English prose and
+ * is deliberately NOT a real tokenizer: a real BPE would make the answer
+ * depend on a vocabulary file, which is the kind of hidden state that stops
+ * a tool being reproducible. Callers needing exactness should measure with
+ * their provider's own counter.
+ */
+export declare function estimateTokens(text: string): number;
+/** Lowercase word tokens — the shared basis for keyword and token measures. */
+export declare function tokenize(text: string): string[];

package/dist/lib/locate.js

@@ -0,0 +1,43 @@
+/**
+ * Offset bookkeeping shared by every tool that reports where something was
+ * found. Kept in one place so "line 12, column 3" means the same thing
+ * whether it came from a regex match or an entity scan.
+ */
+/** Byte offsets at which each line starts, so an offset maps to a line. */
+export function lineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1);
+    }
+    return starts;
+}
+/** Turn a 0-based offset into a 1-based {line, column} by binary search. */
+export function offsetToLineCol(starts, offset) {
+    let lo = 0;
+    let hi = starts.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (starts[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - starts[lo] + 1 };
+}
+/**
+ * The token estimate used across this package.
+ *
+ * Four characters per token is the well-worn heuristic for English prose and
+ * is deliberately NOT a real tokenizer: a real BPE would make the answer
+ * depend on a vocabulary file, which is the kind of hidden state that stops
+ * a tool being reproducible. Callers needing exactness should measure with
+ * their provider's own counter.
+ */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Lowercase word tokens — the shared basis for keyword and token measures. */
+export function tokenize(text) {
+    return (text.toLowerCase().match(/[a-z0-9][a-z0-9'-]*/g) ?? []).filter((t) => t.length > 0);
+}

package/dist/lib/log.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Replace the volatile head of a log line — ISO timestamps, bracketed clock
+ * times — with a placeholder, so two lines differing only in when they
+ * happened collapse into one during dedupe.
+ */
+export declare function stripTimestamps(line: string): string;
+export declare function looksLikeError(line: string): boolean;
+export type CompactedLine = {
+    readonly line: string;
+    readonly count: number;
+    readonly isError: boolean;
+};
+export type CompactLogOptions = {
+    readonly dedupe: boolean;
+    readonly stripTimestamps: boolean;
+    readonly stripAnsiCodes: boolean;
+    readonly errorsFirst: boolean;
+    readonly maxLines: number;
+};
+/**
+ * Collapse a log to its distinct lines, optionally floating failures to the
+ * top. Order within each group is first-seen, so the result still reads
+ * chronologically rather than being reshuffled by frequency.
+ *
+ * This is the tool that turns a 50k-line CI log into something a model can
+ * read in one turn — or, better, that a rule can decide on with no model at
+ * all.
+ */
+export declare function compactLogLines(text: string, opts: CompactLogOptions): {
+    lines: CompactedLine[];
+    totalLines: number;
+    distinctLines: number;
+    truncated: boolean;
+};

package/dist/lib/log.js

@@ -0,0 +1,63 @@
+import { stripAnsi } from "./normalize";
+/**
+ * Replace the volatile head of a log line — ISO timestamps, bracketed clock
+ * times — with a placeholder, so two lines differing only in when they
+ * happened collapse into one during dedupe.
+ */
+export function stripTimestamps(line) {
+    return line
+        .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:[.,]\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, "<ts>")
+        .replace(/\[\d{2}:\d{2}:\d{2}(?:[.,]\d+)?\]/g, "[<ts>]")
+        .replace(/\b\d{2}:\d{2}:\d{2}(?:[.,]\d+)?\b/g, "<ts>");
+}
+/** Lines matching this read as failures and are surfaced first. */
+const ERROR_PATTERN = /\b(error|errors|err|fail|failed|failure|fatal|panic|exception|traceback|refused|denied|timeout|timed out|cannot|unable to|not found|missing|invalid|unexpected)\b/i;
+export function looksLikeError(line) {
+    return ERROR_PATTERN.test(line);
+}
+/**
+ * Collapse a log to its distinct lines, optionally floating failures to the
+ * top. Order within each group is first-seen, so the result still reads
+ * chronologically rather than being reshuffled by frequency.
+ *
+ * This is the tool that turns a 50k-line CI log into something a model can
+ * read in one turn — or, better, that a rule can decide on with no model at
+ * all.
+ */
+export function compactLogLines(text, opts) {
+    const raw = (opts.stripAnsiCodes ? stripAnsi(text) : text).split("\n");
+    const totalLines = raw.length;
+    const counts = new Map();
+    const order = [];
+    for (const original of raw) {
+        const trimmed = original.trimEnd();
+        if (trimmed.trim() === "")
+            continue;
+        const key = opts.stripTimestamps ? stripTimestamps(trimmed) : trimmed;
+        const prior = counts.get(key);
+        if (prior === undefined) {
+            counts.set(key, 1);
+            order.push(key);
+        }
+        else if (opts.dedupe) {
+            counts.set(key, prior + 1);
+        }
+        else {
+            order.push(key);
+        }
+    }
+    const entries = order.map((line) => ({
+        line,
+        count: opts.dedupe ? (counts.get(line) ?? 1) : 1,
+        isError: looksLikeError(line),
+    }));
+    const sorted = opts.errorsFirst
+        ? [...entries.filter((e) => e.isError), ...entries.filter((e) => !e.isError)]
+        : entries;
+    return {
+        lines: sorted.slice(0, opts.maxLines),
+        totalLines,
+        distinctLines: entries.length,
+        truncated: sorted.length > opts.maxLines,
+    };
+}

package/dist/lib/markdown.d.ts

@@ -0,0 +1,34 @@
+export type Heading = {
+    readonly depth: number;
+    readonly title: string;
+    readonly line: number;
+    readonly slug: string;
+};
+/** GitHub-style heading anchor: lowercase, drop punctuation, spaces to dashes. */
+export declare function slugify(title: string): string;
+/**
+ * Collect ATX headings, ignoring any inside a fenced code block — a
+ * `# comment` in a shell sample is not a section, and treating it as one
+ * corrupts every section boundary after it.
+ */
+export declare function parseHeadings(markdown: string): Heading[];
+/**
+ * Return one section's body: the heading plus everything until the next
+ * heading at the same or shallower depth. Matches on slug or exact title, so
+ * a caller can address a section either way.
+ */
+export declare function sectionBody(markdown: string, wanted: string): string | undefined;
+/** Render the heading tree as an indented outline with line numbers. */
+export declare function renderOutline(headings: ReadonlyArray<Heading>, maxDepth: number): string;
+/** Every fenced code block, with its language tag and start line. */
+export declare function codeBlocks(markdown: string): Array<{
+    language: string;
+    code: string;
+    line: number;
+}>;
+/**
+ * Render rows as a GitHub-flavoured markdown table, padded so the source is
+ * readable. Column order comes from `columns`, or from the union of keys in
+ * first-seen order when it is omitted.
+ */
+export declare function markdownTable(rows: ReadonlyArray<Readonly<Record<string, unknown>>>, columns?: ReadonlyArray<string>): string;

package/dist/lib/markdown.js

@@ -0,0 +1,120 @@
+/** GitHub-style heading anchor: lowercase, drop punctuation, spaces to dashes. */
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, "")
+        .trim()
+        .replace(/\s+/g, "-");
+}
+/**
+ * Collect ATX headings, ignoring any inside a fenced code block — a
+ * `# comment` in a shell sample is not a section, and treating it as one
+ * corrupts every section boundary after it.
+ */
+export function parseHeadings(markdown) {
+    const out = [];
+    let inFence = false;
+    let fenceChar = "";
+    const lines = markdown.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fence = line.match(/^\s*(`{3,}|~{3,})/);
+        if (fence !== null) {
+            const marker = fence[1][0];
+            if (!inFence) {
+                inFence = true;
+                fenceChar = marker;
+            }
+            else if (marker === fenceChar) {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+        if (m === null)
+            continue;
+        const title = m[2].trim();
+        out.push({ depth: m[1].length, title, line: i + 1, slug: slugify(title) });
+    }
+    return out;
+}
+/**
+ * Return one section's body: the heading plus everything until the next
+ * heading at the same or shallower depth. Matches on slug or exact title, so
+ * a caller can address a section either way.
+ */
+export function sectionBody(markdown, wanted) {
+    const headings = parseHeadings(markdown);
+    const target = slugify(wanted);
+    const idx = headings.findIndex((h) => h.slug === target || h.title === wanted);
+    if (idx === -1)
+        return undefined;
+    const start = headings[idx];
+    const next = headings.slice(idx + 1).find((h) => h.depth <= start.depth);
+    const lines = markdown.split("\n");
+    const end = next === undefined ? lines.length : next.line - 1;
+    return lines
+        .slice(start.line - 1, end)
+        .join("\n")
+        .trimEnd();
+}
+/** Render the heading tree as an indented outline with line numbers. */
+export function renderOutline(headings, maxDepth) {
+    const kept = headings.filter((h) => h.depth <= maxDepth);
+    if (kept.length === 0)
+        return "(no headings)";
+    const shallowest = Math.min(...kept.map((h) => h.depth));
+    return kept.map((h) => `${"  ".repeat(h.depth - shallowest)}L${h.line}  ${h.title}`).join("\n");
+}
+/** Every fenced code block, with its language tag and start line. */
+export function codeBlocks(markdown) {
+    const out = [];
+    const lines = markdown.split("\n");
+    let open;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const fence = line.match(/^\s*(`{3,}|~{3,})\s*(\S*)/);
+        if (fence !== null) {
+            const marker = fence[1][0];
+            if (open === undefined) {
+                open = { language: fence[2] ?? "", startLine: i + 1, fenceChar: marker, body: [] };
+            }
+            else if (marker === open.fenceChar) {
+                out.push({ language: open.language, code: open.body.join("\n"), line: open.startLine });
+                open = undefined;
+            }
+            continue;
+        }
+        if (open !== undefined)
+            open.body.push(line);
+    }
+    return out;
+}
+/**
+ * Render rows as a GitHub-flavoured markdown table, padded so the source is
+ * readable. Column order comes from `columns`, or from the union of keys in
+ * first-seen order when it is omitted.
+ */
+export function markdownTable(rows, columns) {
+    const cols = columns ?? [...new Set(rows.flatMap((r) => Object.keys(r)))].filter((c) => c.length > 0);
+    if (cols.length === 0)
+        return "";
+    const cell = (v) => {
+        if (v === null || v === undefined)
+            return "";
+        const s = typeof v === "object" ? JSON.stringify(v) : String(v);
+        // A literal pipe would break the row into extra columns.
+        return s.replace(/\|/g, "\\|").replace(/\n/g, " ");
+    };
+    const body = rows.map((r) => cols.map((c) => cell(r[c])));
+    const widths = cols.map((c, i) => Math.max(c.length, ...body.map((r) => r[i].length), 3));
+    const pad = (s, w) => s + " ".repeat(w - s.length);
+    const lines = [
+        `| ${cols.map((c, i) => pad(c, widths[i])).join(" | ")} |`,
+        `| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`,
+        ...body.map((r) => `| ${r.map((v, i) => pad(v, widths[i])).join(" | ")} |`),
+    ];
+    return lines.join("\n");
+}

package/dist/lib/normalize.d.ts

@@ -0,0 +1,39 @@
+/** Strip ANSI escapes so a captured terminal log compares as plain text. */
+export declare function stripAnsi(text: string): string;
+export type NormalizeOptions = {
+    readonly eol?: "lf" | "crlf";
+    readonly trimTrailingWhitespace?: boolean;
+    readonly collapseBlankLines?: boolean;
+    readonly tabsToSpaces?: number;
+    readonly stripAnsiCodes?: boolean;
+    readonly stripInvisible?: boolean;
+    readonly unicode?: "NFC" | "NFD" | "NFKC" | "NFKD";
+    readonly ensureFinalNewline?: boolean;
+    readonly lowercase?: boolean;
+};
+/**
+ * Canonicalize text so two copies differing only in invisible ways compare
+ * equal. Run this before hashing, diffing, or de-duplicating; it is why a
+ * "file changed" check stops firing on a line-ending flip.
+ */
+export declare function normalizeText(text: string, opts: NormalizeOptions): string;
+export type SortOptions = {
+    readonly order?: "asc" | "desc";
+    readonly unique?: boolean;
+    readonly numeric?: boolean;
+    readonly ignoreCase?: boolean;
+    readonly field?: number;
+    readonly delimiter?: string;
+    readonly keepEmpty?: boolean;
+};
+/** Sort, de-duplicate, and optionally key lines by a delimited field. */
+export declare function sortLines(text: string, opts: SortOptions): string[];
+/**
+ * Replace terms using operator-supplied mappings, longest term first so a
+ * multi-word entry wins over a substring of itself. Whole-word by default,
+ * which is what stops "AI" rewriting the middle of "CHAIN".
+ */
+export declare function glossaryReplace(text: string, mapping: Readonly<Record<string, string>>, wholeWord: boolean, caseSensitive: boolean): {
+    text: string;
+    replacements: Record<string, number>;
+};

package/dist/lib/normalize.js

@@ -0,0 +1,122 @@
+import { escapeFor } from "./format";
+/** CSI/SGR escapes emitted by terminals into captured output. */
+const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[ -/]*[@-~]`, "g");
+/** Strip ANSI escapes so a captured terminal log compares as plain text. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+/**
+ * Zero-width and bidirectional-control characters that survive copy-paste and
+ * silently break diffs and equality checks. Built from explicit code points
+ * rather than written as a character range: a range spanning the zero-width
+ * joiner can split a joined sequence, which is what
+ * `noMisleadingCharacterClass` warns about.
+ */
+const INVISIBLE_CODE_POINTS = [
+    0x200b, // zero-width space
+    0x200c, // zero-width non-joiner
+    0x200d, // zero-width joiner
+    0xfeff, // byte-order mark
+    0x2060, // word joiner
+    0x180e, // Mongolian vowel separator
+    0x202a, // bidi embedding and override
+    0x202b,
+    0x202c,
+    0x202d,
+    0x202e,
+    0x2066, // bidi isolates
+    0x2067,
+    0x2068,
+    0x2069,
+];
+const INVISIBLE_PATTERN = new RegExp(INVISIBLE_CODE_POINTS.map((cp) => `\\u${cp.toString(16).padStart(4, "0")}`).join("|"), "g");
+/**
+ * Canonicalize text so two copies differing only in invisible ways compare
+ * equal. Run this before hashing, diffing, or de-duplicating; it is why a
+ * "file changed" check stops firing on a line-ending flip.
+ */
+export function normalizeText(text, opts) {
+    let out = text;
+    if (opts.stripAnsiCodes === true)
+        out = stripAnsi(out);
+    if (opts.stripInvisible === true)
+        out = out.replace(INVISIBLE_PATTERN, "");
+    if (opts.unicode !== undefined)
+        out = out.normalize(opts.unicode);
+    if (opts.tabsToSpaces !== undefined)
+        out = out.replace(/\t/g, " ".repeat(opts.tabsToSpaces));
+    // Fold to LF first so later rules see one shape, then convert at the end.
+    out = out.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    if (opts.trimTrailingWhitespace === true) {
+        out = out
+            .split("\n")
+            .map((l) => l.replace(/[ \t]+$/, ""))
+            .join("\n");
+    }
+    if (opts.collapseBlankLines === true)
+        out = out.replace(/\n{3,}/g, "\n\n");
+    if (opts.lowercase === true)
+        out = out.toLowerCase();
+    if (opts.ensureFinalNewline === true && !out.endsWith("\n"))
+        out += "\n";
+    if (opts.eol === "crlf")
+        out = out.replace(/\n/g, "\r\n");
+    return out;
+}
+/** Sort, de-duplicate, and optionally key lines by a delimited field. */
+export function sortLines(text, opts) {
+    let lines = text.split("\n");
+    if (opts.keepEmpty !== true)
+        lines = lines.filter((l) => l.trim() !== "");
+    const keyOf = (line) => {
+        const base = opts.field !== undefined ? (line.split(opts.delimiter ?? "\t")[opts.field] ?? "") : line;
+        return opts.ignoreCase === true ? base.toLowerCase() : base;
+    };
+    if (opts.unique === true) {
+        const seen = new Set();
+        lines = lines.filter((l) => {
+            const k = keyOf(l);
+            if (seen.has(k))
+                return false;
+            seen.add(k);
+            return true;
+        });
+    }
+    const sorted = [...lines].sort((a, b) => {
+        const ka = keyOf(a);
+        const kb = keyOf(b);
+        if (opts.numeric === true) {
+            const na = Number.parseFloat(ka);
+            const nb = Number.parseFloat(kb);
+            const aNum = Number.isNaN(na) ? Number.POSITIVE_INFINITY : na;
+            const bNum = Number.isNaN(nb) ? Number.POSITIVE_INFINITY : nb;
+            if (aNum !== bNum)
+                return aNum - bNum;
+            return ka.localeCompare(kb);
+        }
+        return ka.localeCompare(kb);
+    });
+    return opts.order === "desc" ? sorted.reverse() : sorted;
+}
+/**
+ * Replace terms using operator-supplied mappings, longest term first so a
+ * multi-word entry wins over a substring of itself. Whole-word by default,
+ * which is what stops "AI" rewriting the middle of "CHAIN".
+ */
+export function glossaryReplace(text, mapping, wholeWord, caseSensitive) {
+    const replacements = {};
+    let out = text;
+    for (const term of Object.keys(mapping).sort((a, b) => b.length - a.length)) {
+        const escaped = escapeFor(term, "regex");
+        const source = wholeWord ? `(?<![\\w-])${escaped}(?![\\w-])` : escaped;
+        const re = new RegExp(source, caseSensitive ? "g" : "gi");
+        let count = 0;
+        out = out.replace(re, () => {
+            count++;
+            return mapping[term];
+        });
+        if (count > 0)
+            replacements[term] = count;
+    }
+    return { text: out, replacements };
+}

package/dist/lib/regex.d.ts

@@ -0,0 +1,20 @@
+/** A single regex hit, located by offset AND by line/column. */
+export type RegexMatch = {
+    readonly match: string;
+    readonly index: number;
+    readonly line: number;
+    readonly column: number;
+    readonly groups: Readonly<Record<string, string>>;
+    readonly captures: ReadonlyArray<string | undefined>;
+};
+/**
+ * Run a regex over text and return located matches.
+ *
+ * Always compiles with `g` so the scan advances, and a zero-width match bumps
+ * `lastIndex` by one so a pattern like `a*` terminates instead of spinning
+ * forever at the same offset.
+ */
+export declare function regexExtractAll(text: string, pattern: string, flags: string, maxMatches: number): {
+    matches: RegexMatch[];
+    truncated: boolean;
+};