tarsec 0.5.0 → 0.5.2

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

@@ -1,136 +1,85 @@
 /** 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 = {
+export type Word = LiteralWord | PathWord | FlagWord | SingleQuotedWord | DoubleQuotedWord | VariableWord | InterpolatedVariableWord;
+export type ScriptName = LiteralWord | PathWord;
+export type LiteralWord = {
     tag: "literal";
     text: string;
-} | {
+};
+export type PathWord = {
+    tag: "path";
+    text: string;
+};
+export type FlagWord = {
+    tag: "flag";
+    flagName: string;
+    flagValue?: string;
+};
+export type SingleQuotedWord = {
     tag: "singleQuoted";
     text: string;
-} | {
+};
+export type DoubleQuotedWord = {
     tag: "doubleQuoted";
-    parts: WordPart[];
-} | {
+    parts: Word[];
+};
+export type VariableWord = {
     tag: "variable";
     name: string;
-} | {
-    tag: "paramExpansion";
-    expression: string;
-} | {
-    tag: "commandSubstitution";
-    command: List;
-} | {
-    tag: "arithmeticExpansion";
-    expression: string;
-};
-export type BashWord = {
-    tag: "word";
-    parts: WordPart[];
 };
+/** A word built from two or more adjacent parts: `$HOME.txt`, `"a"b`,
+ * `"$HOME"/x`. These are ONE word in bash; split into separate words they
+ * become separate arguments and the command means something else.
+ *
+ * Quoted parts belong here as much as variables do — quoting a variable
+ * and appending to it (`"$HOME"/bin`) is idiomatic shell. */
+export type InterpolatedVariableWord = {
+    tag: "interpolatedVariable";
+    parts: (LiteralWord | VariableWord | SingleQuotedWord | DoubleQuotedWord)[];
+};
+export declare function literalWord(text: string): LiteralWord;
 /** `name=value` (or `name=` with a null value) before a command. */
 export type Assignment = {
     tag: "assignment";
     name: string;
-    value: BashWord | null;
+    value: Word | null;
 };
-/** A redirect like `> out.txt`, `2>&1`, or `<<< "$str"`. `fd` is the
- * explicit file descriptor (`2` in `2>`), or null for the default. */
+/** A redirect like `> out.txt`, `>> log`, `2> err.txt` or `< in.txt`.
+ * `fd` is the explicit file descriptor (`2` in `2>`), or undefined for the
+ * default. Only `>`, `>>`, `<` and `&>` are recognized; `2>&1`, heredocs
+ * and here-strings are rejected rather than parsed. */
 export type Redirect = {
     tag: "redirect";
-    fd: number | null;
+    fd?: number;
     op: string;
-    target: BashWord;
+    target: Word;
 };
 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;
+    /** The command name, or null for an assignment-only line (`FOO=bar`).
+     *  Bash requires at least one of a command name or an assignment. */
+    command: ScriptName | null;
+    /** Every word after the command name, in source order. There is no
+     *  `subcommands` field: no syntactic rule separates `git status` from
+     *  `echo status`, so splitting them would put a command's real
+     *  arguments in whichever bucket the preceding word happened to pick. */
+    args: Word[];
     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 Command = SimpleCommand | And | Or | Parens;
+export type And = {
+    tag: "and";
+    left: Command;
+    right: Command;
 };
