Regex Crafting skill for Claude Code

#!/usr/bin/env python3
"""Test a regular expression against must-match / must-not-match cases and probe for
catastrophic backtracking. Uses Python's `re` engine (a backtracking engine, so the
probe is representative of PCRE, JavaScript, Java, .NET, Ruby; not of RE2/Go/Rust).

Usage:
  python3 regex_test.py --pattern 'REGEX' --cases cases.txt [--flags imsx] [--mode search|fullmatch]
                        [--probe] [--timeout 2.0]

cases.txt format (one case per line):
  + text that must match
  - text that must NOT match
  = text => expected first match (or group 1 if the pattern has groups)
  # comment lines and blank lines are ignored
Use \\t, \\n, \\x00 style escapes inside cases if needed.

Exit code: 0 all cases pass and no backtracking blow-up found; 1 otherwise; 2 bad input.
"""
from __future__ import annotations

import argparse
import multiprocessing as mp
import re
import sys
import time

FLAG_MAP = {"i": re.IGNORECASE, "m": re.MULTILINE, "s": re.DOTALL, "x": re.VERBOSE, "a": re.ASCII}


def compile_pattern(pattern: str, flags: str) -> re.Pattern[str]:
    value = 0
    for ch in flags:
        if ch not in FLAG_MAP:
            raise SystemExit(f"unknown flag {ch!r}; use any of {''.join(FLAG_MAP)}")
        value |= FLAG_MAP[ch]
    try:
        return re.compile(pattern, value)
    except re.error as exc:
        print(f"INVALID PATTERN: {exc}", file=sys.stderr)
        sys.exit(2)


def unescape(text: str) -> str:
    return text.encode("utf-8").decode("unicode_escape") if "\\" in text else text


def load_cases(path: str) -> list[tuple[str, str, str | None]]:
    cases: list[tuple[str, str, str | None]] = []
    with open(path, encoding="utf-8") as fh:
        for lineno, raw in enumerate(fh, 1):
            line = raw.rstrip("\n")
            if not line.strip() or line.lstrip().startswith("#"):
                continue
            kind, _, rest = line.partition(" ")
            if kind in ("+", "-"):
                cases.append((kind, unescape(rest), None))
            elif kind == "=":
                text, sep, expected = rest.partition(" => ")
                if not sep:
                    raise SystemExit(f"line {lineno}: '=' cases need 'text => expected'")
                cases.append((kind, unescape(text), unescape(expected)))
            else:
                raise SystemExit(f"line {lineno}: start with '+', '-', '=' or '#': {line!r}")
    if not cases:
        raise SystemExit("no cases found")
    return cases


def run_match(rx: re.Pattern[str], mode: str, text: str) -> re.Match[str] | None:
    return rx.fullmatch(text) if mode == "fullmatch" else rx.search(text)


def check_cases(rx: re.Pattern[str], mode: str, cases) -> int:
    failures = 0
    for kind, text, expected in cases:
        m = run_match(rx, mode, text)
        if kind == "+":
            ok = m is not None
            detail = "" if ok else "expected a match, got none"
        elif kind == "-":
            ok = m is None
            detail = "" if ok else f"expected no match, matched {m.group(0)!r}"
        else:
            got = None if m is None else (m.group(1) if rx.groups else m.group(0))
            ok = got == expected
            detail = "" if ok else f"expected {expected!r}, got {got!r}"
        status = "PASS" if ok else "FAIL"
        print(f"{status} {kind} {text!r}" + (f"  -- {detail}" if detail else ""))
        failures += 0 if ok else 1
    return failures


def _timed_worker(pattern: str, flags: int, mode: str, text: str, queue) -> None:
    rx = re.compile(pattern, flags)
    start = time.perf_counter()
    run_match(rx, mode, text)
    queue.put(time.perf_counter() - start)


def timed(rx: re.Pattern[str], mode: str, text: str, timeout: float) -> float | None:
    """Return seconds taken, or None if it exceeded the timeout (process is killed)."""
    queue: mp.Queue = mp.Queue()
    proc = mp.Process(target=_timed_worker, args=(rx.pattern, rx.flags, mode, text, queue))
    proc.start()
    proc.join(timeout)
    if proc.is_alive():
        proc.terminate()
        proc.join()
        return None
    return queue.get() if not queue.empty() else None


def probe(rx: re.Pattern[str], mode: str, cases, timeout: float) -> int:
    """Pump the middle of each matching case and append a failing suffix; watch growth."""
    seeds = [text for kind, text, _ in cases if kind in ("+", "=") and len(text) >= 1]
    if not seeds:
        print("PROBE skipped: no positive cases to pump")
        return 0
    problems = 0
    for seed in seeds:
        third = max(1, len(seed) // 3)
        prefix, pump = seed[:third], seed[third:2 * third] or seed
        suffix = seed[2 * third:] + "\x00!"
        times: list[tuple[int, float]] = []
        verdict = "linear"
        for reps in (8, 16, 32, 64, 128, 256, 1024, 4096):
            text = prefix + pump * reps + suffix
            took = timed(rx, mode, text, timeout)
            if took is None:
                verdict = f"CATASTROPHIC: >{timeout}s at input length {len(text)}"
                break
            times.append((len(text), took))
            if len(times) >= 2:
                (n1, t1), (n2, t2) = times[-2], times[-1]
                if t1 > 0.002 and t2 / t1 > 6 * (n2 / n1):
                    verdict = f"SUPER-LINEAR: {t1:.4f}s at len {n1} -> {t2:.4f}s at len {n2}"
                    break
        flagged = verdict != "linear"
        problems += 1 if flagged else 0
        last = times[-1] if times else (0, 0.0)
        tail = "" if flagged else f" (len {last[0]} in {last[1]:.4f}s)"
        print(f"PROBE {'FAIL' if flagged else 'PASS'} pump={pump!r}: {verdict}{tail}")
    return problems


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("--pattern", required=True)
    ap.add_argument("--cases", required=True, help="path to cases file")
    ap.add_argument("--flags", default="", help="any of: i m s x a")
    ap.add_argument("--mode", choices=("search", "fullmatch"), default="search")
    ap.add_argument("--probe", action="store_true", help="probe for catastrophic backtracking")
    ap.add_argument("--timeout", type=float, default=2.0, help="seconds per probe attempt")
    args = ap.parse_args()

    rx = compile_pattern(args.pattern, args.flags)
    cases = load_cases(args.cases)
    failures = check_cases(rx, args.mode, cases)
    problems = probe(rx, args.mode, cases, args.timeout) if args.probe else 0
    total = sum(1 for _ in cases)
    print(f"\n{total - failures}/{total} cases passed; {problems} backtracking problem(s)")
    return 1 if failures or problems else 0


if __name__ == "__main__":
    sys.exit(main())