@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/compat/no-declare-g.js

@@ -0,0 +1,59 @@
+/**
+ * `sh/compat/no-declare-g`: reports `declare -g` and `typeset -g` in files
+ * whose target shell lacks the `-g` option, that is, Bash older than 4.2
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 rejects `-g` as an invalid option, so the declaration fails and the
+ * variable is never created. The message suggests the portable alternative:
+ * in Bash before 4.2 a plain `name=value` assignment inside a function already
+ * sets the global, as long as the function has not declared the name `local`.
+ *
+ * What is read: `declare`/`typeset` option clusters containing `g` (`-g`,
+ * `-gx`, `-Ag`), found as `declarationFlagVisitor` defines. `local` and
+ * `export` are outside this rule's scope.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { declarationFlagVisitor } from './declaration-options.js';
+/**
+ * Whether a plain assignment can stand in for a command's options, which
+ * contain `g`: only when every option word is a `-` cluster of `g` and `x`
+ * letters (`-g`, `-gx`, `-g -x`), since `export name=value` expresses `x`. Any
+ * other option sets an attribute (`-A`, `-i`, `-r`, …) that an assignment
+ * cannot, whether it is joined to the `g` (`-Ag`) or a word of its own
+ * (`-g -A`).
+ */
+function isPlainAssignmentEquivalent(options) {
+    return options.every((option) => /^-[gx]+$/u.test(option));
+}
+/**
+ * The `sh/compat/no-declare-g` rule module.
+ *
+ * @internal
+ */
+export const noDeclareG = createCompatRule({
+    name: 'compat/no-declare-g',
+    feature: 'declareGlobal',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `declare -g` and `typeset -g` when the target shell lacks the option',
+        },
+        messages: {
+            declareGlobal: '`{{command}} -g` needs {{required}}, but this file targets {{target}}. Assign the global with a plain `name=value` (a variable not declared `local` is global), or `export name=value` to also export it.',
+            declareGlobalWithAttributes: '`{{command}} {{flags}}` needs {{required}}, but this file targets {{target}}. A plain `name=value` cannot express its other options, so dropping `g` is not enough: declare the variable outside any function, or raise the target.',
+        },
+    },
+    create(context, gate) {
+        return declarationFlagVisitor(context.sourceCode, 'g', (node, command, options) => {
+            if (!isPlainAssignmentEquivalent(options)) {
+                context.report({
+                    node,
+                    messageId: 'declareGlobalWithAttributes',
+                    data: { ...gate, command, flags: options.join(' ') },
+                });
+                return;
+            }
+            context.report({ node, messageId: 'declareGlobal', data: { ...gate, command } });
+        });
+    },
+});

package/dist/rules/compat/no-double-bracket.d.ts

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

package/dist/rules/compat/no-double-bracket.js

