@eslint/shell 0.0.0-stage → 0.1.0

package/dist/rules/no-useless-cat.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Rule to disallow piping from a single-file `cat`.
+ * Mirrors ShellCheck SC2002.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { getCommandName, getStaticText } from "./utils.js";
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+function hasPotentialExpansion(word) {
+    const checkParts = (parts, quoted = false) => parts.some(part => {
+        switch (part.type) {
+            case "Literal":
+                return (!quoted &&
+                    (part.value.includes("*") ||
+                        part.value.includes("?") ||
+                        part.value.includes("[") ||
+                        part.value.includes("{") ||
+                        part.value.includes("}")));
+            case "SingleQuotedString":
+                return part.dollar;
+            case "DoubleQuotedString":
+                return checkParts(part.parts, true);
+            default:
+                return false;
+        }
+    });
+    return checkParts(word.parts);
+}
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Disallow useless `cat` at the start of a pipeline",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-useless-cat.md",
+        },
+        schema: [],
+        messages: {
+            uselessCat: "Useless cat. Consider 'cmd < file' or 'cmd file' instead. (ShellCheck SC2002)",
+        },
+    },
+    create(context) {
+        return {
+            Pipeline(node) {
+                const first = node.commands[0];
+                if (!first ||
+                    first.type !== "Command" ||
+                    getCommandName(first) !== "cat" ||
+                    first.redirects.length > 0 ||
+                    first.arguments.length !== 1) {
+                    return;
+                }
+                const argument = first.arguments[0];
+                const text = argument ? getStaticText(argument) : null;
+                // Skip flags, stdin markers, and arguments that can expand to
+                // multiple words.
+                if (text === null ||
+                    text.startsWith("-") ||
+                    !argument ||
+                    hasPotentialExpansion(argument)) {
+                    return;
+                }
+                context.report({
+                    node: first,
+                    messageId: "uselessCat",
+                });
+            },
+        };
+    },
+};
+export default rule;

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

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to disallow `$(echo ...)` command substitutions.
+ * Mirrors ShellCheck SC2116.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "uselessEcho";
+}>;
+export default rule;

