tarsec 0.4.7 → 0.5.1

package/dist/parsers/bash/lists.js

@@ -0,0 +1,85 @@
+/** Pipelines, `&&`/`||` chains, and command lists.
+ *
+ * The core fail-closed rule lives here: commands are SEPARATED by `;`,
+ * `&`, or newline. A construct that stops early leaves text no separator
+ * precedes, which fails the enclosing parse instead of becoming a
+ * phantom second command (the way `files=(a b c)` would otherwise parse
+ * as an assignment followed by a subshell). */
+import { lazy, many, optional, or, seq } from "../../combinators.js";
+import { trace } from "../../trace.js";
+import { bangToken, bashLexemes, linebreak, newlineToken, } from "./lexemes.js";
+import { commandParser as commandParserImport } from "./commands.js";
+const L = bashLexemes;
+// Deferred to parse time: see the module-cycle note in commands.ts.
+const commandParser = lazy(() => commandParserImport);
+const pipeOperator = seq([or(L.operator("|&"), L.operator("|")), linebreak], (results) => results[0]);
+// Explicit seq/many instead of sepBy1: `echo hi |` must FAIL, not parse
+// as `echo hi` with the `|` silently swallowed.
+const pipelineParser = seq([
+    optional(bangToken),
+    commandParser,
+    many(seq([pipeOperator, commandParser], (results) => results[1])),
+], (results) => ({
+    tag: "pipeline",
+    negated: results[0] !== null,
+    commands: [results[1], ...results[2]],
+}));
+const andOrTail = seq([or(L.operator("&&"), L.operator("||")), linebreak, pipelineParser], (results) => ({
+    op: results[0],
+    pipeline: results[2],
+}));
+const andOrParser = seq([pipelineParser, many(andOrTail)], (results) => ({
+    tag: "andOr",
+    first: results[0],
+    rest: results[1],
+}));
+const itemSeparator = or(seq([L.operator("&"), linebreak], () => ({ background: true })), seq([L.operator(";"), linebreak], () => ({ background: false })), seq([newlineToken, linebreak], () => ({ background: false })));
+const listBody = seq([
+    andOrParser,
+    many(seq([itemSeparator, andOrParser], (results) => ({
+        separator: results[0],
+        command: results[1],
+    }))),
+    optional(itemSeparator),
+], (results) => {
+    const pairs = results[1];
+    const trailing = results[2];
+    const commands = [results[0], ...pairs.map((pair) => pair.command)];
+    // Separator i follows command i and carries its `&` marker.
+    const separators = [
+        ...pairs.map((pair) => pair.separator),
+        trailing,
+    ];
+    const items = commands.map((command, index) => {
+        var _a;
+        return ({
+            tag: "listItem",
+            command,
+            background: ((_a = separators[index]) === null || _a === void 0 ? void 0 : _a.background) === true,
+        });
+    });
+    return {
+        list: { tag: "list", items },
+        endedWithSeparator: trailing !== null,
+    };
+});
+const EMPTY_LIST = { tag: "list", items: [] };
+const list0Impl = trace("bash:list0", seq([L.whitespace, linebreak, optional(listBody)], (results) => { var _a, _b; return (_b = (_a = results[2]) === null || _a === void 0 ? void 0 : _a.list) !== null && _b !== void 0 ? _b : EMPTY_LIST; }));
+const list1Impl = trace("bash:list1", seq([L.whitespace, linebreak, listBody], (results) => results[2].list));
+const list1WithEndImpl = seq([L.whitespace, linebreak, listBody], (results) => results[2]);
+/** A possibly-empty command list. Empty lists are only legal where bash
+ * allows them: the top level, `$()`, and case-item bodies. Declared as a
+ * function so the words/lists/commands module cycle is safe under any
+ * import order. */
+export function list0(input) {
+    return list0Impl(input);
+}
+/** A command list with at least one command — the body of every compound
+ * command, subshell, and group. */
+export function list1(input) {
+    return list1Impl(input);
+}
+/** `list1`, but also reporting whether it ended with a separator. */
+export function list1WithEnd(input) {
+    return list1WithEndImpl(input);
+}

package/dist/parsers/bash/types.d.ts

