@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-parameter-transformation`
 
-Disallow the parameter transformations `${v@op}` in scripts whose target shell lacks the
+Disallow the parameter transformations `${v@op}` in scripts that must support a shell lacking 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.
 
@@ -12,14 +12,14 @@ and `@k` needs Bash 5.2. POSIX sh has none of them.
 
 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 rule reads every parameter expansion whose operator is `@` followed by one of the ten letters. It reports when the minimum Bash version the file must support predates that letter's release; the report is on the whole expansion. A file that must support 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:
+The message names an alternative that works on the shells the file must support:
 
-- `@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`.
+- `@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 file that must support POSIX sh, 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.
+- `@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 file that must support POSIX sh.
+- `@U`, `@u`, `@L`: the Bash 4.0 case expansions `"${v^^}"`, `"${v^}"`, `"${v,,}"` when the minimum supported Bash is 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.
@@ -27,18 +27,18 @@ Under `dialect: "posix"` the parser itself rejects `${v@op}`, so a POSIX file th
 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.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports an operator when `minBashVersion` is older than its release.
 - `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-parameter-transformation': 'error',
   },
@@ -49,9 +49,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
 log "running ${cmd@Q}"
@@ -59,9 +59,9 @@ upper=${name@U}
 printf '%s\n' "${args[@]@K}"
 ```
 
-With `shellVersion: "5.0"`, only the case operator reports:
+With `minBashVersion: "5.0"`, only the case operator reports:
 
-<!-- example: {"dialect": "bash", "shellVersion": "5.0", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "5.0", "findings": 1} -->
 
 ```sh
 log "running ${cmd@Q}"
@@ -70,25 +70,25 @@ upper=${name@U}
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "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.
+With `minBashVersion: "5.2"` or newer, or with no `minBashVersion`, 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.
+leave `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 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.
+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 script that must support a Bash older than the operator's release. This rule exists for those targets.

package/docs/rules/compat/no-pipe-all.md

@@ -1,6 +1,6 @@
 # `sh/compat/no-pipe-all`
 
-Disallow the `|&` pipe, shorthand for `2>&1 |`, in scripts whose target shell lacks it: Bash older
+Disallow the `|&` pipe, shorthand for `2>&1 |`, in scripts that must support a shell lacking it: Bash older
 than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -20,15 +20,15 @@ Under `dialect: "posix"` the parser itself rejects `|&`, so a POSIX file that us
 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`.
+- `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: "mksh"` or `"zsh"`: never reports (in zsh, `|&` is a different operator).
 
 ### Suggestion
 
 A suggestion rewrites the operator:
 
-<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 make |& tee build.log
 # becomes
@@ -37,12 +37,12 @@ make 2>&1 | tee build.log
 
 ## 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-pipe-all': 'error',
   },
@@ -53,28 +53,28 @@ 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
 make |& tee build.log
 ```
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 make 2>&1 | tee build.log
 make || echo "failed |& retried"
 ```
 
-With `shellVersion: "4.0"` or newer, or with no `shellVersion`, `|&` is fine.
+With `minBashVersion: "4.0"` or newer, or with no `minBashVersion`, `|&` 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
@@ -82,4 +82,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 `|&` 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 `|&` for a Bash 3.2 target. This rule exists for that target.
+shellcheck reports `|&` 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 `|&` for a script that must support Bash 3.2. This rule checks that support requirement.

package/docs/rules/compat/no-printf-time-format.md

@@ -1,6 +1,6 @@
 # `sh/compat/no-printf-time-format`
 
-Disallow `printf`'s `%(fmt)T` date format in scripts whose target shell lacks it: Bash older than
+Disallow `printf`'s `%(fmt)T` date format in scripts that must support a shell lacking it: 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 for the current time is `date '+fmt'`, which takes the
 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`; dash's `printf` has no `%(fmt)T`.
+- `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; dash's `printf` has no `%(fmt)T`.
 - `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-printf-time-format': '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
 printf '%(%Y-%m-%d)T\n' -1
 printf -v stamp '[%(%H:%M:%S)T]' -1
@@ -51,20 +51,20 @@ printf -v stamp '[%(%H:%M:%S)T]' -1
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 date '+%Y-%m-%d'
 stamp="[$(date '+%H:%M:%S')]"
 printf '100%%(of it)T\n'
 ```
 
-With `shellVersion: "4.2"` or newer, or with no `shellVersion`, `%(fmt)T` is fine.
+With `minBashVersion: "4.2"` or newer, or with no `minBashVersion`, `%(fmt)T` is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.2, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.2, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -72,4 +72,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 0.11.0 reports nothing for `printf "%(%s)T\n" -1` under either `-s sh` or `-s bash`. So shellcheck gives no finding for `%(fmt)T` in a POSIX sh script or in a Bash 3.2 target. This rule exists for both.
+shellcheck 0.11.0 reports nothing for `printf "%(%s)T\n" -1` under either `-s sh` or `-s bash`. So shellcheck gives no finding for `%(fmt)T` in a POSIX sh script or in a script that must support Bash 3.2. This rule exists for both.

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

