parseman 0.32.0 → 0.34.0

package/dist/index.js

@@ -1,4 +1,9 @@
 // src/combinators/first-set.ts
+function resolveNamedRef(p, resolve) {
+  if (resolve === void 0) return void 0;
+  const name = p._ruleName;
+  return name === void 0 ? void 0 : resolve(name);
+}
 function union(a, b) {
   if (a.kind === "any" || b.kind === "any") return { kind: "any" };
   if (a.kind === "empty") return b;
@@ -36,10 +41,10 @@ function any() {
 function empty() {
   return { kind: "empty" };
 }
-function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
+function matchesEmpty(p, seen = /* @__PURE__ */ new Set(), resolve) {
   if (seen.has(p)) return true;
   seen.add(p);
-  const me = (c) => matchesEmpty(c, seen);
+  const me = (c) => matchesEmpty(c, seen, resolve);
   const d = p._def;
   switch (d.tag) {
     case "literal":
@@ -56,8 +61,16 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
     case "many":
     case "optional":
     case "not":
+    case "peek":
       return true;
     // zero repetitions / absent / lookahead
+    // Default `sepBy` is `(item (sep item)*)?` — it MATCHES THE EMPTY STRING.
+    // Any `min >= 1` requires that many ITEMS, so it is nullable only when the
+    // item is. (Keying this off `min === 1` reported every `{ min: 2 }` list as
+    // nullable — safe, but wrong, and it put a bogus `nullable-prefix` note on
+    // the gating diagnostic for a list that can never match empty.)
+    case "sepBy":
+      return d.min >= 1 ? me(d.parser) : true;
     case "oneOrMore":
       return me(d.parser);
     case "sequence":
@@ -81,7 +94,8 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
       try {
         return me(d.thunk());
       } catch {
-        return true;
+        const t = resolveNamedRef(p, resolve);
+        return t ? me(t) : true;
       }
     default:
       return true;
@@ -90,18 +104,45 @@ function matchesEmpty(p, seen = /* @__PURE__ */ new Set()) {
 function isZeroWidthAssertion(p) {
   return p._def.tag === "not";
 }
+function isPositiveLookahead(p) {
+  return p._def.tag === "peek";
+}
+function narrowBy(acc, constraint) {
+  if (constraint.kind === "any") return acc;
+  if (acc === null) return constraint;
+  if (acc.kind === "any") return constraint;
+  if (acc.kind === "empty" || constraint.kind === "empty") return { kind: "empty" };
+  const ranges = [];
+  for (const a of acc.ranges) for (const b of constraint.ranges) {
+    const lo = Math.max(a.lo, b.lo);
+    const hi = Math.min(a.hi, b.hi);
+    if (lo <= hi) ranges.push({ lo, hi });
+  }
+  return ranges.length === 0 ? { kind: "empty" } : { kind: "ranges", ranges };
+}
+function applyAssertion(fs, assertion) {
+  if (assertion === null) return fs;
+  if (fs.kind === "empty") return assertion;
+  return narrowBy(fs, assertion) ?? fs;
+}
 function sequenceFirstSet(parsers) {
   let fs = empty();
+  let assertion = null;
   for (const p of parsers) {
+    if (isPositiveLookahead(p)) {
+      assertion = narrowBy(assertion, p._meta.firstSet);
+      continue;
+    }
     if (!isZeroWidthAssertion(p)) fs = union(fs, p._meta.firstSet);
-    if (!matchesEmpty(p)) return fs;
+    if (!matchesEmpty(p)) return applyAssertion(fs, assertion);
   }
-  return fs;
+  return applyAssertion(fs, assertion);
 }
-function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
+function firstSetOf(p, seen = /* @__PURE__ */ new Set(), resolve) {
   if (seen.has(p)) return any();
   seen.add(p);
-  const fs = (c) => firstSetOf(c, seen);
+  const fs = (c) => firstSetOf(c, seen, resolve);
+  const empties = (c) => matchesEmpty(c, /* @__PURE__ */ new Set(), resolve);
   const d = p._def;
   switch (d.tag) {
     case "literal":
@@ -113,7 +154,8 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
       try {
         return fs(d.thunk());
       } catch {
-        return any();
+        const t = resolveNamedRef(p, resolve);
+        return t ? fs(t) : any();
       }
     case "choice": {
       let out = empty();
@@ -122,11 +164,20 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
     }
     case "sequence": {
       let out = empty();
+      let assertion = null;
       for (const term of d.parsers) {
+        if (isPositiveLookahead(term)) {
+          assertion = narrowBy(assertion, fs(term));
+          continue;
+        }
         if (!isZeroWidthAssertion(term)) out = union(out, fs(term));
-        if (!matchesEmpty(term)) return out;
+        if (!empties(term)) return applyAssertion(out, assertion);
       }
-      return out;
+      return applyAssertion(out, assertion);
+    }
+    case "peek": {
+      const inner = d.parser;
+      return empties(inner) ? any() : fs(inner);
     }
     case "oneOrMore":
     case "many":
@@ -142,6 +193,7 @@ function firstSetOf(p, seen = /* @__PURE__ */ new Set()) {
       return fs(d.parser);
     case "sepBy":
       return fs(d.parser);
+    // both min 0 and min 1 start with the item
     case "skip":
       return fs(d.main);
     default:
@@ -826,9 +878,46 @@ function firstSetFromRegex(source) {
   return { firstSet: firstSet(ast), canMatchNewline: firstCanBeNewline(ast) };
 }
 
+// src/combinators/case-fold.ts
+function canonical(ch2) {
+  const u = ch2.toUpperCase();
+  if (u.length !== 1) return ch2;
+  if (ch2.codePointAt(0) >= 128 && u.codePointAt(0) < 128) return ch2;
+  return u;
+}
+var foldIndex = null;
+function buildFoldIndex() {
+  const byCanonical = /* @__PURE__ */ new Map();
+  for (let cp = 0; cp < 65536; cp++) {
+    if (cp >= 55296 && cp <= 57343) continue;
+    const key = canonical(String.fromCharCode(cp));
+    const bucket = byCanonical.get(key);
+    if (bucket) bucket.push(cp);
+    else byCanonical.set(key, [cp]);
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const members of byCanonical.values()) {
+    if (members.length < 2) continue;
+    for (const cp of members) index.set(cp, members);
+  }
+  return index;
+}
+function caseFoldVariants(cp) {
+  if (cp < 128) {
+    if (cp >= 65 && cp <= 90) return [cp, cp + 32];
+    if (cp >= 97 && cp <= 122) return [cp, cp - 32];
+    return [cp];
+  }
+  if (cp > 65535) return [cp];
+  foldIndex ??= buildFoldIndex();
+  return foldIndex.get(cp) ?? [cp];
+}
+
 // src/combinators/keywords.ts
-function word(str, boundary = "_0-9A-Za-z") {
-  return keywords([str], { boundary });
+function word(str, boundaryOrOpts, opts) {
+  const boundary = typeof boundaryOrOpts === "string" ? boundaryOrOpts : "_0-9A-Za-z";
+  const rest = typeof boundaryOrOpts === "object" && boundaryOrOpts !== null ? boundaryOrOpts : opts;
+  return keywords([str], { ...rest, boundary });
 }
 function makeWord(boundary = "_0-9A-Za-z") {
   return (str) => keywords([str], { boundary });
@@ -840,7 +929,7 @@ function keywords(words, opts = {}) {
   const sorted = [...new Set(words)].sort((a, b) => b.length - a.length);
   const alt = sorted.map(escapeRe).join("|");
   const boundary = opts.boundary ? `(?![${opts.boundary}])` : "";
-  const flags = opts.caseInsensitive ? "iuy" : "uy";
+  const flags = opts.caseInsensitive ? "iy" : "uy";
   const re = new RegExp(`(?:${alt})${boundary}`, flags);
   let firstSet2 = empty();
   for (const w of sorted) {
@@ -848,10 +937,7 @@ function keywords(words, opts = {}) {
     const cp = w.codePointAt(0);
     firstSet2 = union(firstSet2, fromChar(cp));
     if (opts.caseInsensitive) {
-      const u = String.fromCodePoint(cp).toUpperCase().codePointAt(0);
-      const l = String.fromCodePoint(cp).toLowerCase().codePointAt(0);
-      if (u !== void 0) firstSet2 = union(firstSet2, fromChar(u));
-      if (l !== void 0) firstSet2 = union(firstSet2, fromChar(l));
+      for (const v2 of caseFoldVariants(cp)) firstSet2 = union(firstSet2, fromChar(v2));
     }
   }
   const meta = { firstSet: firstSet2, canMatchNewline: false, isTrivia: false };
@@ -1000,6 +1086,7 @@ function deriveExpected(c) {
     case "oneOrMore":
     case "transform":
     case "not":
+    case "peek":
       return deriveExpected(def.parser);
     case "lazy": {
       const name = c._ruleName;
@@ -1473,6 +1560,13 @@ function rollbackTrivia(ctx, mark) {
   rollbackCstCapture(ctx, { raw: mark.raw, tlog: mark.tlog, leaves: mark.leaves, fields: mark.fields, errors: mark.errors });
   if (ctx._triviaLog) ctx._triviaLog.length = mark.log;
 }
+function saveLookaheadMark(ctx) {
+  return { ...saveTriviaMark(ctx), probeBest: ctx._probe ? ctx._probe.best : null };
+}
+function rollbackLookahead(ctx, mark) {
+  rollbackTrivia(ctx, mark);
+  if (ctx._probe) ctx._probe.best = mark.probeBest;
+}
 function scanWithLabels(input, cur, ctx) {
   const triviaP = ctx.trivia;
   const spec = analyzeLabeledTrivia(triviaP);
@@ -1870,13 +1964,26 @@ function repItem(combinator, input, cur, ctx, guardable) {
   }
   return { value: result.value, end: result.span.end };
 }
-function many(combinator) {
+function resolveBounds(what, opts) {
+  const min = opts.min ?? 0;
+  const max = opts.max ?? Infinity;
+  const bad = (msg) => {
+    throw new RangeError(`parseman: ${what} ${msg}`);
+  };
+  if (!Number.isInteger(min) || min < 0) bad(`min must be a non-negative integer (got ${String(opts.min)})`);
+  if (max !== Infinity && (!Number.isInteger(max) || max < 1)) bad(`max must be a positive integer (got ${String(opts.max)})`);
+  if (max < min) bad(`max (${max}) is less than min (${min}) \u2014 the combinator could never succeed`);
+  return { min, max };
+}
+function many(combinator, opts = {}) {
+  const { min, max } = resolveBounds("many()", opts);
+  if (min >= 1) return atLeast(combinator, min, max);
   const meta = {
     firstSet: combinator._meta.firstSet,
     canMatchNewline: combinator._meta.canMatchNewline,
     isTrivia: false
   };
-  const def = { tag: "many", parser: combinator, min: 0 };
+  const def = { tag: "many", parser: combinator, min: 0, ...max === Infinity ? {} : { max } };
   let expected;
   const guardable = combinator._meta.firstSet.kind !== "any" && !matchesEmpty(combinator);
   return {
@@ -1886,7 +1993,9 @@ function many(combinator) {
     parse(input, pos, ctx) {
       const values = def.valueUnused ? void 0 : [];
       let cur = pos;
+      let count = 0;
       while (cur < input.length) {
+        if (count >= max) break;
         const item = repItem(combinator, input, cur, ctx, guardable);
         if (item === "stop") break;
         if ("fail" in item) {
@@ -1897,23 +2006,28 @@ function many(combinator) {
           const { error, end } = recoverScan(input, item.failPos, ctx, sync, expected);
           if (values !== void 0) values.push(error);
           captureError(ctx, error);
+          count++;
           cur = end;
           continue;
         }
         if (values !== void 0) values.push(item.value);
+        count++;
         cur = item.end;
       }
       return { ok: true, value: values ?? void 0, span: { start: pos, end: cur } };
     }
   };
 }
-function oneOrMore(combinator) {
+function oneOrMore(combinator, opts = {}) {
+  return many(combinator, { ...opts, min: opts.min ?? 1 });
+}
+function atLeast(combinator, min, max) {
   const meta = {
     firstSet: combinator._meta.firstSet,
     canMatchNewline: combinator._meta.canMatchNewline,
     isTrivia: false
   };
-  const def = { tag: "oneOrMore", parser: combinator, min: 1 };
+  const def = { tag: "oneOrMore", parser: combinator, min, ...max === Infinity ? {} : { max } };
   let expected;
   const guardable = combinator._meta.firstSet.kind !== "any" && !matchesEmpty(combinator);
   return {
@@ -1925,7 +2039,19 @@ function oneOrMore(combinator) {
       if (!first.ok) return first;
       const values = def.valueUnused ? void 0 : [first.value];
       let cur = first.span.end;
+      let count = 1;
+      while (count < min) {
+        const item = repItem(combinator, input, cur, ctx, guardable);
+        if (item === "stop" || "fail" in item) {
+          expected ??= deriveExpected(combinator);
+          return { ok: false, expected: expected.length > 0 ? expected : [combinator._tag], span: { start: cur, end: cur } };
+        }
+        if (values !== void 0) values.push(item.value);
+        cur = item.end;
+        count++;
+      }
       while (cur < input.length) {
+        if (count >= max) break;
         const item = repItem(combinator, input, cur, ctx, guardable);
         if (item === "stop") break;
         if ("fail" in item) {
@@ -1936,10 +2062,12 @@ function oneOrMore(combinator) {
           const { error, end } = recoverScan(input, item.failPos, ctx, sync, expected);
           if (values !== void 0) values.push(error);
           captureError(ctx, error);
+          count++;
           cur = end;
           continue;
         }
         if (values !== void 0) values.push(item.value);
+        count++;
         cur = item.end;
       }
       return { ok: true, value: values ?? void 0, span: { start: pos, end: cur } };
@@ -1969,17 +2097,33 @@ function optional(combinator) {
     }
   };
 }
-function sepBy(combinator, separator) {
+function oneOrMoreSep(combinator, separator, opts = {}) {
+  return sepBy(combinator, separator, { ...opts, min: opts.min ?? 1 });
+}
+function sepBy(combinator, separator, opts = {}) {
+  const { min, max } = resolveBounds("sepBy()", opts);
+  const trailing = opts.trailing ?? "forbid";
   const meta = {
     firstSet: combinator._meta.firstSet,
     canMatchNewline: combinator._meta.canMatchNewline || separator._meta.canMatchNewline,
     isTrivia: false
   };
   let expected;
+  const failAt2 = (at) => {
+    expected ??= deriveExpected(combinator);
+    return { ok: false, expected: expected.length > 0 ? expected : [combinator._tag], span: { start: at, end: at } };
+  };
   return {
     _tag: "sepBy",
     _meta: meta,
-    _def: { tag: "sepBy", parser: combinator, separator },
+    _def: {
+      tag: "sepBy",
+      parser: combinator,
+      separator,
+      min,
+      ...max === Infinity ? {} : { max },
+      ...trailing === "forbid" ? {} : { trailing }
+    },
     parse(input, pos, ctx) {
       const first = combinator.parse(input, pos, ctx);
       const values = [];
@@ -1990,6 +2134,7 @@ function sepBy(combinator, separator) {
       } else {
         const term = ctx._tolerant ? ctx._sync : void 0;
         if (term === void 0 || matchesAt(term, input, pos, ctx)) {
+          if (min >= 1) return failAt2(pos);
           return { ok: true, value: [], span: { start: pos, end: pos } };
         }
         expected ??= deriveExpected(combinator);
@@ -1999,6 +2144,7 @@ function sepBy(combinator, separator) {
         cur = rec.end;
       }
       while (cur < input.length) {
+        if (values.length >= max) break;
         const loopMark = saveTriviaMark(ctx);
         let sepPos = cur;
         if (ctx.trivia) {
@@ -2015,6 +2161,7 @@ function sepBy(combinator, separator) {
           rollbackTrivia(ctx, loopMark);
           break;
         }
+        const sepMark = trailing === "forbid" ? void 0 : saveTriviaMark(ctx);
         let nextPos = sep.span.end;
         if (ctx.trivia) {
           if (needsDeferredTriviaCommit(ctx)) {
@@ -2036,12 +2183,18 @@ function sepBy(combinator, separator) {
             cur = rec.end;
             continue;
           }
+          if (sepMark !== void 0) {
+            rollbackTrivia(ctx, sepMark);
+            cur = sep.span.end;
+            break;
+          }
           rollbackTrivia(ctx, loopMark);
           break;
         }
         values.push(next.value);
         cur = next.span.end;
       }
+      if (values.length < min) return failAt2(cur);
       return { ok: true, value: values, span: { start: pos, end: cur } };
     }
   };
@@ -2131,6 +2284,7 @@ function markUnusedValues(root) {
         visit(def.separator, false);
         return;
       case "not":
+      case "peek":
         visit(def.parser, false);
         return;
       case "grammar":
@@ -2249,9 +2403,9 @@ function not(combinator) {
     _meta: meta,
     _def: { tag: "not", parser: combinator },
     parse(input, pos, ctx) {
-      const mark = saveCstMark(ctx);
+      const mark = saveLookaheadMark(ctx);
       const result = combinator.parse(input, pos, ctx);
-      rollbackCstCapture(ctx, mark);
+      rollbackLookahead(ctx, mark);
       if (result.ok) {
         return { ok: false, expected: [`not(${combinator._tag})`], span: { start: pos, end: pos } };
       }
@@ -2260,6 +2414,28 @@ function not(combinator) {
   };
 }
 
+// src/combinators/peek.ts
+function peek(combinator) {
+  const meta = {
+    // A nullable body imposes no first-char constraint — `any()`, not its set.
+    firstSet: matchesEmpty(combinator) ? any() : combinator._meta.firstSet,
+    canMatchNewline: false,
+    isTrivia: false
+  };
+  return {
+    _tag: "peek",
+    _meta: meta,
+    _def: { tag: "peek", parser: combinator },
+    parse(input, pos, ctx) {
+      const mark = saveLookaheadMark(ctx);
+      const result = combinator.parse(input, pos, ctx);
+      rollbackLookahead(ctx, mark);
+      if (result.ok) return { ok: true, value: null, span: { start: pos, end: pos } };
+      return { ok: false, expected: [`peek(${combinator._tag})`], span: { start: pos, end: pos } };
+    }
+  };
+}
+
 // src/compiler/build-arity.ts
 var PARAM_LIST_RE = (
   // (params) => ...   |   function name?(params) ...   |   single-ident arrow `x => ...`
@@ -2358,6 +2534,7 @@ function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
     case "expect":
     case "withCtx":
     case "not":
+    case "peek":
       return parserHasOwnFields(d.parser, seen);
     default:
       return false;
@@ -2397,6 +2574,7 @@ function parserHasTriviaSite(p, seen = /* @__PURE__ */ new Set()) {
     case "expect":
     case "withCtx":
     case "not":
+    case "peek":
     case "field":
       return parserHasTriviaSite(d.parser, seen);
     case "choice":
@@ -2446,6 +2624,7 @@ function parserEnablesTriviaCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "expect":
     case "withCtx":
     case "not":
+    case "peek":
       return parserEnablesTriviaCapture(d.parser, seen);
     // leaf() clears the inner CST/trivia collector and publishes only its own
     // terminal result. An inner parser() capture cannot reach this node.
@@ -2821,7 +3000,7 @@ function leaf(root, fn) {
 }
 
 // src/version.ts
-var PARSEMAN_VERSION = "0.32.0";
+var PARSEMAN_VERSION = "0.34.0";
 
 // src/analysis/gating.ts
 var isAny = (fs) => fs.kind === "any";
@@ -2861,14 +3040,15 @@ function firstSetToString(fs) {
 var ruleNameOf = (p) => p._ruleName;
 var SUGGESTIONS = {
   "broad-recognizer": "if this arm leads with a keyword regex, use word('kw', boundary) / keywords([...]) \u2014 they expose an EXACT, gating first-set and lower to the same charCodeAt scan. A genuine scanTo fallback is fine; accept it in the gating snapshot if intentional.",
-  "leading-not": "let the arm lead with its actual consuming terminal (first-sets gate it automatically); keep not(...) only as a TRAILING boundary. Do not hand-roll not(not(...)) to fake gating.",
-  "nullable-prefix": "a leading optional/many lets a later, broad term start the arm. Split the empty case into its own arm, or gate on the prefix first char.",
+  "leading-not": "let the arm lead with its actual consuming terminal (first-sets gate it automatically); keep not(...) only as a TRAILING boundary. Do not hand-roll not(not(...)) to fake gating \u2014 use peek(X), which is zero-width AND carries X first-set.",
+  "nullable-prefix": "a leading optional/many lets a later, broad term start the arm. Split the empty case into its own arm, or gate on the prefix first char. A plain sepBy(item, sep) is ALSO nullable \u2014 pass { min: 1 } for a list that cannot be empty.",
   "cross-artifact-ref": "parseman >=0.32.0 resolves a g.Foo ref first-set at fuse time; if still ANY the target rule is itself ungated \u2014 analyze it and give it a concrete non-nullable lead.",
   "opaque-wrapper": "this wrapper (guard/withCtx/recover) contributes no first char; put a concrete leading terminal before it.",
   "ref-cycle": "a recursive ref resolved to ANY; ensure the recursion has a concrete terminal lead on the base case."
 };
-function classifyBroadArm(arm) {
+function classifyBroadArm(arm, resolve) {
   const seen = /* @__PURE__ */ new Set();
+  const relabel = (inner, cause, detail) => ({ cause, detail, ...inner?.unresolvedExternal ? { unresolvedExternal: true } : {} });
   const walk2 = (p) => {
     if (seen.has(p)) return { cause: "ref-cycle", detail: "ref cycle" };
     seen.add(p);
@@ -2880,6 +3060,10 @@ function classifyBroadArm(arm) {
         return isAny(p._meta.firstSet) ? { cause: "broad-recognizer", detail: `broad recognizer (${d.tag})` } : null;
       case "not":
         return { cause: "leading-not", detail: "leading not(...) (first-set ANY)" };
+      // peek() CARRIES its body's first-set, so it is only broad when the body is
+      // (or the body is nullable) — walk in for the real cause.
+      case "peek":
+        return walk2(d.parser);
       case "scanTo":
         return { cause: "broad-recognizer", detail: "scanTo (any first char)" };
       // `guard` (the `gate()` state predicate) has a genuinely-`any` first-set of
@@ -2896,18 +3080,23 @@ function classifyBroadArm(arm) {
         return walk2(d.parser);
       case "lazy": {
         const name = p._ruleName;
+        let target;
         try {
-          const inner = walk2(d.thunk());
-          if (name !== void 0) return inner ? { cause: "cross-artifact-ref", detail: `via ref g.${name} \u2192 ${inner.detail}` } : null;
-          return inner;
+          target = d.thunk();
         } catch {
-          return { cause: "cross-artifact-ref", detail: `unresolved ref${name ? ` g.${name}` : ""}` };
+          const bound = name !== void 0 ? resolve?.(name) : void 0;
+          if (bound === void 0)
+            return { cause: "cross-artifact-ref", detail: `unresolved ref${name ? ` g.${name}` : ""}`, unresolvedExternal: name !== void 0 };
+          target = bound;
         }
+        const inner = walk2(target);
+        if (name !== void 0) return inner ? relabel(inner, "cross-artifact-ref", `via ref g.${name} \u2192 ${inner.detail}`) : null;
+        return inner;
       }
       case "optional":
       case "many": {
         const inner = walk2(d.parser);
-        return { cause: "nullable-prefix", detail: inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term" };
+        return relabel(inner, "nullable-prefix", inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term");
       }
       case "oneOrMore":
       case "transform":
@@ -2929,13 +3118,13 @@ function classifyBroadArm(arm) {
             sawNullablePrefix = true;
             continue;
           }
-          if (isAny(firstSetOf(t))) {
+          if (isAny(firstSetOf(t, /* @__PURE__ */ new Set(), resolve))) {
             const inner = walk2(t);
             if (sawNullablePrefix)
-              return { cause: "nullable-prefix", detail: inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term" };
+              return relabel(inner, "nullable-prefix", inner ? `nullable prefix \u2192 ${inner.detail}` : "nullable prefix to broad term");
             return inner ?? { cause: "broad-recognizer", detail: "sequence leading term is broad" };
           }
-          if (matchesEmpty(t)) {
+          if (matchesEmpty(t, /* @__PURE__ */ new Set(), resolve)) {
             sawNullablePrefix = true;
             continue;
           }
@@ -2946,7 +3135,7 @@ function classifyBroadArm(arm) {
       case "choice": {
         for (const a of d.parsers) {
           const r = walk2(a);
-          if (r) return { cause: r.cause, detail: `choice arm \u2192 ${r.detail}` };
+          if (r) return relabel(r, r.cause, `choice arm \u2192 ${r.detail}`);
         }
         return null;
       }
@@ -2983,7 +3172,7 @@ function detectAntiPatterns(rule, arms) {
           kind: "double-not",
           rule,
           armIndex: i,
-          message: "not(not(...)) hand-rolls automatic first-char gating and MISCOMPILES among shared-first-char sibling arms (its first-set is ANY, poisoning dispatch). Remove it; let the arm lead with its consuming terminal, or use word()/keywords() for an exact first-set."
+          message: "not(not(...)) hand-rolls automatic first-char gating and MISCOMPILES among shared-first-char sibling arms (its first-set is ANY, poisoning dispatch). Prefer letting the arm lead with its consuming terminal; where a real positive lookahead IS needed, use peek(X) \u2014 zero-width like not(not(X)) but it CARRIES X's first-set, so the arm still dispatches."
         });
       } else {
         out.push({
@@ -3006,6 +3195,9 @@ function detectAntiPatterns(rule, arms) {
   return out;
 }
 function analyzeGating(entry, opts) {
+  return analyzeGatingRules([[ruleNameOf(entry) ?? opts?.entryName ?? "<entry>", entry]], opts);
+}
+function analyzeGatingRules(ruleMap, opts) {
   const raw = [];
   const antiPatterns = [];
   const visited = /* @__PURE__ */ new Set();
@@ -3015,7 +3207,7 @@ function analyzeGating(entry, opts) {
     const d = p._def;
     const rule = ruleNameOf(p) ?? enclosingRule;
     if (d.tag === "choice") {
-      raw.push({ g: analyzeChoice(p, d, rule), rule });
+      raw.push({ g: analyzeChoice(p, d, rule, opts?.resolveRef), rule });
       antiPatterns.push(...detectAntiPatterns(rule, d.parsers));
     }
     const rec = d;
@@ -3032,7 +3224,7 @@ function analyzeGating(entry, opts) {
     }
     for (const k of kids) visit(k, rule);
   };
-  visit(entry, ruleNameOf(entry) ?? "<entry>");
+  for (const [name, root] of ruleMap) visit(root, ruleNameOf(root) ?? name);
   const perRule = /* @__PURE__ */ new Map();
   for (const r of raw) perRule.set(r.rule, (perRule.get(r.rule) ?? 0) + 1);
   const seenInRule = /* @__PURE__ */ new Map();
@@ -3048,18 +3240,19 @@ function analyzeGating(entry, opts) {
   });
   const gated = choices.filter((c) => c.gates === "yes").length;
   const recoverable = choices.filter((c) => c.gates === "recoverable").length;
-  const ungated = choices.filter((c) => c.gates === "no" && !c.accepted);
+  const ungated = choices.filter((c) => c.gates === "no" && !c.accepted && !c.deferred);
   const accepted = choices.filter((c) => c.gates === "no" && c.accepted);
+  const deferred = choices.filter((c) => c.gates === "no" && !c.accepted && c.deferred);
   const acceptedUnused = [...accept].filter((id) => !usedAccept.has(id));
-  return { totalChoices: choices.length, gated, recoverable, ungated, accepted, acceptedUnused, choices, antiPatterns };
+  return { totalChoices: choices.length, gated, recoverable, ungated, accepted, deferred, acceptedUnused, choices, antiPatterns };
 }
-function analyzeChoice(p, d, rule) {
+function analyzeChoice(p, d, rule, resolve) {
   const arms = d.parsers;
   const shallow = arms.map((a) => a._meta.firstSet);
-  const deep = arms.map((a) => firstSetOf(a));
+  const deep = arms.map((a) => firstSetOf(a, /* @__PURE__ */ new Set(), resolve));
   const anyArms = deep.map((fs, index) => ({ fs, index })).filter((x) => isAny(x.fs)).map(({ index }) => {
-    const { cause, detail } = classifyBroadArm(arms[index]);
-    return { index, cause, detail, shallowAnyOnly: false, suggestion: SUGGESTIONS[cause] };
+    const { cause, detail, unresolvedExternal } = classifyBroadArm(arms[index], resolve);
+    return { index, cause, detail, shallowAnyOnly: false, unresolvedExternal: unresolvedExternal === true, suggestion: SUGGESTIONS[cause] };
   });
   const overlaps = [];
   for (let i = 0; i < deep.length; i++)
@@ -3075,10 +3268,12 @@ function analyzeChoice(p, d, rule) {
   if (d.disjoint) gates = "yes";
   else if (anyArms.length === 0 && overlaps.length === 0) gates = "recoverable";
   else gates = "no";
+  const deferred = gates === "no" && overlaps.length === 0 && anyArms.length > 0 && anyArms.every((a) => a.unresolvedExternal);
   return {
     rule,
     strategy: d.strategy?.tag ?? "firstMatch",
     gates,
+    deferred,
     combinedFirstSet: { shallow: combine(shallow), deep: combine(deep) },
     anyArms,
     overlaps
@@ -3245,6 +3440,7 @@ function children(def, winners) {
     case "field":
     case "grammar":
     case "not":
+    case "peek":
     case "node":
     case "guard":
     case "withCtx":
@@ -5010,6 +5206,9 @@ function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
     case "keywords":
     case "guard":
     case "not":
+    // peek(): emitted under a non-capturing probe ctx and zero-width on both
+    // outcomes, so it can never leave a partial capture behind.
+    case "peek":
     case "trivia":
     case "token":
     case "leaf":
@@ -5081,6 +5280,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "leaf":
       return true;
     case "not":
+    case "peek":
     case "guard":
     case "trivia":
     case "unknown":
@@ -5207,6 +5407,7 @@ function emitKeywordsFast(def, ctx, pos) {
   if (def.words.length === 0 || def.words.some((w) => w.length === 0)) return null;
   if (def.words.some((w) => Array.from(w).length !== w.length)) return null;
   if (def.caseInsensitive && def.boundary) return null;
+  if (def.caseInsensitive && def.words.some((w) => w.split("").some((c) => c.charCodeAt(0) > 127))) return null;
   let boundary = null;
   if (def.boundary) {
     let body = def.boundary;
@@ -5254,7 +5455,7 @@ function emitKeywords(def, ctx, pos) {
   if (fast) return fast;
   const alt = def.words.map(escapeKeywordRe).join("|");
   const boundary = def.boundary ? `(?![${def.boundary}])` : "";
-  const flags = def.caseInsensitive ? "iuy" : "uy";
+  const flags = def.caseInsensitive ? "iy" : "uy";
   const source = `(?:${alt})${boundary}`;
   const key = `${source}/${flags}`;
   let rName = ctx.regexMap.get(key);
@@ -5400,6 +5601,7 @@ function failsAtStart(p) {
     case "keywords":
     case "guard":
     case "not":
+    case "peek":
       return true;
     case "transform":
     case "label":
@@ -5813,14 +6015,17 @@ function emitMany(def, ctx, pos) {
   ];
   const mySyncV = ctx.recovery ? v(ctx, "_mysy") : "";
   if (ctx.recovery) stmts.push(`${ind(ctx)}const ${mySyncV} = _ctx._sync`);
-  if (def.min === 1) {
+  for (let i = 0; i < def.min; i++) {
     const firstR = emit(def.parser, ctx, curV);
     stmts.push(...firstR.stmts);
     if (wantValue) stmts.push(`${ind(ctx)}${arrV}.push(${firstR.valueVar})`);
     stmts.push(`${ind(ctx)}${curV} = ${firstR.endVar}`);
   }
+  const maxV = def.max === void 0 ? null : wantValue ? `${arrV}.length` : v(ctx, "_cnt");
+  if (maxV !== null && !wantValue) stmts.push(`${ind(ctx)}let ${maxV} = ${def.min}`);
   stmts.push(`${ind(ctx)}while (${curV} < input.length) {`);
   ctx.indent++;
+  if (maxV !== null) stmts.push(`${ind(ctx)}if (${maxV} >= ${def.max}) break`);
   let itemPos = curV;
   let rollback = "";
   if (ctx.activeTrivia) {
@@ -5861,7 +6066,7 @@ function emitMany(def, ctx, pos) {
       `${ind(ctx)}if (!${iterOk}) {`,
       `${ind(ctx)}  ${rollback}if (_ctx._tolerant && ${mySyncV} !== undefined && !_ctx._rec.at(${mySyncV}, input, ${itemPos}, _ctx)) {`,
       `${ind(ctx)}    const ${rrV} = _ctx._rec.scan(input, ${itemPos}, _ctx, ${mySyncV}, ${exp})`,
-      ...wantValue ? [`${ind(ctx)}    ${arrV}.push(${rrV}.error)`] : [],
+      ...wantValue ? [`${ind(ctx)}    ${arrV}.push(${rrV}.error)`] : maxV !== null ? [`${ind(ctx)}    ${maxV}++`] : [],
       `${ind(ctx)}    _ctx._rec.capture(_ctx, ${rrV}.error)`,
       `${ind(ctx)}    ${curV} = ${rrV}.end`,
       `${ind(ctx)}    continue`,
@@ -5874,6 +6079,7 @@ function emitMany(def, ctx, pos) {
     stmts.push(`${ind(ctx)}if (!${iterOk} || ${iterEnd} <= ${itemPos}) { ${rollback}break }`);
   }
   if (wantValue) stmts.push(`${ind(ctx)}${arrV}.push(${iterVal})`);
+  else if (maxV !== null) stmts.push(`${ind(ctx)}${maxV}++`);
   stmts.push(`${ind(ctx)}${curV} = ${iterEnd}`);
   ctx.indent--;
   stmts.push(`${ind(ctx)}}`);
@@ -5938,8 +6144,8 @@ function emitSepBy(_p, def, ctx, pos) {
     ...rec ? [`${ind(ctx)}const ${mySyncV} = _ctx._sync`] : [],
     ...firstStmts
   ];
-  const failItem = (nextOkVar, itemPosVar, rb, originalFail) => {
-    if (!rec) return [originalFail];
+  const failItem = (nextOkVar, itemPosVar, breakStmt) => {
+    if (!rec) return [`${ind(ctx)}if (!${nextOkVar}) ${breakStmt === "break" ? "break" : `{ ${breakStmt} }`}`];
     const rr = v(ctx, "_rr");
     return [
       `${ind(ctx)}if (!${nextOkVar}) {`,
@@ -5947,10 +6153,24 @@ function emitSepBy(_p, def, ctx, pos) {
       `${ind(ctx)}    const ${rr} = _ctx._rec.scan(input, ${itemPosVar}, _ctx, ${scanSync}, ${exp})`,
       `${ind(ctx)}    ${arrV}.push(${rr}.error); _ctx._rec.capture(_ctx, ${rr}.error); ${curV} = ${rr}.end; continue`,
       `${ind(ctx)}  }`,
-      `${ind(ctx)}  ${rb}break`,
+      `${ind(ctx)}  ${breakStmt}`,
       `${ind(ctx)}}`
     ];
   };
+  const itemFailBreak = (sepEndVar, sepRb, postSepRb) => def.trailing === void 0 ? `${sepRb}break` : `${postSepRb}${curV} = ${sepEndVar}; break`;
+  const postSepMarks = () => {
+    if (def.trailing === void 0 || !ctx.capturing) return { decl: [], rb: "" };
+    const lv = v(ctx, "_tlv"), rw = v(ctx, "_trw"), tl = v(ctx, "_ttl"), lg = v(ctx, "_tlg");
+    return {
+      decl: [
+        `${ind(ctx)}const ${lv} = _ctx._cstLeaves ? _ctx._cstLeaves.length : 0`,
+        `${ind(ctx)}const ${rw} = _ctx._cstRawChildren ? _ctx._cstRawChildren.length : 0`,
+        `${ind(ctx)}const ${tl} = _ctx._cstTriviaLog ? _ctx._cstTriviaLog.length : 0`,
+        `${ind(ctx)}const ${lg} = _ctx._triviaLog ? _ctx._triviaLog.length : 0`
+      ],
+      rb: `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${lv}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${rw}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${tl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${lg}; `
+    };
+  };
   if (rec) {
     const rr0 = v(ctx, "_rr0");
     const didV = v(ctx, "_did");
@@ -5976,6 +6196,7 @@ function emitSepBy(_p, def, ctx, pos) {
     );
     ctx.indent++;
   }
+  if (def.max !== void 0) stmts.push(`${ind(ctx)}if (${arrV}.length >= ${def.max}) break`);
   let sepAtPos = curV;
   if (ctx.activeTrivia) {
     if (ctx.capturing) {
@@ -5996,12 +6217,14 @@ function emitSepBy(_p, def, ctx, pos) {
       const rollbackToSep = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${markLv}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${markLog}; `;
       const { stmts: sepStmts, okVar: sepOk, endVar: sepEnd } = emitFallible(def.separator, ctx, sepAtPos, true);
       stmts.push(...sepStmts, `${ind(ctx)}if (!${sepOk}) { ${rollbackToSep}break }`);
+      const post = postSepMarks();
+      stmts.push(...post.decl);
       const npV = v(ctx, "_np");
       stmts.push(`${ind(ctx)}const ${npV} = ${capFn}(input, ${sepEnd}, _ctx, 1)`);
       const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, npV, true);
       stmts.push(
         ...nextStmts,
-        ...failItem(nextOk, npV, rollbackToSep, `${ind(ctx)}if (!${nextOk}) { ${rollbackToSep}break }`),
+        ...failItem(nextOk, npV, itemFailBreak(sepEnd, rollbackToSep, post.rb)),
         `${ind(ctx)}${arrV}.push(${nextVal})`,
         `${ind(ctx)}${curV} = ${nextEnd}`
       );
@@ -6017,7 +6240,7 @@ function emitSepBy(_p, def, ctx, pos) {
       const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, npV, true);
       stmts.push(
         ...nextStmts,
-        ...failItem(nextOk, npV, "", `${ind(ctx)}if (!${nextOk}) break`),
+        ...failItem(nextOk, npV, itemFailBreak(sepEnd, "", "")),
         `${ind(ctx)}${arrV}.push(${nextVal})`,
         `${ind(ctx)}${curV} = ${nextEnd}`
       );
@@ -6034,10 +6257,12 @@ function emitSepBy(_p, def, ctx, pos) {
     const { stmts: sepStmts, okVar: sepOk, endVar: sepEnd } = emitFallible(def.separator, ctx, sepAtPos, true);
     stmts.push(...sepStmts, `${ind(ctx)}if (!${sepOk}) break`);
     const nextRb = markLv ? `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${markLv}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${markRw}; ` : "";
+    const post = postSepMarks();
+    stmts.push(...post.decl);
     const { stmts: nextStmts, okVar: nextOk, valVar: nextVal, endVar: nextEnd } = emitFallible(def.parser, ctx, sepEnd, true);
     stmts.push(
       ...nextStmts,
-      ...failItem(nextOk, sepEnd, nextRb, `${ind(ctx)}if (!${nextOk}) { ${nextRb}break }`),
+      ...failItem(nextOk, sepEnd, itemFailBreak(sepEnd, nextRb, post.rb)),
       `${ind(ctx)}${arrV}.push(${nextVal})`,
       `${ind(ctx)}${curV} = ${nextEnd}`
     );
@@ -6046,6 +6271,9 @@ function emitSepBy(_p, def, ctx, pos) {
   stmts.push(`${ind(ctx)}}`);
   ctx.indent--;
   stmts.push(`${ind(ctx)}}`);
+  if (def.min >= 1) {
+    stmts.push(...emitIfFail(ctx, `${arrV}.length < ${def.min}`, failArrBody(ctx, deriveExpectedArr([def.parser]), curV)));
+  }
   return { stmts, valueVar: arrV, endVar: curV };
 }
 function emitScanTo(def, ctx, pos) {
@@ -6097,17 +6325,44 @@ function emitScanTo(def, ctx, pos) {
   return { stmts, valueVar: valV, endVar: curV };
 }
 function emitNot(def, ctx, pos) {
+  const sinksLive = !!ctx.capturing || !!ctx.recovery;
+  const leaves = sinksLive ? v(ctx, "_ntl") : null;
+  const raw = sinksLive ? v(ctx, "_ntr") : null;
+  const tl = sinksLive ? v(ctx, "_ntt") : null;
+  const log = sinksLive ? v(ctx, "_ntg") : null;
+  const fields = sinksLive ? v(ctx, "_ntf") : null;
+  const errors = sinksLive ? v(ctx, "_nte") : null;
   const { stmts, okVar } = emitFallible(def.parser, ctx, pos, true);
   const label2 = JSON.stringify(`not(${def.parser._tag})`);
   return {
     stmts: [
+      ...sinksLive ? [
+        `${ind(ctx)}const ${leaves} = _ctx._cstLeaves?.length ?? 0, ${raw} = _ctx._cstRawChildren?.length ?? 0, ${tl} = _ctx._cstTriviaLog?.length ?? 0, ${log} = _ctx._triviaLog?.length ?? 0, ${fields} = _ctx._fields?.length ?? 0, ${errors} = _ctx._errors?.length ?? 0`
+      ] : [],
       ...stmts,
+      ...sinksLive ? [
+        `${ind(ctx)}if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${leaves}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${raw}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${tl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${log}; if (_ctx._fields) _ctx._fields.length = ${fields}; if (_ctx._errors) _ctx._errors.length = ${errors}`
+      ] : [],
       ...emitIfFail(ctx, okVar, failBody(ctx, label2, pos))
     ],
     valueVar: "null",
     endVar: pos
   };
 }
+function emitPeek(def, ctx, pos) {
+  const probeCtx = { ...ctx, capturing: false, noHoist: true };
+  const { stmts, okVar } = emitFallible(def.parser, probeCtx, pos, true);
+  ctx.vars = probeCtx.vars;
+  const label2 = JSON.stringify(`peek(${def.parser._tag})`);
+  return {
+    stmts: [
+      ...stmts,
+      ...emitIfFail(ctx, `!${okVar}`, failBody(ctx, label2, pos))
+    ],
+    valueVar: "null",
+    endVar: pos
+  };
+}
 function escapeTokenLiteral(value) {
   return value.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
 }
@@ -6395,9 +6650,9 @@ function emitRuntimeFallback(parser2, ctx, pos) {
   return { stmts, valueVar: vv, endVar: ev };
 }
 function emitLazy(p, def, ctx, pos) {
-  const canonical = ctx.ruleNames?.get(p);
+  const canonical2 = ctx.ruleNames?.get(p);
   const usage = ctx.lazyUsage;
-  if (!canonical && usage && (usage.counts.get(p) ?? 0) <= 1 && !usage.recursive.has(p)) {
+  if (!canonical2 && usage && (usage.counts.get(p) ?? 0) <= 1 && !usage.recursive.has(p)) {
     let resolved;
     try {
       resolved = def.thunk();
@@ -6407,7 +6662,7 @@ function emitLazy(p, def, ctx, pos) {
     return emit(resolved, ctx, pos);
   }
   if (!ctx.namedParsers.has(p)) {
-    const fnName2 = canonical ?? `${nsp(ctx)}_pf${ctx.namedParsers.size}`;
+    const fnName2 = canonical2 ?? `${nsp(ctx)}_pf${ctx.namedParsers.size}`;
     ctx.namedParsers.set(p, fnName2);
     let resolved;
     try {
@@ -6690,6 +6945,8 @@ function emitDispatch(p, ctx, pos) {
     }
     case "not":
       return emitNot(def, ctx, pos);
+    case "peek":
+      return emitPeek(def, ctx, pos);
     case "node":
       return emitNode(def, ctx, pos);
     case "scanTo":
@@ -6778,6 +7035,7 @@ function hasNodeDef(p, seen = /* @__PURE__ */ new Set()) {
     case "many":
     case "oneOrMore":
     case "not":
+    case "peek":
     case "transform":
       return hasNodeDef(d.parser, seen);
     case "skip":
@@ -6829,17 +7087,18 @@ function childrenOf(def) {
     case "field":
     case "grammar":
     case "not":
+    case "peek":
     case "node":
     case "withCtx":
     case "expect":
       return [def.parser];
-    // emitMany's oneOrMore branch and emitSepBy both codegen `def.parser` TWICE
-    // (a mandatory first match, then again inside the repeat loop) — two real
-    // emit() call sites, so the usage analysis must see two edges here or it
+    // emitMany's min>=1 branch and emitSepBy both codegen `def.parser` more than
+    // once (`min` mandatory matches, then again inside the repeat loop) — each is a
+    // real emit() call site, so the usage analysis must see one edge per site or it
     // undercounts a single-use `parser` ref as inline-safe when it's actually
-    // referenced from two positions within this one compiled function.
+    // referenced from several positions within this one compiled function.
     case "oneOrMore":
-      return [def.parser, def.parser];
+      return Array.from({ length: def.min + 1 }, () => def.parser);
     case "sepBy":
       return [def.parser, def.parser, def.separator];
     case "skip":
@@ -6985,12 +7244,41 @@ function resolveGatingLevel(opt) {
   return "warn";
 }
 function runGatingDiagnostic(combinator, opt) {
+  return reportGating(opt, (o) => analyzeGating(combinator, o));
+}
+function runGatingDiagnosticRules(ruleMap, opt) {
+  return reportGating(opt, (o) => analyzeGatingRules(ruleMap, o));
+}
+function runFusedGatingDiagnostic(getRuleMaps, opt) {
+  if (resolveGatingLevel(opt) === "off") return void 0;
+  const ruleMaps = getRuleMaps();
+  if (!ruleMaps.some((map) => hasExternalRuleRef(map))) return void 0;
+  const winners = /* @__PURE__ */ new Map();
+  for (const map of ruleMaps) for (const [name, rule] of map) {
+    if (rule._def.tag === "lazy") {
+      try {
+        rule._def.thunk();
+      } catch {
+        continue;
+      }
+    }
+    winners.set(name, rule);
+  }
+  const entries = [...winners];
+  return reportGating(opt, (o) => {
+    const deferredHere = new Set(analyzeGatingRules(entries, o).deferred.map((c) => c.id));
+    const fused = analyzeGatingRules(entries, { ...o, resolveRef: (name) => winners.get(name) });
+    return { ...fused, ungated: fused.ungated.filter((c) => deferredHere.has(c.id)), antiPatterns: [] };
+  });
+}
+function reportGating(opt, analyze) {
   const level = resolveGatingLevel(opt);
   if (level === "off") return void 0;
-  const accept = opt !== null && typeof opt === "object" ? opt.accept : void 0;
+  const obj = opt !== null && typeof opt === "object" ? opt : void 0;
+  const analyzeOpts = obj?.accept !== void 0 || obj?.entryName !== void 0 ? { ...obj.accept !== void 0 ? { accept: obj.accept } : {}, ...obj.entryName !== void 0 ? { entryName: obj.entryName } : {} } : void 0;
   let report;
   try {
-    report = analyzeGating(combinator, accept ? { accept } : void 0);
+    report = analyze(analyzeOpts);
   } catch {
     return void 0;
   }
@@ -7127,6 +7415,7 @@ function publicRuleWrapperSource(rule, fnSource) {
 }
 function compileLinkable(ruleMapArg, ns, opts) {
   if (!ns) throw new Error("compileLinkable: ns must be a non-empty namespace");
+  if (opts?.gating !== void 0) runGatingDiagnosticRules(ruleMapArg, opts.gating);
   for (const [, rule] of ruleMapArg) markUnusedValues(rule);
   const grammarTrivia = opts?.trivia ?? ruleMapArg.map(([, r]) => r._meta.grammarTrivia).find(Boolean);
   const grammarScanSkip = opts?.scanSkip ?? ruleMapArg.map(([, r]) => r._meta.grammarScanSkip).find(Boolean);
@@ -7183,6 +7472,7 @@ function compileLinkable(ruleMapArg, ns, opts) {
     fnNameToKey.set(fn, key);
   }
   ctx.ruleNames = ruleNames;
+  const externalRefs = /* @__PURE__ */ new Set();
   {
     const scanned = /* @__PURE__ */ new Set();
     const scanExternal = (p) => {
@@ -7198,11 +7488,14 @@ function compileLinkable(ruleMapArg, ns, opts) {
         }
         if (resolved === void 0) {
           const name = p._ruleName;
-          if (name && !ctx.namedParsers.has(p)) {
-            assertRuleName(name);
-            const fn = `_r_${name}`;
-            ruleNames.set(p, fn);
-            ctx.namedParsers.set(p, fn);
+          if (name) {
+            externalRefs.add(p);
+            if (!ctx.namedParsers.has(p)) {
+              assertRuleName(name);
+              const fn = `_r_${name}`;
+              ruleNames.set(p, fn);
+              ctx.namedParsers.set(p, fn);
+            }
           }
           return;
         }
@@ -7315,12 +7608,32 @@ function compileLinkable(ruleMapArg, ns, opts) {
     needsEmptyTl: !!ctx.needsEmptyTl,
     needsHostReads: !!ctx.needsHostReads,
     hasDirectBuilders: ruleMap.some(([, rule]) => hasDirectBuildDef(rule)),
-    isRecognitionOnly: !hasSemanticReduction(ruleMap.map(([, rule]) => rule)),
+    isRecognitionOnly: !hasSemanticReduction(ruleMap.map(([, rule]) => rule), externalRefs),
     mfFns: mfSrcs ? [] : ctx.mapFns,
     buildFns: buildSrcs ? [] : ctx.buildFns
   };
 }
-function hasSemanticReduction(roots) {
+function hasExternalRuleRef(ruleMap) {
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (p) => {
+    if (seen.has(p)) return false;
+    seen.add(p);
+    const def = p._def;
+    if (def.tag === "lazy") {
+      let resolved;
+      try {
+        resolved = def.thunk();
+      } catch {
+        resolved = void 0;
+      }
+      if (resolved === void 0) return p._ruleName !== void 0;
+      return visit(resolved);
+    }
+    return childrenOf(def).some(visit);
+  };
+  return ruleMap.some(([, rule]) => visit(rule));
+}
+function hasSemanticReduction(roots, externalRefs) {
   const seen = /* @__PURE__ */ new Set();
   const visit = (parser2) => {
     if (seen.has(parser2)) return false;
@@ -7331,6 +7644,7 @@ function hasSemanticReduction(roots) {
     if (def.tag === "guard" || def.tag === "withCtx") return true;
     if (def.tag === "node" && def.build !== void 0) return true;
     if (def.tag === "lazy") {
+      if (externalRefs?.has(parser2)) return false;
       try {
         return visit(def.thunk());
       } catch {
@@ -7422,6 +7736,7 @@ function childrenOf2(def) {
     case "label":
     case "field":
     case "not":
+    case "peek":
     case "node":
     case "withCtx":
     case "expect":
@@ -7455,9 +7770,16 @@ function lazyTarget(c) {
 }
 var Unserializable = class extends Error {
 };
-function serializeRuleMap(ruleMap) {
+function repeatOpts(min, max, trailing) {
+  const parts = [];
+  if (min !== 0) parts.push(`min: ${min}`);
+  if (max !== void 0) parts.push(`max: ${max}`);
+  if (trailing !== void 0) parts.push(`trailing: ${JSON.stringify(trailing)}`);
+  return parts.length === 0 ? "" : `, { ${parts.join(", ")} }`;
+}
+function serializeRuleMap(ruleMap, scanSkip) {
   try {
-    return new Serializer(ruleMap).run();
+    return new Serializer(ruleMap, scanSkip ?? []).run();
   } catch (e) {
     if (e instanceof Unserializable) {
       if (process.env.PARSEMAN_IR_DEBUG) console.error(`[ir] fallback: ${e.message}`);
@@ -7558,6 +7880,7 @@ function evalRuleMapIR(ir) {
     "optional",
     "sepBy",
     "not",
+    "peek",
     "node",
     "parser",
     "scanTo",
@@ -7590,6 +7913,7 @@ function evalRuleMapIR(ir) {
     optional,
     sepBy,
     not,
+    peek,
     node,
     parser,
     scanTo,
@@ -7618,10 +7942,28 @@ var Serializer = class {
   decls = [];
   ruleValues = /* @__PURE__ */ new Set();
   ruleMap;
-  constructor(ruleMap) {
+  scanSkip;
+  constructor(ruleMap, scanSkip = []) {
     this.ruleMap = ruleMap;
+    this.scanSkip = scanSkip;
     for (const [, c] of ruleMap) this.ruleValues.add(this.body(c));
   }
+  /** A grammar-level `scanSkip` unit is an opaque TERMINAL (a string, a balanced
+   * bracket) — it must not reach a grammar-rule ref (`g[name]`), because the
+   * serialized `scanSkip` array sits in the `rules({ scanSkip })` OPTIONS position,
+   * outside the `(g) => …` factory where `g` is bound. A unit that does reference a
+   * rule can't be carried in options; bail to the full-pieces fallback. */
+  assertNoRuleRef(c, seen) {
+    if (seen.has(c)) return;
+    seen.add(c);
+    if (c._def.tag === "lazy") {
+      if (ruleNameOf2(c) !== void 0) throw new Unserializable("scanSkip unit references a grammar rule");
+      const target = lazyTarget(c);
+      if (target) this.assertNoRuleRef(target, seen);
+      return;
+    }
+    for (const child of childrenOf2(c._def)) this.assertNoRuleRef(child, seen);
+  }
   /** A `rules()` map wraps each rule value in a named `lazy` proxy; the real body is
    * its target (compileLinkable unwraps the same way). A ref INSIDE a body stays a
    * `g[name]` ref — only the top-level entry is unwrapped. */
@@ -7630,21 +7972,38 @@ var Serializer = class {
   }
   run() {
     for (const [, c] of this.ruleMap) this.analyze(this.body(c), /* @__PURE__ */ new Set());
+    for (const c of this.scanSkip) {
+      this.assertNoRuleRef(c, /* @__PURE__ */ new Set());
+      this.analyze(c, /* @__PURE__ */ new Set());
+    }
     let n = 0;
     for (const [c, count] of this.counts) {
       if (this.ruleValues.has(c)) continue;
       if (count >= 2 || this.selfRef.has(c)) this.constName.set(c, `_s${n++}`);
     }
+    const outerDecls = [];
+    const innerDecls = [];
+    let optionsArg = "";
+    if (this.scanSkip.length > 0) {
+      this.decls = outerDecls;
+      const units = this.scanSkip.map((c) => this.ref(c, null));
+      optionsArg = `{ scanSkip: [${units.join(", ")}] }, `;
+    }
+    this.decls = innerDecls;
     const body = this.ruleMap.map(([name, c]) => `  ${JSON.stringify(name)}: ${this.wrap(this.body(c))}`).join(",\n");
-    if (this.decls.length === 0) return `rules((g) => ({
+    const factory = innerDecls.length === 0 ? `(g) => ({
 ${body}
-}))`;
-    return `rules((g) => {
-${this.decls.map((d) => "  " + d).join("\n")}
+})` : `(g) => {
+${innerDecls.map((d) => "  " + d).join("\n")}
   return ({
 ${body}
 })
-})`;
+}`;
+    const call = `rules(${optionsArg}${factory})`;
+    return outerDecls.length === 0 ? call : `(() => {
+${outerDecls.map((d) => "  " + d).join("\n")}
+  return ${call}
+})()`;
   }
   /** Count identity references and flag self-referential subtrees. `active` is the
    * set of combinators on the current DFS path (to detect a lazy pointing back). */
@@ -7729,17 +8088,21 @@ ${body}
         return `_gch([${items.join(", ")}])`;
       }
       case "many":
-        return `many(${kid(def.parser)})`;
+        return `many(${kid(def.parser)}${repeatOpts(def.min, def.max)})`;
+      // A `oneOrMore` def with min > 1 came from `many(x, { min: n })`; round-trip
+      // it through `many` so the bounds survive (oneOrMore defaults min to 1).
       case "oneOrMore":
-        return `oneOrMore(${kid(def.parser)})`;
+        return def.min === 1 && def.max === void 0 ? `oneOrMore(${kid(def.parser)})` : `many(${kid(def.parser)}${repeatOpts(def.min, def.max)})`;
       case "optional":
         return `optional(${kid(def.parser)})`;
       case "attempt":
         return `attempt(${kid(def.parser)})`;
       case "sepBy":
-        return `sepBy(${kid(def.parser)}, ${kid(def.separator)})`;
+        return `sepBy(${kid(def.parser)}, ${kid(def.separator)}${repeatOpts(def.min, def.max, def.trailing)})`;
       case "not":
         return `not(${kid(def.parser)})`;
+      case "peek":
+        return `peek(${kid(def.parser)})`;
       case "trivia":
         return `trivia(${kid(def.parser)})`;
       case "token":
@@ -7932,6 +8295,9 @@ var COMPOSED_COVERAGE_RULES = /* @__PURE__ */ Symbol.for("parseman.composedCover
 function isIRPiece(p) {
   return !!p && typeof p === "object" && typeof p.ir === "string" && typeof p.ns === "string" && !("ruleFns" in p);
 }
+function carriedRuleMaps(carried) {
+  return carried.filter(isIRPiece).map((p) => evalRuleMapIR(p.ir));
+}
 function coverageRulesOf(carried) {
   const winners = {};
   for (const piece of carried) {
@@ -7994,7 +8360,8 @@ function itemCarried(item, used, trivia2) {
       return false;
     }
   });
-  const ir = serializeRuleMap(entries);
+  const scanSkip = entries.map(([, val]) => val._meta.grammarScanSkip).find(Boolean);
+  const ir = serializeRuleMap(entries, scanSkip);
   return ir ? [{ ns, ir }] : [linkable(map, ns, trivia2)];
 }
 function composingTriviaOf(items) {
@@ -8015,6 +8382,7 @@ function compose(items) {
   const used = /* @__PURE__ */ new Set();
   const trivia2 = composingTriviaOf(items);
   const carried = items.flatMap((item) => itemCarried(item, used, trivia2));
+  runFusedGatingDiagnostic(() => carriedRuleMaps(carried));
   const pieces = carried.map((p) => materializePiece(p, trivia2));
   const map = fuseRules(pieces);
   Object.defineProperty(map, COMPOSED_PIECES, { value: carried, enumerable: false });
@@ -8847,7 +9215,7 @@ function coverageEntry(entry, collector, maps, trace) {
           };
         }
         case "sepBy":
-          return sepBy(build(def.parser), build(def.separator));
+          return sepBy(build(def.parser), build(def.separator), { min: def.min, ...def.max === void 0 ? {} : { max: def.max }, ...def.trailing === void 0 ? {} : { trailing: def.trailing } });
         case "transform":
           return transform(build(def.parser), def.fn);
         case "skip":
@@ -8868,6 +9236,8 @@ function coverageEntry(entry, collector, maps, trace) {
           }, build(def.parser));
         case "not":
           return not(build(def.parser));
+        case "peek":
+          return peek(build(def.parser));
         case "node": {
           const opts = { ...def.unwrap ? { unwrap: true } : {}, ...def.collapse ? { collapse: true } : {}, ...def.captureTrivia ? { captureTrivia: true } : {}, ...def.trailingTrivia ? { trailingTrivia: true } : {} };
           return def.type === void 0 ? node(build(def.parser), def.build, opts) : node(def.type, build(def.parser), def.build, opts);
@@ -9242,6 +9612,7 @@ export {
   absolutize,
   absolutizeCST,
   analyzeGating,
+  analyzeGatingRules,
   annotateSpan,
   applyEdit,
   attempt,
@@ -9289,10 +9660,12 @@ export {
   not,
   offsetToLineCol,
   oneOrMore,
+  oneOrMoreSep,
   optional,
   parse,
   parseDoc,
   parser,
+  peek,
   ref,
   regex,
   relativize,