tarsec 0.5.1 → 0.5.2

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

@@ -1,57 +1,54 @@
 /**
- * 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.
+ * A deliberately small bash parser: a narrow subset of bash that is either
+ * parsed correctly or rejected, never silently mis-parsed. Intended for
+ * contexts where acting on a wrong parse is worse than rejecting a command
+ * outright — an unsupported construct costs you a rejection, not a wrong
+ * answer.
  *
- * 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:
+ * `bashParser` is the entry point. It parses a whole script and fails
+ * unless the entire input is consumed.
  *
  * ```ts
- * setInputStr(input);
- * resetRightmostFailure();
- * const result = bashParser(input);
- * if (!result.success) console.log(getErrorMessage());
+ * const result = bashParser("git commit -m 'hi'");
+ * if (result.success) console.log(result.result);
  * ```
+ *
+ * The AST is shaped for consumers asking "what command is this, and what
+ * does it operate on?" — a `SimpleCommand` carries `command`, `args`,
+ * `assignments` and `redirects` as separate fields. There is no
+ * `subcommands` field: no syntactic rule separates `git status` from
+ * `echo status`, so `args` is one ordered list.
+ *
+ * SUPPORTED
+ * - Simple commands: a name, arguments, and `name=value` assignments
+ *   before it. A line that is only an assignment (`FOO=bar`) is a command
+ *   with a null `command`.
+ * - Words: bare words (letters, digits, and `_ - . = : +`), paths
+ *   (any word containing `/`), single and double quotes, `$var` and
+ *   `${var}`, and `-f` / `--flag` / `--flag=value` flags.
+ * - Double quotes interpolate `$var` and handle `\"`, `\\`, `\$`, `` \` ``.
+ * - Words built from adjacent parts: `$HOME/bin`, `"a"b`, `"$HOME"/x`.
+ * - Redirects: `>`, `>>`, `<`, and `&>`, with an optional attached file
+ *   descriptor on the first three (`2> err.txt`).
+ * - `&&` / `||` chains (one precedence level, left-associative, as in
+ *   bash) and `( ... )` grouping.
+ * - Commands separated by `;` or newlines, including CRLF.
+ *
+ * REJECTED, and worth knowing because a reader would not predict them
+ * - Pipelines (`|`), background (`&`), and `;` inside `( ... )` — so
+ *   `(a && b) || c` parses but `a && (b; c)` does not.
+ * - Reserved words ANYWHERE, not only at command position: `echo if` and
+ *   `echo done` are valid bash and are rejected here.
+ * - `--` as an end-of-flags marker, so `git checkout -- file` is rejected,
+ *   as is a bare `-` for stdin (`cat -`).
+ * - Compound commands: `if`, `for`, `while`, `case`, function definitions.
+ * - Command substitution `$(...)`, backticks, arithmetic `$((...))`,
+ *   parameter expansion beyond `${name}` (`${x:-y}`), and the special
+ *   parameters `$?` / `$@` / `$$`.
+ * - Globs (`*`, `?`, `[...]`), tilde (`~/x`), brace expansion, heredocs
+ *   and here-strings, `2>&1`, comments (`#`), and escapes outside double
+ *   quotes (`echo a\ b`).
+ * - Characters outside the word set above, including `@` and `%`.
  */
 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>;
+export * from "./parsers.js";

package/dist/parsers/bash/index.js