@@ -47,12 +47,12 @@ if [ -r ./lib.sh ]; then . ./lib.sh; else echo fallback; fi
 
 This is a POSIX-only gate. Every Bash has `source`, 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-test-v.md

@@ -24,19 +24,19 @@ The portable alternative is `[ -n "${name+set}" ]`. `${name+set}` expands to `se
 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 `test -v` and `[ -v ]` at any `shellVersion`; dash has no `-v` test.
+- `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 `test -v` and `[ -v ]` regardless of Bash releases; dash has no `-v` test.
 - `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-test-v': 'error',
   },
@@ -47,9 +47,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
 if [[ -v CI ]]; then echo ci; fi
 if test -v HOME; then echo home; fi
@@ -58,20 +58,20 @@ if test -v HOME; then echo home; fi
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 if [ -n "${CI+set}" ]; then echo ci; fi
 [ "$flag" = -v ] && verbose=1
 grep -v '^#' config
 ```
 
-With `shellVersion: "4.2"` or newer, or with no `shellVersion`, the `-v` test is fine.
+With `minBashVersion: "4.2"` or newer, or with no `minBashVersion`, the `-v` test is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.2, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.2, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -79,4 +79,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 `[[` and `test -v` 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 `[[ -v x ]]` for a Bash 3.2 target. This rule exists for that target.
+shellcheck reports `[[` and `test -v` 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 `[[ -v x ]]` for a script that must support Bash 3.2. This rule checks that support requirement.

package/docs/rules/compat/no-unicode-escape.md

@@ -27,18 +27,18 @@ Under `dialect: "posix"` the parser reads `$'…'` as a literal `$` followed by
 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 escape when `shellVersion` is older than its release (4.2, or 4.3 for U+0080 to U+00FF).
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports an escape when `minBashVersion` is older than its release (4.2, or 4.3 for U+0080 to U+00FF).
 - `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-unicode-escape': 'error',
   },
@@ -49,17 +49,17 @@ 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
 ok=$'\u2713'
 printf '%s\n' $'caf\u00e9'
 ```
 
-With `shellVersion: "4.2"`, only the Latin-1 range reports:
+With `minBashVersion: "4.2"`, only the Latin-1 range reports:
 
