tarsec 0.5.1 → 0.5.3

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

@@ -0,0 +1,50 @@
+/**
+ * Turn a parsed AST back into a bash command.
+ *
+ * The inverse of `bashParser`, with one guarantee that matters more than
+ * exact reproduction: **the output is always safe to hand to bash**. Text
+ * that needs quoting gets quoted, whatever the node's tag claims. The
+ * parser cannot produce a `LiteralWord` holding `; rm -rf /` — its word
+ * charset forbids `;` — but a consumer can construct or mutate one, and a
+ * naive emitter would hand that straight to a shell.
+ *
+ * Where quoting cannot rescue a field — a variable name, an assignment
+ * target, a redirect operator — an `AstToBashError` is thrown instead.
+ * Quoting those would stop them being a variable, a target or an operator
+ * at all, so refusing is the only way to keep the guarantee.
+ *
+ * ```ts
+ * const ast = bashParser("git commit -m 'hi'").result;
+ * astToBash(ast); // "git commit -m 'hi'"
+ * ```
+ */
+import { BashAST, BashNode } from "./types.js";
+/**
+ * Thrown for an AST that cannot be written as bash at all.
+ *
+ * Quoting rescues word TEXT — `'; rm -rf /'` is one harmless argument.
+ * It cannot rescue a variable name, an assignment target or a redirect
+ * operator: quoting those stops them being a variable, a target or an
+ * operator. Emitting them raw would let a hand-built AST inject a second
+ * command, so the only way to keep the safety guarantee is to refuse.
+ */
+export declare class AstToBashError extends Error {
+    constructor(message: string);
+}
+/**
+ * Turn an AST back into bash source.
+ *
+ * Accepts a whole script (commands joined with `; `) or any single node,
+ * down to a lone word — handy in tests and while debugging.
+ *
+ * For anything the parser produced, `bashParser(astToBash(ast))` gives an
+ * equal AST. That is equality of ASTs, not of strings: whitespace
+ * normalizes, and redirects move to the end of their command.
+ *
+ * For a hand-built AST the guarantee is deliberately weaker. The output is
+ * always safe and always produces the words asked for, but a tag can
+ * change on the way back: `literal "a b"` emits `'a b'` and returns as a
+ * `singleQuoted`. No emission preserves both the tag and the meaning, and
+ * meaning is the one worth keeping.
+ */
+export declare function astToBash(node: BashNode | BashAST): string;

package/dist/parsers/bash/astToBash.js