@@ -1,58 +1,54 @@
 /**
- * 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.
+ * A deliberately small bash parser: a narrow subset of bash that is either
+ * parsed correctly or rejected, never silently mis-parsed. Intended for
+ * contexts where acting on a wrong parse is worse than rejecting a command
+ * outright — an unsupported construct costs you a rejection, not a wrong
+ * answer.
  *
- * 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:
+ * `bashParser` is the entry point. It parses a whole script and fails
+ * unless the entire input is consumed.
  *
  * ```ts
- * setInputStr(input);
- * resetRightmostFailure();
- * const result = bashParser(input);
- * if (!result.success) console.log(getErrorMessage());
+ * const result = bashParser("git commit -m 'hi'");
+ * if (result.success) console.log(result.result);
  * ```
+ *
+ * The AST is shaped for consumers asking "what command is this, and what
+ * does it operate on?" — a `SimpleCommand` carries `command`, `args`,
+ * `assignments` and `redirects` as separate fields. There is no
+ * `subcommands` field: no syntactic rule separates `git status` from
+ * `echo status`, so `args` is one ordered list.
+ *
+ * SUPPORTED
+ * - Simple commands: a name, arguments, and `name=value` assignments
+ *   before it. A line that is only an assignment (`FOO=bar`) is a command
+ *   with a null `command`.
+ * - Words: bare words (letters, digits, and `_ - . = : +`), paths
+ *   (any word containing `/`), single and double quotes, `$var` and
+ *   `${var}`, and `-f` / `--flag` / `--flag=value` flags.
+ * - Double quotes interpolate `$var` and handle `\"`, `\\`, `\$`, `` \` ``.
+ * - Words built from adjacent parts: `$HOME/bin`, `"a"b`, `"$HOME"/x`.
+ * - Redirects: `>`, `>>`, `<`, and `&>`, with an optional attached file
+ *   descriptor on the first three (`2> err.txt`).
+ * - `&&` / `||` chains (one precedence level, left-associative, as in
+ *   bash) and `( ... )` grouping.
+ * - Commands separated by `;` or newlines, including CRLF.
+ *
+ * REJECTED, and worth knowing because a reader would not predict them
+ * - Pipelines (`|`), background (`&`), and `;` inside `( ... )` — so
+ *   `(a && b) || c` parses but `a && (b; c)` does not.
+ * - Reserved words ANYWHERE, not only at command position: `echo if` and
+ *   `echo done` are valid bash and are rejected here.
+ * - `--` as an end-of-flags marker, so `git checkout -- file` is rejected,
+ *   as is a bare `-` for stdin (`cat -`).
+ * - Compound commands: `if`, `for`, `while`, `case`, function definitions.
+ * - Command substitution `$(...)`, backticks, arithmetic `$((...))`,
+ *   parameter expansion beyond `${name}` (`${x:-y}`), and the special
+ *   parameters `$?` / `$@` / `$$`.
+ * - Globs (`*`, `?`, `[...]`), tilde (`~/x`), brace expansion, heredocs
+ *   and here-strings, `2>&1`, comments (`#`), and escapes outside double
+ *   quotes (`echo a\ b`).
+ * - Characters outside the word set above, including `@` and `%`.
  */
 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]);
+export * from "./parsers.js";

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

