@sema-agent/core 7.27.0 → 7.28.0

package/dist/tools/fs/bash-lexer.d.ts

@@ -1,152 +0,0 @@
-/**
- * The ONE shell lexer of the read faces, in two modes.
- *
- * STRICT is the residual space the classify faces live in: the caller has hard-rejected `< > $ ( ) \` \n \r \\`
- * (or, under the rule lane's tolerate option, passes `<`/`>` through as ordinary text), so the whole of bash's
- * word grammar left to model is quote pairing, the four connectors and whitespace. LENIENT is the space the
- * refused-command whitelist reads — everything the strict gate refused, RECORDED instead of refused: heredoc
- * bodies, substitution bodies, redirections, comments, escapes, line continuations, subshell groups,
- * backgrounding, line breaks.
- *
- * One walker serves both. The lenient-only constructs are branches the strict caller can never reach (their
- * characters are gone before it calls), so for every strict-accepted input the two modes produce the same words
- * and the same connectors — up to the strict mode's own two residuals (a `#` is a word there, and JS whitespace
- * rather than bash's blanks bounds a word); the whitelist stopped being a second parser the day it read this stream.
- *
- * Quoting. A quote character opens a region, the matching one closes it, and a quote of the OTHER kind inside an
- * open region is ordinary text. When a region is still open at the end of the input the pass is re-run with
- * quotes as ordinary characters — the QUOTE-BLIND reading, which yields strictly more words and more segments
- * (the fail-closed direction every consumer here errs in). {@link quoteMask} is the positional projection of the
- * same rule, for the callers that need "is this character quoted" rather than tokens.
- *
- * Line continuations. Bash removes a `\<newline>` pair from its input before it recognises anything — except
- * inside single quotes, inside a comment (the newline ends the comment) and inside a QUOTED here-document body.
- * The walker does the same at the point of reading: every lookahead below reads the next LOGICAL character, past
- * any continuation, so a pair can stand inside a construct's spelling (`$\<newline>(…)` opens a substitution)
- * 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 — what a caller handing over one already-split segment
-     *  expects. */
-    readonly connectors?: "split" | "text";
-}
-/** An argv word in BOTH spellings. `raw` is what the SHELL sees (quotes, escapes and substitution text
- *  retained) — the only spelling in which "is this metacharacter quoted?" is still answerable; `folded` is what
- *  the PROGRAM receives after quote removal, with every substitution replaced by {@link SUBSTITUTION_PLACEHOLDER}
- *  and a literal leading tilde spelled `./~…` (see {@link literalTildeSpelling}). */
-export interface LexedWord {
-    readonly kind: "word";
-    readonly raw: string;
-    readonly folded: string;
-}
-/** A redirection and the word it takes. A descriptor duplication (`>&2`, `<&0`, `>&-`, `>&1-`) takes none. */
-export interface LexedRedirect {
-    readonly kind: "redirect";
-    readonly op: "<" | ">" | ">>" | "<<<" | "&>" | "&>>" | ">&" | "<&";
-    readonly target?: LexedWord;
-}
-/** 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". */
-export interface LexedHeredoc {
-    readonly kind: "heredoc";
-    readonly delimiter: string;
-    readonly quoted: boolean;
-    readonly body: string;
-}
-/** A subshell parenthesis, standing alone: structure, not a word. */
-export interface LexedGroup {
-    readonly kind: "group";
-    readonly op: "(" | ")";
-}
-export type LexedToken = LexedWord | LexedRedirect | LexedHeredoc | LexedGroup;
-/** The connector bash ran a segment through — `"start"` for the first one. A closed set, because the read
- *  boundary distinguishes all four: `&&` is the only one under which the previous segment is known to have
- *  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. */
-export type LenientConnector = ShellSegmentConnector | "&" | "\n";
-export interface LexedSegment {
-    /** The segment's text exactly as written (surrounding whitespace included) — what a caller that wants the
-     *  string rather than the tokens reads. Here-document bodies are not part of any segment's text. */
-    readonly text: string;
-    readonly connector: LenientConnector;
-    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[];
-}
-export interface LexedCommand {
-    readonly segments: readonly LexedSegment[];
-    /** Every substitution body of the command, in order (the per-segment lists concatenated). */
-    readonly substitutions: readonly string[];
-}
-/** One segment's argv words in both spellings, index-aligned by construction (folding is strictly per word — it
- *  never splits or joins). The one shape every downstream arm of the classifier reads. */
-export interface SegmentTokens {
-    readonly folded: readonly string[];
-    readonly raw: readonly string[];
-}
-/** What a substitution leaves in a word's FOLDED spelling: a marker no argv word can spell, so a consumer that
- *  judges words sees "this word carries text the shell computes" rather than the computing text itself. */
-export declare const SUBSTITUTION_PLACEHOLDER = " subst";
-export type QuoteOpen = '"' | "'" | undefined;
-/**
- * Does the `$` at `at` OPEN a quote form (`$'…'` / `$"…"`)? ONE question, asked by every walker that has to
- * answer it — the word scan here and the expansion scan in the classifier — because a `$` one of them reads
- * as escaped and the other as bare yields two different words for the same text, and the judge then compares
- * the wrong one. Escaped means an ODD run of backslashes in front of it: `\$'y'` is a literal `$`, while
- * `x\\$'y'` is a literal backslash followed by a real ANSI-C quote (both read off /bin/bash). Counting the
- * run is what a one-character peek behind cannot do.
- */
-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, and a pairing walk blind to it reads the real
- *  closing quote as an OPENING one and everything after as quoted, which hides an expansion the shell performs. */
-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 themselves belong to the region they bound — they are not operators
- * either way — so `openedBy` names that region's quote character at their own index too.
- *
- * `quoted` is a VIEW of `openedBy`, minted in the same step: a consumer asking only "is this inside quotes"
- * reads it, one asking WHICH quote (single quotes suppress every expansion, double quotes suppress neither `$`
- * nor the backtick) reads `openedBy`, and the two cannot drift.
- *
- * `balanced` is false when a region is still open at the end of the string. Callers must then NOT use the mask:
- * an unterminated quote is a string bash itself cannot parse, and every consumer falls back to the quote-BLIND
- * reading, which is the stricter one.
- *
- * EXACTNESS. This models bash only for the residual character space the strict faces operate in, where backslash
- * escapes and subshells are rejected outright — there `'` and `"` pairing is the whole of quoting, so a region
- * computed here is exactly a region bash quotes. A caller deciding about `$` or a backtick on this mask owes
- * the argument in `bash-readonly-classifier.ts`. It is NOT a general shell quoting parser.
- */
-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 quoted tilde-prefix, an option payload); 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). */
-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. The honoured pass is authoritative when every quote closes; otherwise the quote-blind pass is
- * the answer — the fail-closed fallback every face here has always taken for a string bash itself cannot parse.
- * In STRICT mode that fallback is two-level, as the faces have always read it: the segments are split blind, and
- * each segment's words are then read on their own balance (`echo "a b"; echo '` keeps `a b` one word in the first
- * segment). The lenient face reads an unbalanced command blind throughout. `{ reject }` names a construct the
- * lenient mode cannot read (an unterminated substitution or here-document, an operator with no operand, a
- * substitution this lexer cannot delimit) or, in strict mode, a backgrounding `&`.
- */
-export declare function lexShellText(source: string, opts: LexOptions): LexedCommand | {
-    reject: string;
-};