@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/rules/compat/no-case-attributes.md

@@ -0,0 +1,82 @@
+# `sh/compat/no-case-attributes`
+
+Disallow the case-converting attributes `declare -l` and `declare -u` (also through `typeset` and
+`local`) 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` | not fixable | `sh/sh`   |
+
+## Rule details
+
+The `-l` and `-u` attributes arrived in Bash 4.0 (Bash NEWS for 4.0), with the case-modifying expansions that [`sh/compat/no-case-modification`](./no-case-modification.md) reports. Bash 3.2 rejects the option with `declare: -l: invalid option`, so the declaration fails and the variable is left unset.
+
+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 `l` or `u` (`-l`, `-u`, `-lx`); the report is on that word. A cluster with both (`-lu`) gets its own message: where the attributes exist, the two cancel out and leave the value as written (observed on Bash 4.0 and 5.3), so the fix is to drop both letters. `-u` of another command (`read -u 3`) and an option after the first operand or after `--` are not read.
+
+The portable alternative is to convert the value when it is assigned, with `tr`: `v=$(printf '%s' "$v" | tr '[:upper:]' '[:lower:]')` for `-l`, and `tr '[:lower:]' '[:upper:]'` for `-u`. An attribute converts every later assignment too, so convert at each assignment that needs 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.0`.
+- `dialect: "posix"`: reports at any `shellVersion`, because POSIX sh has no `declare`.
+- `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-case-attributes': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+
+```sh
+declare -l answer=$1
+f() {
+  local -u code=$2
+}
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+answer=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+f() {
+  local code
+  code=$(printf '%s' "$2" | tr '[:lower:]' '[:upper:]')
+}
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, the attributes are fine.
+
+## 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.
+
+Under `-s sh`, shellcheck 0.11.0 reports the command, not the option: `declare -l` and `declare -u` draw SC3044 (`declare` is undefined in POSIX sh), and `local -l` and `local -u` draw SC3043. Under `-s bash` it reports nothing for these options. It does not know which Bash release a script must run on, so it reports nothing for `declare -l` in a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-case-fallthrough.md