@@ -0,0 +1,52 @@
+/**
+ * `sh/compat/no-double-bracket`: reports `[[ … ]]` in files that target POSIX
+ * sh. Every Bash has it, so this is a POSIX-only gate.
+ *
+ * POSIX section 2.4 leaves the results of `[[` and `]]` unspecified. dash does
+ * not treat `[[` as a word of its grammar: it looks up a command by that name
+ * and fails with `[[: not found` and status 127. Under `set -e` a bare test
+ * stops the script, and in an `if` condition the failure is silent in effect:
+ * dash takes the `else` branch. `bash --posix` and BusyBox ash accept it, so
+ * only some POSIX shells show the problem.
+ *
+ * What is read: a command whose effective name is `[[`, because the POSIX
+ * parser has no conditional clause, outside a branch for one shell (see
+ * `./posix-absent-command.ts`). The expression is not interpreted, and
+ * the parser ends the command at `&&` or `||`, so one finding is reported per
+ * `[[`, on that word. A `[[` the parser cannot read as a command (`=~` with a
+ * parenthesis, `[[ ( a ) ]]`) is a parse error and never reaches this rule.
+ *
+ * No suggestion: `[` splits and globs its unquoted operands and `==` and `=~`
+ * have no `[` spelling, so no rewrite keeps the behaviour in general.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { reachableCommandWord } from './posix-absent-command.js';
+/**
+ * The `sh/compat/no-double-bracket` rule module.
+ *
+ * @internal
+ */
+export const noDoubleBracket = createCompatRule({
+    name: 'compat/no-double-bracket',
+    feature: 'doubleBracket',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `[[ … ]]` when the target shell is POSIX sh',
+        },
+        messages: {
+            doubleBracket: '`[[` is not part of {{target}}. dash fails with `[[: not found`, and an `if` on it takes its `else` branch. Use `[ … ]` for tests and `case` for pattern matching.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        return {
+            CallExpr(node) {
+                const word = reachableCommandWord(sourceCode, node, '[[');
+                if (word === undefined)
+                    return;
+                context.report({ node: word, messageId: 'doubleBracket', data: { target: gate.target } });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-epoch-variables.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoEpochVariablesMessageId = 'epochSeconds' | 'epochRealtime';
+/**
+ * The `sh/compat/no-epoch-variables` rule module.
+ *
+ * @internal
+ */
+export declare const noEpochVariables: import("../define-shell-rule.js").ShellRule<[], NoEpochVariablesMessageId>;

package/dist/rules/compat/no-epoch-variables.js

@@ -0,0 +1,57 @@
+import { createCompatRule } from './create-compat-rule.js';
+/** The two variables, and the message each reports with. */
+const EPOCH_VARIABLES = new Map([
+    ['EPOCHSECONDS', 'epochSeconds'],
+    ['EPOCHREALTIME', 'epochRealtime'],
+]);
+/** The arithmetic nodes whose `Word` operands name variables. */
+const ARITHMETIC_PARENTS = new Set([
+    'ArithmCmd',
+    'ArithmExp',
+    'BinaryArithm',
+    'UnaryArithm',
+    'ParenArithm',
+    'CStyleLoop',
+]);
+/**
+ * The `sh/compat/no-epoch-variables` rule module.
+ *
+ * @internal
+ */
+export const noEpochVariables = createCompatRule({
+    name: 'compat/no-epoch-variables',
+    feature: 'epochVariables',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `$EPOCHSECONDS` and `$EPOCHREALTIME` when the target shell lacks them',
+        },
+        messages: {
+            epochSeconds: '`$EPOCHSECONDS` needs {{required}}, but this file targets {{target}}, where it is unset. Use `$(date +%s)` instead (GNU, BSD and BusyBox `date`; POSIX `date` has no `%s`).',
+            epochRealtime: '`$EPOCHREALTIME` needs {{required}}, but this file targets {{target}}, where it is unset. `$(date +%s)` gives whole seconds (GNU, BSD and BusyBox `date`); there is no portable source of the fraction.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        /** Reports `node` if `name` is one of the two variables. */
+        function check(node, name) {
+            const messageId = name === undefined ? undefined : EPOCH_VARIABLES.get(name);
+            if (messageId !== undefined)
+                context.report({ node, messageId, data: { ...gate } });
+        }
+        return {
+            ParamExp(node) {
+                check(node, node.param?.value);
+            },
+            Word(node) {
+                const parent = sourceCode.getParent(node);
+                if (parent === undefined || !ARITHMETIC_PARENTS.has(parent.type))
+                    return;
+                const [part] = node.parts;
+                if (node.parts.length !== 1 || part.type !== 'Lit')
+                    return;
+                check(node, part.value);
+            },
+        };
+    },
+});

package/dist/rules/compat/no-fd-variable.d.ts

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

package/dist/rules/compat/no-fd-variable.js

@@ -0,0 +1,48 @@
+/**
+ * `sh/compat/no-fd-variable`: reports a `{varname}` redirection, which has
+ * the shell pick a free file descriptor and store its number in the
+ * variable (`exec {fd}>file`), in files whose target shell lacks it, that is,
+ * Bash older than 4.1 (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 4.0 and older treat `{fd}` as an ordinary word: `exec {fd}>out` tries
+ * to run a command named `{fd}`, which fails. The message suggests the
+ * portable alternative: use a fixed descriptor number, such as
+ * `exec 3>file`, `>&3`, then `exec 3>&-`.
+ *
+ * What is read: a `Redirect` whose descriptor is written as `{name}`, which
+ * the parser records separately from the redirection's target; a numbered
+ * descriptor (`3>file`) and a `{…}` word anywhere else (an argument, a brace
+ * group, quoted text) are not reported. The report is on the whole
+ * redirection.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+/** A `{varname}` descriptor as the parser records it. */
+const FD_VARIABLE = /^\{([A-Za-z_][A-Za-z0-9_]*)\}$/u;
+/**
+ * The `sh/compat/no-fd-variable` rule module.
+ *
+ * @internal
+ */
+export const noFdVariable = createCompatRule({
+    name: 'compat/no-fd-variable',
+    feature: 'fdVariable',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `{varname}` file-descriptor redirections (`exec {fd}>file`) when the target shell lacks them',
+        },
+        messages: {
+            fdVariable: '`{{{name}}}` descriptor allocation needs {{required}}, but this file targets {{target}}. Use a fixed descriptor number instead, for example `exec 3>file`, then `>&3`, then `exec 3>&-`.',
+        },
+    },
+    create(context, gate) {
+        return {
+            Redirect(node) {
+                const match = node.n === undefined ? null : FD_VARIABLE.exec(node.n.value);
+                if (match === null)
+                    return;
+                context.report({ node, messageId: 'fdVariable', data: { ...gate, name: match[1] } });
+            },
+        };
+    },
+});

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * `sh/compat/no-globstar`: reports `shopt -s globstar` in files whose target
+ * shell lacks the option, that is, Bash older than 4.0 (macOS's stock
+ * `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 has no such option: `shopt` prints "invalid shell option name"
+ * and the script carries on, and `**` then matches like `*`, so a recursive
+ * glob silently matches fewer files (often none). The message suggests the
+ * portable alternative: search the tree with `find`.
+ *
+ * What is read: a `shopt -s` command naming `globstar`, as
+ * `shoptEnableVisitor` defines (`shopt -u`, `shopt -o` and a name that is not
+ * a static word do not count). The report is on the `globstar` word.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { shoptEnableVisitor } from './shopt-options.js';
+/**
+ * The `sh/compat/no-globstar` rule module.
+ *
+ * @internal
+ */
+export const noGlobstar = createCompatRule({
+    name: 'compat/no-globstar',
+    feature: 'globstar',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `shopt -s globstar` when the target shell lacks the option',
+        },
+        messages: {
+            globstar: "`shopt -s globstar` needs {{required}}, but this file targets {{target}}, where `**` matches like `*`. Search the tree with `find` instead, for example `find dir -name '*.txt'`.",
+        },
+    },
+    create(context, gate) {
+        return shoptEnableVisitor(context, 'globstar', (word) => {
+            context.report({ node: word, messageId: 'globstar', data: { ...gate } });
+        });
+    },
+});

package/dist/rules/compat/no-lastpipe-semantics.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Message ids this rule reports with.
+ *
+ * @internal
+ */
+export type NoLastpipeSemanticsMessageId = 'lastpipe' | 'lastpipePosix';
+/**
+ * The `sh/compat/no-lastpipe-semantics` rule module.
+ *
+ * @internal
+ */
+export declare const noLastpipeSemantics: import("../define-shell-rule.js").ShellRule<[], NoLastpipeSemanticsMessageId>;

package/dist/rules/compat/no-lastpipe-semantics.js

@@ -0,0 +1,53 @@
+/**
+ * `sh/compat/no-lastpipe-semantics`: reports `shopt -s lastpipe` in files
+ * whose target shell lacks the `lastpipe` option, that is, Bash older than 4.2
+ * (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 3.2 has no such option: `shopt` fails with "invalid shell option name"
+ * and the last command of every pipeline keeps running in a subshell, so a
+ * script that relied on `cmd | while read …; do total=…; done` leaving
+ * `total` set in the current shell silently loses the assignment. The message
+ * suggests the portable alternative: feed the loop with process substitution
+ * (`done < <(cmd)`), which keeps the loop in the current shell on every Bash
+ * that has it. A POSIX target has no process substitution, so its message
+ * suggests a temporary file or here-document instead.
+ *
+ * What is read: a `shopt` command (after transparent wrappers such as
+ * `builtin`) whose option words, up to the first operand, include `-s`
+ * (possibly inside a cluster such as `-sq`) and which names `lastpipe` as an
+ * operand. `shopt -u lastpipe` turns the option off (so does a `-u` beside the
+ * `-s`), `shopt -o` names `set -o` options, and a `lastpipe` that is not a static word cannot be read, so none
+ * of those reports.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { shoptEnableVisitor } from './shopt-options.js';
+/** The `shopt` option this rule gates. */
+const LASTPIPE = 'lastpipe';
+/**
+ * The `sh/compat/no-lastpipe-semantics` rule module.
+ *
+ * @internal
+ */
+export const noLastpipeSemantics = createCompatRule({
+    name: 'compat/no-lastpipe-semantics',
+    feature: 'lastpipe',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow `shopt -s lastpipe` when the target shell lacks the option',
+        },
+        messages: {
+            lastpipe: '`shopt -s lastpipe` needs {{required}}, but this file targets {{target}}. Keep the loop in the current shell by feeding it with process substitution instead, for example `while read -r line; do …; done < <(cmd)`.',
+            lastpipePosix: '`shopt -s lastpipe` needs {{required}}, but this file targets {{target}}. Process substitution is not POSIX either; keep the loop in the current shell by writing the output to a temporary file and reading that, for example `cmd > "$tmp"` then `while read -r line; do …; done < "$tmp"`, or by feeding the loop a here-document.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        // Process substitution is a Bash feature, so a POSIX target gets advice
+        // that uses only POSIX constructs.
+        const messageId = sourceCode.dialect === 'posix' ? 'lastpipePosix' : 'lastpipe';
+        return shoptEnableVisitor(context, LASTPIPE, (word) => {
+            context.report({ node: word, messageId, data: { ...gate } });
+        });
+    },
+});

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

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

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

@@ -0,0 +1,62 @@
+/**
+ * `sh/compat/no-let`: reports the `let` builtin in files that target POSIX sh.
+ * Every Bash has it, so this is a POSIX-only gate.
+ *
+ * POSIX section 2.9.1.4 leaves the results of a command named `let`
+ * unspecified. dash has no such command: `let n=1+2` fails with `let: not
+ * found` and status 127, and `n` stays unset. `bash --posix` and BusyBox ash
+ * accept it, so only some POSIX shells show the problem.
+ *
+ * What is read: a command whose effective name is `let`, because the POSIX
+ * parser has no `let` clause, outside a branch for one shell (see
+ * `./posix-absent-command.ts`).
+ *
+ * A function named `let` anywhere in the file exempts a call that names it
+ * directly, since dash can then run that function. 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.
+ *
+ * No suggestion: `let` sets its exit status from the value of its last
+ * expression, which `n=$((1 + 2))` does not, so the rewrite can change what
+ * `set -e` or an `if` sees.
+ */
+import { definedFunctionNames } from '../../command-harvest/harvest-commands.js';
+import { createCompatRule } from './create-compat-rule.js';
+import { reachableCommandWord } from './posix-absent-command.js';
+/** The builtin this rule gates. */
+const LET = 'let';
+/**
+ * The `sh/compat/no-let` rule module.
+ *
+ * @internal
+ */
+export const noLet = createCompatRule({
+    name: 'compat/no-let',
+    feature: 'letCommand',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow the `let` builtin when the target shell is POSIX sh',
+        },
+        messages: {
+            let: '`let` is not part of {{target}}. dash fails with `let: not found` and the assignment never happens. Use arithmetic expansion instead, for example `n=$((1 + 2))`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const fileDefinesLet = definedFunctionNames(sourceCode).has(LET);
+        return {
+            CallExpr(node) {
+                const word = reachableCommandWord(sourceCode, node, LET);
+                if (word === undefined)
+                    return;
+                // Only a name written directly can run a function: a wrapper skips it.
+                if (fileDefinesLet && sourceCode.getCommandName(node) === LET)
+                    return;
+                context.report({ node: word, messageId: 'let', data: { target: gate.target } });
+            },
+        };
+    },
+});

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

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

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

@@ -0,0 +1,122 @@
+/**
+ * `sh/compat/no-mapfile`: reports the `mapfile` builtin and its `readarray`
+ * synonym in files whose target shell lacks them, that is, Bash older than
+ * 4.0 (macOS's stock `/bin/bash` is 3.2) and POSIX sh. Under Bash 3.2 the
+ * name is looked up as an external command, which does not exist, so the
+ * array is never filled.
+ *
+ * The command is recognized as the effective command after following
+ * transparent wrappers (`command mapfile …`, `builtin readarray …`), through
+ * `ShellSourceCode.resolveInvokedCommand`.
+ *
+ * The suggestion rewrites the one shape whose array contents a loop
+ * reproduces exactly, `mapfile -t [NAME]` written directly (no wrapper, no leading
+ * `VAR=value` assignment) in a Bash-family file: it becomes a brace group
+ * that empties the array and appends each line read by
+ * `while IFS= read -r … || [ -n "$REPLY" ]`. The `|| [ -n "$REPLY" ]` keeps a
+ * final line that has no trailing newline, as `mapfile -t` does. Reading with
+ * no variable name keeps every byte of the line, but it assigns `REPLY`:
+ * unlike `mapfile`, the loop leaves `REPLY` set to the empty string, whatever
+ * it held (or whether it was set) before. `REPLY` is `read`'s own default
+ * variable, so this is the narrowest side effect a read loop can have; the
+ * alternatives (a named loop variable, or saving and restoring `REPLY` in
+ * another variable) overwrite a name the script is likelier to use. The
+ * suggestion message states the tradeoff. The brace group keeps the command a single
+ * unit, so a redirection (`< file`) or pipeline (`cmd | mapfile -t a`) still
+ * feeds the loop. Other options (`-d`, `-n`, `-O`, `-s`, `-u`, `-C`, or no
+ * `-t`, which keeps each newline) and POSIX files, which have no arrays at
+ * all, get the report without a suggestion.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+import { createCompatRule } from './create-compat-rule.js';
+/** The builtin's two names. */
+const MAPFILE_COMMANDS = new Set(['mapfile', 'readarray']);
+/** The array `mapfile` fills when no name is given. */
+const DEFAULT_ARRAY = 'MAPFILE';
+/** A shell variable name, the only operand shape the suggestion rewrites. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * The wrappers followed to find the command an invocation runs:
+ * `sh-ast/analyze`'s defaults (which include `command`) plus Bash's
+ * `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/**
+ * The loop that fills `array` exactly as `mapfile -t array` does, wrapped in
+ * a brace group so redirections and pipelines still apply to all of it.
+ */
+function readLoop(array) {
+    return `{ ${array}=(); while IFS= read -r || [ -n "$REPLY" ]; do ${array}+=("$REPLY"); done; }`;
+}
+/**
+ * The array a directly written `mapfile -t [NAME]` fills, or `undefined` when
+ * `node` has any other shape (see the module comment), so no suggestion is
+ * offered.
+ */
+function rewritableArray(sourceCode, node) {
+    const command = sourceCode.getCommandName(node);
+    if (command === null || !MAPFILE_COMMANDS.has(command))
+        return undefined;
+    if (node.assigns.length > 0)
+        return undefined;
+    const words = node.args.slice(1).map((word) => sourceCode.resolveWordText(word));
+    if (words.length === 0 || words.length > 2 || words[0] !== '-t')
+        return undefined;
+    const name = words.length === 2 ? words[1] : DEFAULT_ARRAY;
+    return name !== null && IDENTIFIER.test(name) ? name : undefined;
+}
+/**
+ * The `sh/compat/no-mapfile` rule module.
+ *
+ * @internal
+ */
+export const noMapfile = createCompatRule({
+    name: 'compat/no-mapfile',
+    feature: 'mapfile',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow `mapfile` and `readarray` when the target shell lacks them',
+        },
+        messages: {
+            mapfile: '`{{command}}` needs {{required}}, but this file targets {{target}}. Read the lines with a `while IFS= read -r` loop instead.',
+            useReadLoop: 'Replace with a `while IFS= read -r` loop that appends each line to `{{array}}` (the loop also sets `REPLY` to the empty string).',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const arraysAvailable = sourceCode.dialect !== 'posix';
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true)
+                    return;
+                const command = invoked.effective.text;
+                if (!MAPFILE_COMMANDS.has(command))
+                    return;
+                const array = arraysAvailable ? rewritableArray(sourceCode, node) : undefined;
+                context.report({
+                    node,
+                    messageId: 'mapfile',
+                    data: { ...gate, command },
+                    suggest: array === undefined
+                        ? []
+                        : [
+                            {
+                                messageId: 'useReadLoop',
+                                data: { array },
+                                fix: (fixer) => fixer.replaceText(node, readLoop(array)),
+                            },
+                        ],
+                });
+            },
+        };
+    },
+});

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

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

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

