@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/docs/rules/compat/no-lastpipe-semantics.md

@@ -0,0 +1,73 @@
+# `sh/compat/no-lastpipe-semantics`
+
+Disallow `shopt -s lastpipe` in scripts whose target shell lacks the option: Bash older than 4.2,
+including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+`lastpipe` arrived in Bash 4.2 (Bash NEWS for 4.2: "a new `lastpipe` shell option"). It runs the last command of a pipeline in the current shell. Bash 3.2 has no such option: `shopt` fails with `invalid shell option name`, and the last command keeps running in a subshell, so a `cmd | while read …; do total=…; done` loop silently loses its assignments.
+
+The rule reports a `shopt` command (also through `builtin` or `command`) whose options, up to the first operand, include `-s` and which names `lastpipe`; the report is on the `lastpipe` word. `shopt -u lastpipe`, a query (`shopt lastpipe`), `shopt -o` (which names `set -o` options) and a name that is not static are not reported.
+
+The portable alternative is process substitution: `while read -r line; do …; done < <(cmd)` keeps the loop in the current shell on every Bash that has process substitution. Process substitution is not POSIX, so for `dialect: "posix"` the message suggests a temporary file (`cmd > "$tmp"`, then `done < "$tmp"`) or a here-document instead. It hides `cmd`'s exit status, though: the pipeline's status was the loop's (or, with `pipefail`, the first failure), and with `< <(cmd)` a failing `cmd` is invisible to the script, so check it another way (for example, write `cmd`'s output to a temporary file and test `cmd`'s status before reading it).
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.2`.
+- `dialect: "posix"`: reports at any `shellVersion`.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-lastpipe-semantics': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+```sh
+shopt -s lastpipe
+cmd | while read -r line; do total=$line; done
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+while read -r line; do total=$line; done < <(cmd)
+```
+
+With `shellVersion: "4.2"` or newer, or with no `shellVersion`, the original forms are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.2, or leave
+`shellVersion` unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck warns that variables assigned in the last pipeline element are lost (SC2030/SC2031), and understands `shopt -s lastpipe` for that purpose, but it cannot target a Bash version, so it cannot report the option for a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-let.md

@@ -0,0 +1,78 @@
+# `sh/compat/no-let`
+
+Disallow the `let` builtin in scripts that target POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+POSIX lists `let` among the command names whose results are unspecified ([Shell Command Language, section 2.9.1.4](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_19_09_01_04)). dash, the `/bin/sh` of Debian and Ubuntu, has no such command: `let n=1+2` fails with `let: not found` and status 127, and `n` stays unset. Under `set -e` that stops the script.
+
+`bash --posix` and BusyBox ash both accept `let`, so a script can pass on them and still fail on dash.
+
+Under `dialect: "posix"` the parser reads `let` as an ordinary command, and the rule reports a command whose effective name is `let`, after following wrappers such as `command`. It reports the `let` word. `command -v let` only asks about the word and is not reported. A use only a shell with a version variable can reach is not reported either, such as the body of `if [ -n "${BASH_VERSION-}" ]`, because dash never runs it; [version compatibility](../../compat.md#a-branch-for-one-shell) lists the shapes recognized.
+
+A function named `let` anywhere in the file exempts a call that names it directly, since dash can then run that function. This is only a name check across the whole file: it ignores execution order and does not prove the function exists at the call. Each of these stays silent, and the `let` call still fails on dash with `let: not found` and status 127:
+
+- A call that runs before the definition.
+- A definition in a branch that is not taken.
+- A definition in a subshell, or in a function that is never called.
+- A definition removed by a later `unset -f let`.
+
+A call through a wrapper gets no exemption and is reported. `command let n=1` skips the function and fails with status 127, as does `env let n=1`, and dash has no `builtin` at all.
+
+The portable alternative is arithmetic expansion, `n=$((1 + 2))`. The rule offers no suggestion, because `let` sets its exit status from the value of its last expression and an assignment does not, so the rewrite can change what `set -e` or an `if` sees.
+
+This is a POSIX-only gate. Every Bash has `let`, so whether the rule reports depends only on `dialect`, as described in [version compatibility](../../compat.md):
+
+- `dialect: "posix"`: reports at any `shellVersion`.
+- `dialect: "bash"` (the default), `"bats"`, `"mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'posix' },
+  rules: {
+    'sh/compat/no-let': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix", "findings": 2} -->
+```sh
+let n=1+2
+let "m = n * 2"
+```
+
+### Correct
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix"} -->
+```sh
+n=$((1 + 2))
+m=$((n * 2))
+```
+
+## When not to use it
+
+Turn the rule off when your scripts only ever run where `let` exists, such as under Bash or BusyBox ash, and set `dialect` to match if you can.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck reports this construct as SC3039 for a script whose shebang says `sh`. This rule reports it for the dialect you configure, whatever the shebang says, and at the severity you choose.

package/docs/rules/compat/no-mapfile.md

@@ -0,0 +1,118 @@
+# `sh/compat/no-mapfile`
+
+Disallow the `mapfile` builtin and its synonym `readarray` in scripts whose target shell lacks
+them: Bash older than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
+
+| Configs | Fixable     | Languages |
+| ------- | ----------- | --------- |
+| `bash-3.2`, `posix-portable` | suggestions | `sh/sh`   |
+
+## Rule details
+
+`mapfile` and `readarray` arrived in Bash 4.0. On Bash 3.2 neither is a builtin, so the shell
+looks for an external command of that name, fails with `command not found`, and the array is
+never filled.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
+- `dialect: "posix"`: reports at any `shellVersion`.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+The rule reports every command whose effective command is `mapfile` or `readarray`, after
+following transparent wrappers such as `command` and `builtin`. The report is on the whole
+command.
+
+### Suggestion
+
+For `mapfile -t NAME` or `readarray -t NAME`, written directly (no wrapper and no leading
+`VAR=value`) in a Bash or Bats file, the rule suggests a `while IFS= read -r` loop that fills
+the same array the same way:
+
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+mapfile -t lines < in.txt
+# becomes
+{ lines=(); while IFS= read -r || [ -n "$REPLY" ]; do lines+=("$REPLY"); done; } < in.txt
+```
+
+- `|| [ -n "$REPLY" ]` keeps a last line that has no trailing newline, as `mapfile -t` does.
+- Reading with no variable name keeps each line unchanged, including leading and trailing
+  spaces and backslashes. The tradeoff is that `read` stores each line in `REPLY`, which
+  `mapfile` does not touch. After the loop, `REPLY` is the empty string, whatever it held
+  before. `REPLY` is `read`'s own default variable, so this overwrites less than a named loop
+  variable such as `line` would. If your script uses `REPLY` across this command, save it
+  first or edit the loop.
+- The brace group keeps the replacement a single command, so a redirection (`< in.txt`,
+  `<<< "$text"`, `< <(cmd)`) or a pipeline (`cmd | mapfile -t lines`) still feeds the loop.
+- With no `NAME`, `mapfile` fills `MAPFILE`, and so does the loop.
+
+Other forms are reported without a suggestion, because no loop reproduces them exactly or the
+target has no arrays at all: `mapfile` without `-t` (each element keeps its newline), any other
+option (`-d`, `-n`, `-O`, `-s`, `-u`, `-C`), an array name that is not static, a leading
+assignment, a wrapper, and every file under `dialect: "posix"`.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-mapfile': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+```sh
+mapfile -t lines < in.txt          # mapfile needs Bash 4.0
+git ls-files | readarray -t files  # readarray is the same builtin
+command mapfile -t lines < in.txt  # reached through the command wrapper
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+{ lines=(); while IFS= read -r || [ -n "$REPLY" ]; do lines+=("$REPLY"); done; } < in.txt
+
+while IFS= read -r line; do
+  printf '%s\n' "$line"
+done < in.txt
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "4.0"} -->
+```sh
+mapfile -t lines < in.txt
+```
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck reports Bash-only features in scripts it treats as POSIX sh (the SC3xxx checks), but
+it cannot target a Bash version, so it cannot report `mapfile` in a script that must run on
+Bash 3.2. shellcheck 0.11.0 does recommend `mapfile` or `read -a` over `a=($(cmd))` splitting (SC2207) under `-s bash`, which is
+the opposite advice for a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-nameref.md

@@ -0,0 +1,81 @@
+# `sh/compat/no-nameref`
+
+Disallow namerefs (`declare -n`, `typeset -n`, `local -n`) in scripts whose target shell lacks
+them: Bash older than 4.3, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Namerefs arrived in Bash 4.3 (Bash NEWS for 4.3). Bash 4.2 and older reject `-n` with `local: -n: invalid option`, so the reference is never made, and an assignment through it sets a variable of its own name instead of the caller's.
+
+The rule reads the options of every `declare`, `typeset` and `local` command, up to the first operand, as the builtin does. An option word reports when it is a `-` cluster containing `n` (`-n`, `-rn`); the report is on that word. `export -n`, which removes the export attribute and is in every Bash, is not read, and neither is an `-n` after the first operand or after `--`.
+
+The portable alternative is to pass the variable's name and use it directly. On Bash, assign through the name with `printf -v "$name" '%s' "$value"` and read it with `${!name}`; both are in Bash 3.2. A POSIX target has neither, so its message suggests `eval "$name=\$value"` to assign and `eval "value=\$$name"` to read, after checking that the name is a valid identifier, since `eval` runs whatever the name contains.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.3`.
+- `dialect: "posix"`: reports at any `shellVersion`, with the `eval` advice.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-nameref': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+set_result() {
+  local -n out=$1
+  out=done
+}
+declare -n alias=target
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+set_result() {
+  printf -v "$1" '%s' done
+}
+read_by_name() {
+  printf '%s\n' "${!1}"
+}
+```
+
+With `shellVersion: "4.3"` or newer, or with no `shellVersion`, namerefs are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+Under `-s sh`, shellcheck 0.11.0 reports the command, not the option: `local -n` draws SC3043 (`local` is undefined in POSIX sh), and `declare -n` and `typeset -n` draw SC3044. Under `-s bash` it reports nothing for a nameref. It does not know which Bash release a script must run on, so it reports nothing for a nameref in a Bash 4.2 or 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-negative-array-index.md

@@ -0,0 +1,87 @@
+# `sh/compat/no-negative-array-index`
+
+Disallow negative indexed-array subscripts written as a literal (`${arr[-1]}`, `arr[-1]=x`) in scripts
+whose target shell lacks them: Bash older than 4.3, including the Bash 3.2 that macOS ships as
+`/bin/bash`, and POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | suggestions | `sh/sh`   |
+
+## Rule details
+
+Negative subscripts count back from the end of an indexed array. Bash NEWS for 4.3 introduces assigning, referencing and unsetting elements this way; Bash 4.2 already reads `${arr[-1]}`, but rejects the element length `${#arr[-1]}`, assigning and unsetting with `bad array subscript` (see the [evidence table](../../compat.md#evidence)). The rule uses 4.3, the first release where every use works, so a plain `${arr[-1]}` read at `shellVersion: "4.2"` is reported although 4.2 accepts it. Bash 3.2 fails with `bad array subscript`.
+
+The rule reports a subscript that is a minus sign followed by a static decimal integer, on an expansion (`${arr[-1]}`, `${#arr[-1]}`) or on an assignment (`arr[-1]=x`). It also reports unsetting an element, `unset arr[-1]` (quoted or not, also after options such as `-v` and after `--`), which Bash NEWS for 4.3 covers; that form has no suggestion. It does not report `-0` (zero, which Bash 3.2 accepts), `${v: -1}` (a substring offset, not a subscript), a computed `-$n`, or a parenthesized `-(1)`. An associative array's `-1` key is a plain string; the rule cannot tell and reports it, but associative arrays need Bash 4.0 anyway.
+
+### Suggestion
+
+For a bare `${NAME[-N]}` read, the rule suggests counting from the length:
+
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+echo "${arr[-1]}"
+# becomes
+echo "${arr[$((${#arr[@]}-1))]}"
+```
+
+Negative subscripts count back from the highest assigned index plus one, while `${#arr[@]}` counts set elements, so the two agree only for an array without holes. Other forms are reported without a suggestion.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.3`.
+- `dialect: "posix"`: reports nothing in practice, because POSIX sh has no arrays, because the POSIX parser rejects it with a parse error before any rule runs.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-negative-array-index': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+last=${items[-1]}
+items[-1]=done
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+last=${items[$((${#items[@]}-1))]}
+items[$((${#items[@]}-1))]=done
+```
+
+With `shellVersion: "4.3"` or newer, or with no `shellVersion`, the original forms are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave
+`shellVersion` unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck reports negative array subscripts in scripts it treats as POSIX sh (SC3054), but it cannot target a Bash version, so it cannot report `${arr[-1]}` for a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-nounset-empty-array.md

@@ -0,0 +1,103 @@
+# `sh/compat/no-nounset-empty-array`
+
+Disallow whole-array expansions (`"${a[@]}"`, `${a[*]}`) in a script that turns on `set -u`, when
+its target shell aborts on an empty array: Bash older than 4.4, including the Bash 3.2 that macOS
+ships as `/bin/bash`.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | suggestions | `sh/sh`   |
+
+## Rule details
+
+The syntax is in every Bash, but through Bash 4.3, expanding an empty array while `nounset` is on aborts the script with `a[@]: 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: a script that runs under `set -euo pipefail` and passes an optional, possibly empty, argument array dies on macOS `/bin/bash`.
+
+The rule reports when both of these hold:
+
+- the file turns `nounset` on somewhere: a `set` command that enables it (`set -u`, `set -eu`, `set -o nounset`), or a shebang that passes the flag (`#!/bin/bash -eu`, or `#!/usr/bin/env -S bash -eu`). Where in the file that happens is not considered, because a function defined before `set -u` can run after it;
+- an expansion is `${name[@]}` or `${name[*]}` with no operator, in quotes or not.
+
+A linter cannot know whether an array is empty when the script runs, so every such expansion reports. The check is file-wide: it ignores `set +u`, so an expansion after the file turned `nounset` back off still reports. It also reports arrays that are visibly non-empty (`a=(x); "${a[@]}"`) and arrays already guarded by a length test (`[[ ${#a[@]} -eq 0 ]] && return`). Its message therefore says "If this array is empty", not that it is. These forms work on an empty array under `set -u` in every Bash, and are not reported: `${#a[@]}`, `${!a[@]}`, `${a[@]-default}`, and the guarded forms below, including an expansion inside `${a[@]+…}` or `${a[@]:+…}` of the same array. 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.
+
+The rule offers a guarded spelling as a suggestion when the word is exactly the quoted expansion:
+
+- `"${a[@]}"` becomes `${a[@]+"${a[@]}"}`, which gives no words for an empty array and the same words otherwise;
+- `"${a[*]}"` becomes `"${a[*]-}"`, which gives the one empty word that `"${a[*]}"` gives for an empty array on Bash 4.4, and the same joined word otherwise.
+
+An unquoted expansion, or one inside a longer word, reports with no suggestion. POSIX sh has no arrays; under `dialect: "posix"` the parser rejects array syntax, so this rule never sees one there.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.4`.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+### Suggestion
+
+A suggestion rewrites the quoted `[@]` form:
+
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+set -u
+run_tool "${extra[@]}"
+# becomes
+set -u
+run_tool ${extra[@]+"${extra[@]}"}
+```
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-nounset-empty-array': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+set -euo pipefail
+extra=()
+run_tool "${extra[@]}"
+echo "args: ${extra[*]}"
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+set -euo pipefail
+extra=()
+run_tool ${extra[@]+"${extra[@]}"}
+echo "args: ${extra[*]-}"
+echo "count: ${#extra[@]}"
+```
+
+With `shellVersion: "4.4"` or newer, with no `shellVersion`, or in a file that never turns on
+`set -u`, whole-array expansions are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.4, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck 0.11.0 reports nothing for an empty array expanded under `set -u` (`set -u; a=(); echo "${a[@]}"`) under `-s bash`. Under `-s sh` it reports only the array syntax (SC3030, SC3054), not the abort. An empty array under `set -u` is valid Bash from 4.4 on, and shellcheck does not know which Bash release a script must run on. This rule exists for an older target.

package/docs/rules/compat/no-parameter-transformation.md

@@ -0,0 +1,94 @@
+# `sh/compat/no-parameter-transformation`
+
+Disallow the parameter transformations `${v@op}` in scripts whose target shell lacks the
+operator: `@Q`, `@E`, `@P`, `@A` and `@a` need Bash 4.4, `@U`, `@u`, `@L` and `@K` need Bash 5.1,
+and `@k` needs Bash 5.2. POSIX sh has none of them.
+
+| Configs                      | Fixable     | Languages |
+| ---------------------------- | ----------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Bash 4.4 added the first transformations (Bash NEWS for 4.4), Bash 5.1 the case operators and `@K`, and Bash 5.2 `@k`. A release that lacks the operator fails with `${v@Q}: bad substitution` at the moment the word is expanded. The boundary of each operator was checked against real shells; see [Evidence](../../compat.md#evidence).
+
+The rule reads every parameter expansion whose operator is `@` followed by one of the ten letters. It reports when the file's target lacks that letter's release; the report is on the whole expansion. A target of Bash 5.0, for example, gets reports for `@U` but not for `@Q`. An `@` inside another expansion's word (`${v:-@Q}`) and text in single quotes are not expansions and are not reported.
+
+The message names a portable alternative where one exists for the target:
+
+- `@Q`: `printf '%q' "$v"`. It quotes differently (`a\ b` instead of `'a b'`), but `eval` reads it back as the same value. Not offered for a POSIX target, whose `printf` has no `%q`.
+- `@E`: `printf '%b' "$v"`.
+- `@A`: `declare -p v`. It prints the declaration rather than expanding to it, so capture it (`s=$(declare -p v)`) and `eval "$s"` to re-create the variable. Not offered for a POSIX target.
+- `@U`, `@u`, `@L`: the Bash 4.0 case expansions `"${v^^}"`, `"${v^}"`, `"${v,,}"` for a target from 4.0 to 5.0, or a `tr` conversion for an older Bash.
+- `@P`, `@a`, `@K`, `@k`: no equivalent expansion; the message says so.
+
+Under `dialect: "posix"` the parser itself rejects `${v@op}`, so a POSIX file that uses it fails to parse and this rule does not run on it.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports an operator when `shellVersion` is older than its release.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-parameter-transformation': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+
+```sh
+log "running ${cmd@Q}"
+upper=${name@U}
+printf '%s\n' "${args[@]@K}"
+```
+
+With `shellVersion: "5.0"`, only the case operator reports:
+
+<!-- example: {"dialect": "bash", "shellVersion": "5.0", "findings": 1} -->
+
+```sh
+log "running ${cmd@Q}"
+upper=${name@U}
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+log "running $(printf '%q' "$cmd")"
+upper=$(printf '%s' "$name" | tr '[:lower:]' '[:upper:]')
+```
+
+With `shellVersion: "5.2"` or newer, or with no `shellVersion`, every transformation is fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on a Bash older than the operators they use, or
+leave `shellVersion` unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck 0.11.0 reports nothing for `${v@U}`, `${v@Q}` or `${v@a}` under either `-s sh` or `-s bash` (a variable that is never assigned still draws its unrelated SC2154). So shellcheck gives no finding for these expansions in a POSIX sh script or in a Bash target older than the operator's release. This rule exists for those targets.