@@ -0,0 +1,95 @@
+import { Parser, ParserResult } from "../../types.js";
+import { Assignment, BashAST, Command, DoubleQuotedWord, FlagWord, InterpolatedVariableWord, LiteralWord, Parens, PathWord, Redirect, ScriptName, SimpleCommand, SingleQuotedWord, VariableWord, Word } from "./types.js";
+export declare const RESERVED_WORDS: string[];
+/** Characters allowed inside a VARIABLE name. Deliberately narrower than
+ * `wordChars`: a dot or hyphen ends the name, so `$HOME.txt` is `$HOME`
+ * followed by the text ".txt", as in bash. */
+export declare const varNameChars: Parser<string>;
+/** Characters allowed in a flag name or a flag value. Wider than
+ * `varNameChars` because filenames routinely contain dots and hyphens
+ * (`my-file.txt`).
+ *
+ * Deliberately excludes `=`, unlike `bareWordChars`: `--format=oneline`
+ * splits into a name and a value on that `=`, so a flag name that could
+ * swallow it would take the whole thing as the name. */
+export declare const wordChars: Parser<string>;
+/** Characters allowed in a bare word — a command name, a filename, an
+ * argument. Includes `=` because an assignment-shaped ARGUMENT is an
+ * ordinary word: `env FOO=bar` passes "FOO=bar" to env in one piece.
+ * (A leading assignment is still an assignment: those are parsed before
+ * the command name.) */
+export declare const bareWordChars: Parser<string>;
+/** A bare word may not START with `-`: that is a flag. Without this rule
+ * `subcommands` (bare literals, parsed before `args`) swallows a leading
+ * flag as a literal and `FlagWord` is unreachable for `ls -la`. A hyphen
+ * inside a word (`my-file`) is still fine. */
+export declare const bareWordStartChars: Parser<string>;
+/** The name in `$name` / `${name}`. A lone digit is a positional
+ * parameter (`$1`); unbraced, `$12` is `$1` followed by "2". */
+export declare const varNameParser: Parser<string>;
+/** The target of an assignment. Unlike `varNameParser` this refuses a
+ * digit: bash runs `1x=1` as a command literally named "1x=1", so
+ * recording it as an assignment would misreport what runs. */
+export declare const assignmentNameParser: Parser<string>;
+export declare const literalWordParser: Parser<LiteralWord>;
+export declare const pathWordParser: Parser<PathWord>;
+export declare const flagNameParser: Parser<string>;
+export declare const flagWordNameOnlyParser: Parser<FlagWord>;
+export declare const flagWordNameAndValueParser: Parser<FlagWord>;
+export declare const flagWordParser: Parser<FlagWord>;
+export declare const singleQuotedWordParser: Parser<SingleQuotedWord>;
+/** Double quotes interpolate: `"$HOME"` expands, so the parts are text runs
+ * interleaved with variables. Recording the whole thing as literal text
+ * would pass a dollar sign through to the command instead of its value.
+ *
+ * A `$` that starts no supported expansion (`"$(date)"`, a bare `"$"`)
+ * fails the parse rather than degrading to text. */
+export declare const doubleQuotedWordParser: Parser<DoubleQuotedWord>;
+export declare const variableWordNoBracesParser: Parser<VariableWord>;
+export declare const variableWordWithBracesParser: Parser<VariableWord>;
+export declare const variableWordParser: Parser<VariableWord>;
+/**
+ * An unquoted word that mixes literal text and variables: `$HOME.txt`,
+ * `$HOME/bin`, `prefix$NAME`, `$A$B`.
+ *
+ * These are ONE word in bash. Parsed as separate words they become
+ * separate arguments, which changes what the command means — and in an
+ * assignment (`PATH=$HOME/bin cmd`) it changes which program runs.
+ *
+ * Only matches when the word genuinely mixes: two or more adjacent
+ * parts, in any combination. A single part keeps its own simpler type, so
+ * a plain `file.txt` stays a `LiteralWord` and a lone `$HOME` stays a
+ * `VariableWord` rather than every word acquiring a `parts` array a
+ * consumer has to walk.
+ */
+export declare const interpolatedVariableWordParser: Parser<InterpolatedVariableWord>;
+export declare const wordParser: Parser<Word>;
+export declare const scriptNameParser: Parser<ScriptName>;
+export declare const emptyAssignmentParser: Parser<Assignment>;
+export declare const assignmentWithValueParser: Parser<Assignment>;
+export declare const assignmentParser: Parser<Assignment>;
+export declare const redirectParser: Parser<Redirect>;
+export declare const argParser: Parser<Word>;
+export declare const simpleCommandParser: Parser<SimpleCommand>;
+/**
+ * `a && b || c`, plus `( ... )` grouping.
+ *
+ * Built with `buildExpressionParser` rather than by hand because the naive
+ * shape is left-recursive: an `and` parser whose first move is to call the
+ * command parser recurses forever on the same input. Here the atom
+ * (`simpleCommandParser`) always consumes before any operator is tried.
+ *
+ * Both operators sit at ONE precedence level, left-associative, because
+ * that is what bash does: `a || b && c` is `((a || b) && c)`, not
+ * `(a || (b && c))`. Splitting them across two levels would silently
+ * change the meaning of every mixed chain.
+ */
+export declare const commandParser: Parser<Command>;
+export declare const parensParser: Parser<Parens>;
+/** What separates two commands: a `;` or a newline.
+ *
+ * The trailing run absorbs blank lines and a `;` followed by a newline,
+ * but NOT a second `;` — `echo a ;; echo b` stays a parse error. */
+export declare const commandSeparator: Parser<string[]>;
+/** Parse a whole script: commands separated by `;` or newlines. */
+export declare function bashParser(input: string): ParserResult<BashAST>;

