easy-regex-lib 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1037 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CompiledPattern: () => CompiledPattern,
+  MatchBuilder: () => MatchBuilder,
+  PATTERN_SCHEMA_VERSION: () => PATTERN_SCHEMA_VERSION,
+  alt: () => alt,
+  analyzePattern: () => analyzePattern,
+  anyChar: () => anyChar,
+  booleanLiteral: () => booleanLiteral,
+  compile: () => compile,
+  compilePattern: () => compilePattern,
+  dash: () => dash,
+  deserializePattern: () => deserializePattern,
+  diagnose: () => diagnose,
+  digit: () => digit,
+  dot: () => dot,
+  end: () => end,
+  explainPattern: () => explainPattern,
+  hexDigit: () => hexDigit,
+  integer: () => integer,
+  letter: () => letter,
+  literal: () => literal,
+  match: () => match,
+  namedGroup: () => namedGroup,
+  nonCapturing: () => nonCapturing,
+  optimize: () => optimize,
+  optional: () => optional,
+  patternFromJsonString: () => patternFromJsonString,
+  patternToJsonString: () => patternToJsonString,
+  presets: () => presets,
+  raw: () => raw,
+  regex: () => regex,
+  repeat: () => repeat,
+  seq: () => seq,
+  serializePattern: () => serializePattern,
+  start: () => start,
+  toRegExp: () => toRegExp,
+  underscore: () => underscore,
+  whitespace: () => whitespace,
+  word: () => word,
+  wordBoundary: () => wordBoundary
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/ast.ts
+var PATTERN_SCHEMA_VERSION = 1;
+function seq(...children) {
+  const flat = flattenSequences(children);
+  if (flat.length === 0) return { kind: "Literal", value: "" };
+  if (flat.length === 1) return flat[0];
+  return { kind: "Sequence", children: flat };
+}
+function alt(...children) {
+  const choices = flattenChoices(children);
+  if (choices.length === 0) return { kind: "Literal", value: "" };
+  if (choices.length === 1) return choices[0];
+  return { kind: "Choice", children: choices };
+}
+function repeat(child, min, max, greedy = true) {
+  if (min === 0 && max === 1) return { kind: "Optional", child, greedy };
+  if (min === 1 && max === 1) return child;
+  return { kind: "Repeat", child, min, max, greedy };
+}
+function optional(child, greedy = true) {
+  return { kind: "Optional", child, greedy };
+}
+function namedGroup(name, child) {
+  return { kind: "NamedGroup", name, child };
+}
+function nonCapturing(child) {
+  return { kind: "NonCapturing", child };
+}
+function literal(value) {
+  return { kind: "Literal", value };
+}
+function optimize(pattern) {
+  return flattenAst(pattern);
+}
+function flattenSequences(children) {
+  const out = [];
+  for (const c of children) {
+    const o = optimize(c);
+    if (o.kind === "Literal" && o.value === "") continue;
+    if (o.kind === "Sequence") out.push(...o.children.map(optimize));
+    else out.push(o);
+  }
+  return out;
+}
+function flattenChoices(children) {
+  const out = [];
+  for (const c of children) {
+    const o = optimize(c);
+    if (o.kind === "Choice") out.push(...o.children.map(optimize));
+    else out.push(o);
+  }
+  return dedupeAdjacentDuplicates(out);
+}
+function dedupeAdjacentDuplicates(children) {
+  return children;
+}
+function flattenAst(node) {
+  switch (node.kind) {
+    case "Sequence":
+      return seq(...node.children);
+    case "Choice":
+      return alt(...node.children);
+    case "Repeat":
+      return {
+        ...node,
+        child: flattenAst(node.child)
+      };
+    case "Optional":
+      return { ...node, child: flattenAst(node.child) };
+    case "NamedGroup":
+      return { ...node, child: flattenAst(node.child) };
+    case "NonCapturing":
+      return { ...node, child: flattenAst(node.child) };
+    default:
+      return node;
+  }
+}
+
+// src/primitives.ts
+function wrap(base) {
+  const q = base;
+  q.exactly = (n) => repeat(base, n, n);
+  q.atLeast = (n) => repeat(base, n, Number.POSITIVE_INFINITY);
+  q.atMost = (n) => repeat(base, 0, n);
+  q.between = (min, max) => repeat(base, min, max);
+  q.oneOrMore = () => repeat(base, 1, Number.POSITIVE_INFINITY);
+  q.zeroOrMore = () => repeat(base, 0, Number.POSITIVE_INFINITY);
+  q.maybe = () => optional(base);
+  return q;
+}
+function anyChar() {
+  return wrap({ kind: "Any" });
+}
+function digit(opts = {}) {
+  return wrap({ kind: "Digit", unicode: opts.unicode ?? false });
+}
+function word(opts = {}) {
+  return wrap({ kind: "Word", unicode: opts.unicode ?? false });
+}
+function whitespace(opts = {}) {
+  return wrap({ kind: "Whitespace", unicode: opts.unicode ?? false });
+}
+function letter(opts = {}) {
+  return wrap({
+    kind: "Letter",
+    letterCase: opts.case ?? "both",
+    unicode: opts.unicode ?? false
+  });
+}
+function hexDigit(opts = {}) {
+  const node = opts.uppercaseOnly === void 0 ? { kind: "HexDigit" } : { kind: "HexDigit", uppercaseOnly: opts.uppercaseOnly };
+  return wrap(node);
+}
+function start() {
+  return { kind: "Start" };
+}
+function end() {
+  return { kind: "End" };
+}
+function wordBoundary() {
+  return { kind: "WordBoundary" };
+}
+function raw(source, flags) {
+  return flags === void 0 ? { kind: "RawRegex", source } : { kind: "RawRegex", source, flags };
+}
+function dash() {
+  return literal("-");
+}
+function underscore() {
+  return literal("_");
+}
+function dot() {
+  return literal(".");
+}
+function integer() {
+  return digit().oneOrMore();
+}
+function booleanLiteral() {
+  return alt(literal("true"), literal("false"));
+}
+
+// src/compile.ts
+var META = /* @__PURE__ */ new Set([
+  "\\",
+  "^",
+  "$",
+  ".",
+  "|",
+  "?",
+  "*",
+  "+",
+  "(",
+  ")",
+  "[",
+  "]",
+  "{",
+  "}"
+]);
+function escapeLiteral(s) {
+  let out = "";
+  for (const ch of s) {
+    if (META.has(ch)) out += "\\";
+    out += ch;
+  }
+  return out;
+}
+function compilePattern(root, options = {}) {
+  const ast = optimize(root);
+  const warnings = [];
+  const flagCtx = mergeFlagCtx(options.flags, ast);
+  const frag = emit(ast, {
+    nonCapturing: options.nonCapturing ?? false,
+    flags: flagCtx,
+    warnings
+  });
+  return {
+    pattern: frag.s,
+    flags: stringifyFlags(flagCtx),
+    warnings
+  };
+}
+function toRegExp(root, options = {}) {
+  const { pattern, flags } = compilePattern(root, options);
+  return new RegExp(pattern, flags);
+}
+function defaultFlags() {
+  return {
+    ignoreCase: false,
+    multiline: false,
+    dotAll: false,
+    unicode: false,
+    global: false,
+    sticky: false
+  };
+}
+function mergeFlagCtx(base, ast) {
+  const f = defaultFlags();
+  if (base) applyFlags(f, base);
+  inferFlags(ast, f);
+  return f;
+}
+function applyFlags(f, p) {
+  if (p.ignoreCase) f.ignoreCase = true;
+  if (p.multiline) f.multiline = true;
+  if (p.dotAll) f.dotAll = true;
+  if (p.unicode) f.unicode = true;
+  if (p.global) f.global = true;
+  if (p.sticky) f.sticky = true;
+}
+function inferFlags(ast, f) {
+  walk(ast, (n) => {
+    if (n.kind === "Letter" && n.unicode) f.unicode = true;
+    if (n.kind === "Digit" && n.unicode) f.unicode = true;
+    if (n.kind === "Word" && n.unicode) f.unicode = true;
+    if (n.kind === "Whitespace" && n.unicode) f.unicode = true;
+    if (n.kind === "RawRegex" && n.flags) applyFlags(f, n.flags);
+  });
+}
+function walk(p, fn) {
+  fn(p);
+  switch (p.kind) {
+    case "Sequence":
+      for (const c of p.children) walk(c, fn);
+      break;
+    case "Choice":
+      for (const c of p.children) walk(c, fn);
+      break;
+    case "Repeat":
+      walk(p.child, fn);
+      break;
+    case "Optional":
+      walk(p.child, fn);
+      break;
+    case "NamedGroup":
+      walk(p.child, fn);
+      break;
+    case "NonCapturing":
+      walk(p.child, fn);
+      break;
+    default:
+      break;
+  }
+}
+function stringifyFlags(f) {
+  let s = "";
+  if (f.global) s += "g";
+  if (f.ignoreCase) s += "i";
+  if (f.multiline) s += "m";
+  if (f.dotAll) s += "s";
+  if (f.unicode) s += "u";
+  if (f.sticky) s += "y";
+  return s;
+}
+function emit(node, ctx) {
+  switch (node.kind) {
+    case "Literal":
+      return { s: escapeLiteral(node.value), prec: 3 /* Atom */ };
+    case "Any":
+      return { s: ".", prec: 3 /* Atom */ };
+    case "Digit":
+      return {
+        s: node.unicode ? "\\d" : "\\d",
+        prec: 3 /* Atom */
+      };
+    case "Word":
+      return { s: "\\w", prec: 3 /* Atom */ };
+    case "Whitespace":
+      return { s: "\\s", prec: 3 /* Atom */ };
+    case "Letter": {
+      if (node.unicode) {
+        ctx.flags.unicode = true;
+        if (node.letterCase === "lower") return { s: "\\p{Ll}", prec: 3 /* Atom */ };
+        if (node.letterCase === "upper") return { s: "\\p{Lu}", prec: 3 /* Atom */ };
+        return { s: "\\p{L}", prec: 3 /* Atom */ };
+      }
+      if (node.letterCase === "lower") return { s: "[a-z]", prec: 3 /* Atom */ };
+      if (node.letterCase === "upper") return { s: "[A-Z]", prec: 3 /* Atom */ };
+      return { s: "[A-Za-z]", prec: 3 /* Atom */ };
+    }
+    case "HexDigit":
+      return {
+        s: node.uppercaseOnly ? "[0-9A-F]" : "[0-9A-Fa-f]",
+        prec: 3 /* Atom */
+      };
+    case "Start":
+      return { s: "^", prec: 3 /* Atom */ };
+    case "End":
+      return { s: "$", prec: 3 /* Atom */ };
+    case "WordBoundary":
+      return { s: "\\b", prec: 3 /* Atom */ };
+    case "RawRegex":
+      ctx.warnings.push({
+        code: "raw-regex",
+        message: "Raw regex fragment embedded \u2014 review for ReDoS and engine-specific behavior."
+      });
+      if (node.flags) applyFlags(ctx.flags, node.flags);
+      return { s: node.source, prec: 3 /* Atom */ };
+    case "Sequence": {
+      if (node.children.length === 0) return { s: "", prec: 3 /* Atom */ };
+      let s = "";
+      for (const c of node.children) {
+        const f = emit(c, ctx);
+        s += wrapPrec(f, 1 /* Seq */).s;
+      }
+      return { s, prec: 1 /* Seq */ };
+    }
+    case "Choice": {
+      const parts = node.children.map((c) => {
+        const f = emit(c, ctx);
+        return wrapPrec(f, 0 /* Alt */).s;
+      });
+      return { s: parts.join("|"), prec: 0 /* Alt */ };
+    }
+    case "Repeat": {
+      const inner = emit(node.child, ctx);
+      const core = wrapPrec(inner, 2 /* Quant */);
+      const q = quantifier(node.min, node.max, node.greedy);
+      return { s: `${core.s}${q}`, prec: 2 /* Quant */ };
+    }
+    case "Optional": {
+      const inner = emit(node.child, ctx);
+      const core = wrapPrec(inner, 2 /* Quant */);
+      return { s: `${core.s}?${node.greedy ? "" : "?"}`, prec: 2 /* Quant */ };
+    }
+    case "NamedGroup": {
+      const inner = emit(node.child, ctx);
+      const body = wrapPrec(inner, 1 /* Seq */);
+      if (ctx.nonCapturing) {
+        return { s: `(?:${body.s})`, prec: 3 /* Atom */ };
+      }
+      return { s: `(?<${escapeGroupName(node.name)}>${body.s})`, prec: 3 /* Atom */ };
+    }
+    case "NonCapturing": {
+      const inner = emit(node.child, ctx);
+      return { s: `(?:${inner.s})`, prec: 3 /* Atom */ };
+    }
+    default: {
+      const _exhaustive = node;
+      return _exhaustive;
+    }
+  }
+}
+function escapeGroupName(name) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid named group identifier: ${JSON.stringify(name)}`);
+  }
+  return name;
+}
+function quantifier(min, max, greedy) {
+  const lazy = greedy ? "" : "?";
+  if (min === 0 && max === Number.POSITIVE_INFINITY) return `*${lazy}`;
+  if (min === 1 && max === Number.POSITIVE_INFINITY) return `+${lazy}`;
+  if (min === 0 && max === 1) return `?${lazy}`;
+  if (min === max) return `{${min}}${lazy}`;
+  if (max === Number.POSITIVE_INFINITY) return `{${min},}${lazy}`;
+  return `{${min},${max}}${lazy}`;
+}
+function wrapPrec(f, parent) {
+  if (f.prec < parent) {
+    return { s: `(?:${f.s})`, prec: 3 /* Atom */ };
+  }
+  return f;
+}
+
+// src/explain.ts
+var clauseCounter = 0;
+function nextId() {
+  clauseCounter += 1;
+  return `c${clauseCounter}`;
+}
+function explainPattern(root) {
+  clauseCounter = 0;
+  const ast = optimize(root);
+  const clauses = explainNode(ast);
+  return {
+    clauses,
+    summary: clauses.map((c) => c.text).join(" ")
+  };
+}
+function explainNode(node) {
+  switch (node.kind) {
+    case "Literal":
+      return [
+        {
+          id: nextId(),
+          text: node.value === "" ? "Matches an empty fragment." : `Matches the literal ${quote(node.value)}.`
+        }
+      ];
+    case "Any":
+      return [{ id: nextId(), text: "Matches any single character (except line terminators unless dotAll)." }];
+    case "Digit":
+      return [{ id: nextId(), text: node.unicode ? "Matches a Unicode digit." : "Matches an ASCII digit." }];
+    case "Word":
+      return [{ id: nextId(), text: "Matches a word character." }];
+    case "Whitespace":
+      return [{ id: nextId(), text: "Matches whitespace." }];
+    case "Letter": {
+      if (node.unicode) {
+        if (node.letterCase === "lower") return [{ id: nextId(), text: "Matches a Unicode lowercase letter." }];
+        if (node.letterCase === "upper") return [{ id: nextId(), text: "Matches a Unicode uppercase letter." }];
+        return [{ id: nextId(), text: "Matches a Unicode letter." }];
+      }
+      if (node.letterCase === "lower") return [{ id: nextId(), text: "Matches an ASCII lowercase letter." }];
+      if (node.letterCase === "upper") return [{ id: nextId(), text: "Matches an ASCII uppercase letter." }];
+      return [{ id: nextId(), text: "Matches an ASCII letter." }];
+    }
+    case "HexDigit":
+      return [
+        {
+          id: nextId(),
+          text: node.uppercaseOnly ? "Matches a hexadecimal digit (0-9A-F)." : "Matches a hexadecimal digit (0-9A-Fa-f)."
+        }
+      ];
+    case "Start":
+      return [{ id: nextId(), text: "Must align with the start of the string (or line if multiline)." }];
+    case "End":
+      return [{ id: nextId(), text: "Must align with the end of the string (or line if multiline)." }];
+    case "WordBoundary":
+      return [{ id: nextId(), text: "Requires a word boundary." }];
+    case "RawRegex":
+      return [
+        {
+          id: nextId(),
+          text: `Uses a raw regex fragment: ${quote(node.source)}.`
+        }
+      ];
+    case "Sequence": {
+      const out = [];
+      for (const c of node.children) out.push(...explainNode(c));
+      return out;
+    }
+    case "Choice": {
+      const parts = node.children.map((c) => explainNode(c).map((x) => x.text).join(" "));
+      return [
+        {
+          id: nextId(),
+          text: `Matches one of: ${parts.join(" OR ")}.`
+        }
+      ];
+    }
+    case "Repeat": {
+      const inner = explainNode(node.child).map((x) => x.text).join(" ");
+      const q = describeQuantifier(node.min, node.max, node.greedy);
+      return [{ id: nextId(), text: `${q} ${inner}` }];
+    }
+    case "Optional": {
+      const inner = explainNode(node.child).map((x) => x.text).join(" ");
+      const laz = node.greedy ? "" : " (lazy)";
+      return [{ id: nextId(), text: `Optionally${laz}: ${inner}` }];
+    }
+    case "NamedGroup": {
+      const inner = explainNode(node.child).map((x) => x.text).join(" ");
+      return [{ id: nextId(), text: `Captures "${node.name}" as: ${inner}` }];
+    }
+    case "NonCapturing": {
+      return explainNode(node.child);
+    }
+    default: {
+      const _never = node;
+      return _never;
+    }
+  }
+}
+function quote(s) {
+  return JSON.stringify(s);
+}
+function describeQuantifier(min, max, greedy) {
+  const laz = greedy ? "" : "lazy ";
+  if (min === 0 && max === Number.POSITIVE_INFINITY) return `Repeat ${laz}zero or more times:`;
+  if (min === 1 && max === Number.POSITIVE_INFINITY) return `Repeat ${laz}one or more times:`;
+  if (min === 0 && max === 1) return `At most once${greedy ? "" : " (lazy)"}:`;
+  if (min === max) return `Repeat exactly ${min} times:`;
+  if (max === Number.POSITIVE_INFINITY) return `Repeat at least ${min} times:`;
+  return `Repeat between ${min} and ${max} times:`;
+}
+
+// src/diagnose.ts
+function diagnose(root, input, options = {}) {
+  const ast = optimize(root);
+  const { pattern, flags } = compilePattern(ast, options);
+  const anchored = new RegExp(`^(?:${pattern})$`, flags);
+  const m = anchored.exec(input);
+  if (m) {
+    const groups = m.groups ?? {};
+    return { ok: true, match: m[0], index: 0, groups };
+  }
+  const sim = simulate(ast, input, 0, options);
+  if (sim.ok) {
+    if (sim.end === input.length) {
+      return {
+        ok: false,
+        index: 0,
+        message: "Simulation matched the full input but the anchored RegExp did not \u2014 check lazy quantifiers, ambiguous alternatives, or raw fragments.",
+        expected: explainPattern(ast).summary
+      };
+    }
+    return {
+      ok: false,
+      index: sim.end,
+      message: "The pattern matched only a prefix of the input.",
+      expected: explainPattern(ast).summary
+    };
+  }
+  return {
+    ok: false,
+    index: sim.at,
+    message: "The pattern did not match.",
+    expected: sim.expected
+  };
+}
+function simulate(node, input, pos, options) {
+  switch (node.kind) {
+    case "Sequence": {
+      let p = pos;
+      for (const child of node.children) {
+        const r = simulate(child, input, p, options);
+        if (!r.ok) return r;
+        p = r.end;
+      }
+      return { ok: true, end: p };
+    }
+    case "NonCapturing":
+      return simulate(node.child, input, pos, options);
+    case "NamedGroup":
+      return simulate(node.child, input, pos, options);
+    case "Choice": {
+      let lastFail = null;
+      for (const child of node.children) {
+        const r = simulate(child, input, pos, options);
+        if (r.ok) return r;
+        lastFail = r;
+      }
+      return lastFail ?? {
+        ok: false,
+        at: pos,
+        expected: explainPattern(node).summary
+      };
+    }
+    case "Optional": {
+      const tryMatch = matchPrefix(node.child, input, pos, options);
+      if (!tryMatch) return { ok: true, end: pos };
+      return { ok: true, end: pos + tryMatch.len };
+    }
+    case "Repeat": {
+      let p = pos;
+      let count = 0;
+      while (count < node.min) {
+        const m = matchPrefix(node.child, input, p, options);
+        if (!m) {
+          return {
+            ok: false,
+            at: p,
+            expected: explainPattern(node.child).summary
+          };
+        }
+        p += m.len;
+        count += 1;
+      }
+      if (node.greedy) {
+        while (count < node.max) {
+          const m = matchPrefix(node.child, input, p, options);
+          if (!m) break;
+          p += m.len;
+          count += 1;
+        }
+      }
+      return { ok: true, end: p };
+    }
+    default: {
+      const m = matchPrefix(node, input, pos, options);
+      if (!m) {
+        return {
+          ok: false,
+          at: pos,
+          expected: explainPattern(node).summary
+        };
+      }
+      return { ok: true, end: pos + m.len };
+    }
+  }
+}
+function matchPrefix(node, input, pos, options) {
+  const { pattern, flags } = compilePattern(node, {
+    ...options,
+    nonCapturing: true
+  });
+  const re = new RegExp(`^(?:${pattern})`, flags);
+  const slice = input.slice(pos);
+  const m = re.exec(slice);
+  if (!m || m.index !== 0) return null;
+  return { len: m[0].length };
+}
+
+// src/analyze.ts
+function analyzePattern(root) {
+  const ast = optimize(root);
+  const out = [];
+  walk2(ast, (n) => {
+    if (n.kind === "RawRegex") {
+      out.push({
+        severity: "warn",
+        code: "raw-regex",
+        message: "Raw regex fragments bypass semantic guarantees \u2014 audit for ReDoS."
+      });
+    }
+    if (n.kind === "Repeat") {
+      const inner = n.child;
+      if (inner.kind === "Repeat" || inner.kind === "Optional" && n.max === Number.POSITIVE_INFINITY) {
+        out.push({
+          severity: "info",
+          code: "nested-quantifier",
+          message: "Nested quantifiers can cause catastrophic backtracking \u2014 prefer possessive/atomic patterns when available."
+        });
+      }
+    }
+  });
+  return out;
+}
+function walk2(node, fn) {
+  fn(node);
+  switch (node.kind) {
+    case "Sequence":
+      for (const c of node.children) walk2(c, fn);
+      break;
+    case "Choice":
+      for (const c of node.children) walk2(c, fn);
+      break;
+    case "Repeat":
+      walk2(node.child, fn);
+      break;
+    case "Optional":
+      walk2(node.child, fn);
+      break;
+    case "NamedGroup":
+      walk2(node.child, fn);
+      break;
+    case "NonCapturing":
+      walk2(node.child, fn);
+      break;
+    default:
+      break;
+  }
+}
+
+// src/serialize.ts
+function serializePattern(root) {
+  return {
+    schemaVersion: PATTERN_SCHEMA_VERSION,
+    pattern: toJson(optimize(root))
+  };
+}
+function deserializePattern(data) {
+  if (!data || typeof data !== "object") throw new Error("Invalid pattern payload.");
+  const obj = data;
+  if (obj.schemaVersion !== PATTERN_SCHEMA_VERSION) {
+    throw new Error(`Unsupported schemaVersion: ${String(obj.schemaVersion)}`);
+  }
+  if (!obj.pattern) throw new Error("Missing pattern.");
+  return fromJson(obj.pattern);
+}
+function patternToJsonString(root, space) {
+  return JSON.stringify(serializePattern(root), null, space);
+}
+function patternFromJsonString(text) {
+  return deserializePattern(JSON.parse(text));
+}
+function toJson(node) {
+  switch (node.kind) {
+    case "Repeat":
+      return {
+        kind: "Repeat",
+        child: toJson(node.child),
+        min: node.min,
+        max: node.max === Number.POSITIVE_INFINITY ? "__inf__" : node.max,
+        greedy: node.greedy
+      };
+    case "Sequence":
+      return { kind: "Sequence", children: node.children.map(toJson) };
+    case "Choice":
+      return { kind: "Choice", children: node.children.map(toJson) };
+    case "Optional":
+      return { kind: "Optional", child: toJson(node.child), greedy: node.greedy };
+    case "NamedGroup":
+      return { kind: "NamedGroup", name: node.name, child: toJson(node.child) };
+    case "NonCapturing":
+      return { kind: "NonCapturing", child: toJson(node.child) };
+    case "Literal":
+      return { kind: "Literal", value: node.value };
+    case "Any":
+      return { kind: "Any" };
+    case "Digit":
+      return { kind: "Digit", unicode: node.unicode };
+    case "Word":
+      return { kind: "Word", unicode: node.unicode };
+    case "Whitespace":
+      return { kind: "Whitespace", unicode: node.unicode };
+    case "Letter":
+      return { kind: "Letter", letterCase: node.letterCase, unicode: node.unicode };
+    case "HexDigit":
+      return node.uppercaseOnly === void 0 ? { kind: "HexDigit" } : { kind: "HexDigit", uppercaseOnly: node.uppercaseOnly };
+    case "Start":
+      return { kind: "Start" };
+    case "End":
+      return { kind: "End" };
+    case "WordBoundary":
+      return { kind: "WordBoundary" };
+    case "RawRegex":
+      return {
+        kind: "RawRegex",
+        source: node.source,
+        ...node.flags ? { flags: node.flags } : {},
+        ...node.trusted ? { trusted: node.trusted } : {}
+      };
+    default: {
+      const _never = node;
+      return _never;
+    }
+  }
+}
+function fromJson(node) {
+  switch (node.kind) {
+    case "Repeat":
+      return {
+        kind: "Repeat",
+        child: fromJson(node.child),
+        min: node.min,
+        max: node.max === "__inf__" ? Number.POSITIVE_INFINITY : node.max,
+        greedy: node.greedy
+      };
+    case "Sequence":
+      return { kind: "Sequence", children: node.children.map(fromJson) };
+    case "Choice":
+      return { kind: "Choice", children: node.children.map(fromJson) };
+    case "Optional":
+      return { kind: "Optional", child: fromJson(node.child), greedy: node.greedy };
+    case "NamedGroup":
+      return { kind: "NamedGroup", name: node.name, child: fromJson(node.child) };
+    case "NonCapturing":
+      return { kind: "NonCapturing", child: fromJson(node.child) };
+    case "Literal":
+      return { kind: "Literal", value: node.value };
+    case "Any":
+      return { kind: "Any" };
+    case "Digit":
+      return { kind: "Digit", unicode: node.unicode };
+    case "Word":
+      return { kind: "Word", unicode: node.unicode };
+    case "Whitespace":
+      return { kind: "Whitespace", unicode: node.unicode };
+    case "Letter":
+      return {
+        kind: "Letter",
+        letterCase: node.letterCase,
+        unicode: node.unicode
+      };
+    case "HexDigit":
+      return node.uppercaseOnly === void 0 ? { kind: "HexDigit" } : { kind: "HexDigit", uppercaseOnly: node.uppercaseOnly };
+    case "Start":
+      return { kind: "Start" };
+    case "End":
+      return { kind: "End" };
+    case "WordBoundary":
+      return { kind: "WordBoundary" };
+    case "RawRegex":
+      return {
+        kind: "RawRegex",
+        source: node.source,
+        ...node.flags ? { flags: node.flags } : {},
+        ...node.trusted ? { trusted: node.trusted } : {}
+      };
+    default: {
+      const _never = node;
+      return _never;
+    }
+  }
+}
+
+// src/compiled.ts
+function compile(ast, options = {}) {
+  return new CompiledPattern(ast, options);
+}
+var CompiledPattern = class {
+  constructor(ast, compileOpts = {}) {
+    this.ast = ast;
+    this.compileOpts = compileOpts;
+  }
+  ast;
+  compileOpts;
+  /** Compiled regex source (body only). */
+  get source() {
+    return compilePattern(this.ast, this.compileOpts).pattern;
+  }
+  /** Engine flags string, e.g. `"iu"`. */
+  get flags() {
+    return compilePattern(this.ast, this.compileOpts).flags;
+  }
+  /** Compiler warnings (for example raw-regex notices). */
+  get warnings() {
+    return compilePattern(this.ast, this.compileOpts).warnings;
+  }
+  toRegExp() {
+    return toRegExp(this.ast, this.compileOpts);
+  }
+  test(input) {
+    return this.toRegExp().test(input);
+  }
+  exec(input) {
+    return this.toRegExp().exec(input);
+  }
+  explain() {
+    return explainPattern(this.ast);
+  }
+  diagnose(input) {
+    return diagnose(this.ast, input, this.compileOpts);
+  }
+  analyze() {
+    return analyzePattern(this.ast);
+  }
+  toJSON() {
+    return serializePattern(this.ast);
+  }
+  toJSONString(space) {
+    return patternToJsonString(this.ast, space);
+  }
+};
+
+// src/builder.ts
+var MatchBuilder = class {
+  constructor(defaults = {}) {
+    this.defaults = defaults;
+  }
+  defaults;
+  parts = [];
+  /** Anchor start (`^`). */
+  start() {
+    this.parts.push(start());
+    return this;
+  }
+  /** Anchor end (`$`). */
+  end() {
+    this.parts.push(end());
+    return this;
+  }
+  boundary() {
+    this.parts.push(wordBoundary());
+    return this;
+  }
+  /** Literal text segment (escaped on compile). */
+  text(value) {
+    this.parts.push(literal(value));
+    return this;
+  }
+  /** Alias of `text`. */
+  literal(value) {
+    return this.text(value);
+  }
+  dash() {
+    this.parts.push(dash());
+    return this;
+  }
+  /** Append any composed pattern fragment. */
+  take(fragment) {
+    this.parts.push(fragment);
+    return this;
+  }
+  digit() {
+    this.parts.push(digit());
+    return this;
+  }
+  lettersUpper() {
+    this.parts.push(letter({ case: "upper" }));
+    return this;
+  }
+  lettersLower() {
+    this.parts.push(letter({ case: "lower" }));
+    return this;
+  }
+  named(name, inner) {
+    this.parts.push(namedGroup(name, inner));
+    return this;
+  }
+  build() {
+    return seq(...this.parts);
+  }
+  compile(options = {}) {
+    const merged = {
+      ...options,
+      flags: { ...this.defaults.flags, ...options.flags }
+    };
+    return new CompiledPattern(this.build(), merged);
+  }
+};
+function match(opts) {
+  return new MatchBuilder(opts ?? {});
+}
+function regex(opts) {
+  return match(opts);
+}
+
+// src/presets.ts
+var presets = {
+  /** RFC 4122 UUID (case-insensitive hex). Version nibble not enforced here. */
+  uuid() {
+    return seq(
+      start(),
+      hexDigit().exactly(8),
+      literal("-"),
+      repeat(seq(hexDigit().exactly(4), literal("-")), 3, 3),
+      hexDigit().exactly(12),
+      end()
+    );
+  },
+  /** Conservative ASCII slug: lowercase letters, digits, single dashes between segments. */
+  slug() {
+    const segment = repeat(alt(letter({ case: "lower" }), digit()), 1, Number.POSITIVE_INFINITY);
+    return seq(
+      start(),
+      segment,
+      repeat(seq(dash(), segment), 0, Number.POSITIVE_INFINITY),
+      end()
+    );
+  },
+  hexColor(opts = {}) {
+    const modes = [];
+    if (opts.short !== false) modes.push(seq(literal("#"), hexDigit().exactly(3)));
+    modes.push(seq(literal("#"), hexDigit().exactly(6)));
+    if (opts.alpha) modes.push(seq(literal("#"), hexDigit().exactly(8)));
+    const body = modes.length === 1 ? modes[0] : alt(...modes);
+    return seq(start(), body, end());
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CompiledPattern,
+  MatchBuilder,
+  PATTERN_SCHEMA_VERSION,
+  alt,
+  analyzePattern,
+  anyChar,
+  booleanLiteral,
+  compile,
+  compilePattern,
+  dash,
+  deserializePattern,
+  diagnose,
+  digit,
+  dot,
+  end,
+  explainPattern,
+  hexDigit,
+  integer,
+  letter,
+  literal,
+  match,
+  namedGroup,
+  nonCapturing,
+  optimize,
+  optional,
+  patternFromJsonString,
+  patternToJsonString,
+  presets,
+  raw,
+  regex,
+  repeat,
+  seq,
+  serializePattern,
+  start,
+  toRegExp,
+  underscore,
+  whitespace,
+  word,
+  wordBoundary
+});