@@ -0,0 +1,136 @@
+/** AST types for the bash parser. See `index.ts` for the supported subset. */
+/** One piece of a word. Adjacent parts concatenate: `e'f'"g"$h` is a single
+ * word of four parts. */
+export type WordPart = {
+    tag: "literal";
+    text: string;
+} | {
+    tag: "singleQuoted";
+    text: string;
+} | {
+    tag: "doubleQuoted";
+    parts: WordPart[];
+} | {
+    tag: "variable";
+    name: string;
+} | {
+    tag: "paramExpansion";
+    expression: string;
+} | {
+    tag: "commandSubstitution";
+    command: List;
+} | {
+    tag: "arithmeticExpansion";
+    expression: string;
+};
+export type BashWord = {
+    tag: "word";
+    parts: WordPart[];
+};
+/** `name=value` (or `name=` with a null value) before a command. */
+export type Assignment = {
+    tag: "assignment";
+    name: string;
+    value: BashWord | null;
+};
+/** A redirect like `> out.txt`, `2>&1`, or `<<< "$str"`. `fd` is the
+ * explicit file descriptor (`2` in `2>`), or null for the default. */
+export type Redirect = {
+    tag: "redirect";
+    fd: number | null;
+    op: string;
+    target: BashWord;
+};
+export type SimpleCommand = {
+    tag: "simpleCommand";
+    assignments: Assignment[];
+    words: BashWord[];
+    redirects: Redirect[];
+};
+export type IfCommand = {
+    tag: "if";
+    cond: List;
+    thenBody: List;
+    elifs: {
+        cond: List;
+        thenBody: List;
+    }[];
+    elseBody: List | null;
+    redirects: Redirect[];
+};
+export type LoopCommand = {
+    tag: "loop";
+    kind: "while" | "until";
+    cond: List;
+    body: List;
+    redirects: Redirect[];
+};
+export type ForCommand = {
+    tag: "for";
+    variable: string;
+    /** The `in word...` list, or null for the implicit `in "$@"`. */
+    words: BashWord[] | null;
+    body: List;
+    redirects: Redirect[];
+};
+export type CaseItem = {
+    patterns: BashWord[];
+    body: List;
+    /** `;;`, `;&`, `;;&`, or null when the final item ends at `esac`. */
+    terminator: string | null;
+};
+export type CaseCommand = {
+    tag: "case";
+    subject: BashWord;
+    items: CaseItem[];
+    redirects: Redirect[];
+};
+export type Subshell = {
+    tag: "subshell";
+    body: List;
+    redirects: Redirect[];
+};
+export type Group = {
+    tag: "group";
+    body: List;
+    redirects: Redirect[];
+};
+/** `(( expression ))` as a command. The expression is kept as raw text. */
+export type ArithmeticCommand = {
+    tag: "arithmeticCommand";
+    expression: string;
+    redirects: Redirect[];
+};
+export type FunctionDef = {
+    tag: "functionDef";
+    name: string;
+    body: Command;
+};
+export type Command = SimpleCommand | IfCommand | LoopCommand | ForCommand | CaseCommand | Subshell | Group | ArithmeticCommand | FunctionDef;
+/** One or more commands joined by `|` (or `|&`), optionally negated. */
+export type Pipeline = {
+    tag: "pipeline";
+    negated: boolean;
+    commands: Command[];
+};
+/** Pipelines joined by `&&` / `||`, left to right. */
+export type AndOr = {
+    tag: "andOr";
+    first: Pipeline;
+    rest: {
+        op: "&&" | "||";
+        pipeline: Pipeline;
+    }[];
+};
+export type ListItem = {
+    tag: "listItem";
+    command: AndOr;
+    /** True when the command was followed by `&`. */
+    background: boolean;
+};
+/** A sequence of commands separated by `;`, `&`, or newlines — the top
+ * level of a script, and the body of every compound command. */
+export type List = {
+    tag: "list";
+    items: ListItem[];
+};

package/dist/parsers/bash/types.js

@@ -0,0 +1,2 @@
+/** AST types for the bash parser. See `index.ts` for the supported subset. */
+export {};

package/dist/parsers/bash/words.d.ts

