regex-explain 0.0.0 → 1.0.0

package/dist/cjs/index.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExplanationRenderer = exports.regex101Url = exports.findMatches = exports.describeMatches = exports.RegexFinder = exports.findRegexAt = exports.SUPPORTED_LANGUAGE_IDS = exports.GRAMMARS = exports.parseRegexInput = exports.isRegexSource = exports.explainRegex = exports.describeCount = void 0;
+var explainer_1 = require("./explainer");
+Object.defineProperty(exports, "describeCount", { enumerable: true, get: function () { return explainer_1.describeCount; } });
+Object.defineProperty(exports, "explainRegex", { enumerable: true, get: function () { return explainer_1.explainRegex; } });
+Object.defineProperty(exports, "isRegexSource", { enumerable: true, get: function () { return explainer_1.isRegexSource; } });
+Object.defineProperty(exports, "parseRegexInput", { enumerable: true, get: function () { return explainer_1.parseRegexInput; } });
+var compiler_1 = require("./compiler");
+Object.defineProperty(exports, "GRAMMARS", { enumerable: true, get: function () { return compiler_1.GRAMMARS; } });
+Object.defineProperty(exports, "SUPPORTED_LANGUAGE_IDS", { enumerable: true, get: function () { return compiler_1.SUPPORTED_LANGUAGE_IDS; } });
+var locator_1 = require("./locator");
+Object.defineProperty(exports, "findRegexAt", { enumerable: true, get: function () { return locator_1.findRegexAt; } });
+Object.defineProperty(exports, "RegexFinder", { enumerable: true, get: function () { return locator_1.RegexFinder; } });
+var matches_1 = require("./matches");
+Object.defineProperty(exports, "describeMatches", { enumerable: true, get: function () { return matches_1.describeMatches; } });
+Object.defineProperty(exports, "findMatches", { enumerable: true, get: function () { return matches_1.findMatches; } });
+var extlinks_1 = require("./extlinks");
+Object.defineProperty(exports, "regex101Url", { enumerable: true, get: function () { return extlinks_1.regex101Url; } });
+var render_1 = require("./render");
+Object.defineProperty(exports, "ExplanationRenderer", { enumerable: true, get: function () { return render_1.ExplanationRenderer; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/locator.d.ts

@@ -0,0 +1,80 @@
+import type { RegexSource } from "./explainer";
+/**
+ * A regex found in source text. The pattern has the source language's string escapes decoded, and
+ * the flags are translated to JavaScript.
+ */
+export interface LocatedRegex extends RegexSource {
+    /** Offset where the regex starts, inclusive. */
+    readonly start: number;
+    /** Offset where the regex ends, exclusive. */
+    readonly end: number;
+}
+/**
+ * Sources longer than this, in UTF-16 code units, are not parsed. Regexes in generated or minified
+ * files are rarely worth explaining, and parsing them on every change would be slow.
+ */
+export declare const MAX_SCAN_LENGTH = 1000000;
+/** Finds regexes in documents of the languages in {@link LANGUAGES}. */
+export declare class RegexFinder {
+    private readonly wasmDir;
+    private readonly grammars;
+    private readonly languages;
+    /**
+     * Constructs a new RegexFinder.
+     *
+     * @param wasmDir Directory or URL holding `tree-sitter.wasm` and the `tree-sitter-<grammar>.wasm`
+     *   files, such as the `wasm` directory of `@vscode/tree-sitter-wasm`.
+     */
+    constructor(wasmDir: string);
+    /**
+     * Checks whether regexes can be found in a language.
+     *
+     * @param languageId A VS Code language ID.
+     *
+     * @returns Whether the language has a {@link LanguageSpec}.
+     */
+    supports(languageId: string): boolean;
+    /**
+     * Lists the regexes in source text, in order.
+     *
+     * @param source The source text.
+     * @param languageId The VS Code language ID of the source.
+     *
+     * @returns The regexes found; none for unsupported languages or for sources longer than
+     *   {@link MAX_SCAN_LENGTH}. Patterns built at run time, such as strings with interpolations, are
+     *   skipped.
+     */
+    find(source: string, languageId: string): Promise<LocatedRegex[]>;
+    /**
+     * Creates a parser and compiles the query for a language, once per language.
+     *
+     * @param languageId The VS Code language ID.
+     * @param spec The language's entry in {@link LANGUAGES}.
+     *
+     * @returns The parser and query.
+     */
+    private language;
+    /**
+     * Loads a grammar from the WASM directory, once per grammar.
+     *
+     * @param grammar The grammar name.
+     *
+     * @returns The grammar.
+     */
+    private grammar;
+    /**
+     * Loads the tree-sitter runtime, once per process.
+     *
+     * @returns The runtime's exports.
+     */
+    private runtime;
+}
+/**
+ * Finds the regex that contains an offset.
+ *
+ * @param regexes Regexes from {@link RegexFinder.find}, in order.
+ * @param offset The offset to look up.
+ *
+ * @returns The regex, or undefined if the offset is not inside one.
+ */
+export declare function findRegexAt(regexes: readonly LocatedRegex[], offset: number): LocatedRegex | undefined;

package/dist/cjs/locator.js

@@ -0,0 +1,341 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegexFinder = exports.MAX_SCAN_LENGTH = void 0;
+exports.findRegexAt = findRegexAt;
+const compiler_1 = require("./compiler");
+const strings_1 = require("./strings");
+/**
+ * Sources longer than this, in UTF-16 code units, are not parsed. Regexes in generated or minified
+ * files are rarely worth explaining, and parsing them on every change would be slow.
+ */
+exports.MAX_SCAN_LENGTH = 1_000_000;
+/** Named children of string literals that hold their text rather than delimiters or code. */
+const CONTENT_TYPE = /(?:content|fragment)$/;
+/** Named children of string literals that delimit them. */
+const DELIMITER_TYPE = /(?:_start|_end)$/;
+/** `<script>` blocks of single-file components, with the code in group 1. */
+const SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi;
+/**
+ * Loads and initializes the tree-sitter runtime once per process, from the first finder's
+ * directory.
+ */
+let runtime;
+/**
+ * Loads the tree-sitter runtime and initializes its WebAssembly module.
+ *
+ * @param wasmDir Directory holding `tree-sitter.wasm`.
+ *
+ * @returns The runtime's exports.
+ */
+async function loadRuntime(wasmDir) {
+    const imported = await import("@vscode/tree-sitter-wasm");
+    // The package is CommonJS: ES module loaders put its exports on `default`.
+    const treeSitter = imported.default ?? imported;
+    await treeSitter.Parser.init({ locateFile: (file) => joinPath(wasmDir, file) });
+    return treeSitter;
+}
+/**
+ * Joins a directory and a file name with `/`, which works for file paths on every platform and for
+ * URLs, so that the finder runs under bundlers without Node's `path` module.
+ *
+ * @param dir The directory or URL.
+ * @param file The file name.
+ *
+ * @returns The joined path.
+ */
+function joinPath(dir, file) {
+    return `${dir.replace(/[\\/]+$/, "")}/${file}`;
+}
+/** Finds regexes in documents of the languages in {@link LANGUAGES}. */
+class RegexFinder {
+    wasmDir;
+    grammars = new Map();
+    languages = new Map();
+    /**
+     * Constructs a new RegexFinder.
+     *
+     * @param wasmDir Directory or URL holding `tree-sitter.wasm` and the `tree-sitter-<grammar>.wasm`
+     *   files, such as the `wasm` directory of `@vscode/tree-sitter-wasm`.
+     */
+    constructor(wasmDir) {
+        this.wasmDir = wasmDir;
+    }
+    /**
+     * Checks whether regexes can be found in a language.
+     *
+     * @param languageId A VS Code language ID.
+     *
+     * @returns Whether the language has a {@link LanguageSpec}.
+     */
+    supports(languageId) {
+        return Object.hasOwn(compiler_1.LANGUAGES, languageId);
+    }
+    /**
+     * Lists the regexes in source text, in order.
+     *
+     * @param source The source text.
+     * @param languageId The VS Code language ID of the source.
+     *
+     * @returns The regexes found; none for unsupported languages or for sources longer than
+     *   {@link MAX_SCAN_LENGTH}. Patterns built at run time, such as strings with interpolations, are
+     *   skipped.
+     */
+    async find(source, languageId) {
+        if (source.length > exports.MAX_SCAN_LENGTH || !this.supports(languageId)) {
+            return [];
+        }
+        const spec = compiler_1.LANGUAGES[languageId];
+        const { parser, query } = await this.language(languageId, spec);
+        const includedRanges = spec.scriptBlocks ? scriptRanges(source) : undefined;
+        if (includedRanges?.length === 0) {
+            return [];
+        }
+        const tree = parser.parse(source, null, { includedRanges });
+        if (!tree) {
+            return [];
+        }
+        try {
+            const regexes = query
+                .matches(tree.rootNode)
+                .flatMap((match) => readMatch(match.captures, source, spec) ?? []);
+            // Patterns can match the same regex more than once; the first match at each offset wins, so
+            // the map is built from the end, where later entries replace earlier ones.
+            const byStart = new Map([...regexes].reverse().map((regex) => [regex.start, regex]));
+            return [...byStart.values()].sort((a, b) => a.start - b.start);
+        }
+        finally {
+            tree.delete();
+        }
+    }
+    /**
+     * Creates a parser and compiles the query for a language, once per language.
+     *
+     * @param languageId The VS Code language ID.
+     * @param spec The language's entry in {@link LANGUAGES}.
+     *
+     * @returns The parser and query.
+     */
+    language(languageId, spec) {
+        let loaded = this.languages.get(languageId);
+        if (!loaded) {
+            loaded = Promise.all([this.runtime(), this.grammar(spec.grammar)]).then(([treeSitter, language]) => {
+                const parser = new treeSitter.Parser();
+                parser.setLanguage(language);
+                return { parser, query: new treeSitter.Query(language, spec.query) };
+            });
+            // A cache: each language's parser and query are built once and shared by later calls.
+            // eslint-disable-next-line functional/immutable-data
+            this.languages.set(languageId, loaded);
+        }
+        return loaded;
+    }
+    /**
+     * Loads a grammar from the WASM directory, once per grammar.
+     *
+     * @param grammar The grammar name.
+     *
+     * @returns The grammar.
+     */
+    grammar(grammar) {
+        let loaded = this.grammars.get(grammar);
+        if (!loaded) {
+            loaded = this.runtime().then((treeSitter) => treeSitter.Language.load(joinPath(this.wasmDir, `tree-sitter-${grammar}.wasm`)));
+            // A cache: each grammar's WASM file is loaded once and shared by later calls.
+            // eslint-disable-next-line functional/immutable-data
+            this.grammars.set(grammar, loaded);
+        }
+        return loaded;
+    }
+    /**
+     * Loads the tree-sitter runtime, once per process.
+     *
+     * @returns The runtime's exports.
+     */
+    runtime() {
+        runtime ??= loadRuntime(this.wasmDir);
+        return runtime;
+    }
+}
+exports.RegexFinder = RegexFinder;
+/**
+ * Finds the regex that contains an offset.
+ *
+ * @param regexes Regexes from {@link RegexFinder.find}, in order.
+ * @param offset The offset to look up.
+ *
+ * @returns The regex, or undefined if the offset is not inside one.
+ */
+function findRegexAt(regexes, offset) {
+    return regexes.find((r) => offset >= r.start && offset < r.end);
+}
+/**
+ * Reads the pattern and flags from one query match.
+ *
+ * @param captures The match's captures.
+ * @param source The parsed source text.
+ * @param spec The language.
+ *
+ * @returns The regex, or undefined if its value is not known until run time.
+ */
+function readMatch(captures, source, spec) {
+    const node = (name) => captures.find((c) => c.name === name)?.node;
+    const literal = node("literal");
+    const delimited = node("pattern.delimited");
+    const patternString = node("pattern.string");
+    const flagsString = node("flags.string");
+    const patternNode = node("pattern");
+    let parts;
+    if (literal) {
+        parts = literalParts(literal, source);
+    }
+    else if (delimited) {
+        const value = stringValue(delimited, source);
+        parts = value === undefined ? undefined : (0, strings_1.splitDelimitedPattern)(value);
+    }
+    else if (patternString) {
+        const pattern = stringValue(patternString, source);
+        const flags = flagsString ? stringValue(flagsString, source) : "";
+        parts = pattern === undefined || flags === undefined ? undefined : { pattern, flags };
+    }
+    else if (patternNode) {
+        parts = { pattern: patternNode.text, flags: node("flags")?.text ?? "" };
+    }
+    const range = node("regex") ?? literal ?? delimited ?? patternString ?? patternNode;
+    if (!parts || !range) {
+        return undefined;
+    }
+    return {
+        pattern: parts.pattern,
+        flags: (0, strings_1.translateFlags)(parts.flags, spec.flags ?? {}),
+        start: range.startIndex,
+        end: range.endIndex,
+    };
+}
+/**
+ * Splits a regex literal into the source text between its delimiters and the flags after them.
+ *
+ * @param node A `@literal` capture.
+ * @param source The parsed source text.
+ *
+ * @returns The parts, or undefined if the literal interpolates code.
+ */
+function literalParts(node, source) {
+    const open = node.firstChild;
+    const close = node.lastChild;
+    if (!open || !close || open.startIndex === close.startIndex || node.namedChildren.some(isCode)) {
+        return undefined;
+    }
+    return {
+        pattern: source.slice(open.endIndex, close.startIndex),
+        flags: close.text.slice(1),
+    };
+}
+/**
+ * Computes the value of a string literal, decoding its escapes.
+ *
+ * @param node A string literal node.
+ * @param source The parsed source text.
+ *
+ * @returns The value, or undefined if the string interpolates code or has an escape that cannot be
+ *   decoded.
+ */
+function stringValue(node, source) {
+    if (node.childCount === 0) {
+        return verbatimValue(node.text);
+    }
+    let value = "";
+    for (const child of node.children) {
+        if (!child || !child.isNamed || DELIMITER_TYPE.test(child.type)) {
+            continue;
+        }
+        const piece = child.type === "escape_sequence"
+            ? (0, strings_1.decodeEscape)(child.text)
+            : CONTENT_TYPE.test(child.type)
+                ? contentValue(child, source)
+                : undefined;
+        if (piece === undefined) {
+            return undefined;
+        }
+        value += piece;
+    }
+    return value;
+}
+/**
+ * Computes the value of a string content node, some of which, as in Python, contain the escapes.
+ *
+ * @param node The content node.
+ * @param source The parsed source text.
+ *
+ * @returns The value, or undefined if an escape cannot be decoded.
+ */
+function contentValue(node, source) {
+    let value = "";
+    let offset = node.startIndex;
+    for (const escape of node.descendantsOfType("escape_sequence")) {
+        const decoded = escape ? (0, strings_1.decodeEscape)(escape.text) : undefined;
+        if (!escape || decoded === undefined) {
+            return undefined;
+        }
+        value += source.slice(offset, escape.startIndex) + decoded;
+        offset = escape.endIndex;
+    }
+    return value + source.slice(offset, node.endIndex);
+}
+/**
+ * Computes the value of a string literal that the grammar does not split into parts, such as C#'s
+ * `@"..."`, where a doubled quote stands for one quote.
+ *
+ * @param text The literal's source text.
+ *
+ * @returns The value, or undefined if the text is not a quoted string.
+ */
+function verbatimValue(text) {
+    const quoted = /^[^"'`]*(["'`])([\s\S]*)\1$/.exec(text);
+    return quoted ? quoted[2].replaceAll(quoted[1] + quoted[1], quoted[1]) : undefined;
+}
+/**
+ * Checks whether a child of a literal is code, such as an interpolation, rather than text.
+ *
+ * @param node A named child.
+ *
+ * @returns Whether the node is neither text, an escape, nor a delimiter.
+ */
+function isCode(node) {
+    return (!!node &&
+        node.type !== "escape_sequence" &&
+        !CONTENT_TYPE.test(node.type) &&
+        !DELIMITER_TYPE.test(node.type));
+}
+/**
+ * Lists the `<script>` blocks of a single-file component as parser ranges.
+ *
+ * @param source The component's source text.
+ *
+ * @returns One range per block, covering the code between the tags.
+ */
+function scriptRanges(source) {
+    return [...source.matchAll(SCRIPT_BLOCK)].map((block) => {
+        const startIndex = (block.index ?? 0) + block[0].indexOf(">") + 1;
+        const endIndex = startIndex + block[1].length;
+        return {
+            startIndex,
+            endIndex,
+            startPosition: pointAt(source, startIndex),
+            endPosition: pointAt(source, endIndex),
+        };
+    });
+}
+/**
+ * Converts an offset to a row and column.
+ *
+ * @param source The text.
+ * @param offset The offset.
+ *
+ * @returns The zero-based row and column.
+ */
+function pointAt(source, offset) {
+    const before = source.slice(0, offset);
+    const lineStart = before.lastIndexOf("\n") + 1;
+    return { row: before.split("\n").length - 1, column: offset - lineStart };
+}
+//# sourceMappingURL=locator.js.map

package/dist/cjs/matches.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Runs a regex over text and reports each match with the lines it covers, and words the outcome for
+ * display. The text is matched either as one string or, with `entries`, one line at a time.
+ */
+import type { RegexSource } from "./explainer";
+/** Text to match against a regex. `g` is added to the flags if missing, so every match is found. */
+export interface MatchRequest extends RegexSource {
+    /** The text to search. */
+    readonly text: string;
+    /** The most matches to return. */
+    readonly limit: number;
+    /**
+     * Whether each line of the text is a separate entry, matched on its own, so that `^` and `$`
+     * match at its ends and no match spans lines. A line break at the end of the text does not start
+     * another entry.
+     */
+    readonly entries?: boolean;
+}
+/** One match in the text. */
+export interface FoundMatch {
+    /** Offset of the first matched character, in UTF-16 code units. */
+    readonly start: number;
+    /** Offset just past the last matched character. */
+    readonly end: number;
+    /** The matched text. */
+    readonly text: string;
+    /** The 1-based line the match starts on. */
+    readonly startLine: number;
+    /** The 1-based line the match ends on; equal to `startLine` for single-line matches. */
+    readonly endLine: number;
+    /** The numbered capture groups' values, starting with group 1; undefined if not matched. */
+    readonly groups: readonly (string | undefined)[];
+    /** The named capture groups' values, by name. */
+    readonly named: Readonly<Record<string, string | undefined>>;
+}
+/** A line of the text matched on its own, in a request with `entries`. */
+export interface MatchEntry {
+    /** The 1-based line. */
+    readonly line: number;
+    /** Offset of the line's first character. */
+    readonly start: number;
+    /** Offset just past the line's last character, before its line break. */
+    readonly end: number;
+    /** The line, without its line break. */
+    readonly text: string;
+}
+/** The outcome of a {@link MatchRequest}. */
+export interface MatchResponse {
+    /** The matches, in order. */
+    readonly matches: readonly FoundMatch[];
+    /** Whether matching stopped at the limit. */
+    readonly truncated: boolean;
+    /**
+     * The entries matched, for a request with `entries`. When matching stopped at the limit, the
+     * entries after the one holding the last match are left out.
+     */
+    readonly entries?: readonly MatchEntry[];
+    /** Why the regex could not run, such as a syntax error. */
+    readonly error?: string;
+    /** Whether matching was stopped because it took too long. */
+    readonly timedOut?: boolean;
+}
+/** A capture group of a match, ready to display. */
+export interface MatchGroupModel {
+    /** The group's label: `$1`, `$2`, and so on for numbered groups, or the group's name. */
+    readonly name: string;
+    /** The group's text, or "(no match)" when it did not take part in the match. */
+    readonly value: string;
+    /** Whether the group matched. */
+    readonly matched: boolean;
+}
+/** A match, ready to display. */
+export interface MatchModel {
+    /** Offset of the first matched character, in UTF-16 code units. */
+    readonly start: number;
+    /** Offset just past the last matched character. */
+    readonly end: number;
+    /** The lines the match covers, such as `L3` or `L1–3`. */
+    readonly lines: string;
+    /** The matched text, or "(empty)" for an empty match. */
+    readonly text: string;
+    /** The numbered groups, then the named ones. */
+    readonly groups: readonly MatchGroupModel[];
+}
+/** An entry and its matches, ready to display. */
+export interface EntryModel {
+    /** The entry's line, such as `L3`. */
+    readonly line: string;
+    /** Offset of the entry's first character. */
+    readonly start: number;
+    /** Offset just past the entry's last character. */
+    readonly end: number;
+    /** The entry's text, or "(empty)" for an empty line. */
+    readonly text: string;
+    /** Whether the regex matched the entry. */
+    readonly matched: boolean;
+    /** The matches in the entry, in order. */
+    readonly matches: readonly MatchModel[];
+}
+/** Everything a view of a {@link MatchResponse} shows. */
+export interface MatchesModel {
+    /**
+     * One sentence on the outcome, such as "2 matches.", "1 of 3 entries matches.", or why the regex
+     * could not run.
+     */
+    readonly summary: string;
+    /** Whether the regex could not run to completion, so the summary reports a problem. */
+    readonly problem: boolean;
+    /** The matches, in order. */
+    readonly matches: readonly MatchModel[];
+    /** Each entry with its matches, when the request had `entries`. */
+    readonly entries?: readonly EntryModel[];
+}
+/**
+ * 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.
+ */
+export declare function findMatches(request: MatchRequest): MatchResponse;
+/**
+ * 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.
+ */
+export declare function describeMatches(response: MatchResponse): MatchesModel;