package/dist/parsers/bash/parsers.js

@@ -0,0 +1,306 @@
+import { failure, success } from "../../types.js";
+import { literalWord } from "./types.js";
+import { buildExpressionParser, capture, char, digit, eof, label, lazy, letter, many, many1, many1WithJoin, manyWithJoin, map, noneOf, num, oneOf, optional, or, peek, sepBy1, seqC, seqR, set, str, trace } from "../../index.js";
+export const RESERVED_WORDS = [
+    "if", "then", "elif", "else", "fi",
+    "do", "done", "while", "until", "for", "in",
+    "case", "esac", "function",
+    "select", "coproc", "time", "[[", "]]",
+];
+function result(parser) {
+    return capture(parser, "result");
+}
+function getResult(parser) {
+    return (input) => {
+        const result = parser(input);
+        if (result.success) {
+            return success(result.result.result, result.rest);
+        }
+        else {
+            return result;
+        }
+    };
+}
+const LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+/** Characters allowed inside a VARIABLE name. Deliberately narrower than
+ * `wordChars`: a dot or hyphen ends the name, so `$HOME.txt` is `$HOME`
+ * followed by the text ".txt", as in bash. */
+export const varNameChars = label("a variable name character", oneOf(LETTERS + DIGITS + "_"));
+/** Characters allowed in a flag name or a flag value. Wider than
+ * `varNameChars` because filenames routinely contain dots and hyphens
+ * (`my-file.txt`).
+ *
+ * Deliberately excludes `=`, unlike `bareWordChars`: `--format=oneline`
+ * splits into a name and a value on that `=`, so a flag name that could
+ * swallow it would take the whole thing as the name. */
+export const wordChars = label("a word character", oneOf(LETTERS + DIGITS + "_-./"));
+/** Characters allowed in a bare word — a command name, a filename, an
+ * argument. Includes `=` because an assignment-shaped ARGUMENT is an
+ * ordinary word: `env FOO=bar` passes "FOO=bar" to env in one piece.
+ * (A leading assignment is still an assignment: those are parsed before
+ * the command name.) */
+export const bareWordChars = label("a word character", oneOf(LETTERS + DIGITS + "_-.=:+"));
+/** A bare word may not START with `-`: that is a flag. Without this rule
+ * `subcommands` (bare literals, parsed before `args`) swallows a leading
+ * flag as a literal and `FlagWord` is unreachable for `ls -la`. A hyphen
+ * inside a word (`my-file`) is still fine. */
+export const bareWordStartChars = label("a word character", oneOf(LETTERS + DIGITS + "_.=:+"));
+/** Characters that end a bare word: whitespace and the operators that
+ * separate commands. */
+const WORD_END_CHARS = " \t\n\r&|;()<>";
+/**
+ * Whitespace WITHIN a command: spaces and tabs only.
+ *
+ * Deliberately not tarsec's `spaces`, which includes `\n`. A newline is a
+ * command SEPARATOR, and eating it as whitespace merges commands —
+ * `ls\nrm -rf /tmp/x` becomes a single `ls` with arguments, so anything
+ * that inspects the command name sees `ls` while bash runs the `rm`.
+ */
+const blanks = manyWithJoin(oneOf(" \t"));
+/**
+ * Require that a word ran all the way to a boundary.
+ *
+ * Without this a word parser happily matches the FRONT of a longer token
+ * — `src` out of `src/main.ts`, `FOO` out of `FOO=bar` — and the leftover
+ * (`/main.ts`) matches nothing, so the whole command fails to parse with
+ * no indication of why. Stopping mid-token is never right: whatever
+ * follows is part of the same word.
+ */
+function wholeWord(parser) {
+    // The boundary is REQUIRED, not optional: `optional(peek(...))` succeeds
+    // whether or not a boundary follows, which makes the whole check a no-op
+    // and lets `src` match out of `src/main.ts` again. `eof` covers the word
+    // that ends the input, which is the only reason it looked optional.
+    return getResult(seqC(result(parser), or(peek(oneOf(WORD_END_CHARS)), eof)));
+}
+/** An identifier: `[A-Za-z_][A-Za-z0-9_]*`. `manyWithJoin`, not `many1`,
+ * so a one-character name (`x=1`, `$A`) is valid. */
+const identifierParser = map(seqR(or(letter, char("_")), manyWithJoin(varNameChars)), (result) => result.join(""));
+/** The name in `$name` / `${name}`. A lone digit is a positional
+ * parameter (`$1`); unbraced, `$12` is `$1` followed by "2". */
+export const varNameParser = trace("varNameParser", or(identifierParser, digit));
+/** The target of an assignment. Unlike `varNameParser` this refuses a
+ * digit: bash runs `1x=1` as a command literally named "1x=1", so
+ * recording it as an assignment would misreport what runs. */
+export const assignmentNameParser = trace("assignmentNameParser", identifierParser);
+/** Reserved words are refused everywhere, not only at command position:
+ * this is a small subset of bash, and refusing to parse something valid is
+ * cheaper than mis-parsing it. */
+function rejectReservedWord(result, input) {
+    if (result.success && RESERVED_WORDS.includes(result.result.text)) {
+        return failure(`Reserved word "${result.result.text}" cannot be used.`, input);
+    }
+    return result;
+}
+export const literalWordParser = wholeWord((input) => {
+    const result = trace("literalWordParser", seqC(set("tag", "literal"), capture(map(seqR(bareWordStartChars, manyWithJoin(bareWordChars)), (r) => r.join("")), "text")))(input);
+    return rejectReservedWord(result, input);
+});
+// Slashes are scanned as part of the run rather than used as separators,
+// so a LEADING slash is just another character: `sepBy1` needed a segment
+// before the first separator, which made every absolute path unparseable.
+// A bare "/" and a trailing "/" are both real paths (`ls /`, `ls src/`).
+export const pathWordParser = wholeWord((input) => {
+    const result = trace("pathWordParser", seqC(set("tag", "path"), capture(many1WithJoin(or(bareWordChars, char("/"))), "text")))(input);
+    if (result.success) {
+        const text = result.result.text;
+        if (!text.includes("/")) {
+            return failure(`Path must contain at least one "/".`, input);
+        }
+    }
+    return result;
+});
+export const flagNameParser = trace("flagNameParser", map(seqR(char("-"), optional(char("-")), many1WithJoin(wordChars)), (result) => result.join("")));
+export const flagWordNameOnlyParser = trace("flagWordNameOnlyParser", seqC(set("tag", "flag"), capture(flagNameParser, "flagName")));
+export const flagWordNameAndValueParser = trace("flagWordNameAndValueParser", seqC(set("tag", "flag"), capture(flagNameParser, "flagName"), char("="), capture(many1WithJoin(wordChars), "flagValue")));
+export const flagWordParser = trace("flagWordParser", wholeWord(or(flagWordNameAndValueParser, flagWordNameOnlyParser)));
+export const singleQuotedWordParser = trace("singleQuotedWordParser", seqC(set("tag", "singleQuoted"), char("'"), capture(manyWithJoin(noneOf("'")), "text"), char("'")));
+// A run of ordinary text inside double quotes. Stops at `$` so an
+// expansion is not swallowed as text, and at `\` so an escape is not.
+const doubleQuotedLiteralParser = trace("doubleQuotedLiteralParser", map(many1WithJoin(noneOf('"$\\')), literalWord));
+/** The characters a backslash escapes inside double quotes. Before
+ * anything else the backslash is ordinary text: bash prints `"a\zb"` as
+ * `a\zb`, but `"a\"b"` as `a"b`. */
+const DOUBLE_QUOTE_ESCAPABLE = '"$`\\';
+const doubleQuotedEscapeParser = trace("doubleQuotedEscapeParser", or(map(seqR(char("\\"), oneOf(DOUBLE_QUOTE_ESCAPABLE)), (results) => literalWord(results[1])), map(char("\\"), () => literalWord("\\"))));
+// No alternative can match empty, so `many` below always terminates.
+const doubleQuotedPartParser = trace("doubleQuotedPartParser", or(lazy(() => variableWordParser), doubleQuotedEscapeParser, doubleQuotedLiteralParser));
+/** Merge adjacent literal parts. An escape splits the text run in three
+ * (`a`, `"`, `b`), which is an artifact of how it was parsed rather than
+ * anything a consumer should have to reassemble. */
+function mergeLiterals(parts) {
+    return parts.reduce((merged, part) => {
+        const previous = merged[merged.length - 1];
+        if (part.tag === "literal" && (previous === null || previous === void 0 ? void 0 : previous.tag) === "literal") {
+            merged[merged.length - 1] = literalWord(previous.text + part.text);
+            return merged;
+        }
+        merged.push(part);
+        return merged;
+    }, []);
+}
+/** Double quotes interpolate: `"$HOME"` expands, so the parts are text runs
+ * interleaved with variables. Recording the whole thing as literal text
+ * would pass a dollar sign through to the command instead of its value.
+ *
+ * A `$` that starts no supported expansion (`"$(date)"`, a bare `"$"`)
+ * fails the parse rather than degrading to text. */
+export const doubleQuotedWordParser = trace("doubleQuotedWordParser", seqC(set("tag", "doubleQuoted"), char('"'), capture(map(many(doubleQuotedPartParser), mergeLiterals), "parts"), char('"')));
+export const variableWordNoBracesParser = trace("variableWordNoBracesParser", seqC(set("tag", "variable"), char("$"), capture(varNameParser, "name")));
+export const variableWordWithBracesParser = trace("variableWordWithBracesParser", seqC(set("tag", "variable"), char("$"), char("{"), capture(varNameParser, "name"), char("}")));
+export const variableWordParser = trace("variableWordParser", or(variableWordWithBracesParser, variableWordNoBracesParser));
+// A run of ordinary text inside an unquoted word. Slashes are included so
+// `$HOME/bin` keeps its suffix; `$` is excluded so a variable is not eaten
+// as text.
+const interpolatedLiteralParser = trace("interpolatedLiteralParser", map(many1WithJoin(or(bareWordChars, char("/"))), literalWord));
+// Quoted words are parts too: `"$HOME"/x` and `"a"b` are single words.
+// The literal run cannot contain a quote, so these never overlap.
+const interpolatedPartParser = trace("interpolatedPartParser", or(variableWordParser, singleQuotedWordParser, doubleQuotedWordParser, interpolatedLiteralParser));
+/**
+ * An unquoted word that mixes literal text and variables: `$HOME.txt`,
+ * `$HOME/bin`, `prefix$NAME`, `$A$B`.
+ *
+ * These are ONE word in bash. Parsed as separate words they become
+ * separate arguments, which changes what the command means — and in an
+ * assignment (`PATH=$HOME/bin cmd`) it changes which program runs.
+ *
+ * Only matches when the word genuinely mixes: two or more adjacent
+ * parts, in any combination. A single part keeps its own simpler type, so
+ * a plain `file.txt` stays a `LiteralWord` and a lone `$HOME` stays a
+ * `VariableWord` rather than every word acquiring a `parts` array a
+ * consumer has to walk.
+ */
+export const interpolatedVariableWordParser = wholeWord((input) => {
+    const result = trace("interpolatedVariableWordParser", many1(interpolatedPartParser))(input);
+    if (!result.success)
+        return result;
+    const parts = result.result;
+    // Two or more parts is what makes a word interpolated. A single part
+    // keeps its own simpler type: `file.txt` stays a LiteralWord, `$HOME`
+    // a VariableWord, `"a b"` a DoubleQuotedWord.
+    if (parts.length < 2) {
+        return failure("Not an interpolated word: nothing to interpolate.", input);
+    }
+    return success({ tag: "interpolatedVariable", parts }, result.rest);
+});
+export const wordParser = trace("wordParser", or(flagWordParser, 
+// Before every single-part parser: each of those would match only the
+// FIRST part of an interpolated word and leave the rest to become a
+// separate argument.
+interpolatedVariableWordParser, singleQuotedWordParser, doubleQuotedWordParser, variableWordParser, pathWordParser, literalWordParser));
+export const scriptNameParser = trace("scriptNameParser", or(pathWordParser, literalWordParser));
+export const emptyAssignmentParser = trace("emptyAssignmentParser", seqC(set("tag", "assignment"), capture(assignmentNameParser, "name"), char("="), set("value", null)));
+export const assignmentWithValueParser = trace("assignmentWithValueParser", seqC(set("tag", "assignment"), capture(assignmentNameParser, "name"), char("="), capture(wordParser, "value")));
+export const assignmentParser = trace("assignmentParser", or(assignmentWithValueParser, emptyAssignmentParser));
+// No `<<` or `<<<`: a heredoc's body lives on the lines AFTER the
+// command, so `cat <<EOF` is not a redirect to a file named "EOF".
+// Parsing it as one is a silent mis-parse; leaving the operator out means
+// the `<` alternative fails on the second `<` and the command is rejected
+// instead. Longest alternative first, so `>>` beats `>`.
+const fdRedirectOp = or(str(">>"), str(">"), str("<"));
+// `&>` takes NO file descriptor. Bash reads the `2` in `cmd 2&> f` as an
+// ordinary argument, so accepting `2&>` as "fd 2" makes that argument
+// vanish from the AST — a silent mis-parse, not a rejection.
+const bareRedirectOp = str("&>");
+export const redirectParser = trace("redirectParser", or(seqC(set("tag", "redirect"), optional(capture(map(num, parseInt), "fd")), capture(fdRedirectOp, "op"), blanks, capture(wordParser, "target")), seqC(set("tag", "redirect"), capture(bareRedirectOp, "op"), blanks, capture(wordParser, "target"))));
+export const argParser = trace("argParser", or(flagWordParser, wordParser));
+/** Run a parser, then eat any trailing whitespace.
+ *
+ * The discipline: every token-shaped parser consumes its own TRAILING
+ * space, and leading space is eaten once at the start of the command.
+ * `sepBy(spaces, ...)` cannot express this — it only puts a separator
+ * BETWEEN elements of one group, so the space between the command name
+ * and its first argument, or between the last argument and a redirect,
+ * had nothing to consume it and the rest of the command was left
+ * unparsed. */
+function token(parser) {
+    return map(seqR(parser, blanks), (results) => results[0]);
+}
+/** A redirect or an argument, tried in that order.
+ *
+ * Interleaved rather than parsed as two separate groups, for two reasons.
+ * A digit attached to an operator is a FILE DESCRIPTOR, not an argument —
+ * bash reads `cmd 3> x` as "redirect fd 3, no arguments" — and args-first
+ * would always claim the `3`. And bash allows a redirect anywhere among
+ * the arguments (`cmd > out.txt arg`), which two fixed groups reject. */
+const argOrRedirectParser = trace("argOrRedirectParser", or(redirectParser, argParser));
+const isRedirect = (item) => item.tag === "redirect";
+const simpleCommandShape = seqC(set("tag", "simpleCommand"), blanks, capture(many(token(assignmentParser)), "assignments"), 
+// Optional so a bare `FOO=bar` line parses. Bash requires at least one
+// of a command name or an assignment; that check is below.
+capture(optional(token(scriptNameParser)), "command"), capture(many(token(argOrRedirectParser)), "items"));
+export const simpleCommandParser = trace("simpleCommandParser", (input) => {
+    const parsed = simpleCommandShape(input);
+    if (!parsed.success)
+        return parsed;
+    const { assignments, command, items } = parsed.result;
+    // Neither a command nor an assignment means nothing was parsed at all;
+    // without this every input "succeeds" as an empty command.
+    if (command === null && assignments.length === 0) {
+        return failure("Expected a command or an assignment.", input);
+    }
+    return success({
+        tag: "simpleCommand",
+        assignments,
+        command,
+        args: items.filter((item) => !isRedirect(item)),
+        redirects: items.filter(isRedirect),
+    }, parsed.rest);
+});
+/** An operator in a `&&` / `||` chain, absorbing the whitespace around it.
+ * `buildExpressionParser` applies this directly to the remaining input, so
+ * it has to eat its own surrounding space; optional, so `a&&b` works too. */
+const chainOperator = (symbol) => map(seqR(blanks, str(symbol), blanks), () => symbol);
+/**
+ * `a && b || c`, plus `( ... )` grouping.
+ *
+ * Built with `buildExpressionParser` rather than by hand because the naive
+ * shape is left-recursive: an `and` parser whose first move is to call the
+ * command parser recurses forever on the same input. Here the atom
+ * (`simpleCommandParser`) always consumes before any operator is tried.
+ *
+ * Both operators sit at ONE precedence level, left-associative, because
+ * that is what bash does: `a || b && c` is `((a || b) && c)`, not
+ * `(a || (b && c))`. Splitting them across two levels would silently
+ * change the meaning of every mixed chain.
+ */
+export const commandParser = trace("commandParser", buildExpressionParser(simpleCommandParser, [[
+        {
+            op: chainOperator("&&"),
+            assoc: "left",
+            apply: (left, right) => ({ tag: "and", left, right }),
+        },
+        {
+            op: chainOperator("||"),
+            assoc: "left",
+            apply: (left, right) => ({ tag: "or", left, right }),
+        },
+    ]], 
+// Passed explicitly: the default paren parser returns the inner
+// expression unwrapped, which would drop the `Parens` node.
+lazy(() => parensParser)));
+export const parensParser = trace("parensParser", seqC(set("tag", "parens"), char("("), capture(lazy(() => commandParser), "command"), char(")")));
+/** What separates two commands: a `;` or a newline.
+ *
+ * The trailing run absorbs blank lines and a `;` followed by a newline,
+ * but NOT a second `;` — `echo a ;; echo b` stays a parse error. */
+export const commandSeparator = seqR(blanks, or(char(";"), char("\n"), char("\r")), manyWithJoin(oneOf(" \t\n\r")));
+/** Blank lines before the first command. `simpleCommandParser` only eats
+ *  blanks (spaces and tabs), so without this a script starting with a
+ *  newline — or any CRLF file — is rejected outright. */
+const leadingSeparators = manyWithJoin(oneOf(" \t\n\r"));
+/** Parse a whole script: commands separated by `;` or newlines. */
+export function bashParser(input) {
+    const result = trace("bashParser", seqR(leadingSeparators, sepBy1(commandSeparator, commandParser)))(input);
+    if (!result.success)
+        return result;
+    const commands = result.result[1];
+    if (result.rest.trim() !== "") {
+        // `result.rest`, not `input`: tarsec derives position from
+        // originalInput.length - rest.length, so returning the whole input
+        // would report every error at column 1.
+        return failure(`Unexpected input after commands: "${result.rest}"`, result.rest);
+    }
+    return success(commands, result.rest);
+}