tarsec 0.4.7 → 0.5.0

package/README.md

@@ -36,6 +36,7 @@ parser("hello there"); // failure
 ## Learning tarsec
 - [A five minute introduction](/tutorials/5-minute-intro.md)
 - [The three building blocks in tarsec](/tutorials/three-building-blocks.md)
+- [Lexemes: your grammar's token vocabulary](/tutorials/lexemes.md)
 - [API reference](https://egonschiele.github.io/tarsec/)
 
 ## Features

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from "./types.js";
 export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
+export * from "./lexeme.js";

package/dist/index.js

@@ -5,3 +5,4 @@ export * from "./types.js";
 export * from "./tarsecError.js";
 export * from "./position.js";
 export * from "./rightmostFailure.js";
+export * from "./lexeme.js";

package/dist/lexeme.d.ts

@@ -0,0 +1,71 @@
+import { CharPredicate } from "./parsers.js";
+import { CaptureParser, Parser, PlainObject } from "./types.js";
+/** Configuration for `makeLexemes`. */
+export type LexemeConfig = {
+    /** Characters eaten after every lexeme, e.g. " \t". */
+    whitespace: string;
+    /** Line-comment marker (e.g. "#" or "//"); comments are eaten as whitespace,
+     * up to but NOT including the newline (newlines may be significant). */
+    lineComment?: string;
+    /** When true, `\` followed by a newline is also eaten as whitespace. */
+    lineContinuation?: boolean;
+    /** Charset or predicate for an identifier's first character.
+     * Defaults to letters and "_". */
+    identStart?: string | CharPredicate;
+    /** Charset or predicate for subsequent identifier characters.
+     * Defaults to letters, digits, and "_". */
+    identRest?: string | CharPredicate;
+    /** Words `identifier` refuses to match (and `keyword` accepts). */
+    keywords?: string[];
+    /** Charset or predicate for characters that can appear in operators.
+     * `operator` uses it for longest-match rejection: `operator("<")` refuses
+     * to match the front of `<=`. Defaults to common symbol characters. */
+    operatorChars?: string | CharPredicate;
+};
+export type Lexemes = {
+    /** Whitespace/comment skipper as a parser. Always succeeds. Use once at the
+     * top of a grammar to eat leading whitespace; lexemes handle the rest. */
+    whitespace: Parser<null>;
+    /** Whitespace/comment skipper as a total function: returns the input with
+     * leading whitespace removed. Handy where a parser result would force
+     * callers to handle a failure that cannot happen. */
+    skipWhitespace: (input: string) => string;
+    /** Run a parser, then eat trailing whitespace/comments. Capture-preserving. */
+    lexeme: {
+        <T, C extends PlainObject>(parser: CaptureParser<T, C>): CaptureParser<T, C>;
+        <T>(parser: Parser<T>): Parser<T>;
+    };
+    /** `lexeme(str(s))` — match a literal, eat trailing whitespace. */
+    symbol: <const S extends string>(s: S) => Parser<S>;
+    /** Match an identifier (per identStart/identRest), rejecting keywords. */
+    identifier: Parser<string>;
+    /** Match `s` only when not followed by an identRest character, so
+     * `keyword("if")` rejects "ifx". */
+    keyword: (s: string) => Parser<string>;
+    /** Match `s` only when not followed by an operator character, so
+     * `operator("<")` rejects the front of "<=". The symbolic counterpart
+     * of `keyword`. */
+    operator: (s: string) => Parser<string>;
+    /** Run a parser between "(" and ")", whitespace handled. Returns the
+     * inner result. */
+    parens: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "[" and "]". */
+    brackets: <T>(parser: Parser<T>) => Parser<T>;
+    /** Like `parens`, with "{" and "}". */
+    braces: <T>(parser: Parser<T>) => Parser<T>;
+    /** Zero or more of `parser`, separated by commas. */
+    commaSep: <T>(parser: Parser<T>) => Parser<T[]>;
+    /** One or more of `parser`, separated by commas. */
+    commaSep1: <T>(parser: Parser<T>) => Parser<T[]>;
+};
+/**
+ * Build a set of lexeme helpers: ordinary parsers that handle whitespace,
+ * comments, and keywords in one place. This is a *scannerless* lexeme layer
+ * (like Parsec's `makeTokenParser`), not a lexer — there is no separate pass
+ * and no token array.
+ *
+ * The discipline: every token-shaped parser eats its own *trailing*
+ * whitespace; eat *leading* whitespace once at the top with `whitespace`
+ * (or `skipWhitespace`).
+ */
+export declare function makeLexemes(config: LexemeConfig): Lexemes;

package/dist/lexeme.js

@@ -0,0 +1,130 @@
+import { sepBy, sepBy1, seq } from "./combinators.js";
+import { compileCharPredicate, str } from "./parsers.js";
+import { trace } from "./trace.js";
+import { recordFailure } from "./rightmostFailure.js";
+import { failure, success, } from "./types.js";
+const LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+const OPERATOR_CHARS = "+-*/<>=!&|^%~?:.";
+const BACKSLASH_CODE = 0x5c;
+const NEWLINE = "\n";
+/**
+ * Build a set of lexeme helpers: ordinary parsers that handle whitespace,
+ * comments, and keywords in one place. This is a *scannerless* lexeme layer
+ * (like Parsec's `makeTokenParser`), not a lexer — there is no separate pass
+ * and no token array.
+ *
+ * The discipline: every token-shaped parser eats its own *trailing*
+ * whitespace; eat *leading* whitespace once at the top with `whitespace`
+ * (or `skipWhitespace`).
+ */
+export function makeLexemes(config) {
+    var _a, _b, _c, _d;
+    const isWhitespaceChar = compileCharPredicate(config.whitespace);
+    // Treat an empty marker as absent: `startsWith("", i)` is always true, so
+    // "" would make the comment branch loop forever at a newline.
+    const commentMarker = config.lineComment || undefined;
+    const allowContinuation = config.lineContinuation === true;
+    const skipWhitespace = (input) => {
+        let index = 0;
+        const length = input.length;
+        // Terminates: every branch either advances `index` or breaks.
+        while (index < length) {
+            if (isWhitespaceChar(input.charCodeAt(index))) {
+                index++;
+                continue;
+            }
+            if (allowContinuation &&
+                input.charCodeAt(index) === BACKSLASH_CODE &&
+                input[index + 1] === NEWLINE) {
+                index += 2;
+                continue;
+            }
+            if (commentMarker !== undefined && input.startsWith(commentMarker, index)) {
+                const newlineIndex = input.indexOf(NEWLINE, index);
+                if (newlineIndex === -1) {
+                    index = length;
+                }
+                else {
+                    index = newlineIndex; // stop AT the newline, don't consume it
+                }
+                continue;
+            }
+            break;
+        }
+        return input.slice(index);
+    };
+    const whitespace = trace("lexeme:whitespace", (input) => success(null, skipWhitespace(input)));
+    const lexeme = ((parser) => (input) => {
+        const result = parser(input);
+        if (!result.success)
+            return result;
+        return Object.assign(Object.assign({}, result), { rest: skipWhitespace(result.rest) });
+    });
+    const symbol = (s) => lexeme(str(s));
+    const isIdentStart = compileCharPredicate((_a = config.identStart) !== null && _a !== void 0 ? _a : LETTERS + "_");
+    const isIdentRest = compileCharPredicate((_b = config.identRest) !== null && _b !== void 0 ? _b : LETTERS + DIGITS + "_");
+    const keywordSet = new Set((_c = config.keywords) !== null && _c !== void 0 ? _c : []);
+    const identifier = lexeme(trace("lexeme:identifier", (input) => {
+        if (input.length === 0 || !isIdentStart(input.charCodeAt(0))) {
+            recordFailure(input, "an identifier");
+            return failure("expected an identifier", input);
+        }
+        let end = 1;
+        // Terminates: `end` strictly increases toward input.length.
+        while (end < input.length && isIdentRest(input.charCodeAt(end)))
+            end++;
+        const name = input.slice(0, end);
+        if (keywordSet.has(name)) {
+            recordFailure(input, "an identifier");
+            return failure(`expected an identifier, got keyword ${name}`, input);
+        }
+        return success(name, input.slice(end));
+    }));
+    /** Match `s` as a whole token: it must not be followed by a character
+     * from `continuationChars`, so a shorter token never steals the front of
+     * a longer one. Shared by `keyword` (identifier characters) and
+     * `operator` (operator characters). */
+    function wholeToken(kind, s, isContinuation) {
+        return lexeme(trace(`lexeme:${kind}(${s})`, (input) => {
+            if (!input.startsWith(s)) {
+                recordFailure(input, `${kind} ${s}`);
+                return failure(`expected ${kind} ${s}`, input);
+            }
+            const followingCode = input.charCodeAt(s.length);
+            // charCodeAt returns NaN past the end of input; NaN fails the
+            // predicate, so a token at end-of-input matches.
+            if (!Number.isNaN(followingCode) && isContinuation(followingCode)) {
+                recordFailure(input, `${kind} ${s}`);
+                return failure(`expected ${kind} ${s}`, input);
+            }
+            return success(s, input.slice(s.length));
+        }));
+    }
+    const keyword = (s) => wholeToken("keyword", s, isIdentRest);
+    const isOperatorChar = compileCharPredicate((_d = config.operatorChars) !== null && _d !== void 0 ? _d : OPERATOR_CHARS);
+    const operator = (s) => wholeToken("operator", s, isOperatorChar);
+    function delimited(open, close, parser) {
+        return seq([symbol(open), parser, symbol(close)], (results) => results[1]);
+    }
+    const parens = (parser) => delimited("(", ")", parser);
+    const brackets = (parser) => delimited("[", "]", parser);
+    const braces = (parser) => delimited("{", "}", parser);
+    const comma = symbol(",");
+    const commaSep = (parser) => sepBy(comma, parser);
+    const commaSep1 = (parser) => sepBy1(comma, parser);
+    return {
+        whitespace,
+        skipWhitespace,
+        lexeme,
+        symbol,
+        identifier,
+        keyword,
+        operator,
+        parens,
+        brackets,
+        braces,
+        commaSep,
+        commaSep1,
+    };
+}

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

@@ -0,0 +1,11 @@
+import { Parser, ParserResult } from "../../types.js";
+import { Assignment, Command, Redirect } from "./types.js";
+/** `> file`, `2>&1`, `<<< "$str"`, ... The file descriptor must be
+ * attached to the operator (`2>` redirects fd 2; `2 >` is an argument). */
+export declare const redirectParser: Parser<Redirect>;
+/** `name=value`, `name=`, or `name="$x"y` — value is a full word. */
+export declare const assignmentParser: Parser<Assignment>;
+/** Any single command: simple, compound (with trailing redirects), or a
+ * function definition. Declared as a function so the words/lists/commands
+ * module cycle is safe under any import order. */
+export declare function commandParser(input: string): ParserResult<Command>;

package/dist/parsers/bash/commands.js

@@ -0,0 +1,197 @@
+/** Commands: redirects, assignments, simple commands, compound commands,
+ * and function definitions. */
+import { lazy, many, many1, many1WithJoin, map, not, optional, or, peek, seq, } from "../../combinators.js";
+import { char, oneOf, str } from "../../parsers.js";
+import { trace } from "../../trace.js";
+import { failure, success } from "../../types.js";
+import { bashLexemes, groupClose, groupOpen, linebreak, newlineToken, wordBoundary, } from "./lexemes.js";
+import { list0 as list0Import, list1 as list1Import, list1WithEnd as list1WithEndImport, } from "./lists.js";
+import { commandWord as commandWordImport, identifierRun as identifierRunImport, parenBody as parenBodyImport, wordParser as wordParserImport, } from "./words.js";
+const L = bashLexemes;
+// The words/lists/commands modules form an import cycle. Deferring every
+// cross-module reference to parse time (via lazy) keeps the cycle safe
+// regardless of module evaluation order or transform.
+const list0 = lazy(() => list0Import);
+const list1 = lazy(() => list1Import);
+const commandWord = lazy(() => commandWordImport);
+const identifierRun = lazy(() => identifierRunImport);
+const parenBody = lazy(() => parenBodyImport);
+const wordParser = lazy(() => wordParserImport);
+const list1WithEnd = lazy(() => list1WithEndImport);
+// ---------------------------------------------------------------------------
+// Redirects and assignments
+// ---------------------------------------------------------------------------
+// Longest first, so ">>" wins over ">". The bare "<" refuses a following
+// "<" so heredocs (unsupported) stay unparsed rather than half-parsed.
+const redirectOp = or(str("&>>"), str("&>"), str(">>"), str(">|"), str(">&"), str("<<<"), str("<&"), str("<>"), str(">"), seq([str("<"), not(char("<"))], (results) => results[0]));
+const fileDescriptor = many1WithJoin(oneOf("0123456789"));
+/** `> file`, `2>&1`, `<<< "$str"`, ... The file descriptor must be
+ * attached to the operator (`2>` redirects fd 2; `2 >` is an argument). */
+export const redirectParser = trace("bash:redirect", seq([optional(fileDescriptor), L.lexeme(redirectOp), wordParser], (results) => ({
+    tag: "redirect",
+    fd: results[0] === null ? null : parseInt(results[0], 10),
+    op: results[1],
+    target: results[2],
+})));
+/** `name=value`, `name=`, or `name="$x"y` — value is a full word. */
+export const assignmentParser = L.lexeme(trace("bash:assignment", seq([identifierRun, str("="), optional(wordParser)], (results) => ({
+    tag: "assignment",
+    name: results[0],
+    value: results[2],
+}))));
+// ---------------------------------------------------------------------------
+// Simple commands
+// ---------------------------------------------------------------------------
+const prefixItem = or(assignmentParser, redirectParser);
+function buildSimpleCommand(prefix, first, rest) {
+    const assignments = prefix.filter((item) => item.tag === "assignment");
+    const redirects = [
+        ...prefix.filter((item) => item.tag === "redirect"),
+        ...rest.filter((item) => item.tag === "redirect"),
+    ];
+    const words = [
+        ...(first === null ? [] : [first]),
+        ...rest.filter((item) => item.tag === "word"),
+    ];
+    return { tag: "simpleCommand", assignments, words, redirects };
+}
+// "At least one of prefix/word" expressed as the two valid shapes.
+const simpleCommandParser = trace("bash:simpleCommand", or(seq([many(prefixItem), commandWord, many(or(redirectParser, wordParser))], (results) => buildSimpleCommand(results[0], results[1], results[2])), seq([many1(prefixItem)], (results) => buildSimpleCommand(results[0], null, []))));
+// ---------------------------------------------------------------------------
+// Compound commands
+// ---------------------------------------------------------------------------
+const elifClause = seq([L.keyword("elif"), list1, L.keyword("then"), list1], (results) => ({ cond: results[1], thenBody: results[3] }));
+const elseClause = seq([L.keyword("else"), list1], (results) => results[1]);
+const ifParser = seq([
+    L.keyword("if"), list1,
+    L.keyword("then"), list1,
+    many(elifClause),
+    optional(elseClause),
+    L.keyword("fi"),
+], (results) => ({
+    tag: "if",
+    cond: results[1],
+    thenBody: results[3],
+    elifs: results[4],
+    elseBody: results[5],
+    redirects: [],
+}));
+const loopParser = seq([
+    or(L.keyword("while"), L.keyword("until")), list1,
+    L.keyword("do"), list1, L.keyword("done"),
+], (results) => ({
+    tag: "loop",
+    kind: results[0],
+    cond: results[1],
+    body: results[3],
+    redirects: [],
+}));
+const forParser = seq([
+    L.keyword("for"), L.identifier,
+    optional(seq([L.keyword("in"), many(wordParser)], (results) => results[1])),
+    optional(or(L.operator(";"), newlineToken)),
+    linebreak,
+    L.keyword("do"), list1, L.keyword("done"),
+], (results) => ({
+    tag: "for",
+    variable: results[1],
+    words: results[2],
+    body: results[6],
+    redirects: [],
+}));
+// Patterns via explicit seq/many: sepBy1 silently swallows a trailing
+// separator when the next parse fails, which would hide a real error.
+const casePatterns = seq([
+    wordParser,
+    many(seq([L.operator("|"), wordParser], (results) => results[1])),
+], (results) => [results[0], ...results[1]]);
+// Every item needs `;;` (or `;&` / `;;&`) unless `esac` follows directly.
+const caseTerminator = or(seq([or(L.operator(";;&"), L.operator(";;"), L.operator(";&")), linebreak], (results) => results[0]), map(peek(L.keyword("esac")), () => null));
+// Without a leading `(`, a bare `esac` cannot start a pattern — it ends
+// the case statement (bash rejects `case x in esac) ...`).
+const bareEsac = seq([str("esac"), wordBoundary], () => "esac");
+const caseItemStart = or(seq([L.symbol("("), casePatterns], (results) => results[1]), seq([not(bareEsac), casePatterns], (results) => results[1]));
+const caseItemParser = seq([caseItemStart, L.symbol(")"), list0, caseTerminator], (results) => ({
+    patterns: results[0],
+    body: results[2],
+    terminator: results[3],
+}));
+const caseParser = seq([
+    L.keyword("case"), wordParser, L.keyword("in"), linebreak,
+    many(caseItemParser),
+    L.keyword("esac"),
+], (results) => ({
+    tag: "case",
+    subject: results[1],
+    items: results[4],
+    redirects: [],
+}));
+const arithmeticCommand = L.lexeme(seq([str("(("), parenBody, str("))")], (results) => ({
+    tag: "arithmeticCommand",
+    expression: results[1],
+    redirects: [],
+})));
+const subshellParser = seq([L.symbol("("), list1, L.symbol(")")], (results) => ({
+    tag: "subshell",
+    body: results[1],
+    redirects: [],
+}));
+/** Can `}` directly follow this command, as it can in bash? True for a
+ * compound command with no trailing redirects (`{ { echo a; } }`), and
+ * for a function definition whose body qualifies. A redirect re-enters
+ * word context (`{ { cat; } > log }` is rejected by bash), and `(( ))`
+ * does not qualify. */
+function closesGroup(command) {
+    if (command.tag === "functionDef")
+        return closesGroup(command.body);
+    const isCompound = command.tag === "if" ||
+        command.tag === "loop" ||
+        command.tag === "for" ||
+        command.tag === "case" ||
+        command.tag === "subshell" ||
+        command.tag === "group";
+    return isCompound && command.redirects.length === 0;
+}
+function endsAtCommandPosition({ list, endedWithSeparator }) {
+    if (endedWithSeparator)
+        return true;
+    const lastItem = list.items[list.items.length - 1];
+    const andOr = lastItem.command;
+    const lastPipeline = andOr.rest.length > 0 ? andOr.rest[andOr.rest.length - 1].pipeline : andOr.first;
+    return closesGroup(lastPipeline.commands[lastPipeline.commands.length - 1]);
+}
+// `}` is a reserved word, recognized only at command position: the group
+// body must end with a separator or a bare compound command. Without this
+// check, `{ echo a }` would fail OPEN (bash treats that `}` as an
+// argument to echo and rejects the unterminated group).
+const groupParser = (input) => {
+    const result = seq([groupOpen, list1WithEnd, groupClose], (results) => results[1])(input);
+    if (!result.success)
+        return result;
+    if (!endsAtCommandPosition(result.result)) {
+        return failure("expected ; & or newline before }", input);
+    }
+    return success({ tag: "group", body: result.result.list, redirects: [] }, result.rest);
+};
+const compoundParser = or(ifParser, loopParser, forParser, caseParser, arithmeticCommand, subshellParser, groupParser);
+const compoundWithRedirects = seq([compoundParser, many(redirectParser)], (results) => (Object.assign(Object.assign({}, results[0]), { redirects: results[1] })));
+const functionParens = seq([L.symbol("("), L.symbol(")")], () => "()");
+// "Needs `function` or `()`" expressed as the two valid shapes. The body
+// must be a compound command (bash rejects `f() echo hi` and nested
+// definitions like `f() g() { :; }`); trailing redirects are allowed.
+const functionDefParser = or(seq([L.keyword("function"), L.identifier, optional(functionParens), linebreak, compoundWithRedirects], (results) => ({
+    tag: "functionDef",
+    name: results[1],
+    body: results[4],
+})), seq([L.identifier, functionParens, linebreak, compoundWithRedirects], (results) => ({
+    tag: "functionDef",
+    name: results[0],
+    body: results[3],
+})));
+const commandParserImpl = trace("bash:command", or(compoundWithRedirects, functionDefParser, simpleCommandParser));
+/** Any single command: simple, compound (with trailing redirects), or a
+ * function definition. Declared as a function so the words/lists/commands
+ * module cycle is safe under any import order. */
+export function commandParser(input) {
+    return commandParserImpl(input);
+}

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

@@ -0,0 +1,57 @@
+/**
+ * A fail-closed bash parser: a deliberately smaller bash syntax that is
+ * either parsed correctly or rejected with a parse error — never silently
+ * mis-parsed. Intended for contexts where acting on a wrong parse is
+ * worse than rejecting a valid script.
+ *
+ * Soundness comes from two structural rules plus explicit cuts:
+ *
+ * 1. Separators between commands are MANDATORY (`;`, `&`, or newline),
+ *    so text left over by a construct becomes a parse error instead of a
+ *    phantom second command.
+ * 2. No permissive fallbacks: a `$`, backtick, or `{`/`}` that isn't part
+ *    of a supported construct fails the parse instead of degrading to a
+ *    literal.
+ *
+ * Supported: words with single/double quoting, escapes, `$var`, `${...}`,
+ * recursive `$(...)`, `$((...))`; assignments; redirects (fd prefixes,
+ * `2>&1`, `>&2`, `<<<`); pipelines with `!`; `&&`/`||`; `&` background;
+ * `;`/newline separators; comments and line continuations; `if`/`elif`/
+ * `else`, `while`/`until`, `for`, `case`, subshells, `{ }` groups,
+ * `(( ))`, and both function-definition styles.
+ *
+ * Deliberately UNSUPPORTED (valid bash, rejected here — fail closed):
+ * arrays `x=(...)`, append `x+=`, ANSI-C `$'...'` / locale `$"..."`,
+ * backtick substitution (use `$()`), `[[ ]]` (its `]]` delimiter can
+ * appear inside quoted operands, so scanning for it is unsound; `[` is an
+ * ordinary command and still works), brace expansion `{a,b}` and literal
+ * `{`/`}` in words (quote them), bare `$` (write `\$` or '$'), heredocs,
+ * process substitution `<()`, `select`/`coproc`/`time`.
+ *
+ * Kept as RAW TEXT (delimiters are sound, contents are not interpreted):
+ * `${...}` (balanced braces), `$((...))` and `((...))` (balanced parens —
+ * quotes are not delimiters in bash arithmetic).
+ *
+ * Out of scope by design, as in bash's own parser: glob (`*`, `?`) and
+ * tilde expansion happen after parsing; consumers see the literal word
+ * text and decide for themselves.
+ *
+ * For error positions, use the standard tarsec flow:
+ *
+ * ```ts
+ * setInputStr(input);
+ * resetRightmostFailure();
+ * const result = bashParser(input);
+ * if (!result.success) console.log(getErrorMessage());
+ * ```
+ */
+export * from "./types.js";
+export * from "./lexemes.js";
+export * from "./words.js";
+export * from "./commands.js";
+export * from "./lists.js";
+import { Parser } from "../../types.js";
+import { List } from "./types.js";
+/** Parse a whole script (or any command list) to a `List`. Fails unless
+ * the entire input is consumed. */
+export declare const bashParser: Parser<List>;

package/dist/parsers/bash/index.js

@@ -0,0 +1,58 @@
+/**
+ * A fail-closed bash parser: a deliberately smaller bash syntax that is
+ * either parsed correctly or rejected with a parse error — never silently
+ * mis-parsed. Intended for contexts where acting on a wrong parse is
+ * worse than rejecting a valid script.
+ *
+ * Soundness comes from two structural rules plus explicit cuts:
+ *
+ * 1. Separators between commands are MANDATORY (`;`, `&`, or newline),
+ *    so text left over by a construct becomes a parse error instead of a
+ *    phantom second command.
+ * 2. No permissive fallbacks: a `$`, backtick, or `{`/`}` that isn't part
+ *    of a supported construct fails the parse instead of degrading to a
+ *    literal.
+ *
+ * Supported: words with single/double quoting, escapes, `$var`, `${...}`,
+ * recursive `$(...)`, `$((...))`; assignments; redirects (fd prefixes,
+ * `2>&1`, `>&2`, `<<<`); pipelines with `!`; `&&`/`||`; `&` background;
+ * `;`/newline separators; comments and line continuations; `if`/`elif`/
+ * `else`, `while`/`until`, `for`, `case`, subshells, `{ }` groups,
+ * `(( ))`, and both function-definition styles.
+ *
+ * Deliberately UNSUPPORTED (valid bash, rejected here — fail closed):
+ * arrays `x=(...)`, append `x+=`, ANSI-C `$'...'` / locale `$"..."`,
+ * backtick substitution (use `$()`), `[[ ]]` (its `]]` delimiter can
+ * appear inside quoted operands, so scanning for it is unsound; `[` is an
+ * ordinary command and still works), brace expansion `{a,b}` and literal
+ * `{`/`}` in words (quote them), bare `$` (write `\$` or '$'), heredocs,
+ * process substitution `<()`, `select`/`coproc`/`time`.
+ *
+ * Kept as RAW TEXT (delimiters are sound, contents are not interpreted):
+ * `${...}` (balanced braces), `$((...))` and `((...))` (balanced parens —
+ * quotes are not delimiters in bash arithmetic).
+ *
+ * Out of scope by design, as in bash's own parser: glob (`*`, `?`) and
+ * tilde expansion happen after parsing; consumers see the literal word
+ * text and decide for themselves.
+ *
+ * For error positions, use the standard tarsec flow:
+ *
+ * ```ts
+ * setInputStr(input);
+ * resetRightmostFailure();
+ * const result = bashParser(input);
+ * if (!result.success) console.log(getErrorMessage());
+ * ```
+ */
+export * from "./types.js";
+export * from "./lexemes.js";
+export * from "./words.js";
+export * from "./commands.js";
+export * from "./lists.js";
+import { seq } from "../../combinators.js";
+import { eof } from "../../parsers.js";
+import { list0 } from "./lists.js";
+/** Parse a whole script (or any command list) to a `List`. Fails unless
+ * the entire input is consumed. */
+export const bashParser = seq([list0, eof], (results) => results[0]);

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

@@ -0,0 +1,27 @@
+import { Parser } from "../../types.js";
+/** Words that are reserved at command position (and rejected as
+ * identifiers). Includes constructs this parser deliberately does not
+ * support — `select`, `coproc`, `time`, `[[ ]]` — so they fail the parse
+ * instead of parsing as ordinary words. */
+export declare const WORD_RESERVED: string[];
+export declare const bashLexemes: import("../../lexeme.js").Lexemes;
+/** Characters that end a word. `{` and `}` are metacharacters here
+ * (unlike bash) because brace expansion is unsupported: a brace can only
+ * be a group delimiter or quoted. */
+export declare const METACHARACTERS = " \t\n|&;()<>{}";
+/** The next character (unconsumed) would end a word, or input is done. */
+export declare const wordBoundary: Parser<string | null>;
+/** A reserved word as a whole token. Order doesn't matter: each
+ * alternative carries its own boundary check, so `do` cannot steal the
+ * front of `done`. */
+export declare const reservedToken: Parser<string>;
+/** `{`, `}`, and `!` must be followed by whitespace. This is stricter
+ * than bash on purpose: `!(` is extglob syntax (unsupported), not
+ * negation. */
+export declare const groupOpen: Parser<string>;
+export declare const groupClose: Parser<string>;
+export declare const bangToken: Parser<string>;
+/** A significant newline, with trailing blanks and comments skipped. */
+export declare const newlineToken: Parser<"\n">;
+/** Zero or more blank (or comment-only) lines. */
+export declare const linebreak: Parser<"\n"[]>;

package/dist/parsers/bash/lexemes.js

@@ -0,0 +1,44 @@
+/** Lexeme layer and shared tokens for the bash grammar. */
+import { many, or, peek, seq } from "../../combinators.js";
+import { makeLexemes } from "../../lexeme.js";
+import { char, eof, oneOf, str } from "../../parsers.js";
+/** Words that are reserved at command position (and rejected as
+ * identifiers). Includes constructs this parser deliberately does not
+ * support — `select`, `coproc`, `time`, `[[ ]]` — so they fail the parse
+ * instead of parsing as ordinary words. */
+export const WORD_RESERVED = [
+    "if", "then", "elif", "else", "fi",
+    "do", "done", "while", "until", "for", "in",
+    "case", "esac", "function",
+    "select", "coproc", "time", "[[", "]]",
+];
+const RESERVED_TOKENS = [...WORD_RESERVED, "{", "}", "!"];
+export const bashLexemes = makeLexemes({
+    // Newlines are command separators, never skippable whitespace.
+    whitespace: " \t",
+    lineComment: "#",
+    lineContinuation: true,
+    operatorChars: "&|;<>",
+    keywords: WORD_RESERVED,
+});
+/** Characters that end a word. `{` and `}` are metacharacters here
+ * (unlike bash) because brace expansion is unsupported: a brace can only
+ * be a group delimiter or quoted. */
+export const METACHARACTERS = " \t\n|&;()<>{}";
+/** The next character (unconsumed) would end a word, or input is done. */
+export const wordBoundary = or(peek(oneOf(METACHARACTERS)), eof);
+/** A reserved word as a whole token. Order doesn't matter: each
+ * alternative carries its own boundary check, so `do` cannot steal the
+ * front of `done`. */
+export const reservedToken = or(...RESERVED_TOKENS.map((word) => seq([str(word), wordBoundary], (results) => results[0])));
+const whitespaceOrEnd = or(peek(oneOf(" \t\n")), eof);
+/** `{`, `}`, and `!` must be followed by whitespace. This is stricter
+ * than bash on purpose: `!(` is extglob syntax (unsupported), not
+ * negation. */
+export const groupOpen = bashLexemes.lexeme(seq([str("{"), whitespaceOrEnd], () => "{"));
+export const groupClose = bashLexemes.lexeme(seq([str("}"), wordBoundary], () => "}"));
+export const bangToken = bashLexemes.lexeme(seq([str("!"), whitespaceOrEnd], () => "!"));
+/** A significant newline, with trailing blanks and comments skipped. */
+export const newlineToken = bashLexemes.lexeme(char("\n"));
+/** Zero or more blank (or comment-only) lines. */
+export const linebreak = many(newlineToken);

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

@@ -0,0 +1,18 @@
+import { ParserResult } from "../../types.js";
+import { List } from "./types.js";
+/** A parsed list plus whether it ended with an explicit separator —
+ * group parsing needs this to decide whether `}` is at command position. */
+export type ListWithEnd = {
+    list: List;
+    endedWithSeparator: boolean;
+};
+/** 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 declare function list0(input: string): ParserResult<List>;
+/** A command list with at least one command — the body of every compound
+ * command, subshell, and group. */
+export declare function list1(input: string): ParserResult<List>;
+/** `list1`, but also reporting whether it ended with a separator. */
+export declare function list1WithEnd(input: string): ParserResult<ListWithEnd>;

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.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.
  *

package/dist/parsers.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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tarsec",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "A parser combinator library for TypeScript, inspired by Parsec.",
   "homepage": "https://github.com/egonSchiele/tarsec",
   "scripts": {
@@ -24,6 +24,11 @@
       "import": "./dist/parsers/markdown/index.js",
       "require": "./dist/parsers/markdown/index.js",
       "types": "./dist/parsers/markdown/index.d.ts"
+    },
+    "./parsers/bash": {
+      "import": "./dist/parsers/bash/index.js",
+      "require": "./dist/parsers/bash/index.js",
+      "types": "./dist/parsers/bash/index.d.ts"
     }
   },
   "type": "module",