@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/dist/rules/compat/no-pipe-all.js

@@ -0,0 +1,68 @@
+/**
+ * `sh/compat/no-pipe-all`: reports the `|&` pipe, shorthand for `2>&1 |`, in
+ * files whose target shell lacks it, that is, Bash older than 4.0 (macOS's
+ * stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 rejects `|&` as a syntax error, so the whole script fails to run.
+ * The portable spelling is `cmd 2>&1 | other`. The Bash manual defines `|&`
+ * as that implicit `2>&1`, applied after any redirections the left-hand
+ * command writes, so writing `2>&1` just before the `|` is exactly
+ * equivalent. The rule offers that rewrite as a suggestion.
+ *
+ * What is read: a pipeline (`BinaryCmd`) whose operator is `|&`. A plain `|`,
+ * `||`, `&&`, a background `&`, and any of these inside quotes are other
+ * syntax and are not reported. The report is on the `|&` operator.
+ */
+import { PipeAll } from 'sh-ast';
+import { createCompatRule } from './create-compat-rule.js';
+import { operatorRange } from './operator-range.js';
+/**
+ * The `sh/compat/no-pipe-all` rule module.
+ *
+ * @internal
+ */
+export const noPipeAll = createCompatRule({
+    name: 'compat/no-pipe-all',
+    feature: 'pipeAll',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow the `|&` pipe when the target shell lacks it',
+        },
+        messages: {
+            pipeAll: '`|&` needs {{required}}, but this file targets {{target}}. Write `cmd 2>&1 | other` instead.',
+            useStderrRedirect: 'Replace `|&` with `2>&1 |`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            BinaryCmd(node) {
+                if (node.op !== PipeAll)
+                    return;
+                const range = operatorRange(sourceCode, node, '|&');
+                if (range === undefined) {
+                    context.report({ node, messageId: 'pipeAll', data: { ...gate } });
+                    return;
+                }
+                const [start, end] = range;
+                // `cmd|&other` has no space before the operator, and `2>&1` must not
+                // join the command's last word.
+                const before = sourceCode.text[start - 1];
+                const separator = before === ' ' || before === '\t' ? '' : ' ';
+                context.report({
+                    loc: { start: sourceCode.getLocFromIndex(start), end: sourceCode.getLocFromIndex(end) },
+                    messageId: 'pipeAll',
+                    data: { ...gate },
+                    suggest: [
+                        {
+                            messageId: 'useStderrRedirect',
+                            fix: (fixer) => fixer.replaceTextRange(range, `${separator}2>&1 |`),
+                        },
+                    ],
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-printf-time-format.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoPrintfTimeFormatMessageId = 'printfTime';
+/**
+ * The `sh/compat/no-printf-time-format` rule module.
+ *
+ * @internal
+ */
+export declare const noPrintfTimeFormat: import("../define-shell-rule.js").ShellRule<[], "printfTime">;

package/dist/rules/compat/no-printf-time-format.js

@@ -0,0 +1,99 @@
+/**
+ * `sh/compat/no-printf-time-format`: reports `printf`'s `%(fmt)T` date
+ * format in files whose target shell lacks it, that is, Bash older than 4.2
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 4.1 rejects the directive with "invalid format character", so
+ * nothing is printed. The message suggests the portable alternative for the
+ * current time: `date '+fmt'`, which takes the same `strftime` format.
+ *
+ * What is read: a `printf` command (after transparent wrappers such as
+ * `builtin`) whose format argument, after an optional `-v name` and `--`, is
+ * a static word containing a `%(…)T` directive. The format is scanned as
+ * `printf` reads it: `%%` is a literal percent sign, and a directive may
+ * carry flags, a width and a precision before the `(`. A format that is not
+ * static cannot be read, and is not reported. The report is on the format
+ * word.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+import { createCompatRule } from './create-compat-rule.js';
+/**
+ * The wrappers followed to find the `printf` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** A conversion's flags, width and precision, as `printf` accepts them. */
+const DIRECTIVE_PREFIX = /^[-+ #0']*(?:\d+|\*)?(?:\.(?:\d+|\*)?)?/u;
+/**
+ * The `strftime` format of the first `%(fmt)T` directive in a `printf`
+ * format string, or `undefined` when it has none.
+ */
+function timeFormatIn(format) {
+    for (let index = 0; index < format.length; index++) {
+        if (format[index] !== '%')
+            continue;
+        if (format[index + 1] === '%') {
+            index++;
+            continue;
+        }
+        const rest = format.slice(index + 1);
+        const prefix = DIRECTIVE_PREFIX.exec(rest)?.[0] ?? '';
+        const afterPrefix = rest.slice(prefix.length);
+        if (!afterPrefix.startsWith('('))
+            continue;
+        const close = afterPrefix.indexOf(')');
+        if (close !== -1 && afterPrefix[close + 1] === 'T')
+            return afterPrefix.slice(1, close);
+    }
+    return undefined;
+}
+/**
+ * The `sh/compat/no-printf-time-format` rule module.
+ *
+ * @internal
+ */
+export const noPrintfTimeFormat = createCompatRule({
+    name: 'compat/no-printf-time-format',
+    feature: 'printfTimeFormat',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: "Disallow `printf`'s `%(fmt)T` date format when the target shell lacks it",
+        },
+        messages: {
+            printfTime: "`printf '%({{format}})T'` needs {{required}}, but this file targets {{target}}. For the current time, run `date '+{{format}}'` instead.",
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true || invoked.effective.text !== 'printf')
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                const words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+                let index = 0;
+                const first = words.at(0);
+                if (first !== undefined && sourceCode.resolveWordText(first) === '-v')
+                    index = 2;
+                if (index < words.length && sourceCode.resolveWordText(words[index]) === '--')
+                    index++;
+                const formatWord = words.at(index);
+                if (formatWord === undefined)
+                    return;
+                const text = sourceCode.resolveWordText(formatWord);
+                const format = text === null ? undefined : timeFormatIn(text);
+                if (format === undefined)
+                    return;
+                context.report({ node: formatWord, messageId: 'printfTime', data: { ...gate, format } });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-source.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `source` for the report and `useDot` for
+ * its suggestion.
+ *
+ * @internal
+ */
+export type NoSourceMessageId = 'source' | 'useDot';
+/**
+ * The `sh/compat/no-source` rule module.
+ *
+ * @internal
+ */
+export declare const noSource: import("../define-shell-rule.js").ShellRule<[], NoSourceMessageId>;

package/dist/rules/compat/no-source.js

@@ -0,0 +1,103 @@
+/**
+ * `sh/compat/no-source`: reports the `source` builtin in files that target
+ * POSIX sh, where the portable name is the `.` special built-in. Every Bash has
+ * `source`, so this is a POSIX-only gate.
+ *
+ * POSIX section 2.9.1.4 leaves the results of a command named `source`
+ * unspecified. dash has no such command: `source ./lib.sh` fails with `source:
+ * not found` and status 127, and the file is never read. `bash --posix` and
+ * BusyBox ash accept it, so only some POSIX shells show the problem.
+ *
+ * What is read: a command whose effective name is `source`, outside a branch
+ * for one shell (see `./posix-absent-command.ts`).
+ *
+ * A function named `source` anywhere in the file exempts a call that names it
+ * directly, since dash can then run that function; `bash --posix` refuses that
+ * definition, which this rule does not judge. This is a name check across the
+ * file and does not prove the function exists at the call: execution order, a
+ * definition in a branch or subshell, and `unset -f` are not read, so some exempt
+ * calls still fail on dash. A call through a wrapper is never exempt, because
+ * wrappers such as `command`, `env` and `exec` do not run functions.
+ *
+ * The suggestion replaces the word with `.` only where the two read the same
+ * file with the same effect, apart from a file that cannot be read: `.` then
+ * ends the script on a POSIX shell, so a `|| fallback` never runs, and the
+ * suggestion's text says so. The conditions are:
+ *
+ * - The command is written directly, with no wrapper.
+ * - It has no leading `VAR=value`. Such an assignment persists after `.` on a
+ *   POSIX shell, while Bash outside POSIX mode scopes it to the `source`
+ *   command.
+ * - It has exactly one operand. `.` takes one in POSIX, and dash ignores any
+ *   others where `source` would set the positional parameters.
+ * - The operand has a literal `/`. A name without one makes `.` search `PATH`.
+ */
+import { definedFunctionNames } from '../../command-harvest/harvest-commands.js';
+import { childNodes } from '../../language/syntax-view.js';
+import { createCompatRule } from './create-compat-rule.js';
+import { reachableCommandWord } from './posix-absent-command.js';
+/** The builtin this rule gates. */
+const SOURCE = 'source';
+/**
+ * Whether `word` holds a `/` that no expansion can remove: in unquoted or
+ * quoted literal text, whatever its other parts expand to. A `/` inside an
+ * expansion (`${x%/*}`, `$(pwd)`) does not count, so the walk stops at anything
+ * that is not literal text or a double-quoted group.
+ */
+function hasLiteralSlash(word) {
+    return childNodes(word).some((part) => {
+        if (part.type === 'Lit' || part.type === 'SglQuoted')
+            return part.value.includes('/');
+        return part.type === 'DblQuoted' && hasLiteralSlash(part);
+    });
+}
+/** Whether `.` is an exact replacement for this `source` command (see the module comment). */
+function dotIsEquivalent(sourceCode, node) {
+    if (sourceCode.getCommandName(node) !== SOURCE)
+        return false;
+    if (node.assigns.length > 0 || node.args.length !== 2)
+        return false;
+    return hasLiteralSlash(node.args[1]);
+}
+/**
+ * The `sh/compat/no-source` rule module.
+ *
+ * @internal
+ */
+export const noSource = createCompatRule({
+    name: 'compat/no-source',
+    feature: 'sourceCommand',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow the `source` builtin when the target shell is POSIX sh',
+        },
+        messages: {
+            source: '`source` is not part of {{target}}. dash fails with `source: not found` and the file is never read. Use the `.` special built-in with a path that contains a slash, for example `. ./lib.sh`.',
+            useDot: 'Replace `source` with `.`, which ends the script if the file is missing.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const fileDefinesSource = definedFunctionNames(sourceCode).has(SOURCE);
+        return {
+            CallExpr(node) {
+                const word = reachableCommandWord(sourceCode, node, SOURCE);
+                if (word === undefined)
+                    return;
+                // Only a name written directly can run a function: a wrapper skips it.
+                if (fileDefinesSource && sourceCode.getCommandName(node) === SOURCE)
+                    return;
+                context.report({
+                    node: word,
+                    messageId: 'source',
+                    data: { target: gate.target },
+                    suggest: dotIsEquivalent(sourceCode, node)
+                        ? [{ messageId: 'useDot', fix: (fixer) => fixer.replaceText(word, '.') }]
+                        : [],
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-test-v.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoTestVMessageId = 'testV';
+/**
+ * The `sh/compat/no-test-v` rule module.
+ *
+ * @internal
+ */
+export declare const noTestV: import("../define-shell-rule.js").ShellRule<[], "testV">;

package/dist/rules/compat/no-test-v.js

@@ -0,0 +1,280 @@
+/**
+ * `sh/compat/no-test-v`: reports the `-v name` test (`[[ -v x ]]`,
+ * `test -v x`, `[ -v x ]`) in files whose target shell lacks it, that is,
+ * Bash older than 4.2 (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * In Bash 4.1 and older, `[[ -v x ]]` is a syntax error, so the whole script
+ * fails to parse, and `test -v x` fails with "unary operator expected". The
+ * message suggests the portable alternative, `[ -n "${x+set}" ]`, which is
+ * true exactly when `x` is set (even to the empty string) and is safe under
+ * `set -u`.
+ *
+ * What is read:
+ *
+ * - inside `[[ … ]]`, the parser's `-v` unary test node;
+ * - for `test` and `[` (after transparent wrappers such as `builtin`), the
+ *   arguments, read the way Bash's `test` reads them: with two arguments a
+ *   leading `-v` is the operator; with three, the middle one is a binary
+ *   operator if it can be one, and `! -v name` negates the test; with four,
+ *   `! …` and `( … )` peel off; anything longer goes through `test`'s own
+ *   precedence parser, where `-v` is the operator only where a primary is
+ *   expected and another argument follows it. So `[ "$x" = -v ]` and
+ *   `[ -n -v ]` do not report. A double-quoted expansion (`"$name"`) is one
+ *   operand whatever its value. Any other argument that is not a static word
+ *   ends the reading, because it may expand to several arguments or none.
+ *
+ * The report is on the `[[` test, or on the `-v` word.
+ */
+import { TsVarSet } from 'sh-ast';
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+import { createCompatRule } from './create-compat-rule.js';
+/**
+ * The wrappers followed to find the `test` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** The commands that are Bash's `test` builtin. */
+const TEST_COMMANDS = new Set(['test', '[']);
+/** Bash's `test` binary operators (`test_binop`), without `-a` and `-o`. */
+const BINARY_OPERATORS = new Set([
+    '=',
+    '==',
+    '!=',
+    '<',
+    '>',
+    '-eq',
+    '-ne',
+    '-lt',
+    '-le',
+    '-gt',
+    '-ge',
+    '-nt',
+    '-ot',
+    '-ef',
+]);
+/** Bash's `test` unary operators (`test_unop`). */
+const UNARY_OPERATORS = new Set([
+    '-a',
+    '-b',
+    '-c',
+    '-d',
+    '-e',
+    '-f',
+    '-g',
+    '-h',
+    '-k',
+    '-n',
+    '-o',
+    '-p',
+    '-r',
+    '-s',
+    '-t',
+    '-u',
+    '-v',
+    '-w',
+    '-x',
+    '-z',
+    '-G',
+    '-L',
+    '-O',
+    '-S',
+    '-N',
+    '-R',
+]);
+/**
+ * What a double-quoted, non-static argument stands for while reading `test`'s
+ * arguments: an operand that is never an operator. A NUL cannot occur in a
+ * shell word, so no real argument equals it.
+ */
+const QUOTED_OPERAND = '\0operand';
+/** A shell variable name, optionally with an array subscript. */
+const VARIABLE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?$/u;
+/**
+ * The indices of the arguments in `args` that Bash's `test` reads as the
+ * `-v` operator. `args` are the static texts after the command name (and
+ * without a closing `]`); reading stops at the first `null`.
+ */
+function variableTestIndices(args) {
+    const end = args.indexOf(null);
+    const argv = (end === -1 ? args : args.slice(0, end));
+    const found = [];
+    /** `test`'s two-argument rule, at offset `at`. */
+    function twoArguments(at) {
+        if (argv[at] === '-v')
+            found.push(at);
+    }
+    /** `test`'s three-argument rule, at offset `at`. */
+    function threeArguments(at) {
+        const middle = argv[at + 1];
+        if (BINARY_OPERATORS.has(middle) || middle === '-a' || middle === '-o')
+            return true;
+        if (argv[at] === '!') {
+            twoArguments(at + 1);
+            return true;
+        }
+        return argv[at] === '(' && argv[at + 2] === ')';
+    }
+    /** `test`'s precedence parser over every argument (`expr` in Bash's test.c). */
+    function expression() {
+        let pos = 0;
+        const term = () => {
+            if (pos >= argv.length)
+                return;
+            const word = argv[pos];
+            if (word === '!') {
+                pos++;
+                term();
+                return;
+            }
+            if (word === '(') {
+                pos++;
+                or();
+                if (argv[pos] === ')')
+                    pos++;
+                return;
+            }
+            if (pos + 3 <= argv.length && BINARY_OPERATORS.has(argv[pos + 1])) {
+                pos += 3;
+                return;
+            }
+            if (UNARY_OPERATORS.has(word) && pos + 1 < argv.length) {
+                if (word === '-v')
+                    found.push(pos);
+                pos += 2;
+                return;
+            }
+            pos++;
+        };
+        const and = () => {
+            term();
+            while (argv[pos] === '-a') {
+                pos++;
+                term();
+            }
+        };
+        const or = () => {
+            and();
+            while (argv[pos] === '-o') {
+                pos++;
+                and();
+            }
+        };
+        while (pos < argv.length) {
+            const before = pos;
+            or();
+            if (pos === before)
+                pos++;
+        }
+    }
+    switch (argv.length) {
+        case 0:
+        case 1:
+            break;
+        case 2:
+            if (argv[0] !== '!')
+                twoArguments(0);
+            break;
+        case 3:
+            if (!threeArguments(0))
+                expression();
+            break;
+        case 4:
+            if (argv[0] === '!') {
+                if (!threeArguments(1))
+                    expression();
+            }
+            else if (argv[0] === '(' && argv[3] === ')') {
+                if (argv[1] !== '!')
+                    twoArguments(1);
+            }
+            else {
+                expression();
+            }
+            break;
+        default:
+            expression();
+    }
+    return found;
+}
+/**
+ * The `sh/compat/no-test-v` rule module.
+ *
+ * @internal
+ */
+export const noTestV = createCompatRule({
+    name: 'compat/no-test-v',
+    feature: 'testVariableSet',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow the `-v name` test (`[[ -v x ]]`, `test -v x`) when the target shell lacks it',
+        },
+        messages: {
+            testV: '`-v {{name}}` needs {{required}}, but this file targets {{target}}. Test whether the variable is set with `[ -n "${{{name}}+set}" ]` instead.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        /** The variable name shown in the message for `operand`. */
+        function nameOf(operand) {
+            const text = operand?.type === 'Word' ? sourceCode.resolveWordText(operand) : null;
+            return text !== null && VARIABLE_NAME.test(text) ? text : 'name';
+        }
+        /**
+         * The argument `word` gives `test`: its static text; a stand-in operand
+         * for a word that is one double-quoted string, which always makes exactly
+         * one argument whatever it expands to; or `null` for any other word, which
+         * may split into several arguments or none.
+         */
+        function argumentText(word) {
+            const text = sourceCode.resolveWordText(word);
+            if (text !== null)
+                return text;
+            if (word.parts.length === 1 && word.parts[0].type === 'DblQuoted') {
+                return QUOTED_OPERAND;
+            }
+            return null;
+        }
+        return {
+            UnaryTest(node) {
+                if (node.op !== TsVarSet)
+                    return;
+                context.report({
+                    node,
+                    messageId: 'testV',
+                    data: { ...gate, name: nameOf(node.x) },
+                });
+            },
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true)
+                    return;
+                const command = invoked.effective.text;
+                if (!TEST_COMMANDS.has(command))
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                let words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+                if (command === '[') {
+                    const last = words.at(-1);
+                    if (last === undefined || sourceCode.resolveWordText(last) !== ']')
+                        return;
+                    words = words.slice(0, -1);
+                }
+                const texts = words.map((word) => argumentText(word));
+                for (const index of variableTestIndices(texts)) {
+                    context.report({
+                        node: words[index],
+                        messageId: 'testV',
+                        data: { ...gate, name: nameOf(words[index + 1]) },
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/no-unicode-escape.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Message ids this rule reports with: `unicodeEscape` when the target leaves
+ * the escape undecoded, `unicodeEscapeLatin1` when it decodes it to a
+ * Latin-1 byte.
+ *
+ * @internal
+ */
+export type NoUnicodeEscapeMessageId = 'unicodeEscape' | 'unicodeEscapeLatin1';
+/**
+ * The `sh/compat/no-unicode-escape` rule module.
+ *
+ * @internal
+ */
+export declare const noUnicodeEscape: import("../define-shell-rule.js").ShellRule<[], NoUnicodeEscapeMessageId>;