@eslint/shell 0.0.0-stage → 0.1.0

package/dist/rules/no-backticks.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to disallow legacy backtick command substitution.
+ * Mirrors ShellCheck SC2006.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "useDollarParen";
+}>;
+export default rule;

package/dist/rules/no-backticks.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Rule to disallow legacy backtick command substitution.
+ * Mirrors ShellCheck SC2006.
+ */
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Disallow legacy backtick command substitution in favor of `$(...)`",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-backticks.md",
+        },
+        fixable: "code",
+        schema: [],
+        messages: {
+            useDollarParen: "Use $(...) notation instead of legacy backticks. (ShellCheck SC2006)",
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        return {
+            CommandSubstitution(node) {
+                if (!node.backquotes) {
+                    return;
+                }
+                const [start, end] = sourceCode.getRange(node);
+                const inner = sourceCode.text.slice(start + 1, end - 1);
+                context.report({
+                    node,
+                    messageId: "useDollarParen",
+                    // Escapes behave differently inside backticks, so only
+                    // fix substitutions without backslashes or nesting.
+                    fix: /[\\`]/u.test(inner)
+                        ? undefined
+                        : fixer => [
+                            fixer.replaceTextRange([start, start + 1], "$("),
+                            fixer.replaceTextRange([end - 1, end], ")"),
+                        ],
+                });
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-expansions-in-single-quotes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to flag expansion-like text inside single quotes.
+ * Mirrors ShellCheck SC2016.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "expansionInSingleQuotes";
+}>;
+export default rule;

package/dist/rules/no-expansions-in-single-quotes.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Rule to flag expansion-like text inside single quotes.
+ * Mirrors ShellCheck SC2016.
+ */
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+/**
+ * Matches text that looks like an intended expansion: `$name`, `${...}`,
+ * `$(...)`, or backticks. Positional-style references such as `$1` are
+ * excluded because they are common in awk/sed programs.
+ */
+const EXPANSION_LIKE = /\$[A-Za-z_{(]|`[^`]+`/u;
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Disallow expansion-like syntax inside single quotes, where it is not expanded",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-expansions-in-single-quotes.md",
+        },
+        schema: [],
+        messages: {
+            expansionInSingleQuotes: "Expressions don't expand in single quotes; use double quotes for that. (ShellCheck SC2016)",
+        },
+    },
+    create(context) {
+        return {
+            SingleQuotedString(node) {
+                if (!node.dollar && EXPANSION_LIKE.test(node.value)) {
+                    context.report({
+                        node,
+                        messageId: "expansionInSingleQuotes",
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-ls-iteration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to disallow iterating over `ls` output.
+ * Mirrors ShellCheck SC2045.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "lsIteration";
+}>;
+export default rule;

package/dist/rules/no-ls-iteration.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Rule to disallow iterating over `ls` output.
+ * Mirrors ShellCheck SC2045.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { startsWithCommand } from "./utils.js";
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow iterating over `ls` output, which breaks on special characters",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-ls-iteration.md",
+        },
+        schema: [],
+        messages: {
+            lsIteration: "Iterating over ls output is fragile. Use globs (e.g. *) instead. (ShellCheck SC2045)",
+        },
+    },
+    create(context) {
+        return {
+            ForStatement(node) {
+                for (const word of node.words) {
+                    for (const part of word.parts) {
+                        if (part.type === "CommandSubstitution" &&
+                            startsWithCommand(part.body, "ls")) {
+                            context.report({
+                                node: part,
+                                messageId: "lsIteration",
+                            });
+                        }
+                    }
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-unquoted-expansions.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to require quoting expansions that undergo word
+ * splitting and globbing. Mirrors ShellCheck SC2086/SC2046.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "unquotedParameterExpansion" | "unquotedCommandSubstitution";
+}>;
+export default rule;

package/dist/rules/no-unquoted-expansions.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Rule to require quoting expansions that undergo word
+ * splitting and globbing. Mirrors ShellCheck SC2086/SC2046.
+ */
+import { startsWithCommand } from "./utils.js";
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+/**
+ * Parameters that always expand to values that cannot split, so quoting is
+ * unnecessary.
+ */
+const SAFE_PARAMETERS = new Set(["?", "$", "!", "#", "-"]);
+/** Heredoc-style redirect operators whose targets never word-split. */
+const NON_SPLITTING_REDIRECTS = new Set(["<<", "<<-", "<<<"]);
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require quoting parameter expansions and command substitutions that are subject to word splitting",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-unquoted-expansions.md",
+        },
+        fixable: "code",
+        schema: [],
+        messages: {
+            unquotedParameterExpansion: 'Double quote "{{expansion}}" to prevent word splitting and globbing. (ShellCheck SC2086)',
+            unquotedCommandSubstitution: "Quote this command substitution to prevent word splitting. (ShellCheck SC2046)",
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        function checkWord(word, isForWord = false) {
+            for (const part of word.parts) {
+                if (part.type !== "ParameterExpansion" &&
+                    part.type !== "CommandSubstitution") {
+                    continue;
+                }
+                if (part.type === "ParameterExpansion") {
+                    if (part.lengthOf || SAFE_PARAMETERS.has(part.name)) {
+                        continue;
+                    }
+                }
+                // Only offer a fix when the expansion is the entire word.
+                const isWholeWord = word.parts.length === 1 &&
+                    word.start === part.start &&
+                    word.end === part.end;
+                const isLsIteration = isForWord &&
+                    part.type === "CommandSubstitution" &&
+                    startsWithCommand(part.body, "ls");
+                context.report({
+                    node: part,
+                    messageId: part.type === "ParameterExpansion"
+                        ? "unquotedParameterExpansion"
+                        : "unquotedCommandSubstitution",
+                    data: part.type === "ParameterExpansion"
+                        ? { expansion: sourceCode.getText(part) }
+                        : {},
+                    fix: isWholeWord && !isLsIteration
+                        ? fixer => fixer.replaceText(word, `"${sourceCode.getText(word)}"`)
+                        : undefined,
+                });
+            }
+        }
+        return {
+            Command(node) {
+                if (node.name) {
+                    checkWord(node.name);
+                }
+                for (const argument of node.arguments) {
+                    checkWord(argument);
+                }
+            },
+            ForStatement(node) {
+                for (const word of node.words) {
+                    checkWord(word, true);
+                }
+            },
+            Redirect(node) {
+                if (node.target &&
+                    !NON_SPLITTING_REDIRECTS.has(node.operator)) {
+                    checkWord(node.target);
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-unused-vars.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @fileoverview Rule to flag variables that are assigned but never used.
+ * Mirrors ShellCheck SC2034.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "unusedVariable";
+    RuleOptions: [{
+        allowed?: string[];
+    }?];
+}>;
+export default rule;

package/dist/rules/no-unused-vars.js

@@ -0,0 +1,383 @@
+/**
+ * @fileoverview Rule to flag variables that are assigned but never used.
+ * Mirrors ShellCheck SC2034.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { getCommandName, getStaticText } from "./utils.js";
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+/** Variables that are meaningful to the shell or to common external tools. */
+const SPECIAL_VARIABLES = new Set([
+    "BASH_ENV",
+    "CDPATH",
+    "EDITOR",
+    "ENV",
+    "GLOBIGNORE",
+    "HISTCONTROL",
+    "HISTFILE",
+    "HISTFILESIZE",
+    "HISTSIZE",
+    "HOME",
+    "IFS",
+    "LANG",
+    "LD_LIBRARY_PATH",
+    "OPTARG",
+    "OPTERR",
+    "OPTIND",
+    "PAGER",
+    "PATH",
+    "PROMPT_COMMAND",
+    "PS1",
+    "PS2",
+    "PS3",
+    "PS4",
+    "REPLY",
+    "TERM",
+    "TMOUT",
+    "TZ",
+    "VISUAL",
+]);
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*/u;
+/** `read` flags that consume the following word as their argument. */
+const READ_FLAGS_WITH_ARGUMENT = /^-[a-zA-Z]*[dinNptu]$/u;
+/** `mapfile`/`readarray` flags that consume the following word. */
+const MAPFILE_FLAGS_WITH_ARGUMENT = /^-[a-zA-Z]*[cCdnOsu]$/u;
+/** Test operators whose operands are evaluated arithmetically. */
+const ARITHMETIC_TEST_OPERATORS = new Set([
+    "-eq",
+    "-ne",
+    "-lt",
+    "-le",
+    "-gt",
+    "-ge",
+]);
+/** Arithmetic operators that assign to their left operand. */
+const ARITHMETIC_ASSIGNMENT = /^(?:=|\+=|-=|\*=|\/=|%=|<<=|>>=|&=|\^=|\|=)$/u;
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow variables that are assigned but never used",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-unused-vars.md",
+        },
+        schema: [
+            {
+                type: "object",
+                properties: {
+                    allowed: {
+                        type: "array",
+                        items: { type: "string" },
+                    },
+                },
+                additionalProperties: false,
+            },
+        ],
+        defaultOptions: [{}],
+        messages: {
+            unusedVariable: "Variable '{{name}}' is assigned but never used. (ShellCheck SC2034)",
+        },
+    },
+    create(context) {
+        const [{ allowed = [] } = {}] = context.options;
+        const allowedNames = new Set(allowed);
+        const writes = new Map();
+        const reads = new Set();
+        // Set when the file uses constructs that can reference variables
+        // dynamically (eval, source), making usage analysis unreliable.
+        let unsafe = false;
+        function addWrite(name, node) {
+            if (!writes.has(name)) {
+                writes.set(name, node);
+            }
+        }
+        function addReadableIdentifier(word) {
+            const text = getStaticText(word);
+            const match = text === null ? null : IDENTIFIER.exec(text);
+            if (match) {
+                reads.add(match[0]);
+            }
+        }
+        /**
+         * Records reads/writes for bare identifiers inside arithmetic
+         * expressions, where `x` references the variable without `$`.
+         */
+        function scanArithmetic(expression, isWrite) {
+            switch (expression.type) {
+                case "Word": {
+                    const text = getStaticText(expression);
+                    const match = text === null ? null : IDENTIFIER.exec(text);
+                    if (match && match[0] === text) {
+                        if (isWrite) {
+                            const identifier = {
+                                type: "Identifier",
+                                start: expression.start,
+                                end: expression.end,
+                                name: text,
+                            };
+                            addWrite(text, identifier);
+                        }
+                        else {
+                            reads.add(match[0]);
+                        }
+                    }
+                    break;
+                }
+                case "BinaryArithmetic":
+                    if (ARITHMETIC_ASSIGNMENT.test(expression.operator)) {
+                        scanArithmetic(expression.left, true);
+                        // Compound assignments also read the variable.
+                        if (expression.operator !== "=") {
+                            scanArithmetic(expression.left, false);
+                        }
+                    }
+                    else {
+                        scanArithmetic(expression.left, false);
+                    }
+                    scanArithmetic(expression.right, false);
+                    break;
+                case "UnaryArithmetic":
+                    if (expression.operator === "++" ||
+                        expression.operator === "--") {
+                        scanArithmetic(expression.argument, true);
+                    }
+                    scanArithmetic(expression.argument, false);
+                    break;
+                case "ParenthesizedArithmetic":
+                    scanArithmetic(expression.expression, false);
+                    break;
+                // no default
+            }
+        }
+        /**
+         * Records reads for bare identifiers used as operands of arithmetic
+         * comparisons in `[[ ... ]]`, such as `[[ x -gt 0 ]]`.
+         */
+        function scanTest(expression) {
+            switch (expression.type) {
+                case "BinaryTest":
+                    if (ARITHMETIC_TEST_OPERATORS.has(expression.operator)) {
+                        for (const operand of [
+                            expression.left,
+                            expression.right,
+                        ]) {
+                            if (operand.type === "Word") {
+                                scanArithmetic(operand, false);
+                            }
+                        }
+                    }
+                    else {
+                        scanTest(expression.left);
+                        scanTest(expression.right);
+                    }
+                    break;
+                case "UnaryTest":
+                    scanTest(expression.argument);
+                    break;
+                case "ParenthesizedTest":
+                    scanTest(expression.expression);
+                    break;
+                // no default
+            }
+        }
+        return {
+            VariableAssignment(node) {
+                if (node.name) {
+                    const parent = context.sourceCode.getParent(node);
+                    // Environment prefixes such as `FOO=1 cmd` are passed to
+                    // the command and therefore used.
+                    if (parent?.type === "Command" && parent.name !== null) {
+                        reads.add(node.name.name);
+                    }
+                    addWrite(node.name.name, node.name);
+                }
+                if (node.index) {
+                    scanArithmetic(node.index, false);
+                }
+            },
+            ArrayElement(node) {
+                if (node.index) {
+                    scanArithmetic(node.index, false);
+                }
+            },
+            ParameterExpansion(node) {
+                reads.add(node.name);
+                for (const expression of [
+                    node.index,
+                    node.sliceOffset,
+                    node.sliceLength,
+                ]) {
+                    if (expression) {
+                        scanArithmetic(expression, false);
+                    }
+                }
+            },
+            ForStatement(node) {
+                if (node.variable) {
+                    addWrite(node.variable.name, node.variable);
+                }
+            },
+            TestCommand(node) {
+                scanTest(node.expression);
+            },
+            ArithmeticCommand(node) {
+                if (node.expression) {
+                    scanArithmetic(node.expression, false);
+                }
+            },
+            ArithmeticExpansion(node) {
+                if (node.expression) {
+                    scanArithmetic(node.expression, false);
+                }
+            },
+            ArithmeticForStatement(node) {
+                for (const expression of [node.init, node.test, node.update]) {
+                    if (expression) {
+                        scanArithmetic(expression, false);
+                    }
+                }
+            },
+            LetCommand(node) {
+                for (const expression of node.expressions) {
+                    scanArithmetic(expression, false);
+                }
+            },
+            DeclarationCommand(node) {
+                let exported = node.kind === "export";
+                let nameref = node.kind === "nameref";
+                let printed = false;
+                for (const argument of node.arguments) {
+                    if (argument.type === "Word") {
+                        const text = getStaticText(argument);
+                        if (text !== null && text.startsWith("-")) {
+                            if (text.includes("x")) {
+                                exported = true;
+                            }
+                            // `export -n` removes the export attribute
+                            // rather than creating a nameref.
+                            if (text.includes("n")) {
+                                if (node.kind === "export") {
+                                    exported = false;
+                                }
+                                else {
+                                    nameref = true;
+                                }
+                            }
+                            if (text.includes("p")) {
+                                printed = true;
+                            }
+                        }
+                    }
+                }
+                if (nameref) {
+                    unsafe = true;
+                }
+                for (const argument of node.arguments) {
+                    if (argument.type !== "VariableAssignment" ||
+                        !argument.name) {
+                        continue;
+                    }
+                    // Exported variables are visible to child processes, so
+                    // consider them used. Naming an existing variable in
+                    // `readonly x` or `declare -p x` also references it.
+                    if (exported ||
+                        (argument.value === null &&
+                            argument.array === null &&
+                            (node.kind === "readonly" || printed))) {
+                        reads.add(argument.name.name);
+                    }
+                }
+            },
+            Command(node) {
+                const name = getCommandName(node);
+                switch (name) {
+                    case "eval":
+                    case "source":
+                    case ".":
+                        unsafe = true;
+                        break;
+                    case "unset":
+                    case "export":
+                    case "readonly":
+                        for (const argument of node.arguments) {
+                            addReadableIdentifier(argument);
+                        }
+                        break;
+                    case "getopts": {
+                        const variable = node.arguments[1];
+                        if (variable) {
+                            const text = getStaticText(variable);
+                            if (text !== null && IDENTIFIER.test(text)) {
+                                addWrite(text, {
+                                    type: "Identifier",
+                                    start: variable.start,
+                                    end: variable.end,
+                                    name: text,
+                                });
+                            }
+                        }
+                        break;
+                    }
+                    case "read":
+                    case "mapfile":
+                    case "readarray": {
+                        let skipNext = false;
+                        for (const argument of node.arguments) {
+                            if (skipNext) {
+                                skipNext = false;
+                                continue;
+                            }
+                            const text = getStaticText(argument);
+                            if (text === null) {
+                                continue;
+                            }
+                            if (text.startsWith("-")) {
+                                skipNext =
+                                    name === "read"
+                                        ? READ_FLAGS_WITH_ARGUMENT.test(text)
+                                        : MAPFILE_FLAGS_WITH_ARGUMENT.test(text);
+                                continue;
+                            }
+                            if (IDENTIFIER.test(text)) {
+                                addWrite(text, {
+                                    type: "Identifier",
+                                    start: argument.start,
+                                    end: argument.end,
+                                    name: text,
+                                });
+                            }
+                        }
+                        break;
+                    }
+                    // no default
+                }
+            },
+            "Program:exit"() {
+                if (unsafe) {
+                    return;
+                }
+                for (const [name, identifier] of writes) {
+                    if (reads.has(name) ||
+                        SPECIAL_VARIABLES.has(name) ||
+                        name.startsWith("LC_") ||
+                        allowedNames.has(name) ||
+                        name.startsWith("_")) {
+                        continue;
+                    }
+                    context.report({
+                        node: identifier,
+                        messageId: "unusedVariable",
+                        data: { name },
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-useless-cat.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to disallow piping from a single-file `cat`.
+ * Mirrors ShellCheck SC2002.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "uselessCat";
+}>;
+export default rule;