package/dist/rules/no-useless-echo.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Rule to disallow `$(echo ...)` command substitutions.
+ * Mirrors ShellCheck SC2116.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { isCommandNamed } from "./utils.js";
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "suggestion",
+        docs: {
+            description: "Disallow useless `echo` inside command substitutions",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-useless-echo.md",
+        },
+        schema: [],
+        messages: {
+            uselessEcho: "Useless echo? Instead of 'cmd $(echo foo)', just use 'cmd foo'. (ShellCheck SC2116)",
+        },
+    },
+    create(context) {
+        return {
+            CommandSubstitution(node) {
+                const first = node.body[0];
+                if (node.body.length === 1 &&
+                    first !== undefined &&
+                    isCommandNamed(first, "echo") &&
+                    !first.negated &&
+                    first.redirects.length === 0) {
+                    context.report({
+                        node,
+                        messageId: "uselessEcho",
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/no-variables-in-printf-format.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to disallow variables in the printf format string.
+ * Mirrors ShellCheck SC2059.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "variableInFormat";
+}>;
+export default rule;

package/dist/rules/no-variables-in-printf-format.js

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Rule to disallow variables in the printf format string.
+ * Mirrors ShellCheck SC2059.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { getCommandName, getExpansions, getStaticText } from "./utils.js";
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Disallow variables in the printf format string; use %s placeholders instead",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/no-variables-in-printf-format.md",
+        },
+        schema: [],
+        messages: {
+            variableInFormat: "Don't use variables in the printf format string. Use printf '...%s...' \"$foo\". (ShellCheck SC2059)",
+        },
+    },
+    create(context) {
+        return {
+            Command(node) {
+                if (getCommandName(node) !== "printf") {
+                    return;
+                }
+                let formatIndex = 0;
+                const first = node.arguments[0]
+                    ? getStaticText(node.arguments[0])
+                    : null;
+                if (first === "-v") {
+                    // `printf -v var format ...`
+                    formatIndex = 2;
+                }
+                else if (first !== null && first.startsWith("-v")) {
+                    // `printf -vvar format ...`
+                    formatIndex = 1;
+                }
+                const possibleFormat = node.arguments[formatIndex];
+                if (possibleFormat && getStaticText(possibleFormat) === "--") {
+                    formatIndex++;
+                }
+                const format = node.arguments[formatIndex];
+                if (!format) {
+                    return;
+                }
+                if (getExpansions(format, { includeQuoted: true }).length > 0) {
+                    context.report({
+                        node: format,
+                        messageId: "variableInFormat",
+                    });
+                }
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/require-cd-guard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to require handling `cd` failure.
+ * Mirrors ShellCheck SC2164.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "uncheckedCd" | "addGuard";
+}>;
+export default rule;

package/dist/rules/require-cd-guard.js

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview Rule to require handling `cd` failure.
+ * Mirrors ShellCheck SC2164.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { getCommandName } from "./utils.js";
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require `cd` failures to be handled, e.g. `cd ... || exit`",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/require-cd-guard.md",
+        },
+        hasSuggestions: true,
+        schema: [],
+        messages: {
+            uncheckedCd: "Use 'cd ... || exit' or 'cd ... || return' in case cd fails. (ShellCheck SC2164)",
+            addGuard: "Add '|| exit' after the cd command.",
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        return {
+            Command(node) {
+                if (getCommandName(node) !== "cd") {
+                    return;
+                }
+                // `! cd ...` uses the exit status explicitly.
+                if (node.negated) {
+                    return;
+                }
+                let expression = node;
+                let parent = sourceCode.getParent(expression);
+                while (parent?.type === "LogicalExpression") {
+                    // A failed command can propagate through a left-associative
+                    // chain to an expression whose status is checked.
+                    if (parent.left === expression) {
+                        return;
+                    }
+                    expression = parent;
+                    parent = sourceCode.getParent(expression);
+                }
+                if (parent) {
+                    // `if cd ...`, `while cd ...`, `until cd ...`
+                    if ((parent.type === "IfStatement" ||
+                        parent.type === "WhileStatement" ||
+                        parent.type === "UntilStatement") &&
+                        parent.test.includes(node)) {
+                        return;
+                    }
+                }
+                const canSuggest = !node.background && node.redirects.length === 0;
+                context.report({
+                    node,
+                    messageId: "uncheckedCd",
+                    suggest: canSuggest
+                        ? [
+                            {
+                                messageId: "addGuard",
+                                fix: fixer => fixer.insertTextAfter(node, " || exit"),
+                            },
+                        ]
+                        : [],
+                });
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/require-read-r.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Rule to require the `-r` flag when using `read`.
+ * Mirrors ShellCheck SC2162.
+ */
+import type { ShellRuleDefinition } from "../types.js";
+declare const rule: ShellRuleDefinition<{
+    MessageIds: "missingR";
+}>;
+export default rule;

package/dist/rules/require-read-r.js

@@ -0,0 +1,84 @@
+/**
+ * @fileoverview Rule to require the `-r` flag when using `read`.
+ * Mirrors ShellCheck SC2162.
+ */
+//------------------------------------------------------------------------------
+// Imports
+//------------------------------------------------------------------------------
+import { getCommandName, getStaticText } from "./utils.js";
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+const optionsWithArguments = new Set(["a", "d", "i", "n", "N", "p", "t", "u"]);
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+const rule = {
+    meta: {
+        type: "problem",
+        docs: {
+            description: "Require `read -r` so backslashes are not mangled",
+            recommended: true,
+            url: "https://github.com/eslint/shell/blob/main/docs/rules/require-read-r.md",
+        },
+        fixable: "code",
+        schema: [],
+        messages: {
+            missingR: "read without -r will mangle backslashes. (ShellCheck SC2162)",
+        },
+    },
+    create(context) {
+        return {
+            Command(node) {
+                if (getCommandName(node) !== "read" || !node.name) {
+                    return;
+                }
+                let hasRawOption = false;
+                for (let index = 0; index < node.arguments.length; index++) {
+                    const argument = node.arguments[index];
+                    if (!argument) {
+                        continue;
+                    }
+                    const text = getStaticText(argument);
+                    if (text === "--") {
+                        break;
+                    }
+                    if (text === null ||
+                        !text.startsWith("-") ||
+                        text === "-") {
+                        continue;
+                    }
+                    for (let optionIndex = 1; optionIndex < text.length; optionIndex++) {
+                        const option = text[optionIndex];
+                        if (!option) {
+                            break;
+                        }
+                        if (option === "r") {
+                            hasRawOption = true;
+                            break;
+                        }
+                        if (optionsWithArguments.has(option)) {
+                            if (optionIndex === text.length - 1) {
+                                index++;
+                            }
+                            break;
+                        }
+                    }
+                    if (hasRawOption) {
+                        break;
+                    }
+                }
+                if (hasRawOption) {
+                    return;
+                }
+                const name = node.name;
+                context.report({
+                    node: name,
+                    messageId: "missingR",
+                    fix: fixer => fixer.insertTextAfter(name, " -r"),
+                });
+            },
+        };
+    },
+};
+export default rule;

package/dist/rules/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @fileoverview Shared helpers for shell rules.
+ */
+import type { CommandNode, CommandSubstitutionNode, ParameterExpansionNode, StatementNode, WordNode } from "../types.js";
+/**
+ * Returns the plain text of a word when it is fully static (made up only of
+ * literals and quoted literals), or `null` when the word contains
+ * expansions. Quotes are removed from the result.
+ *
+ * Strings whose runtime text can differ from their source text are not
+ * static: `$'...'` strings containing escapes, which are not decoded, and
+ * locale-translated `$"..."` strings.
+ */
+export declare function getStaticText(word: WordNode): string | null;
+/**
+ * Returns the name of a command when it is a static word, or `null`.
+ */
+export declare function getCommandName(command: CommandNode): string | null;
+/**
+ * Determines whether a command node is a simple command with the given name.
+ */
+export declare function isCommandNamed(statement: StatementNode, name: string): statement is CommandNode;
+/**
+ * Determines whether a command substitution starts with a command of the given
+ * name.
+ */
+export declare function startsWithCommand(body: StatementNode[], name: string): boolean;
+/**
+ * Returns the expansions that make up a word, including those nested inside
+ * double quotes when `includeQuoted` is `true`. Expansions nested inside
+ * another expansion, such as `$b` in `${a:-$b}`, are not returned.
+ */
+export declare function getExpansions(word: WordNode, { includeQuoted }?: {
+    includeQuoted?: boolean | undefined;
+}): (ParameterExpansionNode | CommandSubstitutionNode)[];

package/dist/rules/utils.js

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Shared helpers for shell rules.
+ */
+//------------------------------------------------------------------------------
+// Helpers
+//------------------------------------------------------------------------------
+/**
+ * Returns the plain text of a word when it is fully static (made up only of
+ * literals and quoted literals), or `null` when the word contains
+ * expansions. Quotes are removed from the result.
+ *
+ * Strings whose runtime text can differ from their source text are not
+ * static: `$'...'` strings containing escapes, which are not decoded, and
+ * locale-translated `$"..."` strings.
+ */
+export function getStaticText(word) {
+    let result = "";
+    for (const part of word.parts) {
+        const text = getStaticPartText(part);
+        if (text === null) {
+            return null;
+        }
+        result += text;
+    }
+    return result;
+}
+function getStaticPartText(part) {
+    switch (part.type) {
+        case "Literal":
+            return part.value;
+        case "SingleQuotedString":
+            return part.dollar && part.value.includes("\\") ? null : part.value;
+        case "DoubleQuotedString": {
+            if (part.dollar) {
+                return null;
+            }
+            let result = "";
+            for (const inner of part.parts) {
+                const text = getStaticPartText(inner);
+                if (text === null) {
+                    return null;
+                }
+                result += text;
+            }
+            return result;
+        }
+        default:
+            return null;
+    }
+}
+/**
+ * Returns the name of a command when it is a static word, or `null`.
+ */
+export function getCommandName(command) {
+    if (!command.name) {
+        return null;
+    }
+    return getStaticText(command.name);
+}
+/**
+ * Determines whether a command node is a simple command with the given name.
+ */
+export function isCommandNamed(statement, name) {
+    return statement.type === "Command" && getCommandName(statement) === name;
+}
+/**
+ * Determines whether a command substitution starts with a command of the given
+ * name.
+ */
+export function startsWithCommand(body, name) {
+    const first = body[0];
+    if (!first) {
+        return false;
+    }
+    const firstCommand = first.type === "Pipeline" ? first.commands[0] : first;
+    return firstCommand !== undefined && isCommandNamed(firstCommand, name);
+}
+/**
+ * Returns the expansions that make up a word, including those nested inside
+ * double quotes when `includeQuoted` is `true`. Expansions nested inside
+ * another expansion, such as `$b` in `${a:-$b}`, are not returned.
+ */
+export function getExpansions(word, { includeQuoted = false } = {}) {
+    const expansions = [];
+    const visitParts = (parts, quoted) => {
+        for (const part of parts) {
+            if (part.type === "ParameterExpansion" ||
+                part.type === "CommandSubstitution") {
+                if (!quoted || includeQuoted) {
+                    expansions.push(part);
+                }
+            }
+            else if (part.type === "DoubleQuotedString") {
+                visitParts(part.parts, true);
+            }
+        }
+    };
+    visitParts(word.parts, false);
+    return expansions;
+}