regex-explain 0.0.0 → 1.0.0

package/dist/esm/index.mjs

@@ -0,0 +1,1207 @@
+// src/explainer.ts
+import { RegExpParser, RegExpSyntaxError } from "@eslint-community/regexpp";
+import {
+  getCapturingGroupNumber,
+  getLengthRange,
+  toUnicodeSet
+} from "regexp-ast-analysis";
+import { analyse } from "scslre";
+
+// src/text.ts
+var NAMED_CODE_POINTS = {
+  0: "a null character",
+  8: "a backspace",
+  9: "a tab",
+  10: "a line feed (newline)",
+  11: "a vertical tab",
+  12: "a form feed",
+  13: "a carriage return",
+  32: "a space",
+  160: "a non-breaking space",
+  8232: "a line separator",
+  8233: "a paragraph separator",
+  65279: "a byte order mark"
+};
+function code(text) {
+  const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((m) => m.length));
+  const fence = "`".repeat(longest + 1);
+  const pad = text.startsWith("`") || text.endsWith("`") || /^ .* $/.test(text) ? " " : "";
+  return `${fence}${pad}${text}${pad}${fence}`;
+}
+function describeCodePoint(cp) {
+  const named = NAMED_CODE_POINTS[cp];
+  if (named) {
+    return named;
+  }
+  const ch = String.fromCodePoint(cp);
+  if (/^[\p{C}\p{Z}]$/u.test(ch)) {
+    return `the character U+${cp.toString(16).toUpperCase().padStart(4, "0")}`;
+  }
+  return `the character ${code(ch)}`;
+}
+function lowerFirst(text) {
+  return text.charAt(0).toLowerCase() + text.slice(1);
+}
+function withArticle(noun) {
+  return `${/^[aeiou]/i.test(noun) ? "an" : "a"} ${noun}`;
+}
+function splitCodeSpans(text) {
+  const spans = [...text.matchAll(/(?<!`)(`+)(?!`)([\s\S]+?)(?<!`)\1(?!`)/g)];
+  const plainStarts = [0, ...spans.map((span) => span.index + span[0].length)];
+  const parts = spans.flatMap((span, i) => {
+    const content = span[2];
+    const padded = content.length > 2 && content.startsWith(" ") && content.endsWith(" ");
+    return [
+      ...plainPart(text.slice(plainStarts[i], span.index)),
+      { text: padded ? content.slice(1, -1) : content, code: true }
+    ];
+  });
+  return [...parts, ...plainPart(text.slice(plainStarts[spans.length]))];
+}
+function plainPart(text) {
+  return text === "" ? [] : [{ text, code: false }];
+}
+
+// src/explainer.ts
+function isRegexSource(value) {
+  const candidate = value;
+  return typeof candidate?.pattern === "string" && typeof candidate.flags === "string";
+}
+var FLAG_INFO = {
+  d: { name: "hasIndices", description: "Record start and end indices for each capture group." },
+  g: { name: "global", description: "Find all matches instead of stopping after the first." },
+  i: { name: "ignoreCase", description: "Ignore case: letters match both upper and lower case." },
+  m: {
+    name: "multiline",
+    description: `${code("^")} and ${code("$")} match at the start and end of each line, not just the whole input.`
+  },
+  s: { name: "dotAll", description: `${code(".")} also matches line terminators.` },
+  u: {
+    name: "unicode",
+    description: "Treat the pattern as a sequence of Unicode code points and use strict syntax."
+  },
+  v: {
+    name: "unicodeSets",
+    description: `Unicode mode with set operations (${code("--")}, ${code("&&")}), nested classes, and string properties.`
+  },
+  y: { name: "sticky", description: `Match only at the position given by ${code("lastIndex")}.` }
+};
+var UNICODE_PROPERTY_NAMES = {
+  L: "letter",
+  Letter: "letter",
+  Lu: "uppercase letter",
+  Uppercase_Letter: "uppercase letter",
+  Ll: "lowercase letter",
+  Lowercase_Letter: "lowercase letter",
+  Lt: "titlecase letter",
+  Lm: "modifier letter",
+  Lo: "other letter",
+  M: "mark",
+  Mark: "mark",
+  N: "number",
+  Number: "number",
+  Nd: "decimal digit",
+  Decimal_Number: "decimal digit",
+  P: "punctuation character",
+  Punctuation: "punctuation character",
+  S: "symbol",
+  Symbol: "symbol",
+  Sc: "currency symbol",
+  Currency_Symbol: "currency symbol",
+  Z: "separator",
+  Separator: "separator",
+  Zs: "space separator",
+  Space_Separator: "space separator",
+  C: "control or other character",
+  Other: "control or other character",
+  Cc: "control character",
+  Control: "control character",
+  Alphabetic: "alphabetic character",
+  Alpha: "alphabetic character",
+  White_Space: "whitespace character",
+  space: "whitespace character",
+  Emoji: "emoji character",
+  ASCII: "ASCII character",
+  Any: "character"
+};
+var SCRIPT_KEYS = /* @__PURE__ */ new Set(["Script", "sc", "Script_Extensions", "scx"]);
+function explainRegex(pattern, flags = "", options = {}) {
+  const parser = new RegExpParser({ ecmaVersion: 2025 });
+  let flagsAst;
+  let patternAst;
+  try {
+    flagsAst = parser.parseFlags(flags);
+    patternAst = parser.parsePattern(pattern, 0, pattern.length, {
+      unicode: flagsAst.unicode,
+      unicodeSets: flagsAst.unicodeSets
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      pattern,
+      flags,
+      message: error instanceof Error ? error.message : String(error),
+      index: error instanceof RegExpSyntaxError ? error.index : void 0
+    };
+  }
+  const ctx = { flags: flagsAst };
+  const length = getLengthRange(patternAst.alternatives, flagsAst);
+  return {
+    ok: true,
+    pattern,
+    flags,
+    nodes: explainAlternatives(patternAst.alternatives, ctx),
+    flagExplanations: [...flags].map((flag) => ({ flag, ...FLAG_INFO[flag] })),
+    length: { min: length.min, max: length.max },
+    warnings: options.checkBacktracking === false ? [] : findBacktracking(patternAst, flagsAst, pattern),
+    multiline: flagsAst.multiline || enablesMultiline(patternAst)
+  };
+}
+function enablesMultiline(node) {
+  if (node.type === "Group" && node.modifiers?.add.multiline) {
+    return true;
+  }
+  const children = "alternatives" in node ? node.alternatives : node.type === "Alternative" ? node.elements : node.type === "Quantifier" ? [node.element] : [];
+  return children.some(enablesMultiline);
+}
+function parseRegexInput(text) {
+  const literal2 = /^\/((?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\\[])+)\/([a-z]*)$/s.exec(text.trim());
+  return literal2 ? { pattern: literal2[1], flags: literal2[2] } : { pattern: text, flags: "" };
+}
+function findBacktracking(pattern, flags, source) {
+  const { reports } = analyse({ pattern, flags }, { reportTypes: { Move: false } });
+  return reports.map((report) => toWarning(report, source));
+}
+function toWarning(report, source) {
+  const quant = report.type === "Trade" ? report.startQuant : report.quant;
+  const cost = `so a failed match can take ${report.exponential ? "exponential" : "polynomial"} time`;
+  let description;
+  switch (report.type) {
+    case "Trade":
+      description = `${code(report.startQuant.raw)} and ${code(report.endQuant.raw)} can match the same text, ${cost}`;
+      break;
+    case "Self":
+      description = `${code(report.quant.raw)} is repeated by ${code(report.parentQuant.raw)} and can match the same text in many ways, ${cost}`;
+      break;
+    case "Move":
+      description = `${code(report.quant.raw)} is retried at every position of a failing input, ${cost}`;
+      break;
+  }
+  const fixed = report.fix();
+  return {
+    raw: source.slice(quant.start, quant.end),
+    start: quant.start,
+    end: quant.end,
+    exponential: report.exponential,
+    attackCharacter: report.character.pick,
+    description,
+    fix: fixed ? { pattern: fixed.source, flags: fixed.flags } : void 0
+  };
+}
+function make(span, description, children = []) {
+  return { raw: span.raw, start: span.start, end: span.end, description, children };
+}
+function prefixed(prefix, node) {
+  return { ...node, description: prefix + node.description };
+}
+function explainAlternatives(alternatives, ctx) {
+  if (alternatives.length === 1) {
+    return explainSequence(alternatives[0], ctx);
+  }
+  const options = alternatives.map((alt, i) => {
+    const steps = explainSequence(alt, ctx);
+    if (steps.length === 1) {
+      return make(alt, `Option ${i + 1}: ${lowerFirst(steps[0].description)}`, [
+        ...steps[0].children
+      ]);
+    }
+    return make(alt, `Option ${i + 1}:`, steps);
+  });
+  const span = {
+    raw: alternatives.map((a) => a.raw).join("|"),
+    start: alternatives[0].start,
+    end: alternatives[alternatives.length - 1].end
+  };
+  return [make(span, `Match one of ${alternatives.length} alternatives:`, options)];
+}
+function explainSequence(alt, ctx) {
+  if (alt.elements.length === 0) {
+    return [make(alt, "Match the empty string")];
+  }
+  const steps = alt.elements.reduce((acc, el) => {
+    const last = acc[acc.length - 1];
+    if (el.type !== "Character") {
+      return [...acc, el];
+    }
+    return Array.isArray(last) ? [...acc.slice(0, -1), [...last, el]] : [...acc, [el]];
+  }, []);
+  return steps.map(
+    (step) => Array.isArray(step) ? explainCharacterRun(step, ctx) : explainElement(step, ctx)
+  );
+}
+function caseNote(elements, ctx) {
+  if (!ctx.flags.ignoreCase) {
+    return "";
+  }
+  const sensitive = { ...ctx.flags, ignoreCase: false };
+  const changes = elements.some(
+    (el) => toUnicodeSet(el, ctx.flags).chars.size !== toUnicodeSet(el, sensitive).chars.size
+  );
+  return changes ? " (case-insensitive)" : "";
+}
+function explainCharacterRun(run, ctx) {
+  const note = caseNote(run, ctx);
+  if (run.length === 1) {
+    return make(run[0], `Match ${describeCodePoint(run[0].value)}${note}`);
+  }
+  const text = String.fromCodePoint(...run.map((c) => c.value));
+  const span = {
+    raw: run.map((c) => c.raw).join(""),
+    start: run[0].start,
+    end: run[run.length - 1].end
+  };
+  if (/^[^\p{C}\s](?:[^\p{C}]*[^\p{C}\s])?$/u.test(text)) {
+    return make(span, `Match the text ${code(text)}${note}`);
+  }
+  const names = run.map((c) => describeCodePoint(c.value)).join(", ");
+  return make(span, `Match the sequence ${names}${note}`);
+}
+function explainElement(el, ctx) {
+  switch (el.type) {
+    case "Assertion":
+      return explainAssertion(el, ctx);
+    case "Quantifier":
+      return explainQuantifier(el, ctx);
+    default:
+      return explainQuantifiable(el, ctx);
+  }
+}
+function explainQuantifiable(el, ctx) {
+  switch (el.type) {
+    case "Character":
+      return explainCharacterRun([el], ctx);
+    case "CapturingGroup": {
+      const n = getCapturingGroupNumber(el);
+      const label = el.name ? `Capture group #${n} named ${code(el.name)}` : `Capture group #${n}`;
+      return make(el, `${label}:`, explainAlternatives(el.alternatives, ctx));
+    }
+    case "Group": {
+      if (!el.modifiers) {
+        return make(el, "Group (non-capturing):", explainAlternatives(el.alternatives, ctx));
+      }
+      const inner = applyModifiers(el.modifiers, ctx);
+      const label = `Group with modifiers (${describeModifiers(el.modifiers)}):`;
+      return make(el, label, explainAlternatives(el.alternatives, inner));
+    }
+    case "Backreference":
+      return make(el, `Match the same text last captured by ${describeBackrefTarget(el)}`);
+    case "Assertion":
+      return explainAssertion(el, ctx);
+    case "CharacterClass":
+    case "ExpressionCharacterClass":
+      return explainClass(el, ctx, true);
+    case "CharacterSet":
+      return make(el, `Match ${describeCharacterSet(el, ctx)}${caseNote([el], ctx)}`);
+  }
+}
+function explainQuantifier(q, ctx) {
+  const inner = explainQuantifiable(q.element, ctx);
+  const greed = q.min === q.max ? "" : q.greedy ? " (as many as possible)" : " (as few as possible)";
+  const repetition = `${describeCount(q.min, q.max)}${greed}`;
+  if (inner.children.length === 0) {
+    return make(q, `${inner.description}, ${repetition}`);
+  }
+  const heading = inner.description.replace(/:$/, "");
+  return make(q, `${heading}, ${repetition}:`, [...inner.children]);
+}
+function describeCount(min, max) {
+  if (min === 0 && max === 1) {
+    return "optionally";
+  }
+  if (max === Infinity) {
+    return min === 0 ? "zero or more times" : min === 1 ? "one or more times" : `${min} or more times`;
+  }
+  if (min === max) {
+    return min === 1 ? "exactly once" : `exactly ${min} times`;
+  }
+  return `between ${min} and ${max} times`;
+}
+function explainAssertion(a, ctx) {
+  const where = ctx.flags.multiline ? "a line" : "the input";
+  switch (a.kind) {
+    case "start":
+      return make(a, `Assert position is at the start of ${where}`);
+    case "end":
+      return make(a, `Assert position is at the end of ${where}`);
+    case "word":
+      return make(a, `Assert position is ${a.negate ? "not " : ""}at a word boundary`);
+    case "lookahead":
+      return make(
+        a,
+        a.negate ? "Negative lookahead: assert that what follows does not match:" : "Lookahead: assert that what follows matches:",
+        explainAlternatives(a.alternatives, ctx)
+      );
+    case "lookbehind":
+      return make(
+        a,
+        a.negate ? "Negative lookbehind: assert that what precedes does not match:" : "Lookbehind: assert that what precedes matches:",
+        explainAlternatives(a.alternatives, ctx)
+      );
+  }
+}
+function describeBackrefTarget(ref) {
+  if (ref.ambiguous) {
+    const numbers = ref.resolved.map((g) => `#${getCapturingGroupNumber(g)}`).join(" or ");
+    return `the group named ${code(ref.ref)} (${numbers})`;
+  }
+  const n = getCapturingGroupNumber(ref.resolved);
+  return typeof ref.ref === "string" ? `group #${n} (${code(ref.ref)})` : `group #${n}`;
+}
+function applyModifiers(m, ctx) {
+  const flag = (name) => m.remove?.[name] ? false : m.add?.[name] ? true : ctx.flags[name];
+  return {
+    flags: {
+      ...ctx.flags,
+      ignoreCase: flag("ignoreCase"),
+      multiline: flag("multiline"),
+      dotAll: flag("dotAll")
+    }
+  };
+}
+function describeModifiers(m) {
+  const names = (f) => f ? [
+    f.ignoreCase ? "ignore case" : "",
+    f.multiline ? "multiline" : "",
+    f.dotAll ? "dotAll" : ""
+  ].filter(Boolean) : [];
+  const on = names(m.add);
+  const off = names(m.remove);
+  return [on.length ? `enable ${on.join(", ")}` : "", off.length ? `disable ${off.join(", ")}` : ""].filter(Boolean).join("; ");
+}
+function explainClass(cls, ctx, topLevel) {
+  const verb = topLevel ? "Match " : "";
+  const note = topLevel ? caseNote([cls], ctx) : "";
+  if (cls.type === "ExpressionCharacterClass") {
+    const what2 = cls.negate ? "any character not in" : "a character in";
+    return make(cls, `${verb}${what2} the set${note}:`, [explainClassElement(cls.expression, ctx)]);
+  }
+  if (cls.elements.length === 0) {
+    return make(
+      cls,
+      cls.negate ? `${verb}any character at all` : `${verb}nothing (an empty class never matches)`
+    );
+  }
+  const what = cls.negate ? "any character except" : "one of";
+  return make(
+    cls,
+    `${verb}${what}${note}:`,
+    cls.elements.map((e) => explainClassElement(e, ctx))
+  );
+}
+function explainClassElement(el, ctx) {
+  switch (el.type) {
+    case "Character":
+      return make(el, describeCodePoint(el.value));
+    case "CharacterClassRange":
+      return make(
+        el,
+        `a character from ${describeCodePoint(el.min.value)} to ${describeCodePoint(el.max.value)}`
+      );
+    case "CharacterSet":
+      return make(el, describeCharacterSet(el, ctx));
+    case "CharacterClass":
+    case "ExpressionCharacterClass":
+      return explainClass(el, ctx, false);
+    case "ClassStringDisjunction": {
+      const strings = el.alternatives.map(
+        (a) => a.elements.length ? code(String.fromCodePoint(...a.elements.map((c) => c.value))) : "the empty string"
+      );
+      return make(
+        el,
+        strings.length === 1 ? `the string ${strings[0]}` : `one of the strings ${strings.join(", ")}`
+      );
+    }
+    case "ClassIntersection":
+      return make(
+        el,
+        "characters that are in all of:",
+        flattenOperands(el).map((o) => explainClassElement(o, ctx))
+      );
+    case "ClassSubtraction": {
+      const [first, ...rest] = flattenOperands(el);
+      return make(el, "characters that are:", [
+        prefixed("in ", explainClassElement(first, ctx)),
+        ...rest.map((o) => prefixed("but not ", explainClassElement(o, ctx)))
+      ]);
+    }
+  }
+}
+function flattenOperands(node) {
+  const left = node.left.type === node.type ? flattenOperands(node.left) : [node.left];
+  return [...left, node.right];
+}
+function describeCharacterSet(set, ctx) {
+  switch (set.kind) {
+    case "any":
+      return ctx.flags.dotAll ? "any character" : "any character except a line break";
+    case "digit":
+      return set.negate ? "any character that is not a digit" : "a digit (0-9)";
+    case "space":
+      return set.negate ? "any character that is not whitespace" : "a whitespace character (space, tab, line break, etc.)";
+    case "word":
+      return set.negate ? "any character that is not a word character" : "a word character (letter, digit, or underscore)";
+    case "property":
+      return describeProperty(set);
+  }
+}
+function describeProperty(set) {
+  const raw = set.value ? `${set.key}=${set.value}` : set.key;
+  if (set.strings) {
+    return `a string with Unicode property ${code(raw)}`;
+  }
+  const name = set.value ?? set.key;
+  const friendly = set.value && SCRIPT_KEYS.has(set.key) ? `character in the ${set.value.replace(/_/g, " ")} script` : UNICODE_PROPERTY_NAMES[name] ?? `character with Unicode property ${code(raw)}`;
+  return set.negate ? `any character that is not ${withArticle(friendly)}` : withArticle(friendly);
+}
+
+// src/compiler.ts
+var JS_STRING = "[(string) (template_string)]";
+var JS_QUERY = `
+(regex pattern: (regex_pattern) @pattern flags: (regex_flags)? @flags) @regex
+(new_expression
+  constructor: (identifier) @_constructor
+  arguments: (arguments . ${JS_STRING} @pattern.string . ${JS_STRING}? @flags.string)
+  (#eq? @_constructor "RegExp"))
+(call_expression
+  function: (identifier) @_constructor
+  arguments: (arguments . ${JS_STRING} @pattern.string . ${JS_STRING}? @flags.string)
+  (#eq? @_constructor "RegExp"))
+`;
+var CS_STRING = "[(string_literal) (verbatim_string_literal) (raw_string_literal)]";
+var RUBY_FLAGS = { m: "s", o: "", n: "", e: "", s: "", u: "" };
+var PHP_FLAGS = { u: "", S: "" };
+var LANGUAGES = {
+  javascript: { grammar: "javascript", query: JS_QUERY },
+  javascriptreact: { grammar: "javascript", query: JS_QUERY },
+  typescript: { grammar: "typescript", query: JS_QUERY },
+  typescriptreact: { grammar: "tsx", query: JS_QUERY },
+  vue: { grammar: "typescript", query: JS_QUERY, scriptBlocks: true },
+  svelte: { grammar: "typescript", query: JS_QUERY, scriptBlocks: true },
+  python: {
+    grammar: "python",
+    query: `
+(call
+  function: (attribute object: (identifier) @_module attribute: (identifier) @_function)
+  arguments: (argument_list . (string) @pattern.string)
+  (#any-of? @_module "re" "regex")
+  (#any-of? @_function
+    "compile" "search" "match" "fullmatch" "split" "findall" "finditer" "sub" "subn"))
+`
+  },
+  go: {
+    grammar: "go",
+    query: `
+(call_expression
+  function: (selector_expression operand: (identifier) @_package field: (field_identifier) @_function)
+  arguments: (argument_list
+    . [(raw_string_literal) (interpreted_string_literal)] @pattern.string)
+  (#eq? @_package "regexp")
+  (#any-of? @_function
+    "Compile" "CompilePOSIX" "MustCompile" "MustCompilePOSIX" "Match" "MatchReader" "MatchString"))
+`
+  },
+  rust: {
+    grammar: "rust",
+    query: `
+(call_expression
+  function: (scoped_identifier path: (_) @_type name: (identifier) @_function)
+  arguments: (arguments . [(string_literal) (raw_string_literal)] @pattern.string)
+  (#match? @_type "(^|::)(Regex|RegexBuilder)$")
+  (#eq? @_function "new"))
+`
+  },
+  java: {
+    // Text blocks ("""...""") strip indentation, which the decoder does not model.
+    grammar: "java",
+    query: `
+(method_invocation
+  object: (identifier) @_class
+  name: (identifier) @_method
+  arguments: (argument_list . (string_literal) @pattern.string)
+  (#eq? @_class "Pattern")
+  (#eq? @_method "compile")
+  (#not-match? @pattern.string "^\\"\\"\\""))
+(method_invocation
+  name: (identifier) @_method
+  arguments: (argument_list . (string_literal) @pattern.string)
+  (#any-of? @_method "matches" "split")
+  (#not-match? @pattern.string "^\\"\\"\\""))
+(method_invocation
+  name: (identifier) @_method
+  arguments: (argument_list . (string_literal) @pattern.string . (_))
+  (#any-of? @_method "replaceAll" "replaceFirst")
+  (#not-match? @pattern.string "^\\"\\"\\""))
+`
+  },
+  csharp: {
+    // Multi-line raw strings strip indentation, which the decoder does not model.
+    grammar: "c-sharp",
+    query: `
+(object_creation_expression
+  type: (_) @_type
+  arguments: (argument_list . (argument ${CS_STRING} @pattern.string))
+  (#match? @_type "(^|\\\\.)Regex$")
+  (#not-match? @pattern.string "^\\"\\"\\"+\\\\s*\\n"))
+(invocation_expression
+  function: (member_access_expression expression: (_) @_type name: (identifier) @_method)
+  arguments: (argument_list . (argument) . (argument ${CS_STRING} @pattern.string))
+  (#match? @_type "(^|\\\\.)Regex$")
+  (#any-of? @_method "Count" "EnumerateMatches" "IsMatch" "Match" "Matches" "Replace" "Split")
+  (#not-match? @pattern.string "^\\"\\"\\"+\\\\s*\\n"))
+(attribute
+  name: (identifier) @_attribute
+  (attribute_argument_list . (attribute_argument ${CS_STRING} @pattern.string))
+  (#eq? @_attribute "GeneratedRegex")
+  (#not-match? @pattern.string "^\\"\\"\\"+\\\\s*\\n"))
+`
+  },
+  ruby: {
+    grammar: "ruby",
+    flags: RUBY_FLAGS,
+    query: `
+(regex) @literal
+(call
+  receiver: (constant) @_class
+  method: (identifier) @_method
+  arguments: (argument_list . (string) @pattern.string)
+  (#eq? @_class "Regexp")
+  (#any-of? @_method "new" "compile"))
+`
+  },
+  php: {
+    grammar: "php",
+    flags: PHP_FLAGS,
+    query: `
+(function_call_expression
+  function: (name) @_function
+  arguments: (arguments . (argument [(string) (encapsed_string)] @pattern.delimited))
+  (#match? @_function "^preg_(filter|grep|match|match_all|replace|replace_callback|split)$"))
+`
+  }
+};
+var SUPPORTED_LANGUAGE_IDS = Object.keys(LANGUAGES);
+var GRAMMARS = [
+  ...new Set(Object.values(LANGUAGES).map((spec) => spec.grammar))
+];
+
+// src/strings.ts
+var SIMPLE_ESCAPES = {
+  b: "\b",
+  f: "\f",
+  n: "\n",
+  r: "\r",
+  t: "	",
+  v: "\v"
+};
+var CLOSING_BRACKETS = {
+  "(": ")",
+  "[": "]",
+  "{": "}",
+  "<": ">"
+};
+function decodeEscape(escape) {
+  const body = escape.slice(1);
+  const hex = /^(?:x([\da-f]{1,2})|[xu]\{([\da-f]+)\}|u([\da-f]{4})|U([\da-f]{8}))$/i.exec(body);
+  if (hex) {
+    const codePoint = parseInt(hex.slice(1).find((group) => group !== void 0) ?? "", 16);
+    return codePoint <= 1114111 ? String.fromCodePoint(codePoint) : void 0;
+  }
+  if (/^[0-7]{1,3}$/.test(body)) {
+    return String.fromCodePoint(parseInt(body, 8));
+  }
+  if (/^\r?\n$/.test(body)) {
+    return "";
+  }
+  if ([...body].length !== 1 || body === "a" || body === "e") {
+    return void 0;
+  }
+  return SIMPLE_ESCAPES[body] ?? body;
+}
+function splitDelimitedPattern(value) {
+  const open = value.charAt(0);
+  if (open === "" || /[\p{L}\p{N}\s\\]/u.test(open)) {
+    return void 0;
+  }
+  const close = value.lastIndexOf(CLOSING_BRACKETS[open] ?? open);
+  if (close < 1) {
+    return void 0;
+  }
+  return { pattern: value.slice(1, close), flags: value.slice(close + 1) };
+}
+function translateFlags(flags, map) {
+  return [...flags].map((flag) => map[flag] ?? flag).join("");
+}
+
+// src/locator.ts
+var MAX_SCAN_LENGTH = 1e6;
+var CONTENT_TYPE = /(?:content|fragment)$/;
+var DELIMITER_TYPE = /(?:_start|_end)$/;
+var SCRIPT_BLOCK = /<script\b[^>]*>([\s\S]*?)<\/script\s*>/gi;
+var runtime;
+async function loadRuntime(wasmDir) {
+  const imported = await import("@vscode/tree-sitter-wasm");
+  const treeSitter = imported.default ?? imported;
+  await treeSitter.Parser.init({ locateFile: (file) => joinPath(wasmDir, file) });
+  return treeSitter;
+}
+function joinPath(dir, file) {
+  return `${dir.replace(/[\\/]+$/, "")}/${file}`;
+}
+var RegexFinder = class {
+  wasmDir;
+  grammars = /* @__PURE__ */ new Map();
+  languages = /* @__PURE__ */ 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(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 > MAX_SCAN_LENGTH || !this.supports(languageId)) {
+      return [];
+    }
+    const spec = LANGUAGES[languageId];
+    const { parser, query } = await this.language(languageId, spec);
+    const includedRanges = spec.scriptBlocks ? scriptRanges(source) : void 0;
+    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) ?? []);
+      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) };
+        }
+      );
+      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`))
+      );
+      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;
+  }
+};
+function findRegexAt(regexes, offset) {
+  return regexes.find((r) => offset >= r.start && offset < r.end);
+}
+function readMatch(captures, source, spec) {
+  const node = (name) => captures.find((c) => c.name === name)?.node;
+  const literal2 = node("literal");
+  const delimited = node("pattern.delimited");
+  const patternString = node("pattern.string");
+  const flagsString = node("flags.string");
+  const patternNode = node("pattern");
+  let parts;
+  if (literal2) {
+    parts = literalParts(literal2, source);
+  } else if (delimited) {
+    const value = stringValue(delimited, source);
+    parts = value === void 0 ? void 0 : splitDelimitedPattern(value);
+  } else if (patternString) {
+    const pattern = stringValue(patternString, source);
+    const flags = flagsString ? stringValue(flagsString, source) : "";
+    parts = pattern === void 0 || flags === void 0 ? void 0 : { pattern, flags };
+  } else if (patternNode) {
+    parts = { pattern: patternNode.text, flags: node("flags")?.text ?? "" };
+  }
+  const range = node("regex") ?? literal2 ?? delimited ?? patternString ?? patternNode;
+  if (!parts || !range) {
+    return void 0;
+  }
+  return {
+    pattern: parts.pattern,
+    flags: translateFlags(parts.flags, spec.flags ?? {}),
+    start: range.startIndex,
+    end: range.endIndex
+  };
+}
+function literalParts(node, source) {
+  const open = node.firstChild;
+  const close = node.lastChild;
+  if (!open || !close || open.startIndex === close.startIndex || node.namedChildren.some(isCode)) {
+    return void 0;
+  }
+  return {
+    pattern: source.slice(open.endIndex, close.startIndex),
+    flags: close.text.slice(1)
+  };
+}
+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" ? decodeEscape(child.text) : CONTENT_TYPE.test(child.type) ? contentValue(child, source) : void 0;
+    if (piece === void 0) {
+      return void 0;
+    }
+    value += piece;
+  }
+  return value;
+}
+function contentValue(node, source) {
+  let value = "";
+  let offset = node.startIndex;
+  for (const escape of node.descendantsOfType("escape_sequence")) {
+    const decoded = escape ? decodeEscape(escape.text) : void 0;
+    if (!escape || decoded === void 0) {
+      return void 0;
+    }
+    value += source.slice(offset, escape.startIndex) + decoded;
+    offset = escape.endIndex;
+  }
+  return value + source.slice(offset, node.endIndex);
+}
+function verbatimValue(text) {
+  const quoted = /^[^"'`]*(["'`])([\s\S]*)\1$/.exec(text);
+  return quoted ? quoted[2].replaceAll(quoted[1] + quoted[1], quoted[1]) : void 0;
+}
+function isCode(node) {
+  return !!node && node.type !== "escape_sequence" && !CONTENT_TYPE.test(node.type) && !DELIMITER_TYPE.test(node.type);
+}
+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)
+    };
+  });
+}
+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 };
+}
+
+// src/matches.ts
+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) {
+    const found2 = [...take(request.text.matchAll(regex), request.limit + 1)];
+    return {
+      matches: found2.slice(0, request.limit).map((match) => toFoundMatch(match, 0, lineStarts)),
+      truncated: found2.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)
+  };
+}
+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;
+}
+function* matchEntries(entries, regex) {
+  for (const entry of entries) {
+    for (const match of entry.text.matchAll(regex)) {
+      yield { entry, match };
+    }
+  }
+}
+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 }
+  };
+}
+function* take(items, count) {
+  if (count <= 0) {
+    return;
+  }
+  let taken = 0;
+  for (const item of items) {
+    yield item;
+    taken += 1;
+    if (taken === count) {
+      return;
+    }
+  }
+}
+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}.` : `${describeCount2(matches.length, "match", "matches")}${response.truncated ? ` (showing the first ${matches.length})` : ""}.`;
+  return entries ? { summary, problem, matches, entries } : { summary, problem, matches };
+}
+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"}`;
+}
+function describeCount2(count, one, many) {
+  return `${count === 0 ? "No" : count} ${count === 1 ? one : many}`;
+}
+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}\u2013${match.endLine}`,
+    text: match.text === "" ? "(empty)" : match.text,
+    groups: groups.map(([name, value]) => ({
+      name,
+      value: value ?? "(no match)",
+      matched: value !== void 0
+    }))
+  };
+}
+function findLineStarts(text) {
+  const lineBreaks = [...text.matchAll(/\r\n|\r|\n/g)];
+  return [0, ...lineBreaks.map((lineBreak) => lineBreak.index + lineBreak[0].length)];
+}
+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;
+}
+
+// src/extlinks.ts
+var REGEX101 = "https://regex101.com/";
+function regex101Url(source, testString = "") {
+  const params = [
+    ["regex", source.pattern],
+    ["flags", source.flags],
+    ["flavor", "javascript"],
+    ...testString === "" ? [] : [["testString", testString]]
+  ];
+  const query = params.map(([key, value]) => `${key}=${encodeURIComponent(value)}`).join("&");
+  return `${REGEX101}?${query}`;
+}
+
+// src/render.ts
+var ExplanationRenderer = class {
+  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 === void 0 ? void 0 : "^".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)}- ${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) => `| ${"&nbsp;&nbsp;".repeat(row.depth)}${escapePipes(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 === void 0 ? [] : [`  ${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", "", code(model.literal), ""] : [];
+    if (model.error) {
+      const caret = model.error.caret === void 0 ? [] : ["", "```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: ${code(warning.fix)}`] : [],
+      ""
+    ]);
+    const flags = model.flags.length === 0 ? [] : [
+      "",
+      "**Flags**",
+      "",
+      ...model.flags.map((f) => `- ${code(f.flag)} *${f.name}*: ${f.description}`)
+    ];
+    return [...title, ...warnings, ...steps(model.rows), "", `*${model.length}*`, ...flags].join(
+      "\n"
+    );
+  }
+};
+function literal(source) {
+  return `/${source.pattern}/${source.flags}`;
+}
+function described(description) {
+  return { description, parts: splitCodeSpans(description) };
+}
+function flatten(nodes, depth = 0) {
+  return nodes.flatMap((node) => [
+    { raw: node.raw, depth, ...described(node.description) },
+    ...flatten(node.children, depth + 1)
+  ]);
+}
+function plain(parts) {
+  return parts.map((part) => part.code ? `"${part.text}"` : part.text).join("");
+}
+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.`;
+}
+function escapePipes(text) {
+  return text.replaceAll("|", "\\|");
+}
+function escapeMarkdown(text) {
+  return text.replace(/[\\`*_{}[\]()#+\-.!|<>]/g, "\\$&");
+}
+export {
+  ExplanationRenderer,
+  GRAMMARS,
+  RegexFinder,
+  SUPPORTED_LANGUAGE_IDS,
+  describeCount,
+  describeMatches,
+  explainRegex,
+  findMatches,
+  findRegexAt,
+  isRegexSource,
+  parseRegexInput,
+  regex101Url
+};