@@ -0,0 +1,90 @@
+# `sh/compat/no-case-fallthrough`
+
+Disallow the `case` terminators `;&` (run the next branch without testing its pattern) and `;;&`
+(go on testing the next patterns) 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` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Both terminators arrived in Bash 4.0 (Bash NEWS for 4.0). Bash 3.2 rejects them as a syntax error (``syntax error near unexpected token `&'``), so the whole script fails to run. POSIX.1-2024 adds `;&`, but dash 0.5.12 still rejects it (`Syntax error: "&" unexpected`), so the rule treats a POSIX target as lacking it until the `sh` binaries people deploy to catch up.
+
+The rule reports a `case` branch whose terminator is `;&` or `;;&`; the report is on the terminator. The usual `;;`, a branch with no terminator, and these characters in quotes or in a pattern are not reported.
+
+There is no mechanical rewrite, so the rule offers no suggestion. The message names the usual restructuring: for `;&`, repeat the next branch's commands at the end of this branch and end it with `;;`; for `;;&`, end this branch with `;;` and test the patterns that follow it in a second `case` statement.
+
+Under `dialect: "posix"` the parser itself rejects both terminators, so a POSIX file that uses them 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 when `shellVersion` is older than `4.0`.
+- `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-case-fallthrough': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+case $level in
+  debug) verbose=1 ;&
+  info) log=1 ;;
+esac
+case $file in
+  *.tar.gz) compressed=1 ;;&
+  *.tar*) archive=1 ;;
+esac
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+case $level in
+  debug) verbose=1; log=1 ;;
+  info) log=1 ;;
+esac
+case $file in
+  *.tar.gz) compressed=1 ;;
+esac
+case $file in
+  *.tar*) archive=1 ;;
+esac
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, both terminators are fine.
+
+## 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.
+
+Under `-s sh`, shellcheck 0.11.0 reports `;&` and `;;&` as an error, SC2127 ("To use cases with ;&, specify #!/usr/bin/env bash or ksh", or the `;;&` equivalent naming bash), not as one of its SC3xxx portability checks. It reports the same SC2127 under `-s dash`, reports `;;&` (but not `;&`) under `-s ksh`, and reports nothing under `-s bash`. It does not know which Bash release a script must run on, so it reports nothing for either operator in a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-case-modification.md

@@ -0,0 +1,74 @@
+# `sh/compat/no-case-modification`
+
+Disallow the case-modifying parameter expansions `${v^}`, `${v^^}`, `${v,}` and `${v,,}` in scripts whose
+target shell lacks them: Bash older than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+The four case-modifying expansions arrived in Bash 4.0 (Bash NEWS for 4.0: "new case-modifying word
+expansions"). Bash 3.2 fails the command with `bad substitution` when the word is expanded.
+
+The report is on the whole expansion, with or without a trailing pattern (`${v^^[aeiou]}`). The message shows the `tr` replacement for the operator written: `tr` over the whole value for `^^` and `,,`, and `tr` over the first character (`${v%"${v#?}"}`) followed by the rest (`${v#?}`) for `^` and `,`. A pattern form such as `${w^^a}` changes only the characters the pattern matches, which a plain case-converting `tr` does not reproduce (`banana` becomes `bAnAnA`, not `BANANA`), so for those forms the message offers no `tr` equivalent and tells you to spell out the matching characters.
+
+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 nothing in practice for this syntax, 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-case-modification': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+```sh
+name=${input,,}      # lowercase every character
+title=${word^}       # uppercase the first character
+flag=${arg^^[a-z]}   # with a pattern
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+name=$(printf '%s' "$input" | tr '[:upper:]' '[:lower:]')
+title=$(printf '%s' "${word%"${word#?}"}" | tr '[:lower:]' '[:upper:]')"${word#?}"
+```
+
+With `shellVersion: "4.0"` 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.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 case-modifying expansions in scripts it treats as POSIX sh (SC3059), but it cannot target a Bash version, so it cannot report `${v,,}` in a script that must run on Bash 3.2. This rule exists for that target.

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

@@ -0,0 +1,76 @@
+# `sh/compat/no-coproc`
+
+Disallow the `coproc` reserved word in scripts whose target shell lacks it: 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` | not fixable | `sh/sh`   |
+
+## Rule details
+
+`coproc` arrived in Bash 4.0 (Bash NEWS for 4.0: "a new `coproc` reserved word"). On Bash 3.2 the word is an ordinary command name, so `coproc cat` fails with `command not found` and the `COPROC` array is never set.
+
+The rule reports every `coproc` clause, named or not, on the whole clause. Under `dialect: "posix"` the parser reads `coproc cat` as an ordinary command, and the rule reports a command named `coproc` too.
+
+The portable alternative is a named pipe: create it with `mkfifo`, start the coprocess in the background reading or writing the pipe, and open the pipe from the script.
+
+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.
+
+## 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-coproc': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+coproc worker { cat; }
+coproc sort
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+fifo=$(mktemp -u) && mkfifo "$fifo"
+cat < "$fifo" &
+exec 3> "$fifo"
+printf '%s\n' hello >&3
+```
+
+With `shellVersion: "4.0"` 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.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 has no check for `coproc` in a script that must run on an older Bash; it cannot target a Bash version. This rule exists for that target.

package/docs/rules/compat/no-declare-g.md

@@ -0,0 +1,80 @@
+# `sh/compat/no-declare-g`
+
+Disallow `declare -g` and `typeset -g` in scripts whose target shell lacks the `-g` 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
+
+`declare -g` arrived in Bash 4.2 (Bash NEWS for 4.2: "declare/typeset has a new `-g` option"). Bash 3.2 rejects it as an invalid option, so the declaration fails and the variable is never created.
+
+The rule reads the options of every `declare` and `typeset` command, up to the first operand, as the builtin does. An option word reports when it is a `-` cluster containing `g` (`-g`, `-gx`, `-Ag`); the report is on that word. `local`, `readonly` and `export` are ignored, and so is a `-g` after the first operand or after `--`.
+
+The portable alternative: in Bash before 4.2 a plain `name=value` inside a function sets the global, as long as the function has not declared the name `local`. The two are not identical: a plain `name=value` assigns to a `local` of the same name declared by a calling function (dynamic scope) instead of creating a global, and it does not carry the attributes `declare -g` can set, such as `-i`, `-A` and `-r`, so a script using those must restructure rather than drop the flag.
+
+The message says so. For a plain `-g` (and `-gx`, which `export name=value` covers) it suggests the assignment. For any other option (`declare -Ag m`, `typeset -gi n=1`, or as separate words `declare -g -A m`, `typeset -g -r c`) it does not suggest `name=value`, which would drop the attribute; it points at declaring the variable outside any function, or raising the target.
+
+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`, because POSIX sh has no `declare`.
+- `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-declare-g': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+f() {
+  declare -g counter=0
+  typeset -gx exported=1
+}
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+f() {
+  counter=0
+  export exported=1
+}
+```
+
+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 does not know which Bash a script must run on, so it cannot report `declare -g` for a Bash 3.2 target. This rule exists for that target.

package/docs/rules/compat/no-double-bracket.md

@@ -0,0 +1,72 @@
+# `sh/compat/no-double-bracket`
+
+Disallow `[[ … ]]` in scripts that target POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+POSIX lists `[[` and `]]` among the words whose results are unspecified ([Shell Command Language, section 2.4](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_19_04)). dash, the `/bin/sh` of Debian and Ubuntu, looks up a command named `[[` and fails with `[[: not found` and status 127. Under `set -e` a bare test stops the script. In an `if` condition the script carries on down the wrong branch: `if [[ a == a ]]; then echo yes; else echo no; fi` prints `no`.
+
+`bash --posix` and BusyBox ash both accept `[[`, so a script can pass on them and still fail on dash.
+
+Under `dialect: "posix"` the parser reads `[[` as an ordinary command, and the rule reports a command whose effective name is `[[`, after following wrappers such as `command`. It reports the `[[` word, because the parser ends that command at the first `&&` or `||`. `command -v [[` 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 `[[` containing a parenthesis, such as `[[ $a =~ ^(x|y)$ ]]`, is a parse error under `dialect: "posix"` and never reaches this rule.
+
+The portable alternatives are `[ … ]` for tests and `case` for pattern matching. The rule offers no suggestion, because `[` splits and globs its unquoted operands and has no spelling for `==` patterns or `=~`.
+
+This is a POSIX-only gate. Every Bash has `[[`, 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-double-bracket': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix", "findings": 2} -->
+```sh
+if [[ "$1" == "x" ]]; then echo hi; fi
+[[ -n "$a" && -n "$b" ]]
+```
+
+### Correct
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix"} -->
+```sh
+if [ "$1" = "x" ]; then echo hi; fi
+[ -n "$a" ] && [ -n "$b" ]
+case "$1" in
+  x*) echo starts-with-x ;;
+esac
+```
+
+## When not to use it
+
+Turn the rule off when your scripts only ever run where `[[` 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 SC3010 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. shellcheck keeps the misuse of `[[` and `[`, which this rule does not look at.

package/docs/rules/compat/no-epoch-variables.md

@@ -0,0 +1,79 @@
+# `sh/compat/no-epoch-variables`
+
+Disallow `$EPOCHSECONDS` and `$EPOCHREALTIME` in scripts whose target shell lacks them: Bash older
+than 5.0, 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
+
+Both variables arrived in Bash 5.0 (Bash NEWS for 5.0). On an older Bash they are simply unset: nothing fails, and the script quietly gets an empty string where it expected a timestamp. Under `set -u` it aborts instead.
+
+The rule reports every parameter expansion of either name (`$EPOCHSECONDS`, `${EPOCHSECONDS:-0}`), unquoted, in double quotes, or in an unquoted here-document, and either name written bare as an operand in arithmetic (`$(( EPOCHSECONDS - start ))`, `(( t = EPOCHREALTIME ))`). Text in single quotes or in a quoted here-document is not an expansion and is not reported, and neither is a longer name such as `$EPOCHSECONDSX`. The report is on the expansion or the bare name.
+
+A read inside a feature-detect that already falls back (`case "${EPOCHREALTIME:-}" in [0-9]*) … ;; *) fallback ;; esac`, or `${EPOCHSECONDS:-$(date +%s)}`) still reports: the rule cannot tell that the fallback makes the read safe, so suppress those lines or use the portable form.
+
+The usual alternative is `$(date +%s)`. It is not POSIX: `%s` is an extension that GNU, BSD and BusyBox `date` all have. It gives whole seconds, so `$EPOCHREALTIME`'s fraction has no portable equivalent; its message says so.
+
+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 `5.0`.
+- `dialect: "posix"`: reports at any `shellVersion`, because POSIX sh does not set either variable.
+- `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-epoch-variables': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+start=$EPOCHSECONDS
+run_tests
+echo "took $(( EPOCHSECONDS - start ))s"
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+start=$(date +%s)
+run_tests
+echo "took $(( $(date +%s) - start ))s"
+echo 'the variable is spelled $EPOCHSECONDS'
+```
+
+With `shellVersion: "5.0"` or newer, or with no `shellVersion`, both variables are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 5.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 0.11.0 reports `$EPOCHSECONDS` and `$EPOCHREALTIME` as undefined in POSIX sh (SC3028) under `-s sh`, and nothing under `-s bash`. It does not know which Bash release a script must run on, so it reports nothing for either variable in a Bash 4.4 target. This rule exists for that target.

package/docs/rules/compat/no-fd-variable.md

@@ -0,0 +1,78 @@
+# `sh/compat/no-fd-variable`
+
+Disallow `{varname}` redirections, which have the shell pick a free file descriptor and store its
+number in a variable (`exec {fd}>file`), in scripts whose target shell lacks them: Bash older than
+4.1, 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
+
+Descriptor allocation arrived in Bash 4.1 (Bash NEWS for 4.1). Bash 4.0 and older treat `{fd}` as an ordinary word, so `exec {fd}>out` tries to run a command named `{fd}` and fails with `exec: {fd}: not found`.
+
+The rule reports a redirection whose descriptor is written `{name}`, which the parser records separately from the redirection's target; the report is on the whole redirection, including when it closes the descriptor (`exec {fd}>&-`). A numbered descriptor (`3>file`), a `{…}` word separated from the redirection by a space (`echo {fd} >out`), a brace group, and the same text in quotes are not reported.
+
+The portable alternative is a fixed descriptor number: `exec 3>file`, write with `>&3`, then close it with `exec 3>&-`. Pick a number the script does not use for anything else.
+
+Under `dialect: "posix"` the parser itself rejects `{varname}` redirections, so a POSIX file that uses one 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 when `shellVersion` is older than `4.1`.
+- `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-fd-variable': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+exec {log}>>"$logfile"
+echo started >&"$log"
+exec {log}>&-
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+exec 3>>"$logfile"
+echo started >&3
+exec 3>&-
+```
+
+With `shellVersion: "4.1"` or newer, or with no `shellVersion`, `{varname}` redirections are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.1, 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 `{varname}` redirections 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 them for a Bash 3.2 target. This rule exists for that target.