polydeukes 0.6.0 → 0.7.1

package/dist/covenant/bash-line.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Bash command-line tokenizer + mutation-target extraction core.
+ *
+ * Pure functions only — zero I/O, spawn, or logging. A hand-rolled single-pass character
+ * scanner recognizes quote state (`'`, `"`, `$'…'`, `\`), control operators
+ * (`;` `&&` `||` `|` `&`), redirect operators (`>` `>>` `>|` `<` `2>` `&>`, attached `>f`),
+ * and marks tokens opaque when their static value is unknowable (command substitution,
+ * parameter expansion, globs).
+ *
+ * Fail-closed: no input ever throws. A construct the scanner cannot finish reading yields a
+ * partial result — the commands it did read, plus one `unread` span per failure; in
+ * {@link extractMutations} each span becomes one indeterminate entry. Block/allow
+ * decisions, read-only allowlists, and detection rules live in the judges that consume this.
+ */
+/** A single word token with a static-opacity flag (`opaque` = value not knowable). */
+export type WordToken = {
+    text: string;
+    opaque: boolean;
+};
+/** A redirect operator paired with its target word (`>` `>>` `<` `2>` `&>`). */
+export type RedirectToken = {
+    operator: string;
+    target: WordToken;
+};
+/**
+ * One heredoc body a command declared, with its delimiter's quoting. `literal` means the
+ * delimiter was quoted, so the body is written verbatim; an unquoted delimiter expands its
+ * body, which only a consumer can decide what to do about.
+ */
+export type HeredocBody = {
+    body: string;
+    literal: boolean;
+};
+/**
+ * One simple command: its word tokens, any redirect operators, and the heredoc bodies it
+ * declared (in declaration order — absent when it declared none).
+ */
+export type SimpleCommand = {
+    words: WordToken[];
+    redirects: RedirectToken[];
+    heredocs?: HeredocBody[];
+};
+/**
+ * A span of the line the scanner could not read, with the reason it stopped. `reason` is a
+ * telemetry pass-through value: no consumer branches on it.
+ */
+export type UnreadSpan = {
+    text: string;
+    reason: string;
+};
+/**
+ * A half-open span `[start, end)` of the line bash hands to a command as stdin data instead
+ * of executing: a heredoc body, or a herestring's target word.
+ */
+export type DataSpan = {
+    start: number;
+    end: number;
+};
+/**
+ * The tokenizer's result: the commands it read, plus one span per failure it hit. A failure
+ * does not discard the line — the read commands reach precise judgment and only the spans
+ * fall to a consumer's conservative treatment. An empty `unread` is the "fully read" signal.
+ *
+ * `data` lists the stdin-data spans in source order, non-overlapping: heredoc bodies and
+ * herestring words bash hands over without expanding them. A body under an unquoted
+ * delimiter that carries `$` or a backtick, and an opaque herestring word, are text bash
+ * runs first and are not data. A span the scanner could not finish reading is never among
+ * them either, so unread bytes stay on the command line.
+ */
+export type TokenizeResult = {
+    commands: SimpleCommand[];
+    unread: UnreadSpan[];
+    data: DataSpan[];
+};
+/** A detected mutation target (path) with the name of the rule that found it. */
+export type MutationTarget = {
+    path: string;
+    rule: string;
+};
+/**
+ * A detection rule seam: a pure function over a single simple command that returns the
+ * mutation targets it detects.
+ */
+export type MutationRule = {
+    name: string;
+    detect(command: SimpleCommand): MutationTarget[];
+};
+/** A structure that cannot be decided deterministically, with the reason why. */
+export type Indeterminate = {
+    reason: string;
+};
+/** The extraction result — detected mutations and undecidable structures, kept separate. */
+export type MutationAnalysis = {
+    mutations: MutationTarget[];
+    indeterminate: Indeterminate[];
+};
+/**
+ * True when `commandName` (a command word's basename) re-parses its string arguments in a
+ * nested shell — the reinterpretation boundary the tokenizer refuses to parse into. A judge
+ * can consult this to refuse to treat such a command as provably read-only.
+ */
+export declare function isNestedShellCommand(commandName: string): boolean;
+/**
+ * The word that names the command, skipping any leading assignments — undefined when the
+ * command is nothing but assignments.
+ *
+ * Read at the nested-shell boundary only. There an unskipped assignment hides `bash` behind
+ * `FOO=1` and the line passes with confidence; for the read-only allowlist and precedent
+ * evidence the same miss is the conservative direction, so those keep reading `words[0]`.
+ */
+export declare function commandNameWord(command: SimpleCommand): WordToken | undefined;
+/**
+ * Tokenize one shell line into simple commands. Never throws, and never discards what it
+ * read: a construct it cannot finish reading is recorded as an `unread` span and the scan
+ * carries on.
+ */
+export declare function tokenizeCommandLine(line: string): TokenizeResult;
+/**
+ * The executed text of a command line: the line with every `data` span deleted and nothing
+ * put in its place, so the words bash runs keep their spelling and line structure. Bytes
+ * the scanner could not finish reading are not data spans and stay as written.
+ */
+export declare function executedText(line: string): string;
+/**
+ * Extract mutation targets from a shell line via injected rules. A simple command
+ * contributes an indeterminate entry when it is a nested-shell call OR contains any opaque
+ * word (in which case its rules are still applied, but an undecidable structure is present);
+ * each unread span yields one more. Never throws.
+ */
+export declare function extractMutations(line: string, rules: MutationRule[]): MutationAnalysis;