@@ -0,0 +1,22 @@
+import { Parser, ParserResult } from "../../types.js";
+import { BashWord } from "./types.js";
+/** Balanced parens, for `$(( ))` and `(( ))`. Sound because quotes are
+ * not delimiters in bash arithmetic. Declared as a function so the
+ * words/commands module cycle is safe under any import order. */
+export declare function parenBody(input: string): ParserResult<string>;
+/** A word: quoting and expansions handled, trailing whitespace eaten.
+ * Declared as a function so the words/lists/commands module cycle is
+ * safe under any import order. */
+export declare function wordParser(input: string): ParserResult<BashWord>;
+/** A word shaped like an assignment (`name=` / `name+=`). At command
+ * position this is never a plain command word: `name=` was already taken
+ * by the assignment parser, so what reaches here is unsupported syntax
+ * (append, arrays) and must fail rather than parse as a command. */
+export declare const assignmentLookalike: Parser<string>;
+/** A word at command position: rejects reserved words standing alone,
+ * which is how body lists stop at `fi`/`done`/`esac`. Quoted or extended
+ * words (`"fi"`, `fi.txt`) pass, matching bash. */
+export declare function commandWord(input: string): ParserResult<BashWord>;
+/** A run of identifier characters, shared with the assignment parser.
+ * Declared as a function for module-cycle safety. */
+export declare function identifierRun(input: string): ParserResult<string>;

package/dist/parsers/bash/words.js

