@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

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>;

package/dist/rules/compat/no-negative-array-index.js

@@ -0,0 +1,123 @@
+/**
+ * `sh/compat/no-negative-array-index`: reports negative indexed-array
+ * subscripts written as a literal (`${arr[-1]}`, `arr[-2]=x`, `${#arr[-1]}`)
+ * 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 3.2 evaluates `-1` as the arithmetic value minus one and fails with
+ * "bad array subscript", so the read yields nothing and the assignment is
+ * refused. The message suggests the portable alternative: count from the
+ * array length, `${arr[$((${#arr[@]}-1))]}`.
+ *
+ * The suggestion rewrites exactly a bare `${NAME[-N]}` read to
+ * `${NAME[$((${#NAME[@]}-N))]}`. Negative subscripts count back from the
+ * highest assigned index plus one, while `${#NAME[@]}` counts set elements,
+ * so the two agree only for arrays without holes; the suggestion message says
+ * so. Assignments and other expansion forms are reported without a suggestion.
+ *
+ * What is read: an `Index` that is a unary minus applied to a static decimal
+ * integer, on a `ParamExp` or an `Assign`. A computed subscript such as
+ * `-$n` is not a literal and is not reported, and neither is `-0`, which is
+ * zero. A `ParamExp` or `Assign` subscript is read from the syntax tree, so
+ * its operand can be any arithmetic node (`-(1)` holds a parenthesized one);
+ * only a plain word is resolved.
+ *
+ * Unsetting an element (`unset arr[-1]`, quoted or not) is reported from the
+ * `unset` command's operand text, since the parser keeps that operand as an
+ * ordinary word; option words (`-v`) never match an element name.
+ */
+import { Minus } 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';
+/** A bare negative-subscript read, the only shape the suggestion rewrites. */
+const BARE_READ = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\[\s*-\s*(\d+)\s*\]\}$/u;
+/**
+ * The wrappers followed to find an `unset` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** An `unset` operand naming an element by a literal negative subscript. */
+const UNSET_NEGATIVE = /^[A-Za-z_][A-Za-z0-9_]*\[\s*-\s*\d+\s*\]$/u;
+/**
+ * The `sh/compat/no-negative-array-index` rule module.
+ *
+ * @internal
+ */
+export const noNegativeArrayIndex = createCompatRule({
+    name: 'compat/no-negative-array-index',
+    feature: 'negativeArrayIndex',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow negative array subscripts (`${arr[-1]}`) when the target shell lacks them',
+        },
+        messages: {
+            negativeIndex: 'Negative array subscripts need {{required}}, but this file targets {{target}}. Count from the length instead, for example `${arr[$((${#arr[@]}-1))]}`.',
+            useArrayLength: 'Replace with `${{{name}}[$((${#{{name}}[@]}-{{n}}))]}` (the two differ only for an array with unset elements).',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        /** Whether `index` is a unary minus on a static decimal integer. */
+        function isNegativeLiteral(index) {
+            if (index?.type !== 'UnaryArithm' || index.op !== Minus)
+                return false;
+            const operand = index.x;
+            // The operand may be any arithmetic node (`-(1)` holds a ParenArithm);
+            // only a Word can be resolved, and `-0` is zero, not a negative index.
+            if (operand?.type !== 'Word')
+                return false;
+            const digits = sourceCode.resolveWordText(operand) ?? '';
+            return /^\d+$/u.test(digits) && /[1-9]/u.test(digits);
+        }
+        return {
+            CallExpr(node) {
+                const invoked = sourceCode.resolveInvokedCommand(node, {
+                    transparentWrappers: TRANSPARENT_WRAPPERS,
+                });
+                if (invoked?.effective.static !== true || invoked.effective.text !== 'unset')
+                    return;
+                // `chainIndices` index `node.args` directly, so slice before filtering.
+                for (const word of node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1)) {
+                    // An unquoted `a[-1]` holds a glob bracket, so it is not "static"; its
+                    // written text is what names the element.
+                    const text = sourceCode.resolveWordText(word) ?? sourceCode.getText(word);
+                    if (text === '--')
+                        continue;
+                    if (UNSET_NEGATIVE.test(text) && /[1-9]/u.test(text)) {
+                        context.report({ node: word, messageId: 'negativeIndex', data: { ...gate } });
+                    }
+                }
+            },
+            ParamExp(node) {
+                if (!isNegativeLiteral(node.index))
+                    return;
+                const match = BARE_READ.exec(sourceCode.getText(node));
+                context.report({
+                    node,
+                    messageId: 'negativeIndex',
+                    data: { ...gate },
+                    suggest: match === null
+                        ? []
+                        : [
+                            {
+                                messageId: 'useArrayLength',
+                                data: { name: match[1], n: match[2] },
+                                fix: (fixer) => fixer.replaceText(node, `\${${match[1]}[$((\${#${match[1]}[@]}-${match[2]}))]}`),
+                            },
+                        ],
+                });
+            },
+            Assign(node) {
+                if (!isNegativeLiteral(node.index))
+                    return;
+                context.report({ node, messageId: 'negativeIndex', data: { ...gate } });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-nounset-empty-array.d.ts

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

package/dist/rules/compat/no-nounset-empty-array.js

@@ -0,0 +1,158 @@
+/**
+ * `sh/compat/no-nounset-empty-array`: reports whole-array expansions
+ * (`"${a[@]}"`, `${a[*]}`) in a file that turns on `set -u`, when its target
+ * shell is Bash older than 4.4 (macOS's stock `/bin/bash` is 3.2) or POSIX
+ * sh.
+ *
+ * The syntax is in every Bash, but through 4.3 expanding an empty array
+ * while `nounset` is on aborts the script with "unbound variable". Bash 4.4
+ * is the first release where it expands to nothing. This is the classic
+ * "works on Linux CI, breaks on a Mac" failure for a script that passes an
+ * optional, possibly empty, argument array under `set -euo pipefail`.
+ *
+ * The suggestion rewrites a word that is exactly `"${a[@]}"` to
+ * `${a[@]+"${a[@]}"}`, which expands to nothing for an empty array and to the
+ * same words otherwise, and a word that is exactly `"${a[*]}"` to
+ * `"${a[*]-}"`, which keeps the one (empty) word `"${a[*]}"` gives for an
+ * empty array. Other spellings (unquoted, or inside a longer word) are
+ * reported without one. POSIX sh has no arrays at all; under
+ * `dialect: "posix"` the parser rejects array syntax, so the rule never sees
+ * one there.
+ *
+ * What is read:
+ *
+ * - whether the file turns `nounset` on anywhere: a `set` command that
+ *   enables it (`set -u`, `set -eu`, `set -o nounset`), or a shebang that
+ *   passes the flag (`#!/bin/bash -eu`). Where in the file that happens is
+ *   not considered, since a function defined before `set -u` can run after
+ *   it;
+ * - every `${name[@]}` and `${name[*]}` with no operator, except inside
+ *   `${name[@]+…}` or `${name[@]:+…}` of the same array (the guard this rule
+ *   suggests), whose word Bash expands only when the array is set. `${#a[@]}`,
+ *   `${!a[@]}` and `${a[@]-default}` work on an empty array under `set -u` in
+ *   every Bash, so they are not reported. The slice `${a[@]:1}` and the
+ *   replacement `${a[@]/x/y}` were observed to work on Bash 3.2 to 4.1 and
+ *   fail only on 4.2 and 4.3, which a minimum-version gate cannot express, so
+ *   they are not reported either.
+ */
+import { AlternateUnset, AlternateUnsetOrNull } from 'sh-ast';
+import { createCompatRule } from './create-compat-rule.js';
+import { parseSetArguments, shebangOptionChanges } from '../set-options.js';
+/** A shell variable name. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+/**
+ * The guarded spelling of `"${name[subscript]}"`: `${name[@]+"${name[@]}"}`
+ * for `@` (no words for an empty array, the same words otherwise) and
+ * `"${name[*]-}"` for `*` (one empty word for an empty array, as Bash 4.4
+ * gives, and the same joined word otherwise).
+ */
+function guardedExpansion(name, subscript) {
+    return subscript === '@' ? `\${${name}[@]+"\${${name}[@]}"}` : `"\${${name}[*]-}"`;
+}
+/** Whether `changes` turn `nounset` on. */
+function enablesNounset(changes) {
+    return changes.some((change) => change.option === 'nounset' && change.enable);
+}
+/**
+ * The `sh/compat/no-nounset-empty-array` rule module.
+ *
+ * @internal
+ */
+export const noNounsetEmptyArray = createCompatRule({
+    name: 'compat/no-nounset-empty-array',
+    feature: 'nounsetEmptyArray',
+    meta: {
+        type: 'problem',
+        hasSuggestions: true,
+        docs: {
+            description: 'Disallow whole-array expansions under `set -u` when the target shell aborts on an empty array',
+        },
+        messages: {
+            emptyArray: 'If this array is empty, `${{{name}}[{{subscript}}]}` under `set -u` needs {{required}}, but this file targets {{target}}, where it aborts with "unbound variable". Guard it, for example `{{example}}`.',
+            guardExpansion: 'Replace with `{{replacement}}`.',
+        },
+    },
+    create(context, gate) {
+        const { sourceCode } = context;
+        let nounset = enablesNounset(shebangOptionChanges(sourceCode.text));
+        const candidates = [];
+        /** The `@` or `*` of a whole-array subscript, or `undefined`. */
+        function wholeArraySubscript(index) {
+            if (index?.type !== 'Word')
+                return undefined;
+            const text = sourceCode.resolveWordText(index) ?? sourceCode.getText(index);
+            return text === '@' || text === '*' ? text : undefined;
+        }
+        /**
+         * Whether `node` sits inside `${name[…]+…}` or `${name[…]:+…}` of the same
+         * array, as in the guard `${a[@]+"${a[@]}"}`: Bash expands that inner
+         * word only when the array is set, so it cannot abort.
+         */
+        function insideOwnGuard(node, name) {
+            for (let up = sourceCode.getParent(node); up !== undefined; up = sourceCode.getParent(up)) {
+                if (up.type === 'ParamExp' &&
+                    up.param?.value === name &&
+                    (up.exp?.op === AlternateUnset || up.exp?.op === AlternateUnsetOrNull)) {
+                    return true;
+                }
+            }
+            return false;
+        }
+        /**
+         * The quoted expansion `node` is when it is the whole of a word that is
+         * exactly `"${name[@]}"` or `"${name[*]}"`, or `undefined`.
+         */
+        function wholeQuotedWord(node) {
+            const quoted = sourceCode.getParent(node);
+            if (quoted?.type !== 'DblQuoted' || quoted.parts.length !== 1)
+                return undefined;
+            const word = sourceCode.getParent(quoted);
+            return word?.type === 'Word' && word.parts.length === 1 ? quoted : undefined;
+        }
+        return {
+            CallExpr(node) {
+                if (sourceCode.getCommandName(node) !== 'set')
+                    return;
+                const args = node.args.slice(1).map((word) => sourceCode.resolveWordText(word));
+                if (enablesNounset(parseSetArguments(args).changes))
+                    nounset = true;
+            },
+            ParamExp(node) {
+                const name = node.param?.value;
+                if (name === undefined || !IDENTIFIER.test(name))
+                    return;
+                if (node.exp !== undefined || node.slice !== undefined || node.repl !== undefined)
+                    return;
+                if (node.length || node.excl || node.width || node.isset || node.modifiers.length > 0) {
+                    return;
+                }
+                const subscript = wholeArraySubscript(node.index);
+                if (subscript === undefined || insideOwnGuard(node, name))
+                    return;
+                candidates.push({ node, name, subscript });
+            },
+            'File:exit'() {
+                if (!nounset)
+                    return;
+                for (const { node, name, subscript } of candidates) {
+                    const replacement = guardedExpansion(name, subscript);
+                    const quoted = wholeQuotedWord(node);
+                    context.report({
+                        node,
+                        messageId: 'emptyArray',
+                        data: { ...gate, name, subscript, example: replacement },
+                        suggest: quoted === undefined
+                            ? []
+                            : [
+                                {
+                                    messageId: 'guardExpansion',
+                                    data: { replacement },
+                                    fix: (fixer) => fixer.replaceText(quoted, replacement),
+                                },
+                            ],
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/compat/no-parameter-transformation.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Message ids this rule reports with: `transformation` names an alternative,
+ * `transformationNoAlternative` has none to offer.
+ *
+ * @internal
+ */
+export type NoParameterTransformationMessageId = 'transformation' | 'transformationNoAlternative';
+/**
+ * The `sh/compat/no-parameter-transformation` rule module.
+ *
+ * @internal
+ */
+export declare const noParameterTransformation: import("../define-shell-rule.js").ShellRule<[], NoParameterTransformationMessageId>;

package/dist/rules/compat/no-parameter-transformation.js

@@ -0,0 +1,123 @@
+/**
+ * `sh/compat/no-parameter-transformation`: reports the parameter
+ * transformations `${v@op}` in files whose target shell lacks the operator.
+ * The minimum Bash depends on the operator:
+ *
+ * - `@Q`, `@E`, `@P`, `@A`, `@a`: Bash 4.4;
+ * - `@U`, `@u`, `@L` and `@K`: Bash 5.1;
+ * - `@k`: Bash 5.2.
+ *
+ * POSIX sh has none of them. An older Bash fails with "bad substitution"
+ * when the word is expanded. The message names a portable alternative where
+ * one exists for the target: `printf '%q'` for `@Q` (it quotes differently,
+ * but `eval` reads it back as the same value), `printf '%b'` for `@E`,
+ * `declare -p` for `@A`, and for the case operators the Bash 4.0 case
+ * expansions (`${v^^}`, `${v^}`, `${v,,}`) on a Bash that has them, or `tr`
+ * otherwise. `printf '%q'` and `declare -p` are not POSIX, so a POSIX target
+ * is not offered them.
+ *
+ * What is read: a `ParamExp` whose expansion operator is `@` followed by one
+ * of the letters above. The report is on the whole expansion.
+ */
+import { OtherParamOps } from 'sh-ast';
+import { createMultiFeatureCompatRule } from './create-compat-rule.js';
+import { TO_LOWER, TO_UPPER, trExample } from './no-case-modification.js';
+import { isFeatureAvailable } from './version-gates.js';
+/** Each operator letter's gate-table row. */
+const OPERATOR_FEATURES = new Map([
+    ['Q', 'parameterTransformation'],
+    ['E', 'parameterTransformation'],
+    ['P', 'parameterTransformation'],
+    ['A', 'parameterTransformation'],
+    ['a', 'parameterTransformation'],
+    ['U', 'parameterTransformationCase'],
+    ['u', 'parameterTransformationCase'],
+    ['L', 'parameterTransformationCase'],
+    ['K', 'parameterTransformationQuotedKeys'],
+    ['k', 'parameterTransformationKeys'],
+]);
+/** The case operators and their equivalents. */
+const CASE_EQUIVALENTS = new Map([
+    ['U', { expansion: '^^', upper: true, all: true }],
+    ['u', { expansion: '^', upper: true, all: false }],
+    ['L', { expansion: ',,', upper: false, all: true }],
+]);
+/**
+ * The `sh/compat/no-parameter-transformation` rule module.
+ *
+ * @internal
+ */
+export const noParameterTransformation = createMultiFeatureCompatRule({
+    name: 'compat/no-parameter-transformation',
+    features: [...new Set(OPERATOR_FEATURES.values())],
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow parameter transformations (`${v@Q}`, `${v@U}` and the others) when the target shell lacks the operator',
+        },
+        messages: {
+            transformation: '`${…@{{operator}}}` needs {{required}}, but this file targets {{target}}. Use {{alternative}} instead.',
+            transformationNoAlternative: '`${…@{{operator}}}` needs {{required}}, but this file targets {{target}}, which has no equivalent expansion; restructure the code that needs it.',
+        },
+    },
+    create(context, gates) {
+        const { sourceCode, languageOptions } = context;
+        const posix = sourceCode.dialect === 'posix';
+        const caseExpansions = isFeatureAvailable('caseModification', languageOptions);
+        /** The alternative shown for `operator` on `name`, or `undefined`. */
+        function alternative(operator, name) {
+            const value = `"$${name}"`;
+            if (operator === 'Q') {
+                return posix
+                    ? undefined
+                    : `\`printf '%q' ${value}\` (it quotes differently, but \`eval\` reads it back as the same value)`;
+            }
+            if (operator === 'E')
+                return `\`printf '%b' ${value}\``;
+            if (operator === 'A') {
+                return posix
+                    ? undefined
+                    : `\`declare -p ${name}\` (it prints the declaration; capture it and \`eval\` it to re-create the variable)`;
+            }
+            const equivalent = CASE_EQUIVALENTS.get(operator);
+            if (equivalent === undefined)
+                return undefined;
+            if (caseExpansions)
+                return `\`"\${${name}${equivalent.expansion}}"\``;
+            const example = trExample(name, {
+                operator: equivalent.expansion,
+                all: equivalent.all,
+                tr: equivalent.upper ? TO_UPPER : TO_LOWER,
+            });
+            return `\`tr\`, for example ${example}`;
+        }
+        return {
+            ParamExp(node) {
+                const { exp } = node;
+                if (exp?.op !== OtherParamOps || exp.word === undefined)
+                    return;
+                const operator = sourceCode.resolveWordText(exp.word);
+                if (operator === null)
+                    return;
+                const feature = OPERATOR_FEATURES.get(operator);
+                const gate = feature === undefined ? undefined : gates.get(feature);
+                if (gate === undefined)
+                    return;
+                const advice = alternative(operator, node.param?.value ?? 'v');
+                if (advice === undefined) {
+                    context.report({
+                        node,
+                        messageId: 'transformationNoAlternative',
+                        data: { ...gate, operator },
+                    });
+                    return;
+                }
+                context.report({
+                    node,
+                    messageId: 'transformation',
+                    data: { ...gate, operator, alternative: advice },
+                });
+            },
+        };
+    },
+});

package/dist/rules/compat/no-pipe-all.d.ts

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