regex-explain 0.0.0 → 1.0.0

package/dist/cjs/matches.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findMatches = findMatches;
+exports.describeMatches = describeMatches;
+/**
+ * Finds the matches of a regex in text, using JavaScript's `RegExp`.
+ *
+ * @param request The regex, the text, the most matches to return, and whether each line is a
+ *   separate entry.
+ *
+ * @returns The matches, or an error if the regex does not compile. Empty matches are reported once
+ *   at each position, because `matchAll` steps past them.
+ */
+function findMatches(request) {
+    let regex;
+    try {
+        const flags = request.flags.includes("g") ? request.flags : `${request.flags}g`;
+        regex = new RegExp(request.pattern, flags);
+    }
+    catch (error) {
+        return { matches: [], truncated: false, error: error.message };
+    }
+    const lineStarts = findLineStarts(request.text);
+    if (!request.entries) {
+        // One match past the limit tells whether there are more, without running the regex further.
+        const found = [...take(request.text.matchAll(regex), request.limit + 1)];
+        return {
+            matches: found.slice(0, request.limit).map((match) => toFoundMatch(match, 0, lineStarts)),
+            truncated: found.length > request.limit,
+        };
+    }
+    const entries = splitEntries(request.text, lineStarts);
+    const found = [...take(matchEntries(entries, regex), request.limit + 1)];
+    const kept = found.slice(0, request.limit);
+    const truncated = found.length > request.limit;
+    const lastLine = truncated ? (kept[kept.length - 1]?.entry.line ?? 0) : Infinity;
+    return {
+        matches: kept.map(({ entry, match }) => toFoundMatch(match, entry.start, lineStarts)),
+        truncated,
+        entries: entries.filter((entry) => entry.line <= lastLine),
+    };
+}
+/**
+ * Splits text into entries, one per line.
+ *
+ * @param text The text.
+ * @param lineStarts Offsets from {@link findLineStarts}.
+ *
+ * @returns The lines without their line breaks; none for empty text, and no empty entry after a
+ *   final line break.
+ */
+function splitEntries(text, lineStarts) {
+    const lines = lineStarts.map((start, i) => {
+        const content = text
+            .slice(start, lineStarts[i + 1] ?? text.length)
+            .replace(/(?:\r\n|\r|\n)$/, "");
+        return { line: i + 1, start, end: start + content.length, text: content };
+    });
+    return text === "" || /(?:\r\n|\r|\n)$/.test(text) ? lines.slice(0, -1) : lines;
+}
+/**
+ * Runs a regex over each entry on its own.
+ *
+ * @param entries The entries.
+ * @param regex The regex, with the `g` flag.
+ *
+ * @returns Each match with the entry it is in, lazily, so that callers can stop early.
+ */
+function* matchEntries(entries, regex) {
+    for (const entry of entries) {
+        for (const match of entry.text.matchAll(regex)) {
+            yield { entry, match };
+        }
+    }
+}
+/**
+ * Converts a `matchAll` result into a {@link FoundMatch}.
+ *
+ * @param match The result.
+ * @param offset Where the searched string starts in the whole text: 0, or an entry's start.
+ * @param lineStarts Offsets from {@link findLineStarts} for the whole text.
+ *
+ * @returns The match, with offsets and lines in the whole text.
+ */
+function toFoundMatch(match, offset, lineStarts) {
+    const start = offset + match.index;
+    const end = start + match[0].length;
+    return {
+        start,
+        end,
+        text: match[0],
+        startLine: lineAt(lineStarts, start),
+        endLine: lineAt(lineStarts, Math.max(start, end - 1)),
+        groups: match.slice(1),
+        named: { ...match.groups },
+    };
+}
+/**
+ * Yields the first items of an iterable, without reading past them.
+ *
+ * @param items The items.
+ * @param count How many to yield.
+ *
+ * @returns The first `count` items, or all of them if there are fewer.
+ */
+function* take(items, count) {
+    if (count <= 0) {
+        return;
+    }
+    let taken = 0;
+    for (const item of items) {
+        yield item;
+        taken += 1;
+        if (taken === count) {
+            return;
+        }
+    }
+}
+/**
+ * Words the outcome of a match request for display.
+ *
+ * @param response The outcome of {@link findMatches}, or one with `timedOut` or `error` set by the
+ *   caller.
+ *
+ * @returns The summary sentence, whether it reports a problem, each match with its lines and groups
+ *   labeled, and, for entries, each entry with its matches.
+ */
+function describeMatches(response) {
+    const matches = response.matches.map(describeMatch);
+    const entries = response.entries?.map((entry) => {
+        const inEntry = matches.filter((match) => match.start >= entry.start && match.start <= entry.end);
+        return {
+            line: `L${entry.line}`,
+            start: entry.start,
+            end: entry.end,
+            text: entry.text === "" ? "(empty)" : entry.text,
+            matched: inEntry.length > 0,
+            matches: inEntry,
+        };
+    });
+    const problem = !!(response.error || response.timedOut);
+    const shown = response.truncated ? ` (showing the first ${matches.length} matches)` : "";
+    const summary = response.error
+        ? `The regex cannot run: ${response.error}`
+        : response.timedOut
+            ? "Matching timed out: the pattern backtracks too much on this text."
+            : entries
+                ? `${describeEntryCount(entries)}${shown}.`
+                : `${describeCount(matches.length, "match", "matches")}${response.truncated ? ` (showing the first ${matches.length})` : ""}.`;
+    return entries ? { summary, problem, matches, entries } : { summary, problem, matches };
+}
+/**
+ * Words how many entries matched.
+ *
+ * @param entries The entries.
+ *
+ * @returns A phrase such as "1 of 3 entries matches" or "No entries".
+ */
+function describeEntryCount(entries) {
+    if (entries.length === 0) {
+        return "No entries";
+    }
+    const matched = entries.filter((entry) => entry.matched).length;
+    const noun = entries.length === 1 ? "entry" : "entries";
+    return `${matched} of ${entries.length} ${noun} ${matched === 1 ? "matches" : "match"}`;
+}
+/**
+ * Words a count of things.
+ *
+ * @param count The count.
+ * @param one The noun for one.
+ * @param many The noun for several.
+ *
+ * @returns A phrase such as "No matches", "1 match", or "2 matches".
+ */
+function describeCount(count, one, many) {
+    return `${count === 0 ? "No" : count} ${count === 1 ? one : many}`;
+}
+/**
+ * Words one match for display.
+ *
+ * @param match The match.
+ *
+ * @returns The match with its lines and groups labeled.
+ */
+function describeMatch(match) {
+    const groups = [
+        ...match.groups.map((value, i) => [`$${i + 1}`, value]),
+        ...Object.entries(match.named),
+    ];
+    return {
+        start: match.start,
+        end: match.end,
+        lines: match.startLine === match.endLine
+            ? `L${match.startLine}`
+            : `L${match.startLine}–${match.endLine}`,
+        text: match.text === "" ? "(empty)" : match.text,
+        groups: groups.map(([name, value]) => ({
+            name,
+            value: value ?? "(no match)",
+            matched: value !== undefined,
+        })),
+    };
+}
+/**
+ * Finds the offset where each line starts.
+ *
+ * @param text The text.
+ *
+ * @returns The start offsets, beginning with 0.
+ */
+function findLineStarts(text) {
+    const lineBreaks = [...text.matchAll(/\r\n|\r|\n/g)];
+    return [0, ...lineBreaks.map((lineBreak) => lineBreak.index + lineBreak[0].length)];
+}
+/**
+ * Finds the line containing an offset.
+ *
+ * @param lineStarts Offsets from {@link findLineStarts}.
+ * @param offset The offset.
+ *
+ * @returns The 1-based line number.
+ */
+function lineAt(lineStarts, offset) {
+    let low = 0;
+    let high = lineStarts.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        if (lineStarts[middle] <= offset) {
+            low = middle;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    return low + 1;
+}
+//# sourceMappingURL=matches.js.map

package/dist/cjs/render.d.ts

@@ -0,0 +1,120 @@
+import { ExplainResult } from "./explainer";
+import { TextPart } from "./text";
+/** Options for the {@link ExplanationRenderer} output methods. */
+export interface RenderOptions {
+    /** Start with a heading that shows the whole regex. Defaults to `false`. */
+    readonly title?: boolean;
+}
+/** One step of an explanation, flattened out of the node tree. */
+export interface ExplanationRow {
+    /** The pattern source the step covers. */
+    readonly raw: string;
+    /** The step's description, which may contain Markdown code spans. */
+    readonly description: string;
+    /** How deeply the step is nested; top-level steps are 0. */
+    readonly depth: number;
+    /** The description split into plain text and code, for formats other than Markdown. */
+    readonly parts: readonly TextPart[];
+}
+/** A backtracking warning, ready to display. */
+export interface WarningModel {
+    /** What the problem is, which may contain Markdown code spans. */
+    readonly description: string;
+    /** The description split into plain text and code. */
+    readonly parts: readonly TextPart[];
+    /** An equivalent pattern that does not backtrack, as `/pattern/flags`, if one exists. */
+    readonly fix?: string;
+}
+/** A flag's explanation, ready to display. */
+export interface FlagModel {
+    /** The flag letter. */
+    readonly flag: string;
+    /** The flag's name, such as `ignoreCase`. */
+    readonly name: string;
+    /** What the flag does, which may contain Markdown code spans. */
+    readonly description: string;
+    /** The description split into plain text and code. */
+    readonly parts: readonly TextPart[];
+}
+/** A syntax error, ready to display. */
+export interface ErrorModel {
+    /** The parser's message. */
+    readonly message: string;
+    /** The pattern. */
+    readonly pattern: string;
+    /** Offset of the error in the pattern, if known. */
+    readonly index?: number;
+    /** A line of spaces and a `^` that, printed under the pattern, points at the error. */
+    readonly caret?: string;
+}
+/**
+ * Everything an explanation view shows, in display order, with descriptions already split so that a
+ * renderer only maps it to markup.
+ */
+export interface ExplanationModel {
+    /** The regex as `/pattern/flags`. */
+    readonly literal: string;
+    /** The syntax error, for an invalid pattern; the other lists are then empty. */
+    readonly error?: ErrorModel;
+    /** Backtracking warnings. */
+    readonly warnings: readonly WarningModel[];
+    /** The steps, flattened with their depths. */
+    readonly rows: readonly ExplanationRow[];
+    /** How long a match can be, such as "Matches 3 to 7 characters.", for a valid pattern. */
+    readonly length?: string;
+    /** The flags' explanations. */
+    readonly flags: readonly FlagModel[];
+    /** Whether `^` and `$` match at line breaks anywhere in the pattern; false for an error. */
+    readonly multiline: boolean;
+}
+/** Renders an `explainRegex` result in several output formats. */
+export declare class ExplanationRenderer {
+    private readonly result;
+    /**
+     * Constructs a new ExplanationRenderer.
+     *
+     * @param result The result of `explainRegex`.
+     */
+    constructor(result: ExplainResult);
+    /**
+     * Collects everything an explanation view shows. Every output format renders from this model.
+     *
+     * @returns The model.
+     */
+    model(): ExplanationModel;
+    /**
+     * Renders the explanation as a nested Markdown list, suitable for hovers and documentation.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The Markdown.
+     */
+    markdownList(options?: RenderOptions): string;
+    /**
+     * Renders the explanation as a Markdown table with a Code Point and an Explanation column. Nested
+     * steps are indented with non-breaking spaces.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The Markdown.
+     */
+    markdownTable(options?: RenderOptions): string;
+    /**
+     * Renders the explanation as indented plain text, for terminals and logs.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The text.
+     */
+    text(options?: RenderOptions): string;
+    /**
+     * Renders the parts every Markdown format shares around its steps: the title, the error or the
+     * warnings, the match length, and the flags.
+     *
+     * @param options Rendering options.
+     * @param steps Formats the rows as Markdown lines.
+     *
+     * @returns The Markdown.
+     */
+    private markdown;
+}

package/dist/cjs/render.js

@@ -0,0 +1,238 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplanationRenderer = void 0;
+const text_1 = require("./text");
+/** Renders an `explainRegex` result in several output formats. */
+class ExplanationRenderer {
+    result;
+    /**
+     * Constructs a new ExplanationRenderer.
+     *
+     * @param result The result of `explainRegex`.
+     */
+    constructor(result) {
+        this.result = result;
+    }
+    /**
+     * Collects everything an explanation view shows. Every output format renders from this model.
+     *
+     * @returns The model.
+     */
+    model() {
+        const result = this.result;
+        if (!result.ok) {
+            return {
+                literal: literal(result),
+                error: {
+                    message: result.message,
+                    pattern: result.pattern,
+                    index: result.index,
+                    caret: result.index === undefined ? undefined : "^".padStart(result.index + 1),
+                },
+                warnings: [],
+                rows: [],
+                flags: [],
+                multiline: false,
+            };
+        }
+        return {
+            literal: literal(result),
+            multiline: result.multiline,
+            warnings: result.warnings.map((warning) => ({
+                ...described(warning.description),
+                fix: warning.fix && literal(warning.fix),
+            })),
+            rows: flatten(result.nodes),
+            length: describeLength(result),
+            flags: result.flagExplanations.map((f) => ({
+                flag: f.flag,
+                name: f.name,
+                ...described(f.description),
+            })),
+        };
+    }
+    /**
+     * Renders the explanation as a nested Markdown list, suitable for hovers and documentation.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The Markdown.
+     */
+    markdownList(options = {}) {
+        return this.markdown(options, (rows) => rows.map((row) => `${"  ".repeat(row.depth)}- ${(0, text_1.code)(row.raw)} ${row.description}`));
+    }
+    /**
+     * Renders the explanation as a Markdown table with a Code Point and an Explanation column. Nested
+     * steps are indented with non-breaking spaces.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The Markdown.
+     */
+    markdownTable(options = {}) {
+        return this.markdown(options, (rows) => [
+            "| Code Point | Explanation |",
+            "| ---------- | ----------- |",
+            ...rows.map((row) => `| ${"  ".repeat(row.depth)}${escapePipes((0, text_1.code)(row.raw))} | ${escapePipes(row.description)} |`),
+        ]);
+    }
+    /**
+     * Renders the explanation as indented plain text, for terminals and logs.
+     *
+     * @param options Rendering options.
+     *
+     * @returns The text.
+     */
+    text(options = {}) {
+        const model = this.model();
+        const title = options.title ? [model.literal, ""] : [];
+        if (model.error) {
+            const caret = model.error.caret === undefined
+                ? []
+                : [`  ${model.error.pattern}`, `  ${model.error.caret}`];
+            return [...title, `Invalid regular expression: ${model.error.message}`, ...caret].join("\n");
+        }
+        const warnings = model.warnings.flatMap((warning) => [
+            `Warning: ${plain(warning.parts)}.`,
+            ...(warning.fix ? [`  Equivalent safe pattern: ${warning.fix}`] : []),
+        ]);
+        const width = Math.min(30, Math.max(...model.rows.map((row) => row.depth * 2 + row.raw.length)));
+        const steps = model.rows.map((row) => `${`${"  ".repeat(row.depth)}${row.raw}`.padEnd(width)}  ${plain(row.parts)}`);
+        const flags = model.flags.length === 0
+            ? []
+            : ["", "Flags:", ...model.flags.map((f) => `  ${f.flag}  ${f.name}: ${plain(f.parts)}`)];
+        return [
+            ...title,
+            ...warnings,
+            ...(warnings.length > 0 ? [""] : []),
+            ...steps,
+            "",
+            model.length ?? "",
+            ...flags,
+        ].join("\n");
+    }
+    /**
+     * Renders the parts every Markdown format shares around its steps: the title, the error or the
+     * warnings, the match length, and the flags.
+     *
+     * @param options Rendering options.
+     * @param steps Formats the rows as Markdown lines.
+     *
+     * @returns The Markdown.
+     */
+    markdown(options, steps) {
+        const model = this.model();
+        const title = options.title ? ["# Regex explanation", "", (0, text_1.code)(model.literal), ""] : [];
+        if (model.error) {
+            const caret = model.error.caret === undefined
+                ? []
+                : ["", "```text", model.error.pattern, model.error.caret, "```"];
+            const message = `**Invalid regular expression:** ${escapeMarkdown(model.error.message)}`;
+            return [...title, message, ...caret].join("\n");
+        }
+        const warnings = model.warnings.flatMap((warning) => [
+            `> **Warning:** ${warning.description}.`,
+            ...(warning.fix ? [`> Equivalent safe pattern: ${(0, text_1.code)(warning.fix)}`] : []),
+            "",
+        ]);
+        const flags = model.flags.length === 0
+            ? []
+            : [
+                "",
+                "**Flags**",
+                "",
+                ...model.flags.map((f) => `- ${(0, text_1.code)(f.flag)} *${f.name}*: ${f.description}`),
+            ];
+        return [...title, ...warnings, ...steps(model.rows), "", `*${model.length}*`, ...flags].join("\n");
+    }
+}
+exports.ExplanationRenderer = ExplanationRenderer;
+/**
+ * Formats a regex as a literal.
+ *
+ * @param source The regex.
+ *
+ * @returns The pattern between slashes, followed by the flags, such as `/a+/g`.
+ */
+function literal(source) {
+    return `/${source.pattern}/${source.flags}`;
+}
+/**
+ * Pairs a description with its parts.
+ *
+ * @param description A description that may contain Markdown code spans.
+ *
+ * @returns The description and its parts from {@link splitCodeSpans}.
+ */
+function described(description) {
+    return { description, parts: (0, text_1.splitCodeSpans)(description) };
+}
+/**
+ * Flattens an explanation tree into rows, each followed by its descendants.
+ *
+ * @param nodes The sibling nodes.
+ * @param depth The depth of `nodes`, where top-level nodes are 0.
+ *
+ * @returns One row per node, in display order, with its depth.
+ */
+function flatten(nodes, depth = 0) {
+    return nodes.flatMap((node) => [
+        { raw: node.raw, depth, ...described(node.description) },
+        ...flatten(node.children, depth + 1),
+    ]);
+}
+/**
+ * Joins description parts as plain text, with code in double quotes.
+ *
+ * @param parts The parts.
+ *
+ * @returns The text.
+ */
+function plain(parts) {
+    return parts.map((part) => (part.code ? `"${part.text}"` : part.text)).join("");
+}
+/**
+ * Words how long a match can be.
+ *
+ * @param result A successful explanation.
+ *
+ * @returns A sentence such as "Matches 3 to 7 characters."
+ */
+function describeLength(result) {
+    const { min, max } = result.length;
+    if (min === 0 && max === 0) {
+        return "Matches the empty string only (zero characters).";
+    }
+    const unit = (n) => (n === 1 ? "character" : "characters");
+    if (max === Infinity) {
+        return min === 0
+            ? "Matches any number of characters, including none."
+            : `Matches ${min} or more characters.`;
+    }
+    if (min === max) {
+        return `Matches exactly ${min} ${unit(min)}.`;
+    }
+    return `Matches ${min} to ${max} characters.`;
+}
+/**
+ * Escapes the pipes in a Markdown table cell, which GFM treats as cell boundaries even inside code
+ * spans.
+ *
+ * @param text The cell text.
+ *
+ * @returns The escaped text.
+ */
+function escapePipes(text) {
+    return text.replaceAll("|", "\\|");
+}
+/**
+ * Escapes Markdown punctuation in text that did not come from this library.
+ *
+ * @param text The text.
+ *
+ * @returns The escaped text.
+ */
+function escapeMarkdown(text) {
+    return text.replace(/[\\`*_{}[\]()#+\-.!|<>]/g, "\\$&");
+}
+//# sourceMappingURL=render.js.map

package/dist/cjs/strings.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Turns the source text of string literals into the values they denote, so that a pattern written
+ * as `"\\d+"` in source is explained as `\d+`. The tree-sitter grammars mark escapes and
+ * interpolations; this module only decodes escapes.
+ */
+import type { RegexSource } from "./explainer";
+/**
+ * Decodes one escape sequence from a string literal.
+ *
+ * Unknown single-character escapes such as `\q` decode to the character, as in JavaScript and Ruby.
+ * Grammars for languages that keep the backslash, such as Python and PHP, do not mark those as
+ * escapes, so they never reach this function.
+ *
+ * @param escape The escape's source text, starting with a backslash.
+ *
+ * @returns The decoded text, or undefined for escapes that cannot be decoded without knowing the
+ *   language, such as Python's `\N{name}`, or `\a` and `\e`, which are control characters in some
+ *   languages and plain letters in JavaScript.
+ */
+export declare function decodeEscape(escape: string): string | undefined;
+/**
+ * Splits a PCRE-style pattern such as PHP's `'/a+/i'` into its pattern and flags.
+ *
+ * @param value The string's value. Its first character is the delimiter; brackets close with their
+ *   pair.
+ *
+ * @returns The parts, or undefined if the value is not delimited.
+ */
+export declare function splitDelimitedPattern(value: string): RegexSource | undefined;
+/**
+ * Rewrites flags into their JavaScript equivalents.
+ *
+ * @param flags The flags as written in the source language.
+ * @param map Replacement for each flag that differs; an empty string drops a flag that does not
+ *   change what matches. Flags not in the map are kept, so the explainer reports unknown ones.
+ *
+ * @returns The JavaScript flags.
+ */
+export declare function translateFlags(flags: string, map: Readonly<Record<string, string>>): string;