@@ -0,0 +1,112 @@
+/** Words: quoting, escapes, and expansions. A word is one or more
+ * adjacent parts; only the whole word is a lexeme, so parts never eat
+ * trailing whitespace (`$(pwd) x` must not glue `x` onto the word). */
+import { lazy, many, many1, many1WithJoin, map, not, or, seq, } from "../../combinators.js";
+import { anyChar, char, compileCharPredicate, label, oneOf, str, takeWhile, takeWhile1, } from "../../parsers.js";
+import { trace } from "../../trace.js";
+import { bashLexemes, METACHARACTERS, reservedToken } from "./lexemes.js";
+import { list0 as list0Import } from "./lists.js";
+function literal(text) {
+    return { tag: "literal", text };
+}
+/** Merge adjacent literal parts so ASTs read naturally. */
+function mergeLiterals(parts) {
+    const merged = [];
+    for (const part of parts) {
+        const previous = merged[merged.length - 1];
+        if (part.tag === "literal" && (previous === null || previous === void 0 ? void 0 : previous.tag) === "literal") {
+            merged[merged.length - 1] = literal(previous.text + part.text);
+        }
+        else {
+            merged.push(part);
+        }
+    }
+    return merged;
+}
+const WORD_STOP = METACHARACTERS + "'\"`$\\";
+const isWordStop = compileCharPredicate(WORD_STOP);
+const NOT_SINGLE_QUOTE = (code) => code !== 0x27; // '
+const plainRun = map(takeWhile1((code) => !isWordStop(code), "word characters"), literal);
+// No escapes exist inside single quotes; scanning to the next quote is
+// exactly bash's rule.
+const singleQuoted = label("a single-quoted string", seq([char("'"), takeWhile(NOT_SINGLE_QUOTE), char("'")], (results) => ({ tag: "singleQuoted", text: results[1] })));
+const IDENT_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_";
+const SPECIAL_VARIABLES = "?!#@*$-0123456789";
+// No lone-`$` fallback: a `$` that starts no supported expansion is a
+// parse error, which is what makes `$'...'` and `$"..."` fail loudly.
+const variablePart = seq([char("$"), or(oneOf(SPECIAL_VARIABLES), many1WithJoin(oneOf(IDENT_CHARS)))], (results) => ({ tag: "variable", name: results[1] }));
+// Balanced braces by recursion instead of a depth counter: a body is a
+// sequence of non-brace runs and nested `{...}` groups.
+const braceBody = map(many(or(takeWhile1((code) => code !== 0x7b && code !== 0x7d, "brace content"), // { }
+seq([char("{"), lazy(() => braceBody), char("}")], (results) => "{" + results[1] + "}"))), (chunks) => chunks.join(""));
+const paramExpansion = seq([str("${"), braceBody, char("}")], (results) => ({
+    tag: "paramExpansion",
+    expression: results[1],
+}));
+const parenBodyImpl = map(many(or(takeWhile1((code) => code !== 0x28 && code !== 0x29, "paren content"), // ( )
+seq([char("("), lazy(() => parenBodyImpl), char(")")], (results) => "(" + results[1] + ")"))), (chunks) => chunks.join(""));
+/** Balanced parens, for `$(( ))` and `(( ))`. Sound because quotes are
+ * not delimiters in bash arithmetic. Declared as a function so the
+ * words/commands module cycle is safe under any import order. */
+export function parenBody(input) {
+    return parenBodyImpl(input);
+}
+const arithmeticExpansion = seq([str("$(("), parenBody, str("))")], (results) => ({
+    tag: "arithmeticExpansion",
+    expression: results[1],
+}));
+// `char(")")`, not `symbol(")")`: word parts must not eat trailing
+// whitespace. `list0` is deferred to parse time: see the module-cycle
+// note in commands.ts.
+const commandSubstitution = seq([str("$("), lazy(() => list0Import), char(")")], (results) => ({
+    tag: "commandSubstitution",
+    command: results[1],
+}));
+const unquotedEscape = seq([char("\\"), anyChar], 
+// Backslash-newline inside a word disappears (line continuation).
+(results) => literal(results[1] === "\n" ? "" : results[1]));
+const DQ_ESCAPABLE = '"$`\\';
+const doubleQuoteEscape = or(seq([char("\\"), oneOf(DQ_ESCAPABLE)], (results) => literal(results[1])), seq([char("\\"), char("\n")], () => literal("")), 
+// Backslash before any other character stays literal.
+map(char("\\"), () => literal("\\")));
+const isDoubleQuoteStop = compileCharPredicate('"$`\\');
+const doubleQuoteLiteral = map(takeWhile1((code) => !isDoubleQuoteStop(code), "string characters"), literal);
+// No backtick alternative: an unescaped backtick inside double quotes
+// fails the parse (backtick substitution is unsupported; use `$()`).
+const doubleQuoted = seq([
+    char('"'),
+    many(or(arithmeticExpansion, commandSubstitution, paramExpansion, variablePart, doubleQuoteEscape, doubleQuoteLiteral)),
+    char('"'),
+], (results) => ({
+    tag: "doubleQuoted",
+    parts: mergeLiterals(results[1]),
+}));
+const wordPart = or(singleQuoted, doubleQuoted, arithmeticExpansion, commandSubstitution, paramExpansion, variablePart, unquotedEscape, plainRun);
+const wordParserImpl = bashLexemes.lexeme(trace("bash:word", map(many1(wordPart), (parts) => ({
+    tag: "word",
+    parts: mergeLiterals(parts),
+}))));
+/** A word: quoting and expansions handled, trailing whitespace eaten.
+ * Declared as a function so the words/lists/commands module cycle is
+ * safe under any import order. */
+export function wordParser(input) {
+    return wordParserImpl(input);
+}
+/** A word shaped like an assignment (`name=` / `name+=`). At command
+ * position this is never a plain command word: `name=` was already taken
+ * by the assignment parser, so what reaches here is unsupported syntax
+ * (append, arrays) and must fail rather than parse as a command. */
+export const assignmentLookalike = seq([many1WithJoin(oneOf(IDENT_CHARS)), or(str("+="), str("="))], (results) => results[0]);
+const commandWordImpl = seq([not(reservedToken), not(assignmentLookalike), wordParser], (results) => results[2]);
+/** A word at command position: rejects reserved words standing alone,
+ * which is how body lists stop at `fi`/`done`/`esac`. Quoted or extended
+ * words (`"fi"`, `fi.txt`) pass, matching bash. */
+export function commandWord(input) {
+    return commandWordImpl(input);
+}
+const identifierRunImpl = many1WithJoin(oneOf(IDENT_CHARS));
+/** A run of identifier characters, shared with the assignment parser.
+ * Declared as a function for module-cycle safety. */
+export function identifierRun(input) {
+    return identifierRunImpl(input);
+}

package/dist/parsers/markdown/blocks.js