-<!-- example: {"dialect": "bash", "shellVersion": "4.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "4.2", "findings": 1} -->
 ```sh
 ok=$'\u2713'
 printf '%s\n' $'caf\u00e9'
@@ -67,20 +67,20 @@ printf '%s\n' $'caf\u00e9'
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 ok=$'\342\234\223'
 printf '%s\n' $'caf\303\251'
 echo '\u00e9 is written literally here'
 ```
 
-With `shellVersion: "4.3"` or newer, or with no `shellVersion`, every escape is fine.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, every escape is 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
@@ -88,4 +88,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 `$'…'` 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 a `\u` escape for a Bash 3.2 or 4.2 target. This rule exists for that target.
+shellcheck reports `$'…'` 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 a `\u` escape for a script that must support Bash 3.2 or 4.2. This rule checks that support requirement.

package/docs/rules/compat/no-wait-n.md

@@ -1,6 +1,6 @@
 # `sh/compat/no-wait-n`
 
-Disallow `wait -n` in scripts whose target shell lacks it: Bash older than 4.3, including the
+Disallow `wait -n` in scripts that must support a shell lacking it: Bash older than 4.3, including the
 Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -20,19 +20,19 @@ The portable alternative is to wait for one job at a time by its PID: keep each
 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`; POSIX `wait` has no options.
+- `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; POSIX `wait` has no options.
 - `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-wait-n': 'error',
   },
@@ -43,9 +43,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
 for job in a b c d; do
   run "$job" &
@@ -56,9 +56,9 @@ wait
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 pids=
 for job in a b c d; do
@@ -70,11 +70,11 @@ for pid in $pids; do
 done
 ```
 
-With `shellVersion: "4.3"` or newer, or with no `shellVersion`, `wait -n` is fine.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, `wait -n` is 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
@@ -82,4 +82,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 `wait` options 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 `wait -n` for a Bash 4.2 target. This rule exists for that target.
+shellcheck reports `wait` options 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 `wait -n` for a script that must support Bash 4.2. This rule checks that support requirement.

package/docs/rules/no-dynamic-invocation.md

@@ -30,7 +30,8 @@ wrappers_: commands that run the word after them. `time ls` runs `ls`, and
   `bash ./build.sh` runs `./build.sh`. `bash -c STRING`, including a one-letter cluster such as
   `bash -lc STRING`, runs an embedded string. `bash -s` and a bare `bash` read commands from
   standard input, so the shell itself is the command.
-- Any names you add with `allowWrappers`.
+- Project wrappers declared in `settings: { sh: { transparentWrappers: ['with-retry'] } }`,
+  and the shared network wrapper. See [shared transparent wrappers](../transparent-wrappers.md).
 
 A command then reports in one of two ways:
 
@@ -45,8 +46,9 @@ A command then reports in one of two ways:
 
 The rule is syntactic by design. It doesn't track values, so `cmd=ls; "$cmd"` reports. Aliases
 need no handling: non-interactive shells don't expand them, so an alias name is an ordinary
-static command word. Wrapper names match exactly, so `/bin/bash -c …` is a static command named
-`/bin/bash`, not a shell wrapper.
+static command word. Utility wrappers match absolute paths by basename, so `/bin/bash -c …` runs an
+embedded command. Configured utility wrappers also match relative paths; builtin specs
+require exact names.
 
 It does not depend on `languageOptions`.
 
@@ -56,18 +58,20 @@ It does not depend on `languageOptions`.
   `dynamicInvocation` inside a function with one of these names, at any nesting depth, does not
   report. The same command outside that function still reports. `embeddedCommand` still reports
   inside these functions. Each use of the dispatcher stays visible at its call sites.
-- `allowWrappers` (`string[]`, default `[]`): extra transparent wrappers, added to the built-in
-  list above. The word after one is checked as the command that runs. An added wrapper has no
-  known options, so a flag right after it (`with-retry -n 3 curl`) makes the command unknown and
-  reports. A name already in the built-in list keeps its built-in option handling.
+Project wrapper facts belong in shared settings, with no rule override. The former
+`allowWrappers` option is rejected. It added checks rather than suppressing them:
+move its list to shared settings to preserve those checks across all wrapper-following
+rules. Use `allowInFunctions` or a justified ESLint disable comment for an actual allowance.
+See [migration](../transparent-wrappers.md#migration).
 
 ```js
 // eslint.config.js
 {
+  settings: { sh: { transparentWrappers: ['with-retry'] } },
   rules: {
     'sh/no-dynamic-invocation': [
       'error',
-      { allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] },
+      { allowInFunctions: ['dispatch'] },
     ],
   },
 }
@@ -91,9 +95,9 @@ bash -c "$script"         # embeddedCommand: a string of shell code
 sh -c 'make test'         # embeddedCommand, even for a literal string
 ```
 
-With `{ allowWrappers: ['with-retry'] }`:
+With `settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
-<!-- example: {"options": {"allowWrappers": ["with-retry"]}, "findings": 1, "messageIds": ["dynamicInvocation"]} -->
+<!-- example: {"settings": {"sh": {"transparentWrappers": ["with-retry"]}}, "findings": 1, "messageIds": ["dynamicInvocation"]} -->
 ```sh
 with-retry "$c"           # the wrapped command is dynamic
 ```
@@ -110,9 +114,10 @@ alias ll='ls -l'
 ll                        # an alias name is a static command word
 ```
 
-With `{ allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] }`:
+With `{ allowInFunctions: ['dispatch'] }` and
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
-<!-- example: {"options": {"allowInFunctions": ["dispatch"], "allowWrappers": ["with-retry"]}} -->
+<!-- example: {"options": {"allowInFunctions": ["dispatch"]}, "settings": {"sh": {"transparentWrappers": ["with-retry"]}}} -->
 ```sh
 dispatch() {
   "$@"                    # allowed inside the dispatcher

package/docs/rules/no-eval.md

@@ -7,6 +7,10 @@ of code a script runs can be reviewed before it runs.
 | ------- | ------------ | --------- |
 | `recommended`, `agent-authored` | not fixable | `sh/sh` |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 A script you can review is a script whose code is all in front of you. Two constructs defeat
@@ -98,7 +102,8 @@ still report.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-This rule is one of eslint-sh's two deliberate overlaps with shellcheck. shellcheck flags
+This rule is one of eslint-sh's
+[deliberate overlaps with shellcheck](../shellcheck.md#deliberate-overlaps). shellcheck flags
 `eval` only in specific misuse patterns, such as SC2294 (`eval` on an array negates the benefit
 of arrays), and flags `source` of a non-constant path as SC1090 because shellcheck cannot follow
 it. Both treat these as hazards to work around. This rule treats them as a policy: code that

package/docs/rules/no-masked-exit-status.md

@@ -6,6 +6,10 @@ Disallow `local`, `declare`, `typeset`, `export` and `readonly` with a value tak
 | ---------------- | ----------------------------------------- | --------- |
 | `agent-authored` | suggestions (split into two statements) | `sh/sh`   |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 `local x=$(cmd)` runs `cmd`, then runs `local`, and the statement's exit status is the status of