npm - regex-inspector - Versions diffs - 1.0.1 - Mend

regex-inspector 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (32) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 RezaLabs
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,164 @@
+# regex-inspector
+regex-inspector is a zero-dependency TypeScript library and CLI that parses any JavaScript regular expression into a typed AST, reconstructs it back to a string, analyzes it for catastrophic backtracking vulnerabilities, and fixes unsafe patterns automatically. Most regex testing tools only tell you whether a pattern matches your input. They do not tell you whether that pattern will explode when given a long non-matching string. regex-inspector performs static analysis of the regex structure itself, identifying patterns that force exponential backtracking: the root cause of ReDoS (regular expression denial of service) that has caused real outages at Cloudflare, Stack Overflow, and other major platforms.
+## Features
+- **Full regex-to-AST parsing:** Tokenizes any JavaScript regex pattern into a typed AST covering all standard syntax including named groups, lookbehinds, modifier groups, Unicode property escapes, v-flag `\q{...}` and set operations, and octalescent backreference disambiguation.
+- **AST-to-string generation:** Round-trip reconstruction of regex strings from AST nodes with shorthand set normalization (`\d`, `\w`, `\s`, `.`).
+- **ReDoS detection:** Static analysis for three classes of catastrophic backtracking: nested repetition (star height analysis), alternation prefix overlap, and sequential overlapping quantifiers (`.*?<head>.*?<title>.*?</title>` cascading O(N^k) backtracking without explicit nesting).
+- **Severity scoring:** Four levels (`none`, `low`, `high`, `critical`) with automatic mitigation detection from anchoring (`^...$`) and exclusive static suffixes.
+- **Auto-fix:** Strips redundant outer quantifiers (`(a+)+` to `(a+)`) and collapses same-character alternatives (`(a|aa|aaa)+` to `a+`). Every fix is verified safe before return.
+- **CLI with exit codes:** Quick safety check (`npx regex-inspector '(a+)+'`), detailed JSON analysis (`-a`), and auto-fix output (`-f`) with configurable repetition limit.
+- **Convenience API:** `inspect()` combines parse, analyze, and fix in a single call accepting strings, `RegExp` objects, and cross-realm-safe detection.
+- **Zero dependencies:** Fully self-contained TypeScript implementation with no runtime dependencies.
+### ReDoS Detection Details
+**Nested repetition** (star height > 1): `(a+)+y`, `(x+x+)+y`; quantifiers inside quantifiers creating exponential backtracking paths. Automatically accounts for unambiguous inner structure where disjoint charsets make nested quantifiers safe (e.g., `(a+b+)+`).
+**Alternation prefix overlap**: `(a|aa|aaa)+`, `(ab|abc)+`; alternatives inside a quantifier sharing a common prefix, allowing the engine to partition input in exponentially many ways. Extends to character classes (`[a-z]|[a-z][a-z]`), predefined sets (`\d|\d\d`), the dot metacharacter, and mixed CHAR/SET overlap.
+**Sequential overlapping quantifiers**: `.*?<head>.*?<title>.*?</title>`, `. +?a.+?a.+?a`, or `(.*?,){11}P`; consecutive quantifiers whose match domains overlap with the token that follows them. Each quantifier can over-consume the delimiter, creating cascading O(N^k) backtracking when later tokens fail. A single adjacency inside a repeated group (e.g., `(.*?,){11}`) is similarly dangerous because the outer repetition amplifies the overlap.
+### Severity Levels
+| Level | Meaning |
+|-------|---------|
+| `none` | Safe |
+| `low` | Minor issues or mitigated by anchoring/suffix |
+| `high` | Nested repetition, alternation overlap, or sequential overlap |
+| `critical` | Star height >= 3 |
+Mitigating factors (`^...$` anchoring, trailing literal not matchable by preceding quantifiers) reduce severity. A trailing `y` after `(a+)+` helps because `a` cannot match `y`. A trailing `P` after `(.*?,){11}` does not help because dot also matches `P`.
+## Quick Start
+### Installation
+```bash
+npm install regex-inspector
+```
+### Basic Usage
+```javascript
+import { parse, generate, inspect, fix } from 'regex-inspector';
+// Parse a regex into an AST
+const ast = parse('(a+)+y');
+// Reconstruct the pattern string from the AST
+generate(ast);  // => '(a+)+y'
+// Inspect for ReDoS vulnerabilities
+inspect('(a+)+y');
+// => { safe: false, severity: 'low', starHeight: 2, fix: '(a+)y', ... }
+// Auto-fix unsafe patterns
+fix('(a+)+');
+// => { safe: false, fixed: '(a+)', original: '(a+)+', semanticChange: true }
+```
+```sh
+# Quick safety check (exit code)
+npx regex-inspector '(a+)+'           # => critical (exit 1)
+npx regex-inspector '^[a-z]+$'       # => safe (exit 0)
+# Detailed analysis
+npx regex-inspector -a '(x+x+)+y'
+# Auto-fix output
+npx regex-inspector -f '(x+x+)+y'    # => (x+x+)y
+# Custom repetition limit
+npx regex-inspector -l 50 '(a+)+'
+```
+For more complete scenarios, see the [CLI docs](./docs/cli.md) and [API reference](./docs/api.md).
+## Configuration
+regex-inspector works out of the box. The optional `limit` parameter controls the maximum allowed repetition depth:
+```javascript
+import { inspect } from 'regex-inspector';
+const result = inspect('(a+)+', { limit: 50 });
+```
+## Security Advisory
+If you maintain a service that accepts user-provided regex patterns (search fields, filtering tools, log analyzers), every regex you execute is a potential denial-of-service vector. An attacker who submits a long string against a vulnerable regex can pin a CPU core with a single HTTP request.
+regex-inspector detects these patterns so you can reject, fix, or sandbox them before execution. It does not make them safe by itself.
+## API Reference
+Every public function is fully typed and has a corresponding set of unit tests.
+| Function | Input | Output | Purpose |
+|----------|-------|--------|---------|
+| `parse` | `string` | `RootNode` | Tokenize regex into AST |
+| `generate` | `Node` | `string` | Reconstruct regex from AST |
+| `inspect` | `string \| RegExp` | `AnalysisResult` | Parse + analyze + suggest fix |
+| `fix` | `string \| RegExp` | `FixResult` | Auto-fix unsafe patterns |
+| `analyze` | `Node` | `AnalysisResult` | Analyze pre-parsed AST |
+| `fixRegex` | `string \| Node` | `FixResult` | Fix pre-parsed AST |
+The unit tests (in [`test/`](./test)) serve as the definitive, always-correct specification for edge behaviour.
+Full details:
+- **[`/docs` directory](./docs)** for detailed markdown references
+- **[docs/api.md](./docs/api.md)** for the full API reference
+- **[docs/ast.md](./docs/ast.md)** for AST node type documentation
+- **[docs/cli.md](./docs/cli.md)** for CLI usage and options
+- **[docs/syntax.md](./docs/syntax.md)** for supported regex syntax
+- **[docs/errors.md](./docs/errors.md)** for error handling details
+## Contributing
+Pull requests are not accepted. This project is AI-assisted and single-maintainer; every line is curated through a consistent workflow that external PRs would disrupt.
+What is accepted:
+- **Bug reports** with reproduction steps.
+- **Feature requests** that align with the project's core principles.
+- **Documentation corrections** for errors or omissions.
+Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for details.
+This project is maintained by [RezaLabs](https://rezalabs.com).
+## Changelog
+Notable changes between versions are documented in [`CHANGELOG.md`](./CHANGELOG.md). The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+## Development Process
+This project is built with heavy assistance from large language models.
+**Why?** The entire codebase, from architecture decisions down to individual line implementations, is produced through iterative prompting and review with AI. This is intentional. The goal is to test the limits of what AI can generate when held to strict quality standards.
+**What this means for you:**
+- Every commit and every release is reviewed and approved by a human. AI generates proposals; I accept, reject, or modify them.
+- The project is a deliberate exercise in AI-assisted engineering. The output is curated, tested, and documented.
+- If you find an issue, it is my failure as the maintainer to catch it, not an excuse that "the AI wrote it." I own all results.
+This project is as much a product of AI capability as it is of human editorial judgment. You are welcome to judge both.
+## Support
+If this project saves you time or solves a problem you would otherwise pay to fix, consider supporting its continued development.
+- [Buy Me a Coffee](https://buymeacoffee.com/rezalabs)
+- [Ko-fi](https://ko-fi.com/rezalabs)
+Sponsorship is never required, but always appreciated. It funds maintenance, tooling, and the compute needed to iterate with AI assistance at this scale.
+## License
+MIT License. See the full text in [`LICENSE`](./LICENSE).
+Copyright (c) 2026 [RezaLabs](https://rezalabs.com)

package/bin/regex-inspector.js ADDED Viewed

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkgPath = path.resolve(__dirname, "..", "package.json");
+const { version } = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+const { values: opts, positionals } = parseArgs({
+	allowPositionals: true,
+	options: {
+		version: { type: "boolean", short: "v", default: false },
+		help: { type: "boolean", short: "h", default: false },
+		analyze: { type: "boolean", short: "a", default: false },
+		fix: { type: "boolean", short: "f", default: false },
+		limit: { type: "string", short: "l", default: undefined },
+	},
+});
+const HELP = `Usage: regex-inspector [options] <regex>
+Parse, inspect, and fix regular expressions: detect ReDoS vulnerabilities,
+extract AST structure, or auto-fix unsafe patterns.
+When called without options, performs a quick safety check and exits with a
+status code (0 = safe, 1 = unsafe). Use --analyze for a full diagnostic report
+or --fix to generate a safe alternative.
+Exit codes:
+  0  Pattern is safe
+  1  Pattern is unsafe, or an error occurred
+Options:
+  -v, --version          Display the version number
+  -h, --help             Display this help message
+  -a, --analyze          Show detailed analysis with severity, reasons, and suggested fix
+  -f, --fix              Output an auto-fixed safe version of the regex
+  -l, --limit <n>        Maximum allowed repetitions before flagging (default: 25)
+  <regex>                The regular expression pattern to inspect
+Examples:
+  regex-inspector '(a+)+'            Quick safety check (exit code indicates safe/unsafe)
+  regex-inspector -a '(a+)+'         Detailed analysis report
+  regex-inspector -f '(x+x+)+y'      Auto-fix output
+  regex-inspector -l 50 '(a+)+'      Custom repetition limit`;
+if (opts.help) {
+	console.log(HELP);
+	process.exit(0);
+}
+if (opts.version) {
+	console.log(version);
+	process.exit(0);
+}
+if (positionals.length === 0) {
+	console.error("Error: Missing regex argument.");
+	console.log(HELP);
+	process.exit(1);
+}
+if (positionals.length > 1) {
+	console.error("Error: Too many positional arguments.");
+	console.log(HELP);
+	process.exit(1);
+}
+let inspect, fix;
+try {
+	const distPath = path.resolve(__dirname, "..", "dist", "index.js");
+	const dist = await import(pathToFileURL(distPath).href);
+	inspect = dist.inspect;
+	fix = dist.fix ?? dist.fixRegex;
+} catch (_err) {
+	console.error(
+		'regex-inspector: Build not found at dist/index.js. Run "npm run build" first.',
+	);
+	process.exit(1);
+}
+const pattern = positionals[0];
+const limit = opts.limit !== undefined ? parseInt(opts.limit, 10) : undefined;
+if (limit !== undefined && (Number.isNaN(limit) || limit < 1)) {
+	console.error("Error: --limit must be a positive integer.");
+	process.exit(1);
+}
+const options = limit !== undefined ? { limit } : undefined;
+try {
+	if (opts.analyze) {
+		const result = inspect(pattern, options);
+		if (result.safe) {
+			console.log("✓ Pattern is safe.");
+		} else {
+			console.log(`✗ Pattern is unsafe (severity: ${result.severity}).`);
+		}
+		if (result.reasons.length > 0) {
+			console.log("\nReasons:");
+			for (const reason of result.reasons) {
+				console.log(`  • ${reason}`);
+			}
+		}
+		if (result.fix) {
+			console.log(`\nSuggested fix: ${result.fix}`);
+		}
+		console.log("\nFull report:");
+		console.log(JSON.stringify(result, null, 2));
+	} else if (opts.fix) {
+		const result = fix(pattern, options);
+		if (result.fixed) {
+			console.log(result.fixed);
+		} else if (result.safe) {
+			console.log("Pattern is already safe; no fix needed.");
+		} else {
+			console.error("Could not auto-fix this pattern.");
+			process.exit(1);
+		}
+	} else {
+		const result = inspect(pattern, options);
+		if (result.safe) {
+			console.log("✓ safe");
+			process.exit(0);
+		} else {
+			console.log(`✗ ${result.severity}`);
+			process.exit(1);
+		}
+	}
+} catch (err) {
+	console.error("Error:", err.message);
+	process.exit(1);
+}

package/dist/analyze.d.ts ADDED Viewed

@@ -0,0 +1,19 @@
+import type { Node } from "./ast.js";
+export type Severity = "none" | "low" | "high" | "critical";
+export type AnalysisResult = {
+    safe: boolean;
+    severity: Severity;
+    reasons: string[];
+    starHeight: number;
+    repCount: number;
+    hasAlternationReDoS: boolean;
+    hasSequentialOverlap: boolean;
+    anchored: boolean;
+    hasStaticSuffix: boolean;
+    fix: string | null;
+};
+export type AnalyzeOptions = {
+    limit?: number;
+};
+export declare function analyze(ast: Node, opts?: AnalyzeOptions): AnalysisResult;
+//# sourceMappingURL=analyze.d.ts.map

package/dist/analyze.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"analyze.d.ts","sourceRoot":"","sources":["../src/analyze.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEX,IAAI,EAIJ,MAAM,UAAU,CAAC;AAIlB,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;AAE5D,MAAM,MAAM,cAAc,GAAG;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,oBAAoB,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,eAAe,EAAE,OAAO,CAAC;IACzB,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAwkBF,wBAAgB,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,GAAE,cAAmB,GAAG,cAAc,CAuE5E"}