@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/compat.md

@@ -0,0 +1,354 @@
+# Version compatibility (`compat/*` rules)
+
+The `compat/*` rules report shell features that the shell you deploy to does not have. They
+are for scripts that must run on an older Bash, such as the Bash 3.2 that macOS ships as
+`/bin/bash`, or on a plain POSIX `sh`.
+
+`compat/*` is reserved for version gates: rules that read the gate table below and your
+`shellVersion`/`dialect`. A rule that checks the file against your config without reading the
+target, such as [`sh/shebang-matches-dialect`](./rules/shebang-matches-dialect.md), lives outside
+the namespace.
+
+The parser does not do this for you. It accepts everything its grammar knows, whatever target
+you configure: Bash mode parses `declare -A` and `mapfile` even with `shellVersion: "3.2"`, and
+POSIX mode parses `declare -A` as an ordinary command. Only the `compat/*` rules enforce the
+target.
+
+A `compat/*` finding stays reported when the code is behind a runtime version guard
+(`if (( BASH_VERSINFO[0] >= 4 )); then …`): the rules do not follow control flow. Silence a guarded
+use with a disable comment on the line before it:
+
+```sh
+if (( BASH_VERSINFO[0] >= 4 )); then
+  # eslint-disable-next-line sh/compat/no-mapfile
+  mapfile -t lines < file
+fi
+```
+
+## Rules
+
+| Rule | Feature | Bash | POSIX sh |
+| ---- | ------- | ---- | -------- |
+| [`sh/compat/no-append-all-redirect`](./rules/compat/no-append-all-redirect.md) | `&>>` | 4.0 | no |
+| [`sh/compat/no-associative-arrays`](./rules/compat/no-associative-arrays.md) | `declare -A`, `typeset -A` | 4.0 | no |
+| [`sh/compat/no-brace-sequence-padding-step`](./rules/compat/no-brace-sequence-padding-step.md) | `{01..10}`, `{1..10..2}`, `{a..e..2}` | 4.0 | no |
+| [`sh/compat/no-case-attributes`](./rules/compat/no-case-attributes.md) | `declare -l`, `declare -u` (and `typeset`, `local`) | 4.0 | no |
+| [`sh/compat/no-case-fallthrough`](./rules/compat/no-case-fallthrough.md) | `;&`, `;;&` in `case` | 4.0 | no |
+| [`sh/compat/no-case-modification`](./rules/compat/no-case-modification.md) | `${v^}`, `${v^^}`, `${v,}`, `${v,,}` | 4.0 | no |
+| [`sh/compat/no-coproc`](./rules/compat/no-coproc.md) | `coproc` | 4.0 | no |
+| [`sh/compat/no-declare-g`](./rules/compat/no-declare-g.md) | `declare -g`, `typeset -g` | 4.2 | no |
+| [`sh/compat/no-double-bracket`](./rules/compat/no-double-bracket.md) | `[[ … ]]` | every | no |
+| [`sh/compat/no-epoch-variables`](./rules/compat/no-epoch-variables.md) | `$EPOCHSECONDS`, `$EPOCHREALTIME` | 5.0 | no |
+| [`sh/compat/no-fd-variable`](./rules/compat/no-fd-variable.md) | `exec {fd}>file` | 4.1 | no |
+| [`sh/compat/no-globstar`](./rules/compat/no-globstar.md) | `shopt -s globstar` | 4.0 | no |
+| [`sh/compat/no-lastpipe-semantics`](./rules/compat/no-lastpipe-semantics.md) | `shopt -s lastpipe` | 4.2 | no |
+| [`sh/compat/no-let`](./rules/compat/no-let.md) | `let` | every | no |
+| [`sh/compat/no-mapfile`](./rules/compat/no-mapfile.md) | `mapfile`, `readarray` | 4.0 | no |
+| [`sh/compat/no-nameref`](./rules/compat/no-nameref.md) | `declare -n`, `local -n` | 4.3 | no |
+| [`sh/compat/no-negative-array-index`](./rules/compat/no-negative-array-index.md) | `${arr[-1]}`, `arr[-1]=x` | 4.3 | no |
+| [`sh/compat/no-nounset-empty-array`](./rules/compat/no-nounset-empty-array.md) | `"${a[@]}"` of an empty array under `set -u` | 4.4 | no |
+| [`sh/compat/no-parameter-transformation`](./rules/compat/no-parameter-transformation.md) | `${v@Q}`, `@E`, `@P`, `@A`, `@a`; `@U`, `@u`, `@L`, `@K`; `@k` | 4.4; 5.1; 5.2 | no |
+| [`sh/compat/no-pipe-all`](./rules/compat/no-pipe-all.md) | `\|&` | 4.0 | no |
+| [`sh/compat/no-printf-time-format`](./rules/compat/no-printf-time-format.md) | `printf '%(fmt)T'` | 4.2 | no |
+| [`sh/compat/no-source`](./rules/compat/no-source.md) | `source` | every | no |
+| [`sh/compat/no-test-v`](./rules/compat/no-test-v.md) | `[[ -v x ]]`, `test -v x` | 4.2 | no |
+| [`sh/compat/no-unicode-escape`](./rules/compat/no-unicode-escape.md) | `\u`, `\U` in `$'…'`; U+0080 to U+00FF | 4.2; 4.3 | no |
+| [`sh/compat/no-wait-n`](./rules/compat/no-wait-n.md) | `wait -n` | 4.3 | no |
+
+The Bash column is the oldest Bash release that has the feature, taken from the Bash release notes
+([NEWS](https://tiswww.case.edu/php/chet/bash/NEWS)) and checked against real shells built from
+source; see [Evidence](#evidence). Bash 4.2 already reads a negative array subscript (`${arr[-1]}`), but
+it rejects the element length `${#arr[-1]}`, assigning and unsetting; the table uses 4.3, the first
+release where every use works. Two rules gate more than one release. `sh/compat/no-parameter-transformation`
+reports each operator against its own release. `sh/compat/no-unicode-escape` needs 4.2 for most code
+points but 4.3 for U+0080 to U+00FF, because the Bash 4.2 release writes those as a single Latin-1 byte
+instead of UTF-8. `sh/compat/no-nounset-empty-array` gates a behavior, not syntax: every Bash has
+`"${a[@]}"`, but through 4.3 an empty array aborts the script under `set -u`. `every` means every Bash release has the feature, so only
+`dialect: "posix"` can lack it: those three are the POSIX-only gates, and the other twenty-two are
+the version gates. The `bash-3.2` preset enables the version gates and the `posix-portable` preset
+enables all twenty-five; see
+[Presets](#presets).
+
+## Setting the target
+
+Every `compat/*` rule reads the same two `languageOptions`, and nothing else. They have no rule
+options of their own:
+
+```js
+// eslint.config.js
+import { defineConfig } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig({
+  files: ['**/*.sh'],
+  extends: [sh.configs.recommended],
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-associative-arrays': 'error',
+    'sh/compat/no-mapfile': 'error',
+    // …and the other rules in the table above.
+  },
+});
+```
+
+A gated feature is available, and its rule reports nothing, according to these rules:
+
+- **`shellVersion` unset means the newest version.** With no `shellVersion`, every Bash feature
+  is available and no `compat/*` rule reports under `dialect: "bash"`. Set a version to opt in.
+- **Versions compare numerically, major first, then minor.** `shellVersion` has the shape
+  `MAJOR[.MINOR]`. A missing minor is `0`, so `"4"` is the same as `"4.0"`. Each part is a
+  number, not text, so `"3.10"` is newer than `"3.2"` and still older than `"4.0"`. A feature
+  is available when `shellVersion` is its minimum version or newer.
+- **`dialect: "posix"` makes Bash-only features unavailable at any `shellVersion`.** A POSIX sh
+  script cannot rely on a feature that only Bash has, whatever version number is configured.
+- **`dialect: "bats"` is gated as Bash**, because Bats test files run under Bash.
+  `shellVersion` is the version of that Bash.
+- **`dialect: "mksh"` and `dialect: "zsh"` are not gated.** These shells number their own
+  releases, so a `shellVersion` there is not a Bash version, and the rules have no data on
+  which of their releases added which feature. The `compat/*` rules report nothing for them.
+
+## Presets
+
+Two presets name a deployment target and enable every rule that enforces it, so you do not list
+the rules yourself:
+
+- **`sh.configs['bash-3.2']`** sets `languageOptions: { dialect: 'bash', shellVersion: '3.2' }`
+  and enables all twenty-two version-gated `compat/*` rules at `error`. Use it for scripts that must run on the Bash
+  3.2 that macOS ships as `/bin/bash`.
+- **`sh.configs['posix-portable']`** reports the Bash-only constructs in the table above, which
+  fail or read as unset on dash, but not `local`, `echo -e` or the others listed under
+  [What `posix-portable` does not report](#what-posix-portable-does-not-report), so a clean run does
+  not prove a script runs under every POSIX `sh`. It sets `languageOptions: { dialect: 'posix' }` and
+  enables all twenty-five `compat/*` rules, `sh/shebang-matches-dialect`, and
+  `sh/require-strict-mode` configured as `set -eu`, all at `error`. Strict mode is `set -eu` and not
+  `set -euo pipefail` because `pipefail` joined POSIX only in POSIX.1-2024, and older `dash` and
+  BusyBox `ash` reject it, so a `pipefail` requirement would make the autofix break a working
+  `#!/bin/sh` script.
+
+Both presets are single objects with no `files`; extend them from an entry that lists your
+scripts, after `recommended` if you want its rules too:
+
+```js
+// eslint.config.js
+import { defineConfig } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig([
+  { files: ['scripts/**/*.sh'], extends: [sh.configs.recommended, sh.configs['bash-3.2']] },
+  { files: ['install/?*'], extends: [sh.configs.recommended, sh.configs['posix-portable']] },
+]);
+```
+
+Because the presets carry `languageOptions`, a `languageOptions` of your own in the same entry
+overrides them key by key. To run these rules beside shellcheck, see [shellcheck](./shellcheck.md).
+
+## A branch for one shell
+
+`[[`, `let` and `source` are commands to dash, so it only fails when it runs one. A script meant for
+`sh` can hold a branch for one shell, and `sh/compat/no-double-bracket`, `sh/compat/no-let` and
+`sh/compat/no-source` do not report inside it. `V` below is `$BASH_VERSION`, `$KSH_VERSION` or
+`$ZSH_VERSION`, written `$X`, `${X}`, `${X-}` or `${X:-}`, quoted or not. dash sets none of them.
+
+```sh
+if [ -n "${BASH_VERSION-}" ]; then source ~/.bashrc; fi
+[ -n "${BASH_VERSION-}" ] && source ~/.bashrc
+[ -n "${ZSH_VERSION-}" ] || exit 0
+[[ -o nomatch ]]
+```
+
+The shapes recognized are the `then` body of `if [ -n V ]` and the `else` body of `if [ -z V ]`, the
+right side of `[ -n V ] && …` and `[ -z V ] || …`, and the statements after `[ -n V ] || exit` or
+`[ -z V ] && exit` (`return` too) in the same file or `{ … }` block. `test -n V` and `test -z V`
+count as well. The recognition is syntactic, so a version captured in another variable is not
+understood and still reports. A construct dash cannot parse is a syntax error whichever branch it
+is in, and these exemptions do not apply to it.
+
+## What `posix-portable` does not report
+
+These constructs pass `posix-portable` with no finding. shellcheck reports each of them for a
+script whose shebang says `sh`, so run it beside eslint-sh; see [shellcheck](./shellcheck.md).
+
+| Construct | On dash | On BusyBox ash | shellcheck |
+| --------- | ------- | -------------- | ---------- |
+| `local`, other than `-n`, `-l` and `-u` | works | works | SC3043 |
+| `echo -e` | exits 0, prints the `-e` as text | exits 0, reads it as an option | SC3037 |
+| `declare`, `typeset`, other than `-A`, `-g`, `-n`, `-l` and `-u` | `not found` | `not found` | SC3044 |
+| `shopt`, any option but `lastpipe` and `globstar` | `not found` | `not found` | SC3044 |
+| `(( … ))` | `not found` | `not found` | SC3006 |
+| `x+=1` | `not found` | `not found` | SC3024 |
+| `[ a == b ]` | status 2 | works | SC3014 |
+| `$'…'` | prints the `$` as text | works | SC3003 |
+| `$"…"` | prints the `$` as text | prints the `$` as text | SC3004 |
+| `{a,b}` | prints it as text | prints it as text | SC3009 |
+
+`local` is left out because it works on dash and BusyBox ash, although POSIX does not define it and
+ksh93 has no such command. `echo -e` is left out because it never fails: only its output differs.
+`declare`, `typeset`, `shopt`, `(( … ))` and `x+=1` do fail on dash. They are left out because
+shellcheck reports each one and scripts meant for `sh` rarely use them.
+
+A `let` or `source` call written directly also passes when the file defines a function of that name
+anywhere, even if that function cannot run at the call. The check reads the name only, and dash
+still fails on such a call; see [`no-let`](./rules/compat/no-let.md) and
+[`no-source`](./rules/compat/no-source.md).
+
+Some other Bash-only constructs are parse errors under `dialect: "posix"`, so they are reported one
+at a time: `function f {}`, `${v//a/b}`, `${v:1:1}`, `${!v}`, `<<<`, `<(…)`, `&>`, `|&`, `select`,
+arrays, C-style `for`, and a `[[` containing a parenthesis.
+
+`bash --posix` is not a way to check any of this. It accepts `[[`, `let`, `source`, `local` and the
+rest, because POSIX mode does not turn off Bash's extensions.
+
+## Fixes
+
+The `compat/*` rules never autofix, because the portable alternative can change how a script
+behaves. Where a rewrite with the same behavior exists, the rule offers it as an editor
+suggestion that you apply by choice. Each rule's page says when it offers one.
+
+## Not covered
+
+- **Bash syntax that the POSIX parser rejects.** Under `dialect: "posix"`, `|&`, `&>>`, `;&`, `;;&`,
+  `{fd}` redirections, `${v@op}` and arrays are parse errors, so a POSIX file that uses them is
+  reported as unparsable, and the rules for those features never run on it. `$'…'` is read as a
+  literal `$` and a single-quoted string, as dash reads it.
+
+## Evidence
+
+Every row of the table above, and the alternative each rule's message recommends, has been run on
+real shells. [`scripts/compat-matrix/run.sh`](https://github.com/mike-north/eslint-sh/blob/main/scripts/compat-matrix/run.sh) downloads the
+GNU Bash release tarballs and dash, builds each one under the gitignored `scratch/` folder (nothing
+is installed system-wide), and runs every probe in
+[`scripts/compat-matrix/probes/`](https://github.com/mike-north/eslint-sh/tree/main/scripts/compat-matrix/probes) under each shell:
+
+```sh
+scripts/compat-matrix/run.sh
+```
+
+A probe is a short script that uses one feature, or one recommended alternative, and prints a known
+value. "yes" means the shell ran it, exited 0, and printed exactly that value; "no" means it did not.
+Each Bash column is the x.y release tarball with no upstream patches applied, pinned by SHA-256 in
+the script. The `dash` column is the evidence for the POSIX sh column.
+
+| Probe | Checks | bash-3.2 | bash-4.0 | bash-4.1 | bash-4.2 | bash-4.3 | bash-4.4 | bash-5.0 | bash-5.1 | bash-5.2 | bash-5.3 | dash-0.5.12 |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `associative-arrays-alt-jq` | the message's `jq -r --arg k "$key" '.[$k]' map.json` lookup (needs `jq` on PATH) | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `associative-arrays-typeset` | `typeset -A m` keeps two string keys apart | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `associative-arrays` | `declare -A m` keeps two string keys apart | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `brace-pad-step` | zero-padded `{01..03}` and stepped `{1..9..4}` brace expansion | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `brace-sequence-alt-loop` | the messages' counting loops, the padded one with `printf '%02d\n'` and the stepped one by `i + 4`, each written exactly as printed | not run | not run | not run | not run | not run | not run | not run | not run | not run | not run | not run |
+| `case-attributes-alt-tr` | the message's `$(printf '%s' "$v" \| tr '[:upper:]' '[:lower:]')` and its upper-case twin | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `case-fallthrough-alt` | the message's rewrites: the next branch's commands repeated for `;&`, and a second `case` for `;;&` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `case-fallthrough` | `;&` runs the next branch without testing its pattern | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `case-modification-alt-pattern-tr` | the pattern message's `tr a A` advice, spelling out the matched characters | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `case-modification-alt-tr` | the four `tr` examples the message prints, written exactly as it prints them | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `case-modification-pattern` | the pattern forms `${v^^l}` and `${v,,L}` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `case-modification` | `${v^}`, `${v^^}`, `${v,}`, `${v,,}` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `case-resume` | `;;&` goes on to test the next patterns | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `coproc-alt-mkfifo` | the message's named-pipe pattern: `mkfifo`, a background reader/writer, the script opening both pipes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `coproc` | `coproc cat`, writing to and reading back from `${COPROC[@]}` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `declare-g-alt-assign` | the message's plain `name=value` and `export name=value` inside a function | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `declare-g-typeset` | `typeset -g` inside a function sets a global | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `declare-g` | `declare -g` inside a function sets a global | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `declare-lu-local` | `local -l` and `typeset -u` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `declare-lu` | `declare -l` / `declare -u` case-converting attributes | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `double-bracket-alt-test-case` | the message's `[ … ]` for tests and `case` for pattern matching | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `double-bracket` | `[[ abc == a* ]]` matches a pattern, and an `if` on it takes its `then` branch | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `epoch-alt-date` | the message's `$(date +%s)` (GNU, BSD and BusyBox `date`, not POSIX) is a number | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `epochrealtime` | `$EPOCHREALTIME` is set to seconds with a fraction | no | no | no | no | no | no | yes | yes | yes | yes | no |
+| `epochseconds` | `$EPOCHSECONDS` is set to a number | no | no | no | no | no | no | yes | yes | yes | yes | no |
+| `fd-variable-alt-fixed` | the message's fixed descriptor number, `exec 3>file` … `exec 3>&-` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `fd-variable` | `exec {fd}>file` allocates a descriptor into a variable | no | no | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `globstar-alt-find` | the message's `find a -name 'f.txt'` recursive search | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `globstar` | `shopt -s globstar` makes `**` recurse | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `lastpipe-alt-posix-heredoc` | the POSIX message's here-document feeding the loop | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `lastpipe-alt-posix-tmpfile` | the POSIX message's `cmd > "$tmp"` then `while read -r line; do …; done < "$tmp"` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `lastpipe-alt-procsub` | the message's `while read -r line; do …; done < <(cmd)` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `lastpipe` | `shopt -s lastpipe` runs the last pipeline element in the current shell | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `let-alt-arithmetic` | the message's arithmetic expansion, `n=$((1 + 2))` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `let` | `let n=1+2` assigns the sum | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `mapfile-alt-posix-read-loop` | the message's `while IFS= read -r` loop, with a named variable as POSIX requires | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `mapfile-alt-suggestion` | the suggestion's exact rewrite of `mapfile -t a < in.txt`, from a pipeline too | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `mapfile-readarray` | the `readarray -t a < file` synonym | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `mapfile` | `mapfile -t a < file`, including a last line with no newline | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `nameref-alt-posix-eval` | the POSIX message's `eval "$name=\$value"` to assign and `eval "value=\$$name"` to read by name | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `nameref-alt-printf-v` | the message's `printf -v "$name" '%s' value` to assign and `${!name}` to read by name | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `nameref-declare` | `declare -n` and `typeset -n` read through a nameref | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `nameref` | `local -n` makes a nameref that assigns the caller's variable | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `negative-index-alt-length` | the message's `${arr[$((${#arr[@]}-1))]}`, the suggestion's `-2` form, and the docs' assignment form | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `negative-index-assign` | assigning `a[-1]=Z` | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `negative-index-length` | the element length `${#a[-1]}` | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `negative-index-read` | reading `${a[-1]}` and `${a[-2]}` | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `negative-index-unset` | `unset 'a[-1]'` | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `nounset-empty-array-alt` | the message's and suggestion's `${a[@]+"${a[@]}"}` under `set -u`, empty and with words that hold spaces | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `nounset-empty-array-star-alt` | the suggestion's `"${a[*]-}"` under `set -u` gives one empty word for an empty array, and the joined words otherwise | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `nounset-empty-array-star` | `"${a[*]}"` and unquoted `${a[@]}` of an empty array under `set -u` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
+| `nounset-empty-array` | `"${a[@]}"` of an empty array under `set -u` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
+| `param-transform-alt-case-operators` | the case messages' Bash 4.0 spellings for a target from 4.0 to 5.0: `"${v^^}"`, `"${v^}"`, `"${V,,}"` | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `param-transform-alt-declare-p` | the `@A` message's `declare -p`, whose output re-creates the variable | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `param-transform-alt-printf-b` | the `@E` message's `printf '%b'` expanding backslash escapes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `param-transform-alt-printf-q` | the `@Q` message's `printf '%q'`, whose output `eval` reads back as the same value | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `param-transform-alt-tr` | the `tr` examples the `@U`, `@u` and `@L` messages print for a target older than 4.0, written exactly as printed | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `param-transform-eapa` | the other Bash 4.4 operators `${v@E}`, `${v@P}`, `${v@A}`, `${v@a}` | no | no | no | no | no | yes | yes | yes | yes | yes | no |
+| `param-transform-k-lower` | `${a[@]@k}` key-value pairs as separate words | no | no | no | no | no | no | no | no | yes | yes | no |
+| `param-transform-k-upper` | `${a[@]@K}` quoted key-value pairs | no | no | no | no | no | no | no | yes | yes | yes | no |
+| `param-transform-q` | `${v@Q}` quoting transformation | no | no | no | no | no | yes | yes | yes | yes | yes | no |
+| `param-transform-ul` | `${v@U}` / `${v@L}` / `${v@u}` case transformations | no | no | no | no | no | no | no | yes | yes | yes | no |
+| `pipe-amp-alt` | the message's and suggestion's `2>&1 \|`, also after a redirection of the left side, as `\|&` orders it | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `pipe-amp` | `\|&` pipes stderr too | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `printf-time-alt-date` | the message's `date '+FORMAT'` for the current time, here `date '+%Y'` | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `printf-time` | `printf '%(%Y)T' 0` builtin date formatting | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `redirect-amp-append-alt` | the message's and suggestion's `>> log 2>&1` appends stdout and stderr | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `redirect-amp-append` | `&>>` appends stdout and stderr | no | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `source-alt-dot` | the message's `. ./lib.sh`, the `.` special built-in with a path that contains a slash | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `source` | `source ./lib.sh` reads the file into the current shell | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `test-v-alt-plus-set` | the message's `[ -n "${name+set}" ]`, under `set -u`, for a set, an empty and an unset variable | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `test-v` | `[[ -v name ]]` and `test -v name` | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `unicode-escape-alt-octal` | the message's UTF-8 bytes as octal escapes, `$'\303\251'`, with no locale set | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | no |
+| `unicode-escape-beyond-latin1` | `$'\u0041'`, `$'\u2713'` and `$'\U0001F389'`, outside U+0080–U+00FF, are decoded to UTF-8 | no | no | no | yes | yes | yes | yes | yes | yes | yes | no |
+| `unicode-escape` | `$'\u00e9'` (U+00E9, inside U+0080–U+00FF) is decoded to UTF-8 e-acute | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+| `wait-n-alt-pid` | the message's `wait "$pid"` on a job's saved `$!`, which returns that job's status | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes | yes |
+| `wait-n` | `wait -n` waits for the next job to finish | no | no | no | no | yes | yes | yes | yes | yes | yes | no |
+
+How to read it:
+
+- **Gates.** Each feature probe turns from "no" to "yes" at exactly the release in the Bash column
+  of the rule table, and is "no" under dash, matching every `POSIX sh: no`. Bash 4.1 is in the
+  matrix because it is the release just before the 4.2 boundary of `declare -g` and `lastpipe`.
+  Bash 4.0 is the release just before the 4.1 boundary of `{fd}` redirections.
+- **POSIX-only gates.** The rows for `[[`, `let` and `source`, the rule table's `every`, are "yes" on
+  every Bash in the matrix and "no" under dash, so no `shellVersion` can change whether they report.
+  dash runs a script past each one without a syntax error, which is why a shell's own version check
+  can guard them; see [A branch for one shell](#a-branch-for-one-shell).
+- **Parameter transformations.** `@Q`, `@E`, `@P`, `@A` and `@a` start working in 4.4; `@U`, `@u`,
+  `@L` and `@K` in 5.1; `@k` in 5.2.
+- **Unicode escapes.** `unicode-escape-beyond-latin1` (`\u0041`, `\u2713`, `\U0001F389`) works from
+  4.2, but `unicode-escape` (`\u00e9`) only from 4.3: the 4.2 release prints `e9`, the Latin-1 byte,
+  for U+00E9. Bash 3.2 to 4.1 print the escape as literal text, with no error.
+- **Empty arrays under `set -u`.** `"${a[@]}"`, `"${a[*]}"` and an unquoted `${a[@]}` abort with
+  `unbound variable` through 4.3. `${#a[@]}`, `${!a[@]}` and `${a[@]-}` work in every Bash, so the
+  rule does not report them. The slice `${a[@]:0}` and the replacement `${a[@]/x/y}` were also
+  probed outside this table: they work on 3.2 to 4.1, fail on 4.2 and 4.3, and work again from 4.4,
+  which a minimum-version gate cannot express, so the rule does not report them.
+- **Negative subscripts.** Bash 4.2 reads `${a[-1]}`, but rejects `${#a[-1]}`, `a[-1]=Z` and
+  `unset 'a[-1]'` with `bad array subscript`. 4.3 is the first release where every form works.
+- **Brace sequences.** `brace-pad-step` is "no" on Bash 3.2, which prints `1 2 3 {1..9..4}` with
+  no error, and on dash, which prints `{01..03} {1..9..4}`; it is "yes" from 4.0. That row records
+  the `run.sh` result reported in issue #237; the probe was also re-run on `/bin/bash` (3.2.57),
+  Homebrew's Bash 5.3.9 and the system `dash`, with the same outcomes. The
+  `brace-sequence-alt-loop` row has not been run through `run.sh`: its probe was run only on macOS's
+  `/bin/bash` (3.2.57), Homebrew's Bash 5.3.9 and the system `dash`, which are distribution builds,
+  not the tarball releases in the other columns, and each printed the expected line. Fill the row by
+  running `scripts/compat-matrix/run.sh`.
+- **Alternatives.** Every alternative a message recommends for a Bash target works on Bash 3.2,
+  except `param-transform-alt-case-operators` (`"${v^^}"` and its twins), which the
+  `no-parameter-transformation` message offers only for a target from 4.0 to 5.0, where it works.
+  The ones that are "no" under dash (`< <(cmd)`, the `mapfile` suggestion's array loop, the
+  `${arr[$((${#arr[@]}-1))]}` count, `printf -v`, `printf '%q'`, `declare -p`, the `${a[@]+…}` and
+  `${a[*]-}` guards, `$'\303\251'`) use Bash syntax and appear only in Bash-target messages; the
+  alternatives the POSIX-target messages give (`tr`, a named pipe, a temporary file or here-document,
+  a `while IFS= read -r line` loop, a plain assignment, `eval`, `[ -n "${x+set}" ]`, `date`, `find`,
+  `wait "$pid"`, `[ … ]` and `case`, `$(( … ))`, `. ./lib.sh`) all work under dash.
+- **`date +%s`.** `epoch-alt-date` passes under every shell here because the probes run with GNU
+  `date`. `%s` is not in POSIX `date`; the message says so.
+- **`jq`.** The `no-associative-arrays` advice runs an external program, so its row shows that the
+  command as written works wherever `jq` is installed, not that a shell provides it.
+