@@ -98,8 +98,13 @@ const continuationLine = (k) => map(seqC(indentOf(k), capture(manyTillStr("\n"),
 /* A blank line at line-start. `blocks.ts` already defines `blankLine` below,
  * but that variant starts with `\n` (designed for inter-block separators).
  * Here we're already past the previous `\n`, so we need a line-start variant.
- * The matched value isn't used as data; itemBody normalises blanks to "". */
-const blankContinuation = seqR(many(oneOf(" \t")), or(char("\n"), eof));
+ *
+ * We do NOT allow `eof` here: at end-of-input with no trailing whitespace
+ * this would succeed without consuming anything, and `many(itemContentLine(k))`
+ * would either spin or append a phantom blank. The final line of an item body
+ * is handled by `continuationLine`'s own `or(char("\n"), eof)`. The matched
+ * value isn't used as data; itemBody normalises blanks to "". */
+const blankContinuation = seqR(many(oneOf(" \t")), char("\n"));
 /* One line of item body (after the first). Heterogeneous return type:
  *   - continuationLine -> string (the dedented line text)
  *   - blankContinuation -> unknown (discardable seqR output)
@@ -107,17 +112,19 @@ const blankContinuation = seqR(many(oneOf(" \t")), or(char("\n"), eof));
 const itemContentLine = (k) => or(continuationLine(k), blankContinuation);
 /* Reparse an item's collected body as a sequence of blocks via `blockEntry`.
  *
- * No silent fallback. CommonMark guarantees any non-empty buffer produces at
- * least one block (worst case, a paragraph). The only legitimate empty case
- * is an item whose first line is empty and which has no continuations — we
- * handle that explicitly so the invariant `non-empty buf => at least one
- * block` stays a real invariant. */
+ * List item bodies can legitimately begin with blank lines — e.g.
+ * `- \n\n  - inner` collects `"\n- inner"`, and `- ` alone collects `"\n"`.
+ * Strip leading newlines (they carry no AST content) before handing to
+ * `many1(blockEntry)`. After trimming, the invariant `non-empty buf =>
+ * at least one block` holds (CommonMark falls back to a paragraph), so a
+ * parse failure here is a genuine parser bug worth surfacing. */
 const reparseBlocks = (buf) => {
-    if (buf === "")
+    const trimmed = buf.replace(/^\n+/, "");
+    if (trimmed === "")
         return [];
-    const r = many1(lazy(() => blockEntry))(buf);
+    const r = many1(lazy(() => blockEntry))(trimmed);
     if (!r.success) {
-        throw new Error(`reparseBlocks: failed on non-empty buffer: ${JSON.stringify(buf)}`);
+        throw new Error(`reparseBlocks: failed on non-empty buffer: ${JSON.stringify(trimmed)}`);
     }
     return r.result;
 };

package/dist/parsers/markdown/index.d.ts

@@ -3,5 +3,6 @@ export * from "./inline.js";
 export * from "./blocks.js";
 export * from "./references.js";
 export * from "./frontmatter.js";
+import { MarkdownNode } from "./types.js";
 import { Parser } from "../../types.js";
-export declare const markdownParser: Parser<unknown[]>;
+export declare const markdownParser: Parser<MarkdownNode[]>;

package/dist/parsers/markdown/references.js

@@ -16,27 +16,44 @@ export const linkDefinitionParser = seqC(set("type", "link-definition"), char("[
 export const footnoteDefinitionParser = seqC(set("type", "footnote-definition"), str("[^"), capture(many1WithJoin(noneOf("] \n\t")), "id"), str("]:"), spaces, capture(many1WithJoin(noneOf("\n")), "content"));
 /* Resolution pass.
  *
- * Walk the AST. Collect link-definitions, then rewrite ref nodes to inline
- * links/images and strip the definitions. Id matching is case-insensitive. */
+ * Walk the AST. Collect link/footnote definitions (deeply — they can now
+ * appear nested inside list-item block children), then rewrite ref nodes to
+ * inline links/images and strip the definitions everywhere they appear. Id
+ * matching is case-insensitive. */
+const CHILD_KEYS = ["content", "items", "rows"];
+const isDef = (n) => isObj(n) &&
+    (n.type === "link-definition" ||
+        n.type === "footnote-definition");
 export function resolveReferences(ast) {
     const linkDefs = new Map();
     const footnoteDefs = new Map();
-    for (const node of ast) {
+    function collect(node) {
+        if (Array.isArray(node)) {
+            node.forEach(collect);
+            return;
+        }
         if (!isObj(node))
-            continue;
-        const t = node.type;
+            return;
+        const obj = node;
+        const t = obj.type;
         if (t === "link-definition") {
-            const def = node;
+            const def = obj;
             linkDefs.set(def.id.toLowerCase(), def);
         }
         else if (t === "footnote-definition") {
-            const def = node;
+            const def = obj;
             footnoteDefs.set(def.id.toLowerCase(), def);
         }
+        for (const key of CHILD_KEYS) {
+            if (Array.isArray(obj[key]))
+                obj[key].forEach(collect);
+        }
     }
+    collect(ast);
     function walk(node) {
-        if (Array.isArray(node))
-            return node.map(walk);
+        if (Array.isArray(node)) {
+            return node.filter((n) => !isDef(n)).map(walk);
+        }
         if (!isObj(node))
             return node;
         const obj = node;
@@ -75,21 +92,17 @@ export function resolveReferences(ast) {
             }
             return { type: "inline-text", content: `[^${obj.id}]` };
         }
-        // recurse into known child-bearing fields. Nested lists now live inside
-        // a list item's `content` (alongside other block children), so no
-        // dedicated `sublist` traversal is needed.
+        // Recurse into known child-bearing fields. The array path through `walk`
+        // also strips nested link/footnote definitions, so list items, blockquotes,
+        // etc. all get the same treatment as the top-level array.
         const out = Object.assign({}, obj);
-        for (const key of ["content", "items", "rows"]) {
+        for (const key of CHILD_KEYS) {
             if (Array.isArray(obj[key]))
-                out[key] = obj[key].map(walk);
+                out[key] = walk(obj[key]);
         }
         return out;
     }
-    return ast
-        .filter((n) => !(isObj(n) &&
-        (n.type === "link-definition" ||
-            n.type === "footnote-definition")))
-        .map(walk);
+    return walk(ast);
 }
 function isObj(v) {
     return typeof v === "object" && v !== null;

package/dist/parsers/markdown/types.d.ts

@@ -81,6 +81,8 @@ export type ListItem = {
     checked?: boolean;
 };
 export type Block = Paragraph | Heading | CodeBlock | List | BlockQuote | HorizontalRule | Table | HTMLBlock | Image | LinkDef | FootnoteDef;
+/** Top-level node in the markdown AST (optionally prefixed by frontmatter). */
+export type MarkdownNode = Block | Frontmatter;
 export type List = {
     type: "list";
     ordered: boolean;

package/dist/parsers/within.js

@@ -1,5 +1,6 @@
 import { trace } from "../trace.js";
 import { success } from "../types.js";
+import { getParseState } from "../parseState.js";
 /**
  * `within` is a funny combinator. It finds zero or more instances of `parser` within the input.
  * It always succeeds and returns an array of results, each one being a matched or unmatched string.
@@ -59,6 +60,9 @@ import { success } from "../types.js";
  */
 export function within(parser) {
     return trace("within", (input) => {
+        // A search is speculation: probes at every offset must not leak
+        // commits into the committedFailure slot.
+        const slotBefore = getParseState().committedFailure;
         let start = 0;
         let current = 0;
         const results = [];
@@ -89,6 +93,7 @@ export function within(parser) {
                 value: input.slice(start, current),
             });
         }
+        getParseState().committedFailure = slotBefore;
         return success(results, "");
     });
 }

package/dist/parsers.d.ts

@@ -47,6 +47,18 @@ export declare function noneOf(chars: string): Parser<string>;
  * ```
  */
 export type CharPredicate = (code: number) => boolean;
+/**
+ * Compile a string of allowed characters or a user-supplied predicate
+ * into a fast `CharPredicate`. For string inputs whose characters are
+ * all ASCII (code points < 128), the result is a single 128-byte
+ * `Uint8Array` lookup — one array read per character test. Non-ASCII
+ * characters in the string fall back to a `Set<number>` check.
+ * Predicates pass through unchanged.
+ *
+ * @param charsOrPred - a string of allowed characters or a predicate function
+ * @returns - a `CharPredicate` suitable for use in tight scanning loops
+ */
+export declare function compileCharPredicate(charsOrPred: string | CharPredicate): CharPredicate;
 /**
  * A faster version of many/ manyWithJoin for character-class scanning.
  *
@@ -126,8 +138,19 @@ export declare function takeWhile1(charsOrPred: string | CharPredicate, expected
 export declare const anyChar: Parser<string>;
 /**
  * Wraps a parser with a human-readable label for error reporting.
- * On failure, suppresses any inner failure recordings and records only the label.
- * This produces clean error messages like `expected a digit` instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails at the label's own position (it never got
+ * anywhere), its internal failure records are suppressed and only the
+ * label is recorded — producing clean messages like `expected a digit`
+ * instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails STRICTLY INSIDE the labeled region (it
+ * consumed input first), its deeper, more specific record is kept and
+ * the label stays out of the way — so a grammar labeled at every level
+ * still surfaces the deepest thing the parser actually knew.
+ * (Comparing against the label's own position, rather than the previous
+ * record, is what keeps shallow labels clean while deep knowledge
+ * survives.)
  *
  * @param name - human-readable description of what the parser expects
  * @param parser - the parser to wrap

package/dist/parsers.js

@@ -1,5 +1,5 @@
 import { many1WithJoin } from "./combinators.js";
-import { trace } from "./trace.js";
+import { trace, getInputStr } from "./trace.js";
 import { recordFailure, saveRightmostFailure, restoreRightmostFailure } from "./rightmostFailure.js";
 import { captureSuccess, failure, success, } from "./types.js";
 import { escape } from "./utils.js";
@@ -104,7 +104,7 @@ export function noneOf(chars) {
  * @param charsOrPred - a string of allowed characters or a predicate function
  * @returns - a `CharPredicate` suitable for use in tight scanning loops
  */
-function compileCharPredicate(charsOrPred) {
+export function compileCharPredicate(charsOrPred) {
     if (typeof charsOrPred === "function")
         return charsOrPred;
     const chars = charsOrPred;
@@ -241,8 +241,19 @@ export const anyChar = trace("anyChar", (input) => {
 });
 /**
  * Wraps a parser with a human-readable label for error reporting.
- * On failure, suppresses any inner failure recordings and records only the label.
- * This produces clean error messages like `expected a digit` instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails at the label's own position (it never got
+ * anywhere), its internal failure records are suppressed and only the
+ * label is recorded — producing clean messages like `expected a digit`
+ * instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails STRICTLY INSIDE the labeled region (it
+ * consumed input first), its deeper, more specific record is kept and
+ * the label stays out of the way — so a grammar labeled at every level
+ * still surfaces the deepest thing the parser actually knew.
+ * (Comparing against the label's own position, rather than the previous
+ * record, is what keeps shallow labels clean while deep knowledge
+ * survives.)
  *
  * @param name - human-readable description of what the parser expects
  * @param parser - the parser to wrap
@@ -252,6 +263,21 @@ export function label(name, parser) {
     return (input) => {
         const saved = saveRightmostFailure();
         const result = parser(input);
+        if (!result.success && result.committed === true) {
+            // Committed failures carry their own story — no re-labeling,
+            // no restore games.
+            return result;
+        }
+        const afterChild = saveRightmostFailure();
+        const labelPos = getInputStr().length - input.length;
+        const childGotStrictlyDeeper = afterChild.pos > labelPos;
+        if (!result.success && childGotStrictlyDeeper) {
+            // The child FAILED somewhere specific past this label's start —
+            // keep its record; adding the label here would only blur it.
+            // On success the restore below still runs, scrubbing speculative
+            // records left by backtracked alternatives inside the region.
+            return result;
+        }
         restoreRightmostFailure(saved);
         if (!result.success)
             recordFailure(input, name);

package/dist/position.d.ts

@@ -18,14 +18,24 @@ export declare function buildLineTable(source: string): number[];
  * Both line and column are 0-based.
  */
 export declare function offsetToPosition(lineTable: number[], offset: number): Position;
+/**
+ * Compose an inner-parse position with a base position (the point in the
+ * enclosing input where the inner input begins). Offsets and lines add;
+ * the base column applies only while still on the base line (inner line 0).
+ */
+export declare function composePosition(base: Position, pos: Position): Position;
 /**
  * A zero-width parser that returns the current offset into the input string.
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the offset is reported in the enclosing parse's
+ * coordinates (the state's `basePosition` is added).
  */
 export declare const getOffset: Parser<number>;
 /**
  * A zero-width parser that returns the current position (offset, line, column).
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the position is reported in the enclosing parse's
+ * coordinates (composed with the state's `basePosition`).
  */
 export declare const getPosition: Parser<Position>;
 /**