regex-explain 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,277 @@
-# Temporary Holding Version
+# regex-explain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Explains ECMAScript regular expressions in plain English, as a tree of steps that follows the
+pattern's structure. It also reports how long a match can be and warns about catastrophic
+backtracking (ReDoS), suggesting an equivalent safe pattern when one exists. It can also find the
+regexes in source code in several languages, and run a regex over text to list its matches by line.
+
+```sh
+npm install regex-explain
+```
+
+The package ships CommonJS and ES module builds with TypeScript types, and needs Node.js 18 or
+later. Finding regexes in source code also needs the optional peer dependency
+[`@vscode/tree-sitter-wasm`](https://www.npmjs.com/package/@vscode/tree-sitter-wasm):
+
+```sh
+npm install @vscode/tree-sitter-wasm
+```
+
+## Usage
+
+```ts
+import { ExplanationRenderer, explainRegex } from "regex-explain";
+
+const result = explainRegex("^\\d{3}-\\d{4}$");
+console.log(new ExplanationRenderer(result).text());
+```
+
+```text
+^      Assert position is at the start of the input
+\d{3}  Match a digit (0-9), exactly 3 times
+-      Match the character "-"
+\d{4}  Match a digit (0-9), exactly 4 times
+$      Assert position is at the end of the input
+
+Matches exactly 8 characters.
+```
+
+`markdownTable()` renders the same result as Markdown:
+
+<!-- prettier-ignore -->
+```md
+| Code Point | Explanation |
+| ---------- | ----------- |
+| `^` | Assert position is at the start of the input |
+| `\d{3}` | Match a digit (0-9), exactly 3 times |
+| `-` | Match the character `-` |
+| `\d{4}` | Match a digit (0-9), exactly 4 times |
+| `$` | Assert position is at the end of the input |
+
+*Matches exactly 8 characters.*
+```
+
+Use `model()` or walk `result.nodes` to build your own output. Each node carries the source it
+explains and its offsets in the pattern, so you can highlight it:
+
+```json
+{
+  "raw": "\\d{3}",
+  "start": 1,
+  "end": 6,
+  "description": "Match a digit (0-9), exactly 3 times",
+  "children": []
+}
+```
+
+## API
+
+### `explainRegex(pattern, flags?, options?)`
+
+Explains `pattern` (without slashes, as passed to `new RegExp()`) compiled with `flags`. Returns an
+`ExplainResult`; it does not throw for invalid patterns.
+
+- `ExplainOptions`: `{ checkBacktracking?: boolean }`. The backtracking check is on by default.
+- `ExplainResult`: either a `RegexExplanation` (`ok: true`) or a `RegexExplanationError`
+  (`ok: false`, with `message` and, when known, the `index` of the error in the pattern).
+- `RegexExplanation` has:
+  - `nodes`: the top-level `ExplanationNode` steps. Each node has `raw`, `start`, `end`,
+    `description`, and `children`. Descriptions may contain Markdown code spans.
+  - `flagExplanations`: one `FlagExplanation` (`flag`, `name`, `description`) per flag.
+  - `length`: a `LengthSummary` with the `min` and `max` characters a match consumes. `max` is
+    `Infinity` when unbounded.
+  - `warnings`: `BacktrackingWarning` entries with the quantifier's `raw`, `start`, and `end`,
+    whether the backtracking is `exponential`, an `attackCharacter` that triggers it when repeated,
+    a `description`, and a `fix` (`pattern` and `flags`) when an equivalent safe pattern exists.
+  - `multiline`: whether `^` and `$` match at line breaks anywhere in the pattern, through the `m`
+    flag or a group such as `(?m:...)`. `explainRegex("(?m:^a)").multiline` is `true`.
+
+### `parseRegexInput(text)` and `isRegexSource(value)`
+
+`parseRegexInput` reads text a user typed or selected as a `RegexSource` (`{ pattern, flags }`, as
+`new RegExp()` takes them): a literal such as `/ab+c/gi`, optionally surrounded by whitespace, is
+split into its pattern and flags, and anything else is a bare pattern with no flags.
+`parseRegexInput("/ab+c/gi")` returns `{ pattern: "ab+c", flags: "gi" }` and
+`parseRegexInput("ab+c")` returns `{ pattern: "ab+c", flags: "" }`. It does not validate the
+pattern. Results, located regexes, and match requests all extend `RegexSource`. `isRegexSource` is a
+type guard that tells whether an untyped value, such as a command argument, has string `pattern` and
+`flags` properties.
+
+### `ExplanationRenderer`
+
+`new ExplanationRenderer(result)` renders an `ExplainResult` in several formats:
+
+- `markdownList(options?)`: a nested Markdown list, as in hovers.
+- `markdownTable(options?)`: a Markdown table with Code Point and Explanation columns. Nested steps
+  are indented with `&nbsp;`.
+- `text(options?)`: aligned plain text, with code spans shown in double quotes.
+- `model()`: everything a view shows, as an `ExplanationModel`, which the other formats render from:
+  the regex as a `literal` (`/pattern/flags`), the `error` (`ErrorModel`: `message`, `pattern`,
+  `index`, and a `caret` line such as `"   ^"` to print under the pattern) for an invalid pattern,
+  `warnings` (`WarningModel`: the `fix` as a literal), the steps as `rows` (`ExplanationRow`: `raw`
+  and nesting `depth`), the `length` sentence such as "Matches 2 to 4 characters.", `flags`
+  (`FlagModel`: `flag` and `name`), and whether the pattern is `multiline`. Each warning, row, and
+  flag has a `description`, which may contain Markdown code spans, and the same text as `parts`:
+  `TextPart`s with the `text` and whether it is `code`, so that HTML or other UIs render it without
+  a Markdown parser. For an invalid pattern, the model has only the `literal` and `error`; its lists
+  are empty.
+
+The Markdown and text formats put warnings first, then the steps, the match length, and the flags.
+Invalid patterns render the error with a caret under its position. `RenderOptions`:
+`{ title?: boolean }` starts the output with the whole regex (under a heading in Markdown).
+
+### `describeCount(min, max)`
+
+Words a repetition count ("one or more times"), for callers that build their own output.
+
+### `RegexFinder` and `findRegexAt(regexes, offset)`
+
+`new RegexFinder(wasmDir)` finds regexes in source code with tree-sitter: regex literals, and string
+literals passed to regex APIs such as `new RegExp()`, Python's `re.compile()`, or Java's
+`Pattern.compile()`. `wasmDir` is a directory or URL holding `tree-sitter.wasm` and the grammar
+files; in Node, pass the `wasm` directory of `@vscode/tree-sitter-wasm`. The runtime and each
+grammar load on first use. `find` returns no regexes for a source longer than 1,000,000 characters,
+since parsing generated or minified files on every change is slow.
+
+```ts
+import { createRequire } from "module";
+import * as path from "path";
+import { RegexFinder, findRegexAt } from "regex-explain";
+
+const require = createRequire(import.meta.url);
+const finder = new RegexFinder(path.dirname(require.resolve("@vscode/tree-sitter-wasm")));
+const source = 'import re\nDATE = re.compile(r"(\\d{4})-(\\d{2})")\n';
+const regexes = await finder.find(source, "python"); // in an ES module
+// [ { pattern: '(\\d{4})-(\\d{2})', flags: '', start: 28, end: 46 } ]
+findRegexAt(regexes, 30); // the same regex, which covers offset 30
+```
+
+- `find(source, languageId)` resolves to `LocatedRegex`es (`pattern`, `flags`, `start`, and `end`
+  offsets in UTF-16 code units), in order. String escapes are decoded, so `"\\d"` in source becomes
+  `\d`, and flags are translated to JavaScript, such as Ruby's `m` to `s`. Strings built at run
+  time, such as interpolations, are skipped. Unsupported languages give `[]`.
+- `supports(languageId)` tells whether a language is supported.
+- `SUPPORTED_LANGUAGE_IDS` lists the language IDs, which are VS Code's: `javascript`,
+  `javascriptreact`, `typescript`, `typescriptreact`, `vue`, `svelte` (both inside `<script>` blocks
+  only), `python`, `go`, `rust`, `java`, `csharp`, `ruby`, and `php`. The
+  [extension README](https://github.com/awalsh128/vscode-regex-explain/tree/main/packages/vscode-regex-explain#readme)
+  lists the calls recognized in each.
+- `GRAMMARS` lists the grammar names, for copying `tree-sitter-<grammar>.wasm` files when bundling.
+
+### `findMatches(request)`
+
+Runs a `MatchRequest` (`pattern`, `flags`, `text`, a match `limit`, and optionally `entries`) with
+JavaScript's `RegExp`, adding `g` if missing. It returns a `MatchResponse`: the `matches`, whether
+they were `truncated` at the limit, and an `error` if the pattern does not compile. `findMatches`
+never sets `timedOut`; it is there for callers that stop matching from outside, such as a worker
+with a time limit. Each `FoundMatch` has `start` and `end` offsets, the matched `text`, the 1-based
+`startLine` and `endLine`, the numbered `groups`, and the `named` groups.
+
+```ts
+findMatches({
+  pattern: "(\\d{4})-(\\d{2})",
+  flags: "",
+  text: "due 2024-05\nor 2025-01",
+  limit: 100,
+});
+// matches[0]: { start: 4, end: 11, text: "2024-05", startLine: 1, endLine: 1,
+//               groups: ["2024", "05"], named: {} }
+// matches[1]: { start: 15, end: 22, text: "2025-01", startLine: 2, endLine: 2, ... }
+```
+
+With `entries: true`, each line is a separate entry, matched on its own: `^` and `$` match at its
+ends and no match spans lines. A line break at the end of the text does not start another entry. The
+response then also has the `entries` (`MatchEntry`: the 1-based `line`, its `start` and `end`
+offsets without the line break, and its `text`). Match offsets and lines are still in the whole
+text. When matching stops at the limit, entries after the one holding the last match are left out.
+
+```ts
+findMatches({
+  pattern: "^\\d{4}-\\d{2}$",
+  flags: "",
+  text: "2024-05\nsoon\n2025-01",
+  limit: 100,
+  entries: true,
+});
+// matches: "2024-05" (start 0, startLine 1) and "2025-01" (start 13, startLine 3)
+// entries: [ { line: 1, start: 0, end: 7, text: "2024-05" },
+//            { line: 2, start: 8, end: 12, text: "soon" },
+//            { line: 3, start: 13, end: 20, text: "2025-01" } ]
+```
+
+A pattern that backtracks catastrophically can run for a very long time; run untrusted patterns
+where they can be stopped, such as a worker thread.
+
+### `describeMatches(response)`
+
+Words a `MatchResponse` for display, returning a `MatchesModel`: a one-sentence `summary` such as "2
+matches." or why the regex could not run, whether it reports a `problem` (an `error` or `timedOut`),
+and the `matches` (`MatchModel`). Each has the `start` and `end` offsets, `lines` such as `L1` or
+`L1–2`, the `text` ("(empty)" for an empty match), and `groups` (`MatchGroupModel`: the `name`,
+which is `$1`, `$2`, and so on or the group's name, the `value` ("(no match)" if the group did not
+take part), and whether it `matched`).
+
+For a response with `entries`, the summary counts entries instead, such as "2 of 3 entries match."
+or "No entries.", and the model also has the `entries` (`EntryModel`: the `line` such as `L2`, its
+`start` and `end`, its `text` ("(empty)" for an empty line), whether it `matched`, and its
+`matches`). For the entries example above, they are `L1` "2024-05" (matched, 1 match), `L2` "soon"
+(not matched), and `L3` "2025-01" (matched, 1 match).
+
+```ts
+const model = describeMatches(
+  findMatches({
+    pattern: "(?<year>\\d{4})-(\\d{2})",
+    flags: "",
+    text: "due 2024-05\nor 2025-01",
+    limit: 100,
+  })
+);
+// model.summary: "2 matches."   model.problem: false   model.matches[1].lines: "L2"
+// model.matches[0]: { start: 4, end: 11, lines: "L1", text: "2024-05",
+//   groups: [ { name: "$1", value: "2024", matched: true },
+//             { name: "$2", value: "05", matched: true },
+//             { name: "year", value: "2024", matched: true } ] }
+```
+
+### `regex101Url(source, testString?)`
+
+Builds a [regex101](https://regex101.com) link that opens a `RegexSource` in the JavaScript flavor,
+prefilled through the query string as the
+[regex101 FAQ](https://github.com/firasdib/Regex101/wiki/FAQ#how-to-prefill-the-fields-on-the-interface-via-url)
+describes. Values are percent-encoded, and the test string is left out when empty.
+
+```ts
+regex101Url({ pattern: "a+b", flags: "gi" });
+// "https://regex101.com/?regex=a%2Bb&flags=gi&flavor=javascript"
+```
+
+### Migrating from `renderMarkdown` and `renderText`
+
+`renderMarkdown(result, options)`, `renderText(result, options)`, and `describeLength(result)` were
+replaced by `new ExplanationRenderer(result).markdownList(options)`, `.text(options)`, and
+`.model().length`.
+
+## Semantics and limitations
+
+Patterns follow **JavaScript** semantics up to ES2025: named and duplicate named groups, lookbehind,
+Unicode property escapes, the `v` flag's set operations and `\q{...}`, and inline modifiers such as
+`(?i:...)`. Constructs specific to other engines are reported as syntax errors.
+
+The backtracking check omits patterns that are slow only because the engine retries them at every
+input position (for example `/a+b/`); those are too common to be useful as warnings. Fixes are not
+offered when a rewrite would change what a capture group holds.
+
+## How it works
+
+Parsing uses [`@eslint-community/regexpp`](https://github.com/eslint-community/regexpp), the parser
+behind ESLint's regex rules. Character sets, case folding, and match lengths come from
+[`regexp-ast-analysis`](https://github.com/RunDevelopment/regexp-ast-analysis), and backtracking
+analysis from [`scslre`](https://github.com/RunDevelopment/scslre), the libraries used by
+[`eslint-plugin-regexp`](https://github.com/ota-meshi/eslint-plugin-regexp). This package walks the
+parsed tree and words the results. Finding regexes in source code uses tree-sitter grammars from
+[`@vscode/tree-sitter-wasm`](https://github.com/microsoft/vscode-tree-sitter-wasm) with one query
+per language.
+
+## License
+
+Apache-2.0

package/dist/cjs/compiler.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where regexes appear in each supported language, as tree-sitter queries over the grammars in
+ * `@vscode/tree-sitter-wasm`. Adding a language means adding an entry here; the locator and the
+ * bundle script read this table.
+ *
+ * Capture names tell the locator how to read a match:
+ *
+ * - `@regex`: the whole regex expression. The hover covers it; without it, the hover covers the
+ *   pattern capture.
+ * - `@pattern` and `@flags`: nodes whose source text is the pattern or flags as written.
+ * - `@literal`: a regex literal whose first and last children are its delimiters, with the flags
+ *   after the closing delimiter, such as Ruby's `/a+/i` or `%r{a+}i`.
+ * - `@pattern.string` and `@flags.string`: string literals whose values are the pattern or flags.
+ * - `@pattern.delimited`: a string literal whose value is a delimited pattern such as `/a+/i`.
+ *
+ * Captures starting with `_` exist only for predicates.
+ */
+/** How to find regexes in one language. */
+export interface LanguageSpec {
+    /** The grammar, loaded from `tree-sitter-<grammar>.wasm`. */
+    readonly grammar: string;
+    /** A tree-sitter query using the capture names described in this module. */
+    readonly query: string;
+    /** Flags that mean something else in JavaScript, for `translateFlags`. */
+    readonly flags?: Readonly<Record<string, string>>;
+    /** Parse only the `<script>` blocks, for single-file component formats. */
+    readonly scriptBlocks?: boolean;
+}
+/** Supported languages, keyed by VS Code language ID. */
+export declare const LANGUAGES: Readonly<Record<string, LanguageSpec>>;
+/** VS Code language IDs that have a {@link LanguageSpec}, in table order. */
+export declare const SUPPORTED_LANGUAGE_IDS: readonly string[];
+/** Grammar names used by {@link LANGUAGES}, each once. */
+export declare const GRAMMARS: readonly string[];

package/dist/cjs/compiler.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Where regexes appear in each supported language, as tree-sitter queries over the grammars in
+ * `@vscode/tree-sitter-wasm`. Adding a language means adding an entry here; the locator and the
+ * bundle script read this table.
+ *
+ * Capture names tell the locator how to read a match:
+ *
+ * - `@regex`: the whole regex expression. The hover covers it; without it, the hover covers the
+ *   pattern capture.
+ * - `@pattern` and `@flags`: nodes whose source text is the pattern or flags as written.
+ * - `@literal`: a regex literal whose first and last children are its delimiters, with the flags
+ *   after the closing delimiter, such as Ruby's `/a+/i` or `%r{a+}i`.
+ * - `@pattern.string` and `@flags.string`: string literals whose values are the pattern or flags.
+ * - `@pattern.delimited`: a string literal whose value is a delimited pattern such as `/a+/i`.
+ *
+ * Captures starting with `_` exist only for predicates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GRAMMARS = exports.SUPPORTED_LANGUAGE_IDS = exports.LANGUAGES = void 0;
+/** JavaScript string literals, with or without template syntax. */
+const JS_STRING = "[(string) (template_string)]";
+/** Regex literals and `RegExp` constructor calls, shared by the JavaScript-family grammars. */
+const 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"))
+`;
+/** C# string literals that hold a pattern on one line. */
+const CS_STRING = "[(string_literal) (verbatim_string_literal) (raw_string_literal)]";
+/** Ruby flags: `m` is JavaScript's `s`; `o` and the encoding flags do not change what matches. */
+const RUBY_FLAGS = { m: "s", o: "", n: "", e: "", s: "", u: "" };
+/**
+ * PHP (PCRE) flags: `u` and `S` do not change what matches for patterns JavaScript can parse.
+ * Others, such as `x`, are kept so that the explainer reports them.
+ */
+const PHP_FLAGS = { u: "", S: "" };
+/** Supported languages, keyed by VS Code language ID. */
+exports.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)$"))
+`,
+    },
+};
+/** VS Code language IDs that have a {@link LanguageSpec}, in table order. */
+exports.SUPPORTED_LANGUAGE_IDS = Object.keys(exports.LANGUAGES);
+/** Grammar names used by {@link LANGUAGES}, each once. */
+exports.GRAMMARS = [
+    ...new Set(Object.values(exports.LANGUAGES).map((spec) => spec.grammar)),
+];
+//# sourceMappingURL=compiler.js.map