gitx.do 0.0.2 → 0.1.0

package/dist/do/bash-ast.d.ts

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview Bash AST Parser and Safety Analyzer
+ *
+ * This module provides a bash command parser that produces an Abstract Syntax Tree (AST)
+ * for shell commands, along with safety analysis based on AST node inspection.
+ *
+ * The parser handles:
+ * - Simple commands (ls, cat, etc.)
+ * - Pipelines (cmd1 | cmd2)
+ * - Command lists (cmd1 && cmd2, cmd1 || cmd2, cmd1 ; cmd2)
+ * - Subshells ($(...) and `...`)
+ * - Redirections (>, >>, <, 2>&1)
+ * - Variable expansion ($VAR, ${VAR})
+ * - Quoting (single, double, and escape)
+ *
+ * @module do/bash-ast
+ *
+ * @example
+ * ```typescript
+ * import { parseBashCommand, analyzeASTSafety } from './bash-ast'
+ *
+ * const ast = parseBashCommand('rm -rf /')
+ * const safety = analyzeASTSafety(ast)
+ * if (safety.dangerous) {
+ *   console.log(`Command blocked: ${safety.reason}`)
+ * }
+ * ```
+ */
+/**
+ * Type of AST node.
+ */
+export type ASTNodeType = 'command' | 'pipeline' | 'list' | 'subshell' | 'function' | 'word' | 'redirect' | 'assignment';
+/**
+ * Operator types for command lists.
+ */
+export type ListOperator = '&&' | '||' | ';' | '&';
+/**
+ * Redirection type.
+ */
+export type RedirectType = '>' | '>>' | '<' | '2>' | '2>>' | '&>' | '>&' | '<<' | '<<<';
+/**
+ * Base AST node interface.
+ */
+export interface ASTNodeBase {
+    type: ASTNodeType;
+    raw: string;
+    start: number;
+    end: number;
+}
+/**
+ * Word node - represents a simple word or argument.
+ */
+export interface WordNode extends ASTNodeBase {
+    type: 'word';
+    value: string;
+    quoted: 'none' | 'single' | 'double' | 'escaped';
+    expandable: boolean;
+}
+/**
+ * Redirect node - represents I/O redirection.
+ */
+export interface RedirectNode extends ASTNodeBase {
+    type: 'redirect';
+    operator: RedirectType;
+    target: WordNode;
+    fd?: number;
+}
+/**
+ * Assignment node - represents variable assignment.
+ */
+export interface AssignmentNode extends ASTNodeBase {
+    type: 'assignment';
+    name: string;
+    value: WordNode;
+}
+/**
+ * Command node - represents a simple command.
+ */
+export interface CommandNode extends ASTNodeBase {
+    type: 'command';
+    name: WordNode;
+    args: WordNode[];
+    redirects: RedirectNode[];
+    assignments: AssignmentNode[];
+    background: boolean;
+}
+/**
+ * Pipeline node - represents a pipeline of commands.
+ */
+export interface PipelineNode extends ASTNodeBase {
+    type: 'pipeline';
+    commands: (CommandNode | SubshellNode)[];
+    negated: boolean;
+}
+/**
+ * List node - represents a list of pipelines.
+ */
+export interface ListNode extends ASTNodeBase {
+    type: 'list';
+    pipelines: PipelineNode[];
+    operators: ListOperator[];
+}
+/**
+ * Subshell node - represents a subshell.
+ */
+export interface SubshellNode extends ASTNodeBase {
+    type: 'subshell';
+    body: ListNode;
+    style: '$()' | '``' | '()';
+}
+/**
+ * Function definition node.
+ */
+export interface FunctionNode extends ASTNodeBase {
+    type: 'function';
+    name: string;
+    body: ListNode;
+}
+/**
+ * Union of all AST node types.
+ */
+export type ASTNode = WordNode | RedirectNode | AssignmentNode | CommandNode | PipelineNode | ListNode | SubshellNode | FunctionNode;
+/**
+ * Impact level of a command.
+ */
+export type ImpactLevel = 'none' | 'low' | 'medium' | 'high' | 'critical';
+/**
+ * Safety level classification for commands.
+ * - 'safe': Command can be executed without confirmation
+ * - 'dangerous': Command requires confirmation but can be executed with confirm flag
+ * - 'critical': Command is ALWAYS blocked regardless of confirmation (destructive/irreversible)
+ */
+export type SafetyLevel = 'safe' | 'dangerous' | 'critical';
+/**
+ * Safety classification result from AST analysis.
+ */
+export interface ASTSafetyAnalysis {
+    /**
+     * Whether the command is considered dangerous.
+     */
+    dangerous: boolean;
+    /**
+     * Safety classification level.
+     * - 'safe': Can execute without confirmation
+     * - 'dangerous': Requires confirmation (confirm flag allows execution)
+     * - 'critical': Always blocked, cannot be executed even with confirmation
+     */
+    safetyLevel: SafetyLevel;
+    /**
+     * Reason for the classification.
+     */
+    reason?: string;
+    /**
+     * All command names found in the AST.
+     */
+    commands: string[];
+    /**
+     * Impact level of the command.
+     */
+    impact: ImpactLevel;
+    /**
+     * Detailed issues found during analysis.
+     */
+    issues: SafetyIssue[];
+    /**
+     * The parsed AST (for debugging/inspection).
+     */
+    ast?: ASTNode;
+}
+/**
+ * A single safety issue found during analysis.
+ */
+export interface SafetyIssue {
+    /**
+     * Type of safety issue.
+     */
+    type: 'dangerous_command' | 'dangerous_pattern' | 'blocked_command' | 'privilege_escalation' | 'data_destruction' | 'network_exfil' | 'code_injection' | 'critical_pattern';
+    /**
+     * Description of the issue.
+     */
+    message: string;
+    /**
+     * Severity of the issue.
+     */
+    severity: ImpactLevel;
+    /**
+     * Whether this issue represents a critical command that cannot be executed even with confirmation.
+     * When true, the command will be blocked regardless of the confirm flag.
+     */
+    critical?: boolean;
+    /**
+     * Location in the original command.
+     */
+    start?: number;
+    end?: number;
+}
+/**
+ * Parse a bash command string into an AST.
+ *
+ * @param input - The bash command string to parse
+ * @returns The parsed AST (ListNode at the top level)
+ *
+ * @example
+ * ```typescript
+ * const ast = parseBashCommand('ls -la | grep foo && echo done')
+ * // Returns a ListNode with two pipelines
+ * ```
+ */
+export declare function parseBashCommand(input: string): ListNode;
+/**
+ * Analyze a bash command AST for safety.
+ *
+ * @param ast - The parsed AST to analyze
+ * @param blockedCommands - Set of commands that are blocked
+ * @param originalInput - Original input string for pattern matching
+ * @returns Safety analysis result
+ *
+ * @example
+ * ```typescript
+ * const ast = parseBashCommand('rm -rf /')
+ * const safety = analyzeASTSafety(ast)
+ * if (safety.dangerous) {
+ *   console.log(`Blocked: ${safety.reason}`)
+ * }
+ * ```
+ */
+export declare function analyzeASTSafety(ast: ListNode, blockedCommands?: Set<string>, originalInput?: string): ASTSafetyAnalysis;
+/**
+ * Parse and analyze a bash command string for safety.
+ *
+ * This is a convenience function that combines parsing and analysis.
+ *
+ * @param input - The bash command string to analyze
+ * @param blockedCommands - Set of commands that are blocked
+ * @returns Safety analysis result
+ *
+ * @example
+ * ```typescript
+ * const result = parseAndAnalyze('rm -rf /')
+ * if (result.dangerous) {
+ *   console.log(`Command blocked: ${result.reason}`)
+ * }
+ * ```
+ */
+export declare function parseAndAnalyze(input: string, blockedCommands?: Set<string>): ASTSafetyAnalysis;
+//# sourceMappingURL=bash-ast.d.ts.map

package/dist/do/bash-ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bash-ast.d.ts","sourceRoot":"","sources":["../../src/do/bash-ast.ts"],"names":[],"mappings":"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"}