@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-globstar`
 
-Disallow `shopt -s globstar` in scripts whose target shell lacks the option: Bash older than 4.0,
+Disallow `shopt -s globstar` in scripts that must support a shell lacking the option: Bash older than 4.0,
 including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -18,19 +18,19 @@ The portable alternative is `find`, for example `find dir -name '*.txt'`.
 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`, because POSIX sh has no `shopt`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.0`.
+- `dialect: "posix"`: reports regardless of Bash releases, because POSIX sh has no `shopt`.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-globstar': 'error',
   },
@@ -41,9 +41,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 1} -->
 ```sh
 shopt -s nullglob globstar
 for f in src/**/*.sh; do lint "$f"; done
@@ -51,19 +51,19 @@ for f in src/**/*.sh; do lint "$f"; done
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 find src -name '*.sh' -exec lint {} \;
 shopt -s nullglob
 ```
 
-With `shellVersion: "4.0"` or newer, or with no `shellVersion`, `globstar` is fine.
+With `minBashVersion: "4.0"` or newer, or with no `minBashVersion`, `globstar` is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -71,4 +71,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck reports `shopt` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `globstar` for a Bash 3.2 target. This rule exists for that target.
+shellcheck reports `shopt` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `globstar` for a script that must support Bash 3.2. This rule checks that support requirement.

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-lastpipe-semantics`
 
-Disallow `shopt -s lastpipe` in scripts whose target shell lacks the option: Bash older than 4.2,
+Disallow `shopt -s lastpipe` in scripts that must support a shell lacking the option: Bash older than 4.2,
 including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -18,19 +18,19 @@ The portable alternative is process substitution: `while read -r line; do …; d
 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`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.2`.
+- `dialect: "posix"`: reports regardless of Bash releases.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-lastpipe-semantics': 'error',
   },
@@ -41,9 +41,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 1} -->
 ```sh
 shopt -s lastpipe
 cmd | while read -r line; do total=$line; done
@@ -51,23 +51,23 @@ cmd | while read -r line; do total=$line; done
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "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.
+With `minBashVersion: "4.2"` or newer, or with no `minBashVersion`, 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.
+`minBashVersion` 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.
+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 check support for a minimum Bash version, so it cannot report the option for a script that must support Bash 3.2. This rule checks that support requirement.

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

@@ -27,12 +27,12 @@ The portable alternative is arithmetic expansion, `n=$((1 + 2))`. The rule offer
 
 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: "posix"`: reports regardless of Bash releases.
 - `dialect: "bash"` (the default), `"bats"`, `"mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-mapfile`
 
-Disallow the `mapfile` builtin and its synonym `readarray` in scripts whose target shell lacks
+Disallow the `mapfile` builtin and its synonym `readarray` in scripts that must support a shell lacking
 them: Bash older than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable     | Languages |
@@ -16,9 +16,9 @@ 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`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.0`.
+- `dialect: "posix"`: reports regardless of Bash releases.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 The rule reports every command whose effective command is `mapfile` or `readarray`, after
@@ -31,7 +31,7 @@ For `mapfile -t NAME` or `readarray -t NAME`, written directly (no wrapper and n
 `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"} -->
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "minBashVersion": "3.2"} -->
 
 ```sh
 mapfile -t lines < in.txt
@@ -57,12 +57,12 @@ assignment, a wrapper, and every file under `dialect: "posix"`.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-mapfile': 'error',
   },
@@ -73,9 +73,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "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
@@ -84,9 +84,9 @@ command mapfile -t lines < in.txt  # reached through the command wrapper
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 { lines=(); while IFS= read -r || [ -n "$REPLY" ]; do lines+=("$REPLY"); done; } < in.txt
 
@@ -95,16 +95,16 @@ while IFS= read -r line; do
 done < in.txt
 ```
 
-With `shellVersion: "4.0"` or newer, or with no `shellVersion`:
+With `minBashVersion: "4.0"` or newer, or with no `minBashVersion`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "4.0"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "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`
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -113,6 +113,6 @@ eslint-sh is a convention and contract linter: a policy layer, where shellcheck
 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
+it cannot check support for a minimum 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.
+the opposite advice for a script that must support Bash 3.2. This rule checks that support requirement.

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-nameref`
 
-Disallow namerefs (`declare -n`, `typeset -n`, `local -n`) in scripts whose target shell lacks
+Disallow namerefs (`declare -n`, `typeset -n`, `local -n`) in scripts that must support a shell lacking
 them: Bash older than 4.3, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -18,19 +18,19 @@ The portable alternative is to pass the variable's name and use it directly. On
 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.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.3`.