@@ -0,0 +1,259 @@
+const LETTERS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+const DIGITS = "0123456789";
+/** The characters the parser reads as a bare word or a path. Text made
+ *  only of these can be emitted unquoted and read back as the same word.
+ *  This is `bareWordChars` / `bareWordStartChars` from parsers.ts plus
+ *  `/`, since `literalWordParser` and `pathWordParser` between them cover
+ *  both. */
+const BARE_WORD_CHARS = new Set(LETTERS + DIGITS + "_-.=:+/");
+const BARE_WORD_START_CHARS = new Set(LETTERS + DIGITS + "_.=:+/");
+/** Characters that can continue a variable name. A variable part followed
+ *  by one of these has to be braced. */
+const VAR_NAME_CHARS = new Set(LETTERS + DIGITS + "_");
+/** Characters the parser allows in a flag name or value. */
+const FLAG_CHARS = new Set(LETTERS + DIGITS + "_-./");
+/** The redirect operators the parser recognizes. `&>` is separate: bash
+ *  has no fd-prefixed form of it, and the parser rejects `2&> f`. */
+const FD_REDIRECT_OPS = new Set([">", ">>", "<"]);
+const BARE_REDIRECT_OPS = new Set(["&>"]);
+/**
+ * Thrown for an AST that cannot be written as bash at all.
+ *
+ * Quoting rescues word TEXT — `'; rm -rf /'` is one harmless argument.
+ * It cannot rescue a variable name, an assignment target or a redirect
+ * operator: quoting those stops them being a variable, a target or an
+ * operator. Emitting them raw would let a hand-built AST inject a second
+ * command, so the only way to keep the safety guarantee is to refuse.
+ */
+export class AstToBashError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "AstToBashError";
+    }
+}
+/** `[A-Za-z_][A-Za-z0-9_]*`, matching the parser's identifier rule. */
+function isIdentifier(text) {
+    if (text.length === 0)
+        return false;
+    if (!(LETTERS + "_").includes(text[0]))
+        return false;
+    for (const character of text) {
+        if (!VAR_NAME_CHARS.has(character))
+            return false;
+    }
+    return true;
+}
+/** A variable name: an identifier, or a single digit for a positional
+ *  parameter (`$1`), matching `varNameParser`. */
+function isVariableName(text) {
+    return isIdentifier(text) || (text.length === 1 && DIGITS.includes(text));
+}
+function isFlagText(text) {
+    for (const character of text) {
+        if (!FLAG_CHARS.has(character))
+            return false;
+    }
+    return text.length > 0;
+}
+/** Can this text be written without quotes and read back unchanged?
+ *
+ *  A leading `-` disqualifies it: bare `-la` reads back as a flag, not a
+ *  literal. Quoting is the safe answer in that case. */
+function isBareWord(text) {
+    if (text.length === 0)
+        return false;
+    if (!BARE_WORD_START_CHARS.has(text[0]))
+        return false;
+    for (const character of text) {
+        if (!BARE_WORD_CHARS.has(character))
+            return false;
+    }
+    return true;
+}
+/** Wrap text in single quotes. Bash has no escape inside single quotes,
+ *  so an embedded `'` closes the string, emits an escaped quote, and
+ *  reopens: `it's` becomes `'it'\''s'`. */
+function singleQuote(text) {
+    return `'${text.split("'").join("'\\''")}'`;
+}
+/** Emit bare where that reads back unchanged, quoted otherwise. */
+function quoteIfNeeded(text) {
+    return isBareWord(text) ? text : singleQuote(text);
+}
+/** Escape the characters that stay special inside double quotes. */
+function escapeForDoubleQuotes(text) {
+    let out = "";
+    for (const character of text) {
+        if (character === '"' || character === "\\" || character === "$" || character === "`") {
+            out += "\\";
+        }
+        out += character;
+    }
+    return out;
+}
+function doubleQuotedToBash(word) {
+    const inner = word.parts
+        .map((part) => part.tag === "literal" ? escapeForDoubleQuotes(part.text) : wordToBash(part))
+        .join("");
+    return `"${inner}"`;
+}
+/** Would `next` be read as a continuation of the variable name before it? */
+function continuesVariableName(next) {
+    if (next === undefined)
+        return false;
+    const text = next.tag === "literal" ? next.text : "";
+    return text.length > 0 && VAR_NAME_CHARS.has(text[0]);
+}
+/**
+ * Adjacent parts, concatenated with no separator.
+ *
+ * The one subtlety: `[variable "A", literal "bc"]` written plainly gives
+ * `$Abc`, which reads back as a variable named `Abc` — a different
+ * command. A variable is braced whenever the next part could continue its
+ * name.
+ */
+function interpolatedToBash(word) {
+    return word.parts
+        .map((part, index) => {
+        if (part.tag === "variable" && continuesVariableName(word.parts[index + 1])) {
+            return `\${${part.name}}`;
+        }
+        return wordToBash(part);
+    })
+        .join("");
+}
+function wordToBash(word) {
+    switch (word.tag) {
+        case "literal":
+        case "path":
+            return quoteIfNeeded(word.text);
+        case "singleQuoted":
+            return singleQuote(word.text);
+        case "doubleQuoted":
+            return doubleQuotedToBash(word);
+        case "variable":
+            if (!isVariableName(word.name)) {
+                throw new AstToBashError(`Not a valid variable name: ${JSON.stringify(word.name)}`);
+            }
+            return `$${word.name}`;
+        case "flag":
+            return flagToBash(word);
+        case "interpolatedVariable":
+            return interpolatedToBash(word);
+    }
+}
+/** A flag CAN be rescued by quoting: the whole token becomes a single
+ *  argument. It reads back as a quoted word rather than a flag, which is
+ *  the documented trade for hand-built nodes — one argument that means
+ *  what it says beats a flag that starts a second command. */
+function flagToBash(word) {
+    const rendered = word.flagValue === undefined
+        ? word.flagName
+        : `${word.flagName}=${word.flagValue}`;
+    const isSafe = word.flagName.startsWith("-") &&
+        isFlagText(word.flagName.replace(/^--?/, "")) &&
+        (word.flagValue === undefined || isFlagText(word.flagValue));
+    return isSafe ? rendered : singleQuote(rendered);
+}
+function assignmentToBash(assignment) {
+    if (!isIdentifier(assignment.name)) {
+        throw new AstToBashError(`Not a valid assignment name: ${JSON.stringify(assignment.name)}`);
+    }
+    const value = assignment.value === null ? "" : wordToBash(assignment.value);
+    return `${assignment.name}=${value}`;
+}
+function redirectToBash(redirect) {
+    const takesFd = FD_REDIRECT_OPS.has(redirect.op);
+    if (!takesFd && !BARE_REDIRECT_OPS.has(redirect.op)) {
+        throw new AstToBashError(`Not a supported redirect operator: ${JSON.stringify(redirect.op)}`);
+    }
+    if (redirect.fd !== undefined && !takesFd) {
+        throw new AstToBashError(`\`${redirect.op}\` takes no file descriptor.`);
+    }
+    const fd = redirect.fd === undefined ? "" : String(redirect.fd);
+    return `${fd}${redirect.op} ${wordToBash(redirect.target)}`;
+}
+/** Assignments, command, arguments, redirects.
+ *
+ *  Redirects go last because the AST does not record where they sat among
+ *  the arguments — `cmd > out.txt arg` comes back as `cmd arg > out.txt`,
+ *  which is the same command. */
+function simpleCommandToBash(command) {
+    const pieces = [
+        ...command.assignments.map(assignmentToBash),
+        ...(command.command === null ? [] : [wordToBash(command.command)]),
+        ...command.args.map(wordToBash),
+        ...command.redirects.map(redirectToBash),
+    ];
+    return pieces.join(" ");
+}
+/**
+ * A chain operand, parenthesized when it needs to be.
+ *
+ * `&&` and `||` are one precedence level and associate left, so an
+ * `and`/`or` nested on the RIGHT cannot be written flat: `And(a, Or(b, c))`
+ * as `a && b || c` reads back as `Or(And(a, b), c)`, a different tree.
+ *
+ * Bash parens are a subshell, so this is not a pure grouping — but the
+ * parser never builds this shape (chains are left-associative, so right
+ * children are always primaries), and it is the only way to preserve a
+ * hand-built one.
+ */
+function chainOperandToBash(command, isRightOperand) {
+    const needsParens = isRightOperand && (command.tag === "and" || command.tag === "or");
+    const emitted = commandToBash(command);
+    return needsParens ? `(${emitted})` : emitted;
+}
+function commandToBash(command) {
+    switch (command.tag) {
+        case "simpleCommand":
+            return simpleCommandToBash(command);
+        case "and":
+        case "or": {
+            const operator = command.tag === "and" ? "&&" : "||";
+            const left = chainOperandToBash(command.left, false);
+            const right = chainOperandToBash(command.right, true);
+            return `${left} ${operator} ${right}`;
+        }
+        case "parens":
+            return `(${commandToBash(command.command)})`;
+    }
+}
+function isCommand(node) {
+    return (node.tag === "simpleCommand" ||
+        node.tag === "and" ||
+        node.tag === "or" ||
+        node.tag === "parens");
+}
+/**
+ * Turn an AST back into bash source.
+ *
+ * Accepts a whole script (commands joined with `; `) or any single node,
+ * down to a lone word — handy in tests and while debugging.
+ *
+ * For anything the parser produced, `bashParser(astToBash(ast))` gives an
+ * equal AST. That is equality of ASTs, not of strings: whitespace
+ * normalizes, and redirects move to the end of their command.
+ *
+ * For a hand-built AST the guarantee is deliberately weaker. The output is
+ * always safe and always produces the words asked for, but a tag can
+ * change on the way back: `literal "a b"` emits `'a b'` and returns as a
+ * `singleQuoted`. No emission preserves both the tag and the meaning, and
+ * meaning is the one worth keeping.
+ */
+export function astToBash(node) {
+    if (Array.isArray(node)) {
+        return node.map(commandToBash).join("; ");
+    }
+    if (isCommand(node)) {
+        return commandToBash(node);
+    }
+    switch (node.tag) {
+        case "assignment":
+            return assignmentToBash(node);
+        case "redirect":
+            return redirectToBash(node);
+        default:
+            return wordToBash(node);
+    }
+}

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

@@ -1,57 +1,55 @@
 /**
- * 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 "./astToBash.js";
+export * from "./parsers.js";

package/dist/parsers/bash/index.js

@@ -1,58 +1,55 @@
 /**
- * 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 "./astToBash.js";
+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>;