-export type ListItem = {
-    tag: "listItem";
-    command: AndOr;
-    /** True when the command was followed by `&`. */
-    background: boolean;
+export type Or = {
+    tag: "or";
+    left: Command;
+    right: Command;
 };
-/** 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[];
+export type Parens = {
+    tag: "parens";
+    command: Command;
 };
+export type BashNode = Command | SimpleCommand | Assignment | Redirect | Word | ScriptName;
+export type BashAST = Command[];

package/dist/parsers/bash/types.js

@@ -1,2 +1,4 @@
 /** AST types for the bash parser. See `index.ts` for the supported subset. */
-export {};
+export function literalWord(text) {
+    return { tag: "literal", text };
+}

package/dist/parsers/within.js

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

package/dist/parsers.d.ts

@@ -138,8 +138,19 @@ export declare function takeWhile1(charsOrPred: string | CharPredicate, expected
 export declare const anyChar: Parser<string>;
 /**
  * Wraps a parser with a human-readable label for error reporting.
- * On failure, suppresses any inner failure recordings and records only the label.
- * This produces clean error messages like `expected a digit` instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails at the label's own position (it never got
+ * anywhere), its internal failure records are suppressed and only the
+ * label is recorded — producing clean messages like `expected a digit`
+ * instead of `expected one of "0123456789"`.
+ *
+ * If the wrapped parser fails STRICTLY INSIDE the labeled region (it
+ * consumed input first), its deeper, more specific record is kept and
+ * the label stays out of the way — so a grammar labeled at every level
+ * still surfaces the deepest thing the parser actually knew.
+ * (Comparing against the label's own position, rather than the previous
+ * record, is what keeps shallow labels clean while deep knowledge
+ * survives.)
  *
  * @param name - human-readable description of what the parser expects
  * @param parser - the parser to wrap

package/dist/parsers.js

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

package/dist/position.d.ts

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

package/dist/position.js

@@ -1,5 +1,9 @@
-import { getInputStr } from "./trace.js";
+// NOTE: this module deliberately imports nothing from trace.ts — it reads
+// the input via getParseState().inputStr. trace.ts imports composePosition
+// from here, so an import in the other direction would create a runtime
+// module cycle (fragile TDZ hazard under refactoring/bundlers).
 import { success } from "./types.js";
+import { getParseState } from "./parseState.js";
 /**
  * Build a lookup table of line-start offsets for a given source string.
  * This allows O(log n) offset-to-position conversion via binary search.
@@ -17,6 +21,9 @@ export function buildLineTable(source) {
 // table on every invocation. Parses run sequentially with a single
 // `setInputStr` source, so a most-recently-seen cache is sufficient and
 // avoids O(num_calls * source.length) work during a parse.
+// Deliberately NOT part of ParseState: keyed by source-string identity,
+// so a nested parse's source misses and rebuilds — it can never serve a
+// stale table across parse states.
 let cachedSource = null;
 let cachedLineTable = [0];
 function getLineTable(source) {
@@ -49,23 +56,45 @@ export function offsetToPosition(lineTable, offset) {
         column: offset - lineTable[lo],
     };
 }
+/**
+ * Compose an inner-parse position with a base position (the point in the
+ * enclosing input where the inner input begins). Offsets and lines add;
+ * the base column applies only while still on the base line (inner line 0).
+ */
+export function composePosition(base, pos) {
+    if (base.offset === 0 && base.line === 0 && base.column === 0) {
+        return pos;
+    }
+    const column = pos.line === 0 ? base.column + pos.column : pos.column;
+    return {
+        offset: base.offset + pos.offset,
+        line: base.line + pos.line,
+        column,
+    };
+}
 /**
  * A zero-width parser that returns the current offset into the input string.
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the offset is reported in the enclosing parse's
+ * coordinates (the state's `basePosition` is added).
  */
 export const getOffset = (input) => {
-    const source = getInputStr();
-    return success(source.length - input.length, input);
+    const source = getParseState().inputStr;
+    const base = getParseState().basePosition;
+    return success(base.offset + (source.length - input.length), input);
 };
 /**
  * A zero-width parser that returns the current position (offset, line, column).
  * Requires `setInputStr` to have been called with the full input.
+ * Inside `runNested`, the position is reported in the enclosing parse's
+ * coordinates (composed with the state's `basePosition`).
  */
 export const getPosition = (input) => {
-    const source = getInputStr();
+    const source = getParseState().inputStr;
     const offset = source.length - input.length;
     const lineTable = getLineTable(source);
-    return success(offsetToPosition(lineTable, offset), input);
+    const base = getParseState().basePosition;
+    return success(composePosition(base, offsetToPosition(lineTable, offset)), input);
 };
 /**
  * Wraps a parser so that its result includes span information (start and end positions).
@@ -80,18 +109,19 @@ export const getPosition = (input) => {
  */
 export function withSpan(parser) {
     return (input) => {
-        const source = getInputStr();
+        const source = getParseState().inputStr;
         const lineTable = getLineTable(source);
         const startOffset = source.length - input.length;
         const result = parser(input);
         if (!result.success)
             return result;
         const endOffset = source.length - result.rest.length;
+        const base = getParseState().basePosition;
         return success({
             value: result.result,
             span: {
-                start: offsetToPosition(lineTable, startOffset),
-                end: offsetToPosition(lineTable, endOffset),
+                start: composePosition(base, offsetToPosition(lineTable, startOffset)),
+                end: composePosition(base, offsetToPosition(lineTable, endOffset)),
             },
         }, result.rest);
     };

package/dist/rightmostFailure.d.ts

@@ -25,6 +25,16 @@ export declare function saveRightmostFailure(): SavedRightmostFailure;
 export declare function restoreRightmostFailure(saved: SavedRightmostFailure): void;
 /**
  * Formats the rightmost failure into a human-readable error message with line and column info.
+ * A committed failure (see the `committed` combinator) takes precedence
+ * over the rightmost record — the committed error wins reporting even
+ * when some fallback alternative failed deeper into the input.
+ *
+ * Scope: the preference is per parse state. A commit inside `runNested`
+ * lives in the inner state and surfaces through the returned result's
+ * `committed` flag, never through the enclosing parse's getErrorMessage.
+ * The position math assumes the committed failure's `rest` is a suffix
+ * of the CURRENT state's source — don't stash a `runNested` result
+ * (inner-coordinate `rest`) into an outer-state commit.
  * Returns `null` if no failures have been recorded.
  * Requires `setInputStr` to have been called.
  */

package/dist/rightmostFailure.js

@@ -1,10 +1,11 @@
 import { getInputStr } from "./trace.js";
-import { buildLineTable, offsetToPosition } from "./position.js";
-let rightmostFailurePos = -1;
-let rightmostFailureExpected = [];
+import { buildLineTable, offsetToPosition, composePosition } from "./position.js";
+import { getParseState } from "./parseState.js";
 export function resetRightmostFailure() {
-    rightmostFailurePos = -1;
-    rightmostFailureExpected = [];
+    const state = getParseState();
+    state.rightmostFailurePos = -1;
+    state.rightmostFailureExpected = [];
+    state.committedFailure = null;
 }
 /**
  * Record an expected alternative at the current failure position.
@@ -16,17 +17,18 @@ export function resetRightmostFailure() {
  * @param expected - a human-readable description of what was expected
  */
 export function recordFailure(input, expected) {
+    const state = getParseState();
     const source = getInputStr();
     if (source.length === 0)
         return;
     const pos = source.length - input.length;
-    if (pos > rightmostFailurePos) {
-        rightmostFailurePos = pos;
-        rightmostFailureExpected = [expected];
+    if (pos > state.rightmostFailurePos) {
+        state.rightmostFailurePos = pos;
+        state.rightmostFailureExpected = [expected];
     }
-    else if (pos === rightmostFailurePos) {
-        if (!rightmostFailureExpected.includes(expected)) {
-            rightmostFailureExpected.push(expected);
+    else if (pos === state.rightmostFailurePos) {
+        if (!state.rightmostFailureExpected.includes(expected)) {
+            state.rightmostFailureExpected.push(expected);
         }
     }
 }
@@ -35,16 +37,25 @@ export function recordFailure(input, expected) {
  * or `null` if no failures have been recorded.
  */
 export function getRightmostFailure() {
-    if (rightmostFailurePos < 0)
+    const state = getParseState();
+    if (state.rightmostFailurePos < 0)
         return null;
-    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+    return {
+        pos: state.rightmostFailurePos,
+        expected: [...state.rightmostFailureExpected],
+    };
 }
 export function saveRightmostFailure() {
-    return { pos: rightmostFailurePos, expected: [...rightmostFailureExpected] };
+    const state = getParseState();
+    return {
+        pos: state.rightmostFailurePos,
+        expected: [...state.rightmostFailureExpected],
+    };
 }
 export function restoreRightmostFailure(saved) {
-    rightmostFailurePos = saved.pos;
-    rightmostFailureExpected = [...saved.expected];
+    const state = getParseState();
+    state.rightmostFailurePos = saved.pos;
+    state.rightmostFailureExpected = [...saved.expected];
 }
 function formatExpected(expected) {
     if (expected.length === 1)
@@ -55,16 +66,34 @@ function formatExpected(expected) {
 }
 /**
  * Formats the rightmost failure into a human-readable error message with line and column info.
+ * A committed failure (see the `committed` combinator) takes precedence
+ * over the rightmost record — the committed error wins reporting even
+ * when some fallback alternative failed deeper into the input.
+ *
+ * Scope: the preference is per parse state. A commit inside `runNested`
+ * lives in the inner state and surfaces through the returned result's
+ * `committed` flag, never through the enclosing parse's getErrorMessage.
+ * The position math assumes the committed failure's `rest` is a suffix
+ * of the CURRENT state's source — don't stash a `runNested` result
+ * (inner-coordinate `rest`) into an outer-state commit.
  * Returns `null` if no failures have been recorded.
  * Requires `setInputStr` to have been called.
  */
 export function getErrorMessage() {
-    if (rightmostFailurePos < 0)
+    const state = getParseState();
+    const committed = state.committedFailure;
+    if (committed !== null) {
+        const source = getInputStr();
+        const lineTable = buildLineTable(source);
+        const pos = composePosition(state.basePosition, offsetToPosition(lineTable, source.length - committed.rest.length));
+        return `Line ${pos.line + 1}, col ${pos.column + 1}: ${committed.message}`;
+    }
+    if (state.rightmostFailurePos < 0)
         return null;
     const source = getInputStr();
     const lineTable = buildLineTable(source);
-    const pos = offsetToPosition(lineTable, rightmostFailurePos);
+    const pos = composePosition(state.basePosition, offsetToPosition(lineTable, state.rightmostFailurePos));
     const line = pos.line + 1;
     const column = pos.column + 1;
-    return `Line ${line}, col ${column}: expected ${formatExpected(rightmostFailureExpected)}`;
+    return `Line ${line}, col ${column}: expected ${formatExpected(state.rightmostFailureExpected)}`;
 }

package/dist/runNested.d.ts

@@ -0,0 +1,24 @@
+import { Parser, ParserResult } from "./types.js";
+import type { Position } from "./position.js";
+export type NestedOptions = {
+    /** Positions in the sub-parse's results are offset by this, so spans
+     *  and error messages come out in the ENCLOSING parse's coordinates.
+     *  Defaults to zero (positions relative to `input`). */
+    basePosition?: Position;
+};
+/**
+ * Run a complete parse of `input` with its own input string, rightmost-
+ * failure record, and memo caches, restoring the enclosing parse's state
+ * on exit — success, failure, or throw. The one supported way to run a
+ * parse inside another parse.
+ *
+ * @example
+ * ```ts
+ * // While parsing a file, parse an embedded snippet as its own program,
+ * // reporting positions relative to the enclosing file:
+ * const embedded = runNested(exprParser, snippetText, {
+ *   basePosition: openingPosition, // where the snippet starts in the file
+ * });
+ * ```
+ */
+export declare function runNested<T>(parser: Parser<T>, input: string, opts?: NestedOptions): ParserResult<T>;

package/dist/runNested.js

@@ -0,0 +1,28 @@
+import { createParseState, swapParseState } from "./parseState.js";
+/**
+ * Run a complete parse of `input` with its own input string, rightmost-
+ * failure record, and memo caches, restoring the enclosing parse's state
+ * on exit — success, failure, or throw. The one supported way to run a
+ * parse inside another parse.
+ *
+ * @example
+ * ```ts
+ * // While parsing a file, parse an embedded snippet as its own program,
+ * // reporting positions relative to the enclosing file:
+ * const embedded = runNested(exprParser, snippetText, {
+ *   basePosition: openingPosition, // where the snippet starts in the file
+ * });
+ * ```
+ */
+export function runNested(parser, input, opts) {
+    // Deliberately does NOT call setInputStr: createParseState pre-sets
+    // inputStr and a fresh rightmost record (replicating setInputStr's
+    // reset), and calling it here would clobber the fresh state's fields.
+    const savedState = swapParseState(createParseState(input, opts === null || opts === void 0 ? void 0 : opts.basePosition));
+    try {
+        return parser(input);
+    }
+    finally {
+        swapParseState(savedState);
+    }
+}

package/dist/trace.js

@@ -2,6 +2,8 @@ import { escape, round, shorten } from "./utils.js";
 import process from "process";
 import { execSync } from "child_process";
 import { resetRightmostFailure } from "./rightmostFailure.js";
+import { getParseState } from "./parseState.js";
+import { composePosition } from "./position.js";
 const isNode = typeof process !== "undefined" &&
     process.versions != null &&
     process.versions.node != null;
@@ -186,7 +188,6 @@ export function limitSteps(limit, callback) {
     callback();
     stepLimit = -1;
 }
-let inputStr = "";
 /**
  * Use this function in conjunction with the parseError combinator. Before running your parser,
  * call this function, giving it the entire input. Then, if the parseError combinator throws an error,
@@ -194,11 +195,11 @@ let inputStr = "";
  * @param s full string to parse
  */
 export function setInputStr(s) {
-    inputStr = s;
+    getParseState().inputStr = s;
     resetRightmostFailure();
 }
 export function getInputStr() {
-    return inputStr;
+    return getParseState().inputStr;
 }
 export function getDiagnostics(result, input, _message) {
     const inputStr = getInputStr();
@@ -222,9 +223,14 @@ export function getDiagnostics(result, input, _message) {
         }
         const linesIndex = Math.max(0, i - 1);
         const column = lines[linesIndex].length - (acc - index);
-        return {
+        const composed = composePosition(getParseState().basePosition, {
+            offset: index,
             line: i - 1,
             column,
+        });
+        return {
+            line: composed.line,
+            column: composed.column,
             length: 1,
             prettyMessage: messages.join("\n"),
             message: message,