@eslint/shell 0.0.0-stage → 0.1.2

package/dist/parser/parse.js

@@ -0,0 +1,758 @@
+/**
+ * @fileoverview Parses shell source code into an ESTree-style syntax tree by
+ * wrapping the mvdan-sh parser (a GopherJS build of mvdan.cc/sh) and
+ * translating its tree. See docs/syntax-tree.md for the tree format.
+ * @author Claude Opus 5.5
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import mvdan from "mvdan-sh";
+const { syntax } = mvdan;
+const REDIRECT_OPERATOR = /^(?:&>>|&>|>\||>>|>&|<<<|<<-|<<|<&|<>|<|>)/u;
+const UNARY_ARITHMETIC_OPERATOR = /^(?:\+\+|--|[-+!~])/u;
+const PROCESS_SUBSTITUTION_OPERATOR = /^[<>]\(/u;
+const EXTENDED_GLOB_OPERATOR = /^[?*+@!]\(/u;
+const BINARY_COMMAND_OPERATOR = /^(?:\|&|\|\||&&|\|)/u;
+const CASE_TERMINATOR = /^(?:;;&|;;|;&|;\|)/u;
+const LEADING_TRIVIA = /^(?:\s|#.*)*/u;
+// eslint-disable-next-line no-control-regex -- intentionally matches the full ASCII range.
+const NON_ASCII = /[^\x00-\x7f]/u;
+const VARIANTS = new Map([
+    ["bash", syntax.LangBash],
+    ["posix", syntax.LangPOSIX],
+    ["mksh", syntax.LangMirBSDKorn],
+]);
+/**
+ * The error thrown when shell source code cannot be parsed.
+ */
+export class ShellSyntaxError extends SyntaxError {
+    line;
+    column;
+    /** The file path passed to the parser, when there was one. */
+    path;
+    constructor(message, line, column, path) {
+        super(message);
+        this.name = "ShellSyntaxError";
+        this.line = line;
+        this.column = column;
+        this.path = path;
+    }
+}
+/**
+ * Creates a converter from mvdan-sh byte offsets to JavaScript character
+ * offsets. mvdan-sh reports positions as UTF-8 byte offsets, which only
+ * match string indexes for ASCII-only sources.
+ */
+function createByteToCharConverter(text) {
+    if (!NON_ASCII.test(text)) {
+        return byte => byte;
+    }
+    const map = [];
+    let charIndex = 0;
+    for (const char of text) {
+        const codePoint = char.codePointAt(0);
+        const byteLength = codePoint <= 0x7f
+            ? 1
+            : codePoint <= 0x7ff
+                ? 2
+                : codePoint <= 0xffff
+                    ? 3
+                    : 4;
+        for (let i = 0; i < byteLength; i++) {
+            map.push(charIndex);
+        }
+        charIndex += char.length;
+    }
+    map.push(charIndex);
+    return byte => map[Math.min(byte, map.length - 1)];
+}
+/**
+ * Computes a 1-based line and column pair for a character offset.
+ */
+function locate(text, offset) {
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < offset && i < text.length; i++) {
+        if (text[i] === "\n") {
+            line++;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: offset - lineStart + 1 };
+}
+//------------------------------------------------------------------------------
+// Translator
+//------------------------------------------------------------------------------
+/**
+ * Translates an mvdan-sh syntax tree into the ESTree-style tree documented
+ * in docs/syntax-tree.md.
+ */
+class Translator {
+    #text;
+    #toChar;
+    constructor(text) {
+        this.#text = text;
+        this.#toChar = createByteToCharConverter(text);
+    }
+    #start(node) {
+        return this.#toChar(node.Pos().Offset());
+    }
+    #end(node) {
+        return this.#toChar(node.End().Offset());
+    }
+    /**
+     * Extracts the operator token that appears between two child nodes,
+     * e.g. the `&&` in `a && b`. Skips surrounding whitespace and any
+     * comments on either side of the operator.
+     */
+    #operatorBetween(left, right) {
+        const slice = this.#text
+            .slice(this.#end(left), this.#start(right))
+            .replace(LEADING_TRIVIA, "");
+        return slice.split(/\s+/u)[0];
+    }
+    /**
+     * Reads the operator of a `BinaryCmd` at its recorded position.
+     *
+     * This cannot slice between the two operands the way
+     * `#operatorBetween()` does: a heredoc body extends the left operand's
+     * end past the operator, so the slice comes out empty. See the heredoc
+     * section of `docs/syntax-tree.md`.
+     */
+    #binaryCommandOperator(binary) {
+        const opPos = binary.OpPos;
+        return (this.#operatorAt(this.#toChar(opPos.Offset()), BINARY_COMMAND_OPERATOR) ?? "||");
+    }
+    /**
+     * Matches an operator pattern at a character offset.
+     */
+    #operatorAt(offset, pattern) {
+        const match = pattern.exec(this.#text.slice(offset, offset + 3));
+        return match ? match[0] : null;
+    }
+    translateProgram(file) {
+        return {
+            type: "Program",
+            start: 0,
+            end: this.#text.length,
+            body: file.Stmts.map(stmt => this.translateStatement(stmt)),
+            comments: this.collectComments(file),
+        };
+    }
+    collectComments(file) {
+        const comments = [];
+        syntax.Walk(file, node => {
+            if (node && syntax.NodeType(node) === "Comment") {
+                comments.push({
+                    type: "Comment",
+                    start: this.#start(node),
+                    end: this.#end(node),
+                    text: node.Text,
+                });
+            }
+            return true;
+        });
+        comments.sort((a, b) => a.start - b.start);
+        return comments;
+    }
+    /**
+     * Translates an mvdan `Stmt`, folding its statement-level properties
+     * (redirects, negation, background) into the command node.
+     */
+    translateStatement(stmt) {
+        const node = this.#translateCommand(stmt.Cmd);
+        node.start = this.#start(stmt);
+        node.end = this.#end(stmt);
+        node.redirects = (stmt.Redirs ?? []).map(redirect => this.translateRedirect(redirect));
+        node.negated = Boolean(stmt.Negated);
+        node.background = Boolean(stmt.Background);
+        return node;
+    }
+    #statementBase(node) {
+        return {
+            start: node ? this.#start(node) : 0,
+            end: node ? this.#end(node) : 0,
+            redirects: [],
+            negated: false,
+            background: false,
+        };
+    }
+    #translateCommand(cmd) {
+        const nodeType = cmd === null ? "nil" : syntax.NodeType(cmd);
+        switch (nodeType) {
+            case "nil":
+                // A statement with only redirects, such as `> file`.
+                return {
+                    type: "Command",
+                    ...this.#statementBase(null),
+                    assignments: [],
+                    name: null,
+                    arguments: [],
+                };
+            case "CallExpr": {
+                const call = cmd;
+                const args = call.Args.map(word => this.translateWord(word));
+                return {
+                    type: "Command",
+                    ...this.#statementBase(call),
+                    assignments: call.Assigns.map(assign => this.translateAssignment(assign)),
+                    name: args[0] ?? null,
+                    arguments: args.slice(1),
+                };
+            }
+            case "BinaryCmd": {
+                const binary = cmd;
+                const operator = this.#binaryCommandOperator(binary);
+                if (operator === "|" || operator === "|&") {
+                    return this.#translatePipeline(binary);
+                }
+                return {
+                    type: "LogicalExpression",
+                    ...this.#statementBase(binary),
+                    operator: operator === "&&" ? "&&" : "||",
+                    left: this.translateStatement(binary.X),
+                    right: this.translateStatement(binary.Y),
+                };
+            }
+            case "IfClause":
+                return this.#translateIfClause(cmd);
+            case "WhileClause": {
+                const clause = cmd;
+                const base = this.#statementBase(clause);
+                const test = clause.Cond.map(stmt => this.translateStatement(stmt));
+                const body = clause.Do.map(stmt => this.translateStatement(stmt));
+                return clause.Until
+                    ? { type: "UntilStatement", ...base, test, body }
+                    : { type: "WhileStatement", ...base, test, body };
+            }
+            case "ForClause": {
+                const clause = cmd;
+                const base = this.#statementBase(clause);
+                const body = clause.Do.map(stmt => this.translateStatement(stmt));
+                const loop = clause.Loop;
+                if (syntax.NodeType(loop) === "CStyleLoop") {
+                    return {
+                        type: "ArithmeticForStatement",
+                        ...base,
+                        init: loop.Init
+                            ? this.translateArithmetic(loop.Init)
+                            : null,
+                        test: loop.Cond
+                            ? this.translateArithmetic(loop.Cond)
+                            : null,
+                        update: loop.Post
+                            ? this.translateArithmetic(loop.Post)
+                            : null,
+                        body,
+                    };
+                }
+                return {
+                    type: "ForStatement",
+                    ...base,
+                    variable: loop.Name
+                        ? this.#translateIdentifier(loop.Name)
+                        : null,
+                    words: (loop.Items ?? []).map(word => this.translateWord(word)),
+                    body,
+                    select: Boolean(clause.Select),
+                };
+            }
+            case "CaseClause": {
+                const clause = cmd;
+                return {
+                    type: "CaseStatement",
+                    ...this.#statementBase(clause),
+                    discriminant: this.translateWord(clause.Word),
+                    cases: clause.Items.map(item => this.#translateCaseItem(item)),
+                };
+            }
+            case "Block":
+                return {
+                    type: "BlockStatement",
+                    ...this.#statementBase(cmd),
+                    body: cmd.Stmts.map(stmt => this.translateStatement(stmt)),
+                };
+            case "Subshell":
+                return {
+                    type: "Subshell",
+                    ...this.#statementBase(cmd),
+                    body: cmd.Stmts.map(stmt => this.translateStatement(stmt)),
+                };
+            case "FuncDecl": {
+                const decl = cmd;
+                return {
+                    type: "FunctionDeclaration",
+                    ...this.#statementBase(decl),
+                    id: this.#translateIdentifier(decl.Name),
+                    body: this.translateStatement(decl.Body),
+                };
+            }
+            case "TestClause":
+                return {
+                    type: "TestCommand",
+                    ...this.#statementBase(cmd),
+                    expression: this.translateTest(cmd.X),
+                };
+            case "ArithmCmd": {
+                const arith = cmd;
+                return {
+                    type: "ArithmeticCommand",
+                    ...this.#statementBase(arith),
+                    expression: arith.X
+                        ? this.translateArithmetic(arith.X)
+                        : null,
+                };
+            }
+            case "DeclClause": {
+                const decl = cmd;
+                return {
+                    type: "DeclarationCommand",
+                    ...this.#statementBase(decl),
+                    kind: decl.Variant.Value,
+                    arguments: decl.Args.map(assign => this.#translateDeclarationArgument(assign)),
+                };
+            }
+            case "TimeClause": {
+                const clause = cmd;
+                return {
+                    type: "TimeCommand",
+                    ...this.#statementBase(clause),
+                    posix: Boolean(clause.PosixFormat),
+                    body: clause.Stmt
+                        ? this.translateStatement(clause.Stmt)
+                        : null,
+                };
+            }
+            case "CoprocClause": {
+                const clause = cmd;
+                return {
+                    type: "CoprocCommand",
+                    ...this.#statementBase(clause),
+                    name: clause.Name
+                        ? this.translateWord(clause.Name)
+                        : null,
+                    body: clause.Stmt
+                        ? this.translateStatement(clause.Stmt)
+                        : null,
+                };
+            }
+            case "LetClause":
+                return {
+                    type: "LetCommand",
+                    ...this.#statementBase(cmd),
+                    expressions: cmd.Exprs.map(expr => this.translateArithmetic(expr)),
+                };
+            default:
+                throw new Error(`Unsupported mvdan-sh node type: ${nodeType}.`);
+        }
+    }
+    #translatePipeline(binary) {
+        const commands = [];
+        const operators = [];
+        const collect = (stmt) => {
+            const inner = stmt.Cmd;
+            const isBare = !stmt.Negated &&
+                !stmt.Background &&
+                (stmt.Redirs ?? []).length === 0;
+            if (inner !== null &&
+                isBare &&
+                syntax.NodeType(inner) === "BinaryCmd") {
+                const operator = this.#binaryCommandOperator(inner);
+                if (operator === "|" || operator === "|&") {
+                    collect(inner.X);
+                    operators.push(operator);
+                    commands.push(this.translateStatement(inner.Y));
+                    return;
+                }
+            }
+            commands.push(this.translateStatement(stmt));
+        };
+        const operator = this.#binaryCommandOperator(binary);
+        collect(binary.X);
+        operators.push(operator);
+        commands.push(this.translateStatement(binary.Y));
+        return {
+            type: "Pipeline",
+            ...this.#statementBase(binary),
+            commands,
+            operators,
+        };
+    }
+    #translateIfClause(clause) {
+        let alternate = null;
+        const elseClause = clause.Else;
+        if (elseClause) {
+            if (elseClause.Cond.length > 0) {
+                alternate = this.#translateIfClause(elseClause);
+            }
+            else {
+                alternate = {
+                    type: "ElseClause",
+                    start: this.#start(elseClause),
+                    end: this.#end(elseClause),
+                    body: elseClause.Then.map(stmt => this.translateStatement(stmt)),
+                };
+            }
+        }
+        return {
+            type: "IfStatement",
+            ...this.#statementBase(clause),
+            test: clause.Cond.map(stmt => this.translateStatement(stmt)),
+            consequent: clause.Then.map(stmt => this.translateStatement(stmt)),
+            alternate,
+        };
+    }
+    #translateCaseItem(item) {
+        const opPos = item.OpPos;
+        const hasTerminator = opPos.Line() !== 0;
+        return {
+            type: "CaseClause",
+            start: this.#start(item),
+            end: this.#end(item),
+            patterns: item.Patterns.map(word => this.translateWord(word)),
+            body: item.Stmts.map(stmt => this.translateStatement(stmt)),
+            terminator: hasTerminator
+                ? this.#operatorAt(this.#toChar(opPos.Offset()), CASE_TERMINATOR)
+                : null,
+        };
+    }
+    #translateIdentifier(lit) {
+        return {
+            type: "Identifier",
+            start: this.#start(lit),
+            end: this.#end(lit),
+            name: lit.Value,
+        };
+    }
+    translateAssignment(assign) {
+        return {
+            type: "VariableAssignment",
+            start: this.#start(assign),
+            end: this.#end(assign),
+            name: assign.Name
+                ? this.#translateIdentifier(assign.Name)
+                : null,
+            index: assign.Index
+                ? this.translateArithmetic(assign.Index)
+                : null,
+            value: assign.Value
+                ? this.translateWord(assign.Value)
+                : null,
+            array: assign.Array
+                ? this.#translateArray(assign.Array)
+                : null,
+            append: Boolean(assign.Append),
+        };
+    }
+    /**
+     * Declaration command arguments are all `Assign` nodes in mvdan-sh;
+     * plain words such as flags (`-x`) become nameless naked assigns.
+     */
+    #translateDeclarationArgument(assign) {
+        if (!assign.Name && assign.Naked && assign.Value) {
+            return this.translateWord(assign.Value);
+        }
+        return this.translateAssignment(assign);
+    }
+    #translateArray(array) {
+        return {
+            type: "ArrayExpression",
+            start: this.#start(array),
+            end: this.#end(array),
+            elements: array.Elems.map((element) => ({
+                type: "ArrayElement",
+                start: this.#start(element),
+                end: this.#end(element),
+                index: element.Index
+                    ? this.translateArithmetic(element.Index)
+                    : null,
+                value: element.Value
+                    ? this.translateWord(element.Value)
+                    : null,
+            })),
+        };
+    }
+    translateRedirect(redirect) {
+        const opPos = redirect.OpPos;
+        const opStart = this.#toChar(opPos.Offset());
+        const operator = this.#operatorAt(opStart, REDIRECT_OPERATOR) ?? ">";
+        const fdLit = redirect.N;
+        const target = redirect.Word;
+        return {
+            type: "Redirect",
+            start: fdLit ? this.#start(fdLit) : opStart,
+            end: target ? this.#end(target) : opStart + operator.length,
+            operator,
+            fd: fdLit ? Number.parseInt(fdLit.Value, 10) : null,
+            target: target ? this.translateWord(target) : null,
+            heredoc: redirect.Hdoc
+                ? this.translateWord(redirect.Hdoc)
+                : null,
+        };
+    }
+    translateWord(word) {
+        return {
+            type: "Word",
+            start: this.#start(word),
+            end: this.#end(word),
+            parts: word.Parts.map(part => this.translateWordPart(part)),
+        };
+    }
+    translateWordPart(part) {
+        const nodeType = syntax.NodeType(part);
+        const start = this.#start(part);
+        const end = this.#end(part);
+        switch (nodeType) {
+            case "Lit":
+                return {
+                    type: "Literal",
+                    start,
+                    end,
+                    value: part.Value,
+                };
+            case "SglQuoted":
+                return {
+                    type: "SingleQuotedString",
+                    start,
+                    end,
+                    value: part.Value,
+                    dollar: Boolean(part.Dollar),
+                };
+            case "DblQuoted":
+                return {
+                    type: "DoubleQuotedString",
+                    start,
+                    end,
+                    parts: part.Parts.map(inner => this.translateWordPart(inner)),
+                    dollar: Boolean(part.Dollar),
+                };
+            case "ParamExp":
+                return this.#translateParameterExpansion(part);
+            case "CmdSubst":
+                return {
+                    type: "CommandSubstitution",
+                    start,
+                    end,
+                    body: part.Stmts.map(stmt => this.translateStatement(stmt)),
+                    backquotes: this.#text[start] === "`",
+                };
+            case "ProcSubst":
+                return {
+                    type: "ProcessSubstitution",
+                    start,
+                    end,
+                    operator: this.#operatorAt(start, PROCESS_SUBSTITUTION_OPERATOR) ?? "<(",
+                    body: part.Stmts.map(stmt => this.translateStatement(stmt)),
+                };
+            case "ArithmExp":
+                return {
+                    type: "ArithmeticExpansion",
+                    start,
+                    end,
+                    expression: part.X
+                        ? this.translateArithmetic(part.X)
+                        : null,
+                };
+            case "ExtGlob":
+                return {
+                    type: "ExtendedGlob",
+                    start,
+                    end,
+                    operator: this.#operatorAt(start, EXTENDED_GLOB_OPERATOR) ?? "@(",
+                    pattern: (part.Pattern?.Value ??
+                        ""),
+                };
+            default:
+                // Unknown word parts (e.g. BraceExp when enabled) degrade to
+                // literals covering their source text.
+                return {
+                    type: "Literal",
+                    start,
+                    end,
+                    value: this.#text.slice(start, end),
+                };
+        }
+    }
+    #translateParameterExpansion(part) {
+        const start = this.#start(part);
+        const end = this.#end(part);
+        const param = part.Param;
+        const index = part.Index
+            ? this.translateArithmetic(part.Index)
+            : null;
+        let operator = null;
+        let word = null;
+        let replacement = null;
+        let sliceOffset = null;
+        let sliceLength = null;
+        // Character offset where an operator would begin: after the
+        // parameter name, or after the `]` that closes a subscript.
+        let operatorStart = this.#end(param);
+        if (index) {
+            const bracket = this.#text.indexOf("]", index.end);
+            operatorStart = bracket === -1 ? index.end : bracket + 1;
+        }
+        const rbrace = part.Rbrace
+            ? this.#toChar(part.Rbrace.Offset())
+            : end;
+        if (part.Slice) {
+            const slice = part.Slice;
+            operator = ":";
+            sliceOffset = slice.Offset
+                ? this.translateArithmetic(slice.Offset)
+                : null;
+            sliceLength = slice.Length
+                ? this.translateArithmetic(slice.Length)
+                : null;
+        }
+        else if (part.Repl) {
+            const repl = part.Repl;
+            const orig = repl.Orig;
+            const origWord = orig && orig.Parts.length > 0
+                ? this.translateWord(orig)
+                : null;
+            operator = origWord
+                ? this.#text.slice(operatorStart, origWord.start).trim()
+                : repl.All
+                    ? "//"
+                    : "/";
+            word = origWord;
+            replacement =
+                repl.With &&
+                    repl.With.Parts.length > 0
+                    ? this.translateWord(repl.With)
+                    : null;
+        }
+        else if (part.Exp) {
+            const expansion = part.Exp;
+            const expansionWord = expansion.Word;
+            word = expansionWord ? this.translateWord(expansionWord) : null;
+            operator = this.#text
+                .slice(operatorStart, word ? word.start : rbrace)
+                .trim();
+        }
+        else if (part.Names !== 0) {
+            operator = this.#text.slice(operatorStart, rbrace).trim();
+        }
+        return {
+            type: "ParameterExpansion",
+            start,
+            end,
+            name: param.Value,
+            braced: !part.Short,
+            indirect: Boolean(part.Excl),
+            lengthOf: Boolean(part.Length),
+            index,
+            operator: operator || null,
+            word,
+            replacement,
+            sliceOffset,
+            sliceLength,
+        };
+    }
+    translateArithmetic(expr) {
+        const nodeType = syntax.NodeType(expr);
+        const start = this.#start(expr);
+        const end = this.#end(expr);
+        switch (nodeType) {
+            case "BinaryArithm":
+                return {
+                    type: "BinaryArithmetic",
+                    start,
+                    end,
+                    operator: this.#operatorBetween(expr.X, expr.Y),
+                    left: this.translateArithmetic(expr.X),
+                    right: this.translateArithmetic(expr.Y),
+                };
+            case "UnaryArithm": {
+                const opPos = expr.OpPos;
+                return {
+                    type: "UnaryArithmetic",
+                    start,
+                    end,
+                    operator: this.#operatorAt(this.#toChar(opPos.Offset()), UNARY_ARITHMETIC_OPERATOR) ?? "+",
+                    prefix: !expr.Post,
+                    argument: this.translateArithmetic(expr.X),
+                };
+            }
+            case "ParenArithm":
+                return {
+                    type: "ParenthesizedArithmetic",
+                    start,
+                    end,
+                    expression: this.translateArithmetic(expr.X),
+                };
+            default:
+                return this.translateWord(expr);
+        }
+    }
+    translateTest(expr) {
+        const nodeType = syntax.NodeType(expr);
+        const start = this.#start(expr);
+        const end = this.#end(expr);
+        switch (nodeType) {
+            case "BinaryTest":
+                return {
+                    type: "BinaryTest",
+                    start,
+                    end,
+                    operator: this.#operatorBetween(expr.X, expr.Y),
+                    left: this.translateTest(expr.X),
+                    right: this.translateTest(expr.Y),
+                };
+            case "UnaryTest": {
+                const opPos = expr.OpPos;
+                const opStart = this.#toChar(opPos.Offset());
+                const match = /^\S+/u.exec(this.#text.slice(opStart));
+                return {
+                    type: "UnaryTest",
+                    start,
+                    end,
+                    operator: match ? match[0] : "!",
+                    argument: this.translateTest(expr.X),
+                };
+            }
+            case "ParenTest":
+                return {
+                    type: "ParenthesizedTest",
+                    start,
+                    end,
+                    expression: this.translateTest(expr.X),
+                };
+            default:
+                return this.translateWord(expr);
+        }
+    }
+}
+//------------------------------------------------------------------------------
+// Public API
+//------------------------------------------------------------------------------
+/**
+ * Parses shell source code into an ESTree-style syntax tree.
+ * @throws {ShellSyntaxError} When the source code contains a syntax error.
+ */
+export function parseShell(text, options = {}) {
+    const variant = VARIANTS.get(options.variant ?? "bash");
+    if (variant === undefined) {
+        throw new TypeError(`Unknown shell variant "${options.variant}". Expected "bash", "posix", or "mksh".`);
+    }
+    const parser = syntax.NewParser(syntax.KeepComments(true), syntax.Variant(variant));
+    let file;
+    try {
+        file = parser.Parse(text, options.path ?? "<input>");
+    }
+    catch (error) {
+        const parseError = error;
+        if (typeof parseError?.Error === "function") {
+            const byteOffset = parseError.Pos?.Offset() ?? 0;
+            const offset = createByteToCharConverter(text)(byteOffset);
+            const { line, column } = locate(text, offset);
+            throw new ShellSyntaxError(parseError.Text || parseError.Error(), line, column, options.path);
+        }
+        throw error;
+    }
+    const translator = new Translator(text);
+    const ast = translator.translateProgram(file);
+    return { ast, comments: ast.comments };
+}