parseman 0.33.0 → 0.35.0

package/dist/index.cjs

@@ -27,6 +27,7 @@ __export(index_exports, {
   absolutize: () => absolutize,
   absolutizeCST: () => absolutizeCST,
   analyzeGating: () => analyzeGating,
+  analyzeGatingRules: () => analyzeGatingRules,
   annotateSpan: () => annotateSpan,
   applyEdit: () => applyEdit,
   attempt: () => attempt,
@@ -74,10 +75,12 @@ __export(index_exports, {
   not: () => not,
   offsetToLineCol: () => offsetToLineCol,
   oneOrMore: () => oneOrMore,
+  oneOrMoreSep: () => oneOrMoreSep,
   optional: () => optional,
   parse: () => parse,
   parseDoc: () => parseDoc,
   parser: () => parser,
+  peek: () => peek,
   ref: () => ref,
   regex: () => regex,
   relativize: () => relativize,
@@ -102,6 +105,11 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // 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;
@@ -139,10 +147,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":
@@ -159,8 +167,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":
@@ -184,7 +200,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;
@@ -193,18 +210,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":
@@ -216,7 +260,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();
@@ -225,11 +270,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":
@@ -245,6 +299,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:
@@ -386,28 +441,28 @@ function rollbackBufList(b, keyMulti, keySingle, len) {
     else if (len === 1) {
       b[keySingle] = arr[0];
       b[keyMulti] = void 0;
-    } else arr.length = len;
+    } else if (arr.length !== len) arr.length = len;
     return;
   }
   if (len === 0) b[keySingle] = void 0;
 }
 function rollbackCstCapture(ctx, mark) {
-  if (ctx._errors && mark.errors !== void 0) ctx._errors.length = mark.errors;
+  if (ctx._errors && mark.errors !== void 0 && ctx._errors.length !== mark.errors) ctx._errors.length = mark.errors;
   const b = ctx._cstBuf;
   if (b) {
     rollbackBufList(b, "raw", "rawSingle", mark.raw);
     rollbackBufList(b, "ch", "single", mark.leaves);
     if (b.tl) {
       if (mark.tlog === 0) b.tl = void 0;
-      else b.tl.length = mark.tlog;
+      else if (b.tl.length !== mark.tlog) b.tl.length = mark.tlog;
     }
-    if (ctx._fields) ctx._fields.length = mark.fields;
+    if (ctx._fields && ctx._fields.length !== mark.fields) ctx._fields.length = mark.fields;
     return;
   }
-  if (ctx._cstRawChildren) ctx._cstRawChildren.length = mark.raw;
-  if (ctx._cstTriviaLog) ctx._cstTriviaLog.length = mark.tlog;
-  if (ctx._cstLeaves) ctx._cstLeaves.length = mark.leaves;
-  if (ctx._fields) ctx._fields.length = mark.fields;
+  if (ctx._cstRawChildren && ctx._cstRawChildren.length !== mark.raw) ctx._cstRawChildren.length = mark.raw;
+  if (ctx._cstTriviaLog && ctx._cstTriviaLog.length !== mark.tlog) ctx._cstTriviaLog.length = mark.tlog;
+  if (ctx._cstLeaves && ctx._cstLeaves.length !== mark.leaves) ctx._cstLeaves.length = mark.leaves;
+  if (ctx._fields && ctx._fields.length !== mark.fields) ctx._fields.length = mark.fields;
 }
 function pushCstTriviaEntry(ctx, start, end, kindIndex) {
   const insertIdx = cstRawLen(ctx);
@@ -929,9 +984,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 });
@@ -943,7 +1035,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) {
@@ -951,10 +1043,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 };
@@ -1066,6 +1155,10 @@ var REC = { scan: recoverScan, at: matchesAt, or: orSentinel, sentinel: firstSet
 
 // src/combinators/expect.ts
 function deriveExpected(c) {
+  return derive(c, /* @__PURE__ */ new Set());
+}
+function derive(c, seen) {
+  const deriveExpected2 = (p) => derive(p, seen);
   const def = c._def;
   switch (def.tag) {
     case "literal":
@@ -1077,20 +1170,32 @@ function deriveExpected(c) {
     case "label":
       return [def.label];
     case "choice":
-      return def.parsers.flatMap(deriveExpected);
-    case "sequence":
-      return def.parsers.length > 0 ? deriveExpected(def.parsers[0]) : [];
+      return def.parsers.flatMap(deriveExpected2);
+    // Union through the NULLABLE prefix, mirroring `sequenceFirstSet`. A leading
+    // `optional(…)`/`many(…)` can match nothing, so the term after it is equally
+    // able to fail first — deriving from term 0 alone named a token the parse
+    // never actually required. A leading `not(…)` is zero-width and contributes
+    // nothing (its own expectation is about what must NOT be here), but it is
+    // nullable, so keep scanning past it. Stop at the first term that must match.
+    case "sequence": {
+      const out = [];
+      for (const term of def.parsers) {
+        if (!isZeroWidthAssertion(term)) out.push(...deriveExpected2(term));
+        if (!matchesEmpty(term)) break;
+      }
+      return out;
+    }
     case "attempt":
-      return deriveExpected(def.parser);
+      return deriveExpected2(def.parser);
     // Delegating wrappers whose first-token failure is their inner parser's — must
     // pass through so a start-failure (and the first-set-miss fast-path in attempt/
     // node, which reads this) names the real expected token, not the wrapper tag.
     case "field":
     case "withCtx":
     case "recover":
-      return deriveExpected(def.parser);
+      return deriveExpected2(def.parser);
     case "skip":
-      return deriveExpected(def.main);
+      return deriveExpected2(def.main);
     case "expect":
       return def.expected;
     case "node":
@@ -1103,13 +1208,18 @@ function deriveExpected(c) {
     case "oneOrMore":
     case "transform":
     case "not":
-      return deriveExpected(def.parser);
+    case "peek":
+      return deriveExpected2(def.parser);
     case "lazy": {
       const name = c._ruleName;
+      if (seen.has(c)) return name ? [name] : [];
+      seen.add(c);
       try {
-        return deriveExpected(def.thunk());
+        return deriveExpected2(def.thunk());
       } catch {
         return name ? [name] : [];
+      } finally {
+        seen.delete(c);
       }
     }
     default:
@@ -1240,14 +1350,14 @@ function choice(...args) {
         const result = parsers[i].parse(input, pos, ctx);
         if (!result.ok) {
           rollbackCstCapture(ctx, mark);
-          if (logLen !== void 0 && ctx._triviaLog) ctx._triviaLog.length = logLen;
+          if (logLen !== void 0 && ctx._triviaLog && ctx._triviaLog.length !== logLen) ctx._triviaLog.length = logLen;
           expected.push(...result.expected);
           continue;
         }
         const checks = autoNot[i];
         if (checks && autoNotFires(input, result.span.end, checks)) {
           rollbackCstCapture(ctx, mark);
-          if (logLen !== void 0 && ctx._triviaLog) ctx._triviaLog.length = logLen;
+          if (logLen !== void 0 && ctx._triviaLog && ctx._triviaLog.length !== logLen) ctx._triviaLog.length = logLen;
           continue;
         }
         return result;
@@ -1574,7 +1684,14 @@ function saveTriviaMark(ctx) {
 }
 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;
+  if (ctx._triviaLog && ctx._triviaLog.length !== mark.log) 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;
@@ -1935,7 +2052,7 @@ function attempt(parser2) {
       const result = parser2.parse(input, pos, ctx);
       if (result.ok) return result;
       rollbackCstCapture(ctx, mark);
-      if (log !== void 0 && ctx._triviaLog) ctx._triviaLog.length = log;
+      if (log !== void 0 && ctx._triviaLog && ctx._triviaLog.length !== log) ctx._triviaLog.length = log;
       return { ok: false, expected: result.expected, span: { start: pos, end: pos } };
     }
   };
@@ -1973,13 +2090,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 {
@@ -1989,7 +2119,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) {
@@ -2000,23 +2132,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 {
@@ -2028,7 +2165,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) {
@@ -2039,10 +2188,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 } };
@@ -2072,17 +2223,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 = [];
@@ -2093,6 +2260,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);
@@ -2102,6 +2270,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) {
@@ -2118,6 +2287,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)) {
@@ -2139,12 +2309,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 } };
     }
   };