+- `dialect: "posix"`: reports regardless of Bash releases, with the `eval` advice.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-nameref': 'error',
   },
@@ -41,9 +41,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 2} -->
 ```sh
 set_result() {
   local -n out=$1
@@ -54,9 +54,9 @@ declare -n alias=target
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 set_result() {
   printf -v "$1" '%s' done
@@ -66,11 +66,11 @@ read_by_name() {
 }
 ```
 
-With `shellVersion: "4.3"` or newer, or with no `shellVersion`, namerefs are fine.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, 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`
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -78,4 +78,4 @@ unset, which makes the rule report nothing.
 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.
+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 script that must support Bash 4.2 or 3.2. This rule checks that support requirement.

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

@@ -10,15 +10,15 @@ whose target shell lacks them: Bash older than 4.3, including the Bash 3.2 that
 
 ## 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`.
+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 `minBashVersion: "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.
+The rule reports a subscript that is a minus sign followed by a nonzero static integer (decimal, octal, hexadecimal, or Bash `base#digits` for bases 2–64), 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 evaluate arithmetic expressions or machine-integer overflow. Invalid integer spellings such as `08`, `2#2`, or a leading-zero base prefix (`02#1`, `08#1`) are not evidence of a negative index. It does not report zero in any base (`-0`, `-00`, `-0x0`, `-2#0`, 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"} -->
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "minBashVersion": "3.2"} -->
 
 ```sh
 echo "${arr[-1]}"
@@ -31,19 +31,19 @@ Negative subscripts count back from the highest assigned index plus one, while `
 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`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` 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`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-negative-array-index': 'error',
   },
@@ -54,9 +54,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 2} -->
 ```sh
 last=${items[-1]}
 items[-1]=done
@@ -64,24 +64,24 @@ items[-1]=done
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "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.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, 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.
+`minBashVersion` 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.
+shellcheck reports negative array subscripts in scripts it treats as POSIX sh (SC3054), but it cannot check support for a minimum Bash version, so it cannot report `${arr[-1]}` for a script that must support Bash 3.2. This rule checks that support requirement.

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

@@ -6,18 +6,33 @@ ships as `/bin/bash`.
 
 | Configs | Fixable | Languages |
 | ------- | ------- | --------- |
