regex-le: Instructions file for Codex

AGENTS.md — Regex-LE

Technical source of truth for this repo. README.md is the user-facing doc; this file is for anyone (human or agent) changing the code.

This repo hosts two products: the extension at the root (this document's scope) and the Rust CLI in crate/ (its own AGENTS.md + SPEC.md). The crate ports the lint half only — pattern detection and the ReDoS screen, never the tester. The shared corpus lives at crate/fixtures/; scripts/check-extraction-parity.ts fails CI when this extension drifts from it.

What this is

A VS Code extension that finds regex patterns in the active document (literals, new RegExp(...), RegExp(...)), tests them against the file content, and screens them for catastrophic backtracking by demonstration. No network access, no filesystem writes.

Architecture

extension.ts             activate(): createServices() -> registerCommands()
services/serviceFactory  createServices(context) -> { telemetry, notifier, statusBar }
commands/                one file per command (test, extract, validate, help);
                         deps injected as a frozen bag; settings.ts registers openSettings
extraction/regex/
  heuristics.ts          THE single regex-vs-division context rule + flag/compile checks
  position.ts            offset -> {line, column} via newline index (1-based)
  extractPatterns.ts     whole-content extraction, both forms route through heuristics
  mask.ts                the comment and string spans a candidate must not start in
  regexTest.ts           executes with the 'd' flag; group positions from match.indices
  patternSyntax.ts       the pattern text as a tree; refuses what it cannot read
  ambiguity.ts           the ReDoS decider: NFA + backtracking walk under a
                         step budget, reporting only a demonstrated blow-up
  redos.ts               maps that decision to the reported verdict
  performance.ts         heuristic complexity/perf scoring for reports
ui/                      notifier (window messages, gated by notificationsLevel:
                         all -> everything, important -> warn+error, silent -> error only),
                         statusBar
utils/                   errors (sanitizeErrorMessage), safety (size/output guards)
config/config.ts         getConfiguration() snapshot; CONFIG_DEFAULTS table
types.ts                 shared types only — no logic