@@ -2234,6 +2410,7 @@ function markUnusedValues(root) {
         visit(def.separator, false);
         return;
       case "not":
+      case "peek":
         visit(def.parser, false);
         return;
       case "grammar":
@@ -2352,9 +2529,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 } };
       }
@@ -2363,6 +2540,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 => ...`
@@ -2461,6 +2660,7 @@ function parserHasOwnFields(p, seen = /* @__PURE__ */ new Set()) {
     case "expect":
     case "withCtx":
     case "not":
+    case "peek":
       return parserHasOwnFields(d.parser, seen);
     default:
       return false;
@@ -2500,6 +2700,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":
@@ -2549,6 +2750,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.
@@ -2924,7 +3126,7 @@ function leaf(root, fn) {
 }
 
 // src/version.ts
-var PARSEMAN_VERSION = "0.33.0";
+var PARSEMAN_VERSION = "0.35.0";
 
 // src/analysis/gating.ts
 var isAny = (fs) => fs.kind === "any";
@@ -2964,14 +3166,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);
@@ -2983,6 +3186,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
@@ -2999,18 +3206,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":
@@ -3032,13 +3244,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;
           }
@@ -3049,7 +3261,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;
       }
@@ -3086,7 +3298,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({
@@ -3109,6 +3321,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();
@@ -3118,7 +3333,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;
@@ -3135,7 +3350,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();
@@ -3151,18 +3366,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++)
@@ -3178,10 +3394,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
@@ -3348,6 +3566,7 @@ function children(def, winners) {
     case "field":
     case "grammar":
     case "not":
+    case "peek":
     case "node":
     case "guard":
     case "withCtx":
@@ -5098,9 +5317,9 @@ function planDisjointDispatch(parsers) {
   return total >= SWITCH_MIN_CASES ? { kind: "switch", cases } : { kind: "if" };
 }
 function captureRestoreBody(mL, mR, mTl, mLg, mF = null) {
-  const fieldRestore = mF ? `; if (_ctx._fields) _ctx._fields.length = ${mF}` : "";
-  const base = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${mL}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${mR}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${mTl}${fieldRestore}`;
-  return mLg ? `${base}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${mLg}` : base;
+  const fieldRestore = mF ? `; if (_ctx._fields && _ctx._fields.length !== ${mF}) _ctx._fields.length = ${mF}` : "";
+  const base = `if (_ctx._cstLeaves && _ctx._cstLeaves.length !== ${mL}) _ctx._cstLeaves.length = ${mL}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${mR}) _ctx._cstRawChildren.length = ${mR}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${mTl}) _ctx._cstTriviaLog.length = ${mTl}${fieldRestore}`;
+  return mLg ? `${base}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${mLg}) _ctx._triviaLog.length = ${mLg}` : base;
 }
 function mayLeavePartialCapture(p, seen = /* @__PURE__ */ new Set()) {
   if (seen.has(p)) return false;
@@ -5113,6 +5332,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":
@@ -5184,6 +5406,7 @@ function capturesLeaf(p, seen = /* @__PURE__ */ new Set()) {
     case "leaf":
       return true;
     case "not":
+    case "peek":
     case "guard":
     case "trivia":
     case "unknown":
@@ -5310,6 +5533,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;
@@ -5357,7 +5581,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);
@@ -5457,7 +5681,7 @@ function emitSeqValues(def, ctx, pos) {
         const endAfterV = v(ctx, "_sea");
         stmts.push(
           `${ind(ctx)}const ${endAfterV} = ${r2.endVar}`,
-          `${ind(ctx)}if (${endAfterV} > ${scanEndV}) { ${curV} = ${endAfterV} } else { if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${markLog}; }`
+          `${ind(ctx)}if (${endAfterV} > ${scanEndV}) { ${curV} = ${endAfterV} } else { if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${markV}) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${markTl}) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${markLog}) _ctx._triviaLog.length = ${markLog}; }`
         );
         valueVars.push(r2.valueVar);
         continue;
@@ -5503,6 +5727,7 @@ function failsAtStart(p) {
     case "keywords":
     case "guard":
     case "not":
+    case "peek":
       return true;
     case "transform":
     case "label":
@@ -5916,14 +6141,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) {
@@ -5940,7 +6168,7 @@ function emitMany(def, ctx, pos) {
         `${ind(ctx)}const ${npV} = ${capFn}(input, ${curV}, _ctx, 1)`
       );
       itemPos = npV;
-      rollback = `if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${markLog}; `;
+      rollback = `if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${markV}) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${markTl}) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${markLog}) _ctx._triviaLog.length = ${markLog}; `;
     } else {
       const trivFn = ensureTriviaFn(ctx);
       const npV = v(ctx, "_np");
@@ -5964,7 +6192,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`,
@@ -5977,6 +6205,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)}}`);
@@ -6002,7 +6231,7 @@ function emitAttempt(p, def, ctx, pos) {
   const log = v(ctx, "_atg");
   const fields = v(ctx, "_atf");
   const errors = v(ctx, "_ate");
-  const rollback = `if (_ctx._cstLeaves) _ctx._cstLeaves.length = ${leaves}; if (_ctx._cstRawChildren) _ctx._cstRawChildren.length = ${raw}; if (_ctx._cstTriviaLog) _ctx._cstTriviaLog.length = ${trivia2}; if (_ctx._triviaLog) _ctx._triviaLog.length = ${log}; if (_ctx._fields) _ctx._fields.length = ${fields}; if (_ctx._errors) _ctx._errors.length = ${errors}`;
+  const rollback = `if (_ctx._cstLeaves && _ctx._cstLeaves.length !== ${leaves}) _ctx._cstLeaves.length = ${leaves}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${raw}) _ctx._cstRawChildren.length = ${raw}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${trivia2}) _ctx._cstTriviaLog.length = ${trivia2}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${log}) _ctx._triviaLog.length = ${log}; if (_ctx._fields && _ctx._fields.length !== ${fields}) _ctx._fields.length = ${fields}; if (_ctx._errors && _ctx._errors.length !== ${errors}) _ctx._errors.length = ${errors}`;
   const traceId = ctx.coverage?.plan.attempts.get(p);
   const traceRollback = traceId === void 0 ? "" : ` _ctx._grammarTrace?.write({ id: ${JSON.stringify(traceId)}, phase: 'rollback', offset: ${pos} });`;
   const preGuard = [];
@@ -6041,8 +6270,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}) {`,
@@ -6050,10 +6279,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}) _ctx._cstLeaves.length = ${lv}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${rw}) _ctx._cstRawChildren.length = ${rw}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${tl}) _ctx._cstTriviaLog.length = ${tl}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${lg}) _ctx._triviaLog.length = ${lg}; `
+    };
+  };
   if (rec) {
     const rr0 = v(ctx, "_rr0");
     const didV = v(ctx, "_did");
@@ -6079,6 +6322,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) {
@@ -6096,15 +6340,17 @@ function emitSepBy(_p, def, ctx, pos) {
         `${ind(ctx)}const ${spV} = ${capFn}(input, ${curV}, _ctx, 1)`
       );
       sepAtPos = spV;
-      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 rollbackToSep = `if (_ctx._cstLeaves && _ctx._cstLeaves.length !== ${markLv}) _ctx._cstLeaves.length = ${markLv}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${markV}) _ctx._cstRawChildren.length = ${markV}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${markTl}) _ctx._cstTriviaLog.length = ${markTl}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${markLog}) _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}`
       );