-| `bash-3.2`, `posix-portable` | suggestions | `sh/sh`   |
+| `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 rule considers an expansion 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;
+- 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`). This is the conservative starting point 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 suppresses a report only when a narrow local proof establishes safety:
+
+- a preceding static `set +u` or `set +o nounset` leaves nounset off;
+- an ordinary assignment such as `a=(x)` or `a=("")` guarantees a member. `FUNCNAME` is excluded because it does not obey ordinary assignment semantics. Every element must be a static word; quoted empty strings count, while computed words and unquoted globs do not;
+- `[ "${#a[@]}" -eq 0 ] && return` exits the current function on the empty path, or the same zero-length check uses `exit`. `test` and `[[ ... ]]` spellings are also recognized. With `[` or `test`, the length operand must be an ordinary double-quoted word: unquoted counts can split under a changed `IFS`, making the test fail without proving the array non-empty. An optional literal numeric return/exit status is allowed;
+- the expansion is in the then arm of a single positive length test: `[ "${#a[@]}" -gt 0 ]`, `[[ ${#a[@]} -ne 0 ]]`, or `(( ${#a[@]} ))`, for example.
+
+Facts stay in one sequential statement list. A simple assignment invalidates the fact for its target, so `a=(x); a=()` still reports. Static `set` commands apply option changes in order, so re-enabling nounset removes the off proof. Other calls, including function calls, `unset`, and `shopt`, and compound statements discard facts. Assignments and option changes in a function, loop, branch, or subshell do not establish facts in the surrounding list. A loop's word list can use facts from immediately before the loop; its body starts afresh. Redirections, background statements, prefix assignments on the expanding command, arithmetic expansions, indirect expansions, localized strings, or other potentially mutating argument expansions prevent a proof.
+
+A top-level `return` is not an exit proof: when the script is executed rather than sourced, Bash rejects it and continues to the expansion. For example, `set -u; a=(); [ "${#a[@]}" -eq 0 ] && return; echo "${a[@]}"` still reports. Put that guard inside a function or use `exit` when the intended behavior is to exit the script.
+
+The rule does not interpret function bodies at call sites, follow sourced files, or prove data returned by other commands. Dynamic command names, actual calls to `eval`, `source`, `.`, `trap`, `alias`, `unalias`, `enable`, `fc`, `read`, `mapfile`, `readarray`, `getopts`, `unset`, or `let`, indirect expansions (including key/name forms), localized strings, writes or `for`/`select` bindings to special `BASH_*` variables, the executable `PS4` trace prefix, or writable intrinsic integers (`OPTIND`, `RANDOM`, `SECONDS`), definitions overriding proof builtins, function names outside plain shell identifiers, and unrecognized wrapper flags disable local proofs for the file, including when reached through `builtin` or `command` wrappers. Wrapped declaration commands, and declarations using readonly, integer, associative-array or reference attributes or unmodeled arguments, disable local proofs for the file. A reference or integer variable can write interpreter arrays indirectly, so a later `set +u` is not trusted either. Ordinary `local a` and `local -a a` declarations do not block a subsequent literal assignment proof. Unmodeled arithmetic (including numeric `[[ ... ]]` operands, array indices, slices and `let`), `[[ -v ... ]]`, and coprocesses also disable local proofs because they can evaluate variable text or change special arrays. Direct array lengths and literal nonnegative integers remain supported in arithmetic tests. A `printf` call is considered inert only with a static format made of literal text, `%%`, and the simple string conversions `%s`, `%b`, `%q`, or `%c`; `-v` requires a plain ordinary variable name. Other formats, interpreter-backed or unknown destinations and `%n` can write interpreter state, so they disable local proofs, including through wrappers. Command-based `[` and `test` forms require fixed non-name-lookup operators and operands known to be one word (static or a single double-quoted scalar word). `-v`/`-R`, unknown operators, multiword expansions and unmodeled compound tests disable local proofs: their argument parsing can reach arithmetic variable-name evaluation. These restrictions avoid trusting an assignment that can fail, write through a reference, or run under changed interpreter behavior. Ordinary builtin behavior and ordinary variables are assumed when the file contains no evidence to the contrary; this is not a model of arbitrary startup or sourced-caller state.
+
+Consequently, guarded code can still report where the proof would require another execution path, an intervening call, a caller contract, or one of the excluded constructs. The message says the expansion is not proven safe and remains conditional on the array actually being empty and nounset being on.
+
+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:
 
@@ -29,15 +44,15 @@ An unquoted expansion, or one inside a longer word, reports with no 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.4`.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` 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"} -->
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 set -u
 run_tool "${extra[@]}"
@@ -48,25 +63,37 @@ run_tool ${extra[@]+"${extra[@]}"}
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. It is an explicit opt-in for `bash-3.2`. Enable it when a script
+runs with `set -u` on Bash below 4.4 and its arrays can really be empty. Its local proofs
+cannot establish every caller or helper contract, so scripts whose arrays are always non-empty
+can still produce noise. `posix-portable` continues to enable it.
+
+Extend the preset and enable the rule explicitly:
 
 ```js
 // eslint.config.js
-{
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+import { defineConfig } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig({
+  files: ['**/*.sh'],
+  extends: [sh.configs['bash-3.2']],
   rules: {
     'sh/compat/no-nounset-empty-array': 'error',
   },
-}
+});
 ```
 
+For another target, set `languageOptions.minBashVersion` explicitly. The rule reports only below
+Bash 4.4; enabling it does not change that boundary.
+
 ## Examples
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 2} -->
 ```sh
 set -euo pipefail
 extra=()
@@ -76,9 +103,9 @@ echo "args: ${extra[*]}"
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 set -euo pipefail
 extra=()
@@ -87,12 +114,40 @@ echo "args: ${extra[*]-}"
 echo "count: ${#extra[@]}"
 ```
 
-With `shellVersion: "4.4"` or newer, with no `shellVersion`, or in a file that never turns on
+Local proofs also allow these forms with `minBashVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
+```sh
+set -u
+extra=(--verbose)
+run_tool "${extra[@]}"
+```
+
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
+```sh
+set -u
+set +u
+extra=()
+run_tool "${extra[@]}"
+```
+
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
+```sh
+run_optional() {
+  set -u
+  extra=()
+  [ "${#extra[@]}" -eq 0 ] && return
+  run_tool "${extra[@]}"
+}
+run_optional
+```
+
+With `minBashVersion: "4.4"` or newer, with no `minBashVersion`, 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`
+Turn the rule off when your scripts never run on Bash older than 4.4, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck