Regex Lens

Build, understand, validate and test regular expressions directly inside VS Code.

Regex Lens turns hard-to-read regular expressions into structured explanations, token highlighting, a tree view, validation diagnostics, generated examples and a live match tester. It is built for developers who want to understand a regex without leaving the editor.

Why Regex Lens?

Regular expressions are compact, powerful and often painful to review. A pattern like this is easy to paste from StackOverflow and hard to maintain later:

^(?=.*[A-Z])(?=.*\d)[A-Za-z\d]{8,20}$

Regex Lens explains it as a readable structure:

• Summary: the regex describes the full input and uses zero-width assertions.
• ^: start anchor.
• (?=.*[A-Z]): positive lookahead that checks for an uppercase letter without consuming text.
• (?=.*\d): positive lookahead that checks for a digit without consuming text.
• [A-Za-z\d]: character class with child nodes for A-Z, a-z and \d.
• {8,20}: greedy bounded quantifier.
• $: end anchor.

Screenshots

Explanation overview	Flavor and examples	Tree view

Installation

Regex Lens can be installed from a packaged VSIX build:

npm run package:vsix
code --install-extension dist/regex-lens.vsix

Once the extension is published, it will also be available from the VS Code Marketplace under Regex Lens.

Current Status

Regex Lens is currently at 1.1.0.

Implemented roadmap phases:

• 0.1: MVP workflow.
• 0.2: Explanation quality pass.
• 0.3: Match tester and generated examples upgrade.
• 0.4: Diagnostics and editor integration.
• 0.5: Parser upgrade.
• 0.6: Flavor support.
• 0.7: Performance analysis.
• 0.8: Export and documentation.
• 0.9: Flavor depth for possessive quantifiers, atomic groups, inline comments and balancing groups.
• 0.10: Polish and Marketplace readiness.
• 1.0: Stable release.
• 1.1: Full flavor depth for POSIX classes, conditionals, recursion, verbose mode and inline modifiers.

The core workflow is usable:

• Select or place the cursor inside a regex.
• Run a Regex Lens command.
• Inspect the summary, token table, tree, validation result, examples and match tester.
• Edit regex patterns and flags directly inside the match tester.
• Inspect match index, length, numbered captures and named captures.
• Copy full reports, summaries, token tables or code comments, and export shareable Markdown, HTML or PDF files.
• Apply quick fixes for simple regex syntax and flag issues.
• Get AST-backed token ranges for valid JavaScript regex patterns, with lightweight fallback parsing for partial raw selections.
• Switch regex flavors in the Webview and inspect compatibility notes.
• Review severity-ranked performance warnings with exact risky subexpression ranges and rewrite suggestions.
• Export standalone reports for PRs, docs and teaching material.

Regex Lens uses regexpp for valid JavaScript patterns, an embedded dialect parser for Python 3.11+, Java, Go, .NET and PCRE, and the original lightweight fallback only for incomplete JavaScript selections.

Features

• Structured regex explanations instead of one long sentence.
• Plain-language summary in German or English.
• Token-level syntax coloring in the Webview and editor decorations.
• Regex tree view in the Activity Bar.
• Character classes broken down into child range and escape nodes.
• AST-backed parsing for JavaScript regex patterns through regexpp.
• Embedded structural parsing for Python 3.11+, Java, Go, .NET and PCRE without external runtime dependencies.
• Normalized parser metadata exposed on analyzer results.
• Clearer explanations for lookaheads, lookbehinds, non-capturing groups and alternation.
• Source ranges for every token in the structured explanation.
• Hover explanations for anchors, groups, escapes, character classes and quantifiers.
• CodeLens actions above detected regex literals.
• Live validation diagnostics for invalid JavaScript regex literals, unsupported flags, empty alternatives and group issues.
• Quick fixes for simple syntax mistakes and invalid flags.
• Detection for JavaScript and TypeScript literals, RegExp constructors, Java String.matches/Pattern, C# Regex, Go regexp, Python raw strings and re, PHP preg_*, Perl match/qr/m/substitution forms, standalone PCRE lines and common config pattern keys.
• Flavor switcher with compatibility warnings for JavaScript, Python, Java, Go, .NET and PCRE.
• Flavor-specific notes for flags, named groups, lookbehind and cheat-sheet entries.
• Real token recognition for flavor-specific constructs: possessive quantifiers, atomic groups, inline comments, .NET balancing groups, POSIX classes, conditional groups, PCRE recursion and subroutine calls, verbose mode and inline modifiers.
• Match tester with multiline input, highlighted matches and match counts.
• Editable regex and flags inside the match tester.
• Flavor-aware match execution: JavaScript uses the Webview's RegExp; Python, Java, Go, .NET and PCRE use an installed native runtime with a hard timeout and never silently fall back to JavaScript.
• Case-insensitive and multiline flag toggles.
• Match details with index, length, numbered captures and named captures.
• Generated matching and non-matching examples with reasons.
• Copy buttons for generated example sets and individual examples.
• Basic complexity score.
• Performance warnings for nested quantifiers, ambiguous alternation, broad wildcard backtracking and repeated optional groups.
• Editor diagnostics for high-risk and medium-risk regex performance issues.
• Markdown, standalone HTML and PDF export.
• Copy options for full reports, summaries, token tables and language-aware code comments.

Supported Inputs

Regex Lens can explain:

const literal = /[A-Z]{2}\d{4}/;
const stringPattern = "\\d+";
const constructor = new RegExp("\\d+", "gi");

