fullcourtdefense-cli 1.35.7 → 1.35.9

package/dist/shellAst.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Shell AST facts — the structural view of a shell command line that the
+ * deterministic guard and the action-policy engine consume as DATA.
+ *
+ * A tree-sitter-bash parse tree is walked ONCE into a flat, JSON-serializable
+ * list of simple commands in execution order. Each command carries its argv
+ * with quoting resolved, which words are fully literal, the cwd scope in force
+ * when it runs (tracked through `cd`/`pushd`, subshells, loops, functions), the
+ * nesting it sits in, its redirections, and — for wrappers such as `sudo`,
+ * `bash -c '…'`, `docker run … sh -c '…'` — the inner script parsed recursively.
+ *
+ * Contract (the part that keeps this safe to put on the decision path):
+ *
+ *   1. FAIL CLOSED. `complete` is true only when the tree has no ERROR / MISSING
+ *      node and every node type met is in the explicit allow-list below. Any
+ *      structure this module does not understand makes the whole result
+ *      incomplete, and an incomplete result may never RELAX a verdict — the
+ *      regex floor in the guard and the engine then decides alone. (Same
+ *      property Codex's `codex-command` and the tree-sitter rewrite of Claude
+ *      Code's bash safety take: never interpret structure you cannot prove.)
+ *   2. Deterministic, no I/O. This file has no imports; the parser is injected
+ *      as a minimal node interface so the same bytes are vendored into the
+ *      backend (console simulator) and stay byte-identical with the CLI.
+ *   3. Data, not code. The facts cross into the hot-updatable detector worker
+ *      as JSON. Nothing here executes, expands or resolves anything.
+ *
+ * Why an AST at all: every false positive of the last months was structural —
+ * quoted text mistaken for a command, a heredoc body scanned as shell, a bare
+ * `rm -rf *` after `cd scratch/` read as a root wipe, a `$( )` boundary missed.
+ * A parser answers those once; a regex answers them one incident at a time.
+ */
+export interface ShellSyntaxNode {
+    type: string;
+    text: string;
+    startIndex: number;
+    endIndex: number;
+    childCount: number;
+    isMissing: boolean;
+    isNamed: boolean;
+    child(index: number): ShellSyntaxNode | null;
+    childForFieldName(name: string): ShellSyntaxNode | null;
+}
+export type CwdScope = 'scoped' | 'unscoped' | 'unknown';
+export interface ShellRedirectFact {
+    op: string;
+    target: string;
+    literal: boolean;
+}
+export interface ShellWrapperFact {
+    kind: 'privilege' | 'shell' | 'eval' | 'exec' | 'env' | 'container' | 'timing' | 'xargs';
+    program: string;
+    /** The wrapped script when it is a literal string, parsed with the same walker. */
+    inner?: ShellFacts;
+}
+export interface ShellCommandFact {
+    /** argv[0] with quotes resolved; '' when it is dynamic (variable, substitution). */
+    name: string;
+    /** Words with quotes resolved. Dynamic parts keep their source text (`$X`, `$(…)`). */
+    argv: string[];
+    /** argv[i] is entirely literal: no expansion, substitution, glob-carrying variable. */
+    literal: boolean[];
+    /** Source text of the command including its redirects, EXCLUDING heredoc bodies. */
+    text: string;
+    start: number;
+    end: number;
+    /** cwd scope in force when this command runs. */
+    cwdScope: CwdScope;
+    depth: {
+        subshell: number;
+        function: number;
+        loop: number;
+        conditional: number;
+        substitution: number;
+    };
+    /** Members of one pipeline share an id (0 = not in a pipeline). */
+    pipeline: number;
+    redirects: ShellRedirectFact[];
+    hasHeredoc: boolean;
+    wrapper?: ShellWrapperFact;
+}
+export interface ShellFacts {
+    parser: 'tree-sitter-bash';
+    /** No parse errors and every node type understood. Only a complete result may relax a verdict. */
+    complete: boolean;
+    /** Why the result is incomplete (first reason). */
+    incompleteReason?: string;
+    commands: ShellCommandFact[];
+    /** Node types met that are not in the allow-list (for diagnostics / corpus growth). */
+    unknownNodeTypes: string[];
+    /** Any `eval`, `source`/`.`, or dynamic command name — structure the parse cannot see through. */
+    dynamicExecution: boolean;
+}
+/** What a `cd`/`pushd` target says about the cwd afterwards. */
+export declare function cdTargetScope(target: string, literal: boolean): CwdScope;
+/** A parsed inner script: its root plus the release of the parser's native tree. */
+export interface ParsedShellTree {
+    root: ShellSyntaxNode;
+    release(): void;
+}
+export declare const MAX_SHELL_AST_SOURCE = 64000;
+/**
+ * Walk a parsed tree into facts. `nesting` guards the recursion through
+ * literal `bash -c` scripts (depth 3 is plenty; deeper is treated as unknown).
+ */
+export declare function analyzeShellTree(root: ShellSyntaxNode, nesting?: number): ShellFacts;
+/** Register the grammar-backed parser used for inner `bash -c` scripts. */
+export declare function setInnerShellParser(parse: ((source: string) => ParsedShellTree | undefined) | undefined): void;
+/** All commands, including those inside literal wrapper scripts, depth-first in execution order. */
+export declare function flattenShellCommands(facts: ShellFacts): ShellCommandFact[];
+/** True when every part of the analysis (including inner scripts) is complete. */
+export declare function shellFactsFullyComplete(facts: ShellFacts | undefined): facts is ShellFacts;
+/**
+ * Text that looks like PowerShell — tree-sitter-bash will often parse it
+ * WITHOUT errors into nonsense, so the loader refuses it up front and the
+ * PowerShell model in the engine keeps deciding alone.
+ */
+export declare function looksLikePowerShell(command: string): boolean;