@@ -0,0 +1,44 @@
+/**
+ * `sh/compat/no-nameref`: reports namerefs (`declare -n`, `typeset -n`,
+ * `local -n`) in files whose target shell lacks them, that is, Bash older
+ * than 4.3 (macOS's stock `/bin/bash` is 3.2) and POSIX sh.
+ *
+ * Bash 4.2 and older reject `-n` as an invalid option, so the reference is
+ * never made and every assignment through it lands in a variable of its own
+ * name instead. The message suggests the portable alternative for the
+ * target: in Bash, assign by name with `printf -v "$name" '%s' "$value"`
+ * and read by name with `${!name}`, both available in Bash 3.2; in POSIX
+ * sh, which has neither, use `eval`.
+ *
+ * What is read: `declare`/`typeset`/`local` option clusters containing `n`
+ * (`-n`, `-rn`), found as `declarationFlagVisitor` defines. The report is on
+ * the option word.
+ */
+import { createCompatRule } from './create-compat-rule.js';
+import { DECLARATION_AND_LOCAL_COMMANDS, declarationFlagVisitor } from './declaration-options.js';
+/**
+ * The `sh/compat/no-nameref` rule module.
+ *
+ * @internal
+ */
+export const noNameref = createCompatRule({
+    name: 'compat/no-nameref',
+    feature: 'nameref',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow namerefs (`declare -n`, `local -n`) when the target shell lacks them',
+        },
+        messages: {
+            nameref: '`{{command}} -n` needs {{required}}, but this file targets {{target}}. Pass the variable name instead: assign through it with `printf -v "$name" \'%s\' "$value"` and read it with `${!name}`.',
+            namerefPosix: '`{{command}} -n` needs {{required}}, but this file targets {{target}}. Pass the variable name instead and use `eval`: assign with `eval "$name=\\$value"` and read with `eval "value=\\$$name"`, after checking that the name is a valid identifier.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        const messageId = sourceCode.dialect === 'posix' ? 'namerefPosix' : 'nameref';
+        return declarationFlagVisitor(sourceCode, 'n', (node, command) => {
+            context.report({ node, messageId, data: { ...gate, command } });
+        }, DECLARATION_AND_LOCAL_COMMANDS);
+    },
+});

package/dist/rules/compat/no-negative-array-index.d.ts

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