Native regex APIs and strings are detected as well:

email = r"^[^@]+@[^@]+$"

boolean valid = value.matches("[A-Z]{3}-\\d{4}");

bool valid = Regex.IsMatch(value, @"^[A-Z]{3}-\d{4}$");

regex := regexp.MustCompile(`^[A-Z]{3}-[0-9]{4}$`)

preg_match('/\A[A-Z]{3}-\d{4}\z/', $value);

my $regex = qr{\A[A-Z]{3}-\d{4}\z};
my $valid = $value =~ m{\A[A-Z]{3}-\d{4}\z};

.pl and .pm files are also inferred as Perl when VS Code opens them in Plain Text mode.

Config pattern keys are also detected:

{ "pattern": "^\\d{4}$" }

You can also select a raw pattern:

[A-Z]{2}\d{4}

Commands

Open the Command Palette with Ctrl+Shift+P and run:

• Regex Lens: Explain Selection
• Regex Lens: Explain Regex Under Cursor
• Regex Lens: Generate Examples
• Regex Lens: Test Matches
• Regex Lens: Copy Explanation and choose full report, summary, token table or comment output.

The editor context menu also exposes the main actions when text is selected and an under-cursor explanation action when there is no selection.

CodeLens

For detected regex literals, Regex Lens adds inline actions:

• Explain Regex
• Generate Examples
• Test Matches

Example:

const password = /^(?=.*[A-Z])(?=.*\d)[A-Za-z\d]{8,20}$/;

Settings

{
  "regexLens.language": "en",
  "regexLens.showExamples": true,
  "regexLens.showTree": true,
  "regexLens.liveValidation": true,
  "regexLens.highlightMatches": true,
  "regexLens.flavor": "auto"
}

regexLens.language

Controls explanation language.

Supported values:

• de
• en

regexLens.showExamples

Shows or hides generated examples in the Webview.

regexLens.showTree

Shows or hides the tree section in the Webview.

regexLens.liveValidation

Enables diagnostics for detected regex literals.

regexLens.highlightMatches

Enables token highlighting in the editor for detected regex literals.

regexLens.flavor

Controls dialect parsing, explanations and compatibility warnings.

Supported values:

• auto
• javascript
• python
• java
• go
• dotnet
• pcre

Local Development

Install dependencies:

npm install

Compile TypeScript:

npm run compile

Run lint checks:

npm run lint

Run fast unit tests:

npm run test:unit

Run the VS Code extension test host:

npm test

On Windows, npm test can fail before tests start if VS Code is currently being updated and the vscode-updating mutex is held. In that case, wait for the update to finish and rerun the command.

Package a local VSIX build:

npm run package:vsix

Running the Extension

Open this folder in VS Code:

E:\Open Source\regex-explainer\regex-explainer

Then press F5 and choose Run Extension. A new Extension Development Host window opens.

In that window, create a test file:

const password = /^(?=.*[A-Z])(?=.*\d)[A-Za-z\d]{8,20}$/;
const code = /[A-Z]{2}\d{4}/;
const fromString = "\\d+";
const fromConstructor = new RegExp("\\d+", "gi");
const alternation = /cat|dog|bird/;
const captures = /(?<code>[A-Z]{2})(\d{4})/g;
const risky = /(a+)+/;
const ambiguous = /(a|aa)+$/;
const wildcard = /.*a+/;

Place the cursor inside a regex or select one, then run Regex Lens: Explain Selection.

Architecture

Regex Lens
+-- Extension Host
|   +-- Commands
|   +-- Hover Provider
|   +-- CodeLens Provider
|   +-- Diagnostics
|   +-- Tree View
+-- Regex Engine
|   +-- Tokenizer
|   +-- Validation
|   +-- Tree Builder
|   +-- Summary Builder
|   +-- Alternation Annotation
|   +-- Complexity Scoring
|   +-- Performance Warnings
|   +-- Example Generation
+-- Webview UI
    +-- Plain-Language Summary
    +-- Structured Explanation
    +-- Match Tester
    +-- Cheat Sheet
    +-- Copy and Export Actions

Project Layout

src/
+-- extension.ts
+-- regex/
+-- vscode/
+-- webview/
+-- test/

Known Limitations

• JavaScript regex parsing is AST-backed through regexpp. Python 3.11+, Java, Go, .NET and PCRE use an embedded structural dialect parser, so a non-JavaScript pattern is never interpreted through a JavaScript AST merely because its text is valid ECMAScript.
• The embedded dialect parser handles flavor-specific groups, escapes, repetition limits, POSIX classes, conditionals, recursion, verbose mode and scoped modifiers without requiring external language runtimes. Live matching is separate and uses the selected native runtime when one is installed.
• Flavor detection is heuristic.
• Example generation is deterministic and basic.
• Performance analysis is static and conservative; it highlights likely ReDoS/backtracking risks but is not a benchmark runner. It understands that atomic groups and possessive quantifiers are backtracking-immune.
• Native live testing requires the corresponding local runtime on PATH: Python 3 (py, python3 or python), Java 11+ (java), Go (go), PowerShell for .NET (pwsh, or Windows PowerShell on Windows), and PHP with PCRE2 (php). The tester identifies the exact runtime version, stops tests after 2.5 seconds, and reports an unavailable engine instead of using the wrong flavor.

Roadmap

See ROADMAP.md.

License

Regex Lens is licensed under the MIT License. See LICENSE.