@@ -6120,7 +6366,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}`
       );
@@ -6136,11 +6382,13 @@ 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 nextRb = markLv ? `if (_ctx._cstLeaves && _ctx._cstLeaves.length !== ${markLv}) _ctx._cstLeaves.length = ${markLv}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${markRw}) _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}`
     );
@@ -6149,6 +6397,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) {
@@ -6200,17 +6451,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}) _ctx._cstLeaves.length = ${leaves}; if (_ctx._cstRawChildren && _ctx._cstRawChildren.length !== ${raw}) _ctx._cstRawChildren.length = ${raw}; if (_ctx._cstTriviaLog && _ctx._cstTriviaLog.length !== ${tl}) _ctx._cstTriviaLog.length = ${tl}; if (_ctx._triviaLog && _ctx._triviaLog.length !== ${log}) _ctx._triviaLog.length = ${log}; if (_ctx._fields && _ctx._fields.length !== ${fields}) _ctx._fields.length = ${fields}; if (_ctx._errors && _ctx._errors.length !== ${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, "\\$&");
 }
@@ -6498,9 +6776,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();
@@ -6510,7 +6788,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 {
@@ -6793,6 +7071,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":
@@ -6881,6 +7161,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":
@@ -6932,17 +7213,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":
@@ -7088,12 +7370,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;
   }
@@ -7230,6 +7541,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);
@@ -7286,6 +7598,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) => {
@@ -7301,11 +7614,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;
         }
@@ -7418,12 +7734,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;
@@ -7434,6 +7770,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 {
@@ -7525,6 +7862,7 @@ function childrenOf2(def) {
     case "label":
     case "field":
     case "not":
+    case "peek":
     case "node":
     case "withCtx":
     case "expect":
@@ -7558,6 +7896,13 @@ function lazyTarget(c) {
 }
 var Unserializable = class extends Error {
 };
+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, scanSkip ?? []).run();
@@ -7661,6 +8006,7 @@ function evalRuleMapIR(ir) {
     "optional",
     "sepBy",
     "not",
+    "peek",
     "node",
     "parser",
     "scanTo",
@@ -7693,6 +8039,7 @@ function evalRuleMapIR(ir) {
     optional,
     sepBy,
     not,
+    peek,
     node,
     parser,
     scanTo,
@@ -7867,17 +8214,21 @@ ${outerDecls.map((d) => "  " + d).join("\n")}
         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":
@@ -8070,6 +8421,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) {
@@ -8154,6 +8508,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 });
@@ -8986,7 +9341,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":
@@ -9007,6 +9362,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);