@sema-agent/core 7.29.0 → 7.30.0

package/dist/shell/lex.d.ts

@@ -5,13 +5,11 @@
  * environment's last-resort `sh` reads `$'…'`, `+=`, a subscript, `<<<`, `<(…)` and `&>` differently; see
  * {@link bashOnlyConstructsOf}).
  *
- * Two modes remain. STRICT is the residual space the classify faces live in: the caller has hard-rejected
- * `< > $ ( ) \` \n \r \\` (or passes `<`/`>` through as text under the rule lane's tolerate option), so the whole of
- * bash's word grammar left to model there is quote pairing, the four connectors and whitespace. LENIENT is the space
- * the read faces read — everything the strict gate refused, RECORDED instead of refused. The lenient-only
- * constructs are branches the strict caller can never reach, so for every strict-accepted input the two modes
- * produce the same words and connectors, up to the strict mode's two residuals (a `#` is a word there, and JS
- * whitespace rather than bash's blanks bounds a word).
+ * ONE walk, ONE reading: every construct bash reads is RECORDED — a redirection, a substitution, an escape, a
+ * comment, a line break, a backgrounding `&` — never refused here. Which of them a face refuses is that face's
+ * predicate over the result (the classify faces' residual predicate in the read-only classifier); the lexer has
+ * no modes. Bash's own word rules hold throughout: an unquoted word-start `#` begins a comment, and only a blank
+ * (space or tab) bounds a word — a non-breaking space or a vertical tab is a word character.
  *
  * A command bash cannot parse is a {@link LexParseFailure}, never a guessed reading: an unterminated quote,
  * substitution, subscript or here-document yields NO segments. A word bash reads but whose VALUE the text does not
@@ -21,13 +19,6 @@
  * a comment and a QUOTED here-document body. Every lookahead below reads the next LOGICAL character past any
  * continuation, so a pair can stand inside a construct's spelling and never inside the three places bash keeps it.
  */
-export type LexMode = "strict" | "lenient";
-export interface LexOptions {
-    readonly mode: LexMode;
-    /** `"split"` (default): the connectors bound segments. `"text"`: a single segment is being tokenized and an
-     *  unquoted connector character is a word character. */
-    readonly connectors?: "split" | "text";
-}
 /** The dialect this lexer reads. The execution environment falls back to `sh` when no bash is found; a reader on
  *  that path must degrade every word carrying a {@link BashOnlyConstruct} to the conservative reading. */
 export declare const SHELL_LEX_DIALECT = "bash";
@@ -42,18 +33,9 @@ export type ExpansionKind = (typeof EXPANSION_KINDS)[number];
  *  contain — never "the lexer did not look". */
 export declare const UNRESOLVED_REASONS: readonly ["ansi_c_escape", "locale_string", "parameter_text", "subscript_text", "compound_array_value"];
 export type UnresolvedReason = (typeof UNRESOLVED_REASONS)[number];
-/** What the {@link lexShellText} view does with an unresolved word: `refuse` hands the consumer the reason's
- *  sentence; `fold` hands it the folded spelling as the pre-fact readers judged it. The locale string folds:
- *  refusing it would turn a deny row's HIT (judged on the untranslated spelling) into a mere question, and a
- *  reader that asks on both faces AND keeps the deny judgment reads the fact, not this view. */
-export declare const UNRESOLVED_VIEW: {
-    readonly ansi_c_escape: "refuse";
-    readonly locale_string: "fold";
-    readonly parameter_text: "refuse";
-    readonly subscript_text: "refuse";
-    readonly compound_array_value: "refuse";
-};
-/** The sentence the {@link lexShellText} view hands a consumer for an unresolved word it refuses. */
+/** The sentence a consumer hands on for an unresolved word: every reason is one a face ASKS about (the locale
+ *  string included — its translation is not in the text), and a deny row is still judged on the written spelling
+ *  by the readers that keep the word beside the reason. */
 export declare const UNRESOLVED_SENTENCE: {
     readonly ansi_c_escape: "an ANSI-C quoted word carries an escape this lexer does not fold";
     readonly locale_string: "a locale-translated string carries text this lexer does not read";
@@ -61,9 +43,8 @@ export declare const UNRESOLVED_SENTENCE: {
     readonly subscript_text: "a subscript carries text this lexer does not read";
     readonly compound_array_value: "a compound assignment value is a list this lexer does not read";
 };
-/** Why a command yields no segments: bash's own syntax errors, the two constructs this lexer cannot delimit, and
- *  the strict mode's backgrounding refusal. */
-export declare const PARSE_FAILURE_REASONS: readonly ["unterminated_single_quote", "unterminated_double_quote", "unterminated_ansi_c", "unterminated_subscript", "unterminated_compound_value", "unterminated_command_substitution", "unterminated_process_substitution", "unterminated_parameter_expansion", "unterminated_heredoc", "undelimited_substitution", "redirect_without_target", "heredoc_without_delimiter", "heredoc_delimiter_expands", "background_operator"];
+/** Why a command yields no segments: bash's own syntax errors and the two constructs this lexer cannot delimit. */
+export declare const PARSE_FAILURE_REASONS: readonly ["unterminated_single_quote", "unterminated_double_quote", "unterminated_ansi_c", "unterminated_subscript", "unterminated_compound_value", "unterminated_command_substitution", "unterminated_process_substitution", "unterminated_parameter_expansion", "unterminated_heredoc", "undelimited_substitution", "redirect_without_target", "heredoc_without_delimiter", "heredoc_delimiter_expands"];
 export type ParseFailureReason = (typeof PARSE_FAILURE_REASONS)[number];
 export declare const PARSE_FAILURE_SENTENCE: {
     readonly unterminated_single_quote: "a single-quoted word never closes";
@@ -79,10 +60,9 @@ export declare const PARSE_FAILURE_SENTENCE: {
     readonly redirect_without_target: "a redirection names no target";
     readonly heredoc_without_delimiter: "a here-document operator names no delimiter";
     readonly heredoc_delimiter_expands: "a here-document delimiter is not a plain word";
-    readonly background_operator: "`&` backgrounding is not allowed — a backgrounded process outlives the command";
 };
 /** The constructs of this dialect a POSIX `sh` reads as something else. */
-export declare const BASH_ONLY_CONSTRUCTS: readonly ["ansi_c_quoting", "locale_string", "append_assignment", "subscript_assignment", "compound_assignment", "here_string", "process_substitution", "redirect_both", "brace_expansion"];
+export declare const BASH_ONLY_CONSTRUCTS: readonly ["ansi_c_quoting", "locale_string", "append_assignment", "subscript_assignment", "compound_assignment", "here_string", "process_substitution", "redirect_both", "pipe_both", "brace_expansion"];
 export type BashOnlyConstruct = (typeof BASH_ONLY_CONSTRUCTS)[number];
 /**
  * The ANSI-C escapes this lexer folds: the thirteen single-letter ones, whose byte is the same in every bash and
@@ -172,11 +152,16 @@ export interface LexedWord {
      *  assignment word, after a bare control-prefix word, or after a leading redirection list. */
     readonly atCommandPosition: boolean;
 }
-/** A redirection and the word it takes. A descriptor duplication (`>&2`, `<&0`, `>&-`, `>&1-`) takes none. */
+/** A redirection and the word it takes. A descriptor duplication (`>&2`, `<&0`, `>&-`, `>&1-`) takes none: its
+ *  operand is `dup`, the descriptor (or `-`, or a descriptor followed by `-`) as written. `fd` is the descriptor
+ *  number written in front of the operator (`2>f`, `3>&0`); absent when none was (bash's default, `1` for an
+ *  output form and `0` for an input form, is the reader's to apply). */
 export interface LexedRedirect {
     readonly kind: "redirect";
     readonly op: "<" | ">" | ">>" | "<<<" | "&>" | "&>>" | ">&" | "<&";
+    readonly fd?: number;
     readonly target?: LexedWord;
+    readonly dup?: string;
 }
 /** A here-document: the body is DATA the program reads on stdin, never command text. `quoted` records whether
  *  the delimiter word carried a quote or an escape, which is bash's rule for "the body does not expand". */
@@ -197,13 +182,17 @@ export type LexedToken = LexedWord | LexedRedirect | LexedHeredoc | LexedGroup;
  *  exited ZERO, `||` is the only one under which the previous segment may have been SKIPPED ENTIRELY, `|`
  *  puts the segment in a subshell whose directory changes never reach the parent, and `;` is plain sequence. */
 export type ShellSegmentConnector = "start" | ";" | "&&" | "||" | "|";
-/** The lenient mode's two extra boundaries: a backgrounding `&` and a line break. */
+/** The two boundaries the read boundary does not distinguish from a plain sequence: a backgrounding `&` and a
+ *  line break. */
 export type LenientConnector = ShellSegmentConnector | "&" | "\n";
 export interface LexedSegment {
     /** The segment's text exactly as written (surrounding whitespace included). Here-document bodies are not part
      *  of any segment's text. */
     readonly text: string;
     readonly connector: LenientConnector;
+    /** The `|` was spelled `|&`: the previous segment's standard error is piped too (bash 4+; a syntax error on
+     *  bash 3.2, so a reader on the fail-closed side treats the pipe as real). */
+    readonly pipesStderr?: true;
     readonly tokens: readonly LexedToken[];
     /** The bodies of the substitutions found in THIS segment (its words and its redirection targets), in order. */
     readonly substitutions: readonly string[];
@@ -233,7 +222,6 @@ export declare const SUBSTITUTION_PLACEHOLDER = " subst";
 /** Shell control words that stand BEFORE a command: transparent for the boundary walk (the command behind them is
  *  judged), and a position after which bash still accepts an assignment word. */
 export declare const SHELL_CONTROL_PREFIXES: ReadonlySet<string>;
-export type QuoteOpen = '"' | "'" | undefined;
 /**
  * Does the `$` at `at` OPEN a quote form (`$'…'` / `$"…"`)? ONE question, asked by every walker that has to
  * answer it. Escaped means an ODD run of backslashes in front of it: `\$'y'` is a literal `$`, while `x\\$'y'`
@@ -244,34 +232,25 @@ export declare function dollarOpensQuote(text: string, at: number): boolean;
 /** The `'` that CLOSES the ANSI-C quote opened at `open`, or `undefined` when none does. `\'` does not close
  *  one — the single place a quote region honours a backslash. */
 export declare function ansiCQuoteClose(source: string, open: number): number | undefined;
-/**
- * Which QUOTE holds each character of `s`, by the same pairing rule the lexer walks with, and the boolean view of
- * it. The pairing quote characters belong to the region they bound. `balanced` is false when a region is still
- * open at the end of the string; callers must then NOT use the mask. This models bash only for the residual
- * character space the strict faces operate in, where backslash escapes are rejected outright.
- */
-export declare function quoteMask(s: string): {
-    openedBy: readonly QuoteOpen[];
-    quoted: readonly boolean[];
-    balanced: boolean;
-};
 /** The ONE spelling of a LITERAL leading tilde — `./~…`, the relative path it is — for every position bash does not
  *  expand it in; a word without a leading tilde is returned as is. */
 export declare function literalTildeSpelling(word: string): string;
-/** The argv-word projection of a segment: redirections, here-documents and groups are not words the program
- *  receives (bash removes them before exec). */
+/** The argv words of a segment: redirections, here-documents and groups are not words the program receives (bash
+ *  removes them before exec). */
+export declare function argvOf(segment: LexedSegment): readonly LexedWord[];
+/** The two-spelling view of {@link argvOf}, for the readers that compare spellings. */
 export declare function wordsOf(segment: LexedSegment): SegmentTokens;
 /** The substitution bodies of an UNQUOTED here-document body: `$(…)` and backticks are live there, quotes are
  *  ordinary characters, a backslash protects the next character. `undefined` when a substitution never closes. */
 export declare function substitutionsInHeredocBody(body: string): string[] | undefined;
 /** Lex a command: its segments, or the one reason bash (or this lexer) cannot delimit them. */
-export declare function lexShell(source: string, opts: LexOptions): ShellLex;
+export declare function lexShell(source: string): ShellLex;
 /**
  * The refused-reading view of {@link lexShell}: a parse failure, and any word whose value cannot be read off the
- * text and whose reason {@link UNRESOLVED_VIEW} refuses, become the one `{ reject }` sentence a consumer's
- * unreadable arm already takes.
+ * text, become the one `{ reject }` sentence a consumer's unreadable arm already takes. A reader that keeps the
+ * other words (the read station) reads {@link lexShell} and the word's {@link LexedWord.unresolved} instead.
  */
-export declare function lexShellText(source: string, opts: LexOptions): LexedCommand | {
+export declare function lexShellText(source: string): LexedCommand | {
     reject: string;
 };
 /** The constructs of this dialect the command leans on — what a POSIX `sh` would read as something else. Empty