@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

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

@@ -0,0 +1,85 @@
+# `sh/compat/no-pipe-all`
+
+Disallow the `|&` pipe, shorthand for `2>&1 |`, 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` | suggestions | `sh/sh`   |
+
+## Rule details
+
+`|&` arrived in Bash 4.0 (Bash NEWS for 4.0). Bash 3.2 rejects it as a syntax error (``syntax error near unexpected token `&'``), so the whole script fails to run.
+
+The rule reports a pipeline whose operator is `|&`; the report is on the operator. A plain `|`, `||`, `&&`, a background `&` followed by a command, a `>&` redirection, and any of these in quotes or comments are other syntax and are not reported.
+
+The portable spelling is `cmd 2>&1 | other`. The Bash manual defines `|&` as an implicit `2>&1` applied after any redirections the left-hand command writes, so writing `2>&1` just before the `|` is exactly equivalent, also after a redirection such as `2>/dev/null`. The rule offers that rewrite as a suggestion. It edits only the operator, so a here-document on the left-hand command keeps its body where it is.
+
+Under `dialect: "posix"` the parser itself rejects `|&`, so a POSIX file that uses it fails to parse and this rule does not run on it.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` 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"} -->
+```sh
+make |& tee build.log
+# becomes
+make 2>&1 | tee build.log
+```
+
+## 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-pipe-all': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+```sh
+make |& tee build.log
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "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.
+
+## 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 `|&` 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.

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

@@ -0,0 +1,75 @@
+# `sh/compat/no-printf-time-format`
+
+Disallow `printf`'s `%(fmt)T` date format in scripts whose target shell lacks it: 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
+
+The `%(fmt)T` directive arrived in Bash 4.2 (Bash NEWS for 4.2). Bash 4.1 rejects it with ``printf: `(': invalid format character``, so the timestamp is never printed.
+
+The rule reads `printf` commands (also through `builtin` or `command`). The format is the first argument after an optional `-v name` and `--`; when it is a static word, the rule scans it as `printf` does: `%%` is a literal percent sign, and a directive may carry flags, a width and a precision before the `(`. A format with a `%(…)T` directive reports, on the format word. A format that is not static (`printf "$fmt"`) cannot be read, and the same text as another argument or in another command (`echo '%(%Y)T'`) is not a format, so neither reports.
+
+The portable alternative for the current time is `date '+fmt'`, which takes the same `strftime` format. `printf '%(fmt)T' N` formats an arbitrary epoch time `N`, which has no portable `date` spelling (GNU `date -d @N` and BSD `date -r N` differ), so convert those by hand.
+
+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`.
+- `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-printf-time-format': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+printf '%(%Y-%m-%d)T\n' -1
+printf -v stamp '[%(%H:%M:%S)T]' -1
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "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.
+
+## 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 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.

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

@@ -0,0 +1,98 @@
+# `sh/compat/no-source`
+
+Disallow the `source` builtin in scripts that target POSIX sh, where the portable name is `.`.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `posix-portable` | suggestions | `sh/sh`   |
+
+## Rule details
+
+POSIX lists `source` among the command names whose results are unspecified ([Shell Command Language, section 2.9.1.4](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#tag_19_09_01_04)). dash, the `/bin/sh` of Debian and Ubuntu, has no such command: `source ./lib.sh` fails with `source: not found` and status 127, and the file is never read. Under `set -e` that stops the script.
+
+`bash --posix` and BusyBox ash both accept `source`, so a script can pass on them and still fail on dash.
+
+Under `dialect: "posix"` the parser reads `source` as an ordinary command, and the rule reports a command whose effective name is `source`, after following wrappers such as `command`. It reports the `source` word. `command -v source` only asks about the word and is not reported. A use only a shell with a version variable can reach is not reported either, such as the body of `if [ -n "${BASH_VERSION-}" ]`, because dash never runs it; [version compatibility](../../compat.md#a-branch-for-one-shell) lists the shapes recognized.
+
+A function named `source` anywhere in the file exempts a call that names it directly, since dash can then run that function. `bash --posix` refuses to define a function with that name, which this rule does not judge. This is only a name check across the whole file: it ignores execution order and does not prove the function exists at the call. Each of these stays silent, and the `source` call still fails on dash with `source: not found` and status 127:
+
+- A call that runs before the definition.
+- A definition in a branch that is not taken.
+- A definition in a subshell, or in a function that is never called.
+- A definition removed by a later `unset -f source`.
+
+A call through a wrapper gets no exemption and is reported. `command source ./lib.sh` skips the function and fails with status 127, as does `env source ./lib.sh`, and dash has no `builtin` at all.
+
+The portable alternative is the `.` special built-in. The rule offers it as a suggestion only where the two read the same file with the same effect, which needs all of these:
+
+- The command is written directly, with no wrapper.
+- It has no leading assignment. `FOO=1 . ./lib.sh` leaves `FOO` set afterwards on a POSIX shell, while Bash outside POSIX mode scopes `FOO=1 source ./lib.sh` to that command.
+- It has exactly one operand. dash ignores further operands of `.`, where `source` would set the positional parameters.
+- The operand has a literal `/`, outside any expansion. With no slash, `.` searches `PATH` and does not look in the current directory.
+
+<!-- transform: {"kind": "suggestion", "dialect": "posix"} -->
+```sh
+source ./lib.sh
+# becomes
+. ./lib.sh
+```
+
+Other forms get the report without a suggestion.
+
+Those conditions do not cover a file that cannot be read, where the rewrite behaves differently. POSIX says a non-interactive shell aborts when [`.`](https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html#dot) finds no readable file. `. ./missing || echo fallback` ends the script with status 2 on dash and BusyBox ash and status 1 under `bash --posix`, and the fallback never runs. Bash outside POSIX mode returns status 1 from `source` and runs the fallback, and on dash `source ./missing || echo fallback` also runs it, because `source` is not found. To keep a fallback, test first:
+
+```sh
+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: "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-source': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix", "findings": 2} -->
+```sh
+source ./lib.sh
+source "$HOME/.profile"
+```
+
+### Correct
+
+With `dialect: "posix"`:
+
+<!-- example: {"dialect": "posix"} -->
+```sh
+. ./lib.sh
+. "$HOME/.profile"
+```
+
+## When not to use it
+
+Turn the rule off when your scripts only ever run where `source` 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 SC3046 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 whether it can follow the sourced path (SC1090, SC1091).

package/docs/rules/compat/no-test-v.md

@@ -0,0 +1,82 @@
+# `sh/compat/no-test-v`
+
+Disallow the `-v name` test (`[[ -v x ]]`, `test -v x`, `[ -v x ]`) in scripts whose target shell
+lacks it: 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
+
+The `-v` test arrived in Bash 4.2 (Bash NEWS for 4.2). In Bash 4.1 and older, `[[ -v x ]]` is a syntax error (`conditional binary operator expected`), so the whole script fails to parse, not only the test. `test -v x` fails with `unary operator expected`.
+
+The rule reports the `-v` test in two places:
+
+- inside `[[ … ]]`, where the parser gives the test its own node;
+- in a `test` or `[` command (also through `builtin` or `command`), where `-v` is an ordinary argument. The rule reads the arguments the way Bash's `test` does: with two arguments a leading `-v` is the operator; with three, the middle one is a binary operator if it can be one, and `! -v name` negates the test; with four, a leading `!` or surrounding parentheses peel off; anything longer goes through `test`'s own precedence rules, where `-v` is the operator only where a primary is expected and another argument follows it.
+
+So `-v` as an operand does not report: `[ "$a" = -v ]`, `[ -n -v ]`, a lone `[ -v ]`, and `[[ $a == -v ]]` are clean, and so is `-v` of another command (`grep -v`) and any `-v` in quotes. A double-quoted expansion (`"$name"`) always makes exactly one argument, so it counts as an operand; an unquoted one may split into several arguments or none, so reading stops there. The report is on the `[[` test or on the `-v` word.
+
+The portable alternative is `[ -n "${name+set}" ]`. `${name+set}` expands to `set` when the variable is set, even to the empty string, and to nothing when it is unset, and it is safe under `set -u`. Under `dialect: "posix"` the parser does not read `[[` as a test, so only `test` and `[` report there; `[[` itself in a POSIX script is outside this rule.
+
+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.
+- `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-test-v': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+```sh
+if [[ -v CI ]]; then echo ci; fi
+if test -v HOME; then echo home; fi
+[ ! -v TOKEN ] && exit 1
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "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.
+
+## 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 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.

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

@@ -0,0 +1,91 @@
+# `sh/compat/no-unicode-escape`
+
+Disallow the `\uXXXX` and `\UXXXXXXXX` escapes in `$'…'` strings in scripts whose target shell does
+not decode them to UTF-8: Bash older than 4.2 for most code points, and older than 4.3 for U+0080
+to U+00FF. This includes the Bash 3.2 that macOS ships as `/bin/bash`.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Bash 4.2 added `\u` and `\U` escapes to `$'…'` strings (Bash NEWS for 4.2). The release tarballs behave in three ways, observed on real shells (see [Evidence](../../compat.md#evidence)):
+
+- **Bash 4.1 and older** leave the escape as literal text (`$'\u00e9'` is the six characters `\u00e9`), with no error.
+- **Bash 4.2** decodes it, but writes a code point from U+0080 to U+00FF as a single Latin-1 byte even in a UTF-8 locale (`e9` for U+00E9, where UTF-8 is `c3 a9`). Every other code point comes out as UTF-8, both `\u2713` and `\U0001F389`.
+- **Bash 4.3 and newer** write every code point as UTF-8.
+
+So the minimum version depends on the code point: 4.3 for U+0080 to U+00FF, 4.2 for the rest. A distribution's patched 4.2 may differ from the release tarball.
+
+The rule scans each `$'…'` string as Bash decodes it: `\\` is a backslash, `\cX` is one control character (so in `\cu0041` the `u` belongs to `\c`), and `\u` takes one to four hex digits, `\U` one to eight. A `\u` with no hex digit is literal text. It reports once per string, naming the escape that needs the newest release; the report is on the whole string. Plain `'…'` and `"…"` strings do not decode escapes and are not read, and neither are `printf` formats.
+
+The portable alternative is to write the character's UTF-8 bytes as octal escapes, which every Bash decodes in `$'…'`: `$'\303\251'` for U+00E9. The message gives the bytes for the escape it names.
+
+Under `dialect: "posix"` the parser reads `$'…'` as a literal `$` followed by an ordinary single-quoted string, as dash does, so there is no `$'…'` string for this rule to report.
+
+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).
+- `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-unicode-escape': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+```sh
+ok=$'\u2713'
+printf '%s\n' $'caf\u00e9'
+```
+
+With `shellVersion: "4.2"`, only the Latin-1 range reports:
+
+<!-- example: {"dialect": "bash", "shellVersion": "4.2", "findings": 1} -->
+```sh
+ok=$'\u2713'
+printf '%s\n' $'caf\u00e9'
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "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.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck reports `$'…'` 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.

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

@@ -0,0 +1,85 @@
+# `sh/compat/no-wait-n`
+
+Disallow `wait -n` in scripts whose target shell lacks it: Bash older than 4.3, including the
+Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+`wait -n`, which waits for the next job to finish, arrived in Bash 4.3 (Bash NEWS for 4.3). Bash 4.2 and older reject the option with `wait: -n: invalid option` and return 2 at once. A job pool that throttles itself with `wait -n` therefore stops waiting, and every job runs at the same time, with no error that stops the script.
+
+The rule reads `wait` commands (also through `builtin` or `command`). It reports an option word, up to the first operand or `--`, that is a cluster containing `n` (`-n`, `-fn`); the report is on that word. The value after `-p` (Bash 5.1's `wait -p var`) is that option's operand, not an option. `-n` of another command (`echo -n`) and an `-n` after an operand are not read.
+
+A script that defines its own `wait` function still reports: the rule reads the name `wait` and does not follow shell function definitions.
+
+The portable alternative is to wait for one job at a time by its PID: keep each job's `$!`, and run `wait "$pid"`, which returns that job's exit status. This waits for the oldest job rather than the first to finish, so a pool that uses it can sit idle behind one slow job, but it never runs more jobs than its limit.
+
+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.
+- `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-wait-n': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+```sh
+for job in a b c d; do
+  run "$job" &
+  if [ "$(jobs -r | wc -l)" -ge 2 ]; then wait -n; fi
+done
+wait
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+pids=
+for job in a b c d; do
+  run "$job" &
+  pids="$pids $!"
+done
+for pid in $pids; do
+  wait "$pid" || echo "job $pid failed"
+done
+```
+
+With `shellVersion: "4.3"` or newer, or with no `shellVersion`, `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`
+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 `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.

package/docs/rules/max-script-complexity.md

@@ -0,0 +1,109 @@
+# `sh/max-script-complexity`
+
+Cap how many functions, how many levels of nesting and how many statements a single script may
+contain, so that a machine-written script stays reviewable in one sitting.
+
+| Configs          | Fixable     | Languages |
+| ---------------- | ----------- | --------- |
+| `agent-authored` | not fixable | `sh/sh`   |
+
+## Rule details
+
+A script that grows past what a reviewer can hold in their head cannot be vouched for, however
+clean each line is. This rule enforces three independent limits. Each limit is reported **at most
+once per file**, under its own message, and is skipped when set to `null`. A limit of `0` is a real limit: it allows none of that construct, so the first one reports.
+
+- **Function count** (`maxFunctions`, default `20`): the number of function declarations in the
+  file, at any depth. Reported at the file level (line 1), because no one declaration is to blame.
+- **Nesting depth** (`maxNesting`, default `4`): every `if`, `for` (including `select`), `while`,
+  `until`, `case`, subshell `( … )` and brace group `{ …; }` adds one level. Reported at the first
+  construct whose depth is past the limit. An `elif` or `else` arm continues its `if` and adds no
+  depth. A function's own body braces are the function's syntax, not a brace group, and functions,
+  command substitutions and process substitutions add no depth.
+- **Statement count** (`maxStatements`, default `300`): every statement anywhere in the file,
+  because the limit bounds the script's overall size. That includes top-level statements, those in
+  function bodies and in nested compound commands, and the statements in condition and header
+  lists: in `if a; then :; fi` the `if`, the `a` and the `:` are three statements, and likewise the
+  `a` in `while a; do …`. Statements inside command substitutions `$(…)` count too: in
+  `x=$(echo a; echo b)` the assignment and the two `echo` statements are three statements. The operands of `&&`, `||` and `|` are not counted separately, so one
+  pipeline or and-or list is one statement, and a function declaration is one statement plus those
+  in its body. Reported at the first statement past the limit.
+
+The rule inspects syntax only and has no autofix or suggestion: splitting a script is a human
+decision.
+
+## Options
+
+An optional object; each field is a non-negative integer limit, `null` (switches that one limit off) or omitted (takes the default). `0` is a real limit, as in ESLint's `max-depth`, `max-params` and `max-statements`: `maxFunctions: 0` forbids function declarations.
+
+- `maxFunctions` (default `20`): most function declarations allowed.
+- `maxNesting` (default `4`): deepest control-structure nesting allowed.
+- `maxStatements` (default `300`): most statements allowed.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/max-script-complexity': ['error', { maxFunctions: 10, maxNesting: 3, maxStatements: null }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `{ maxNesting: 2 }`:
+
+<!-- example: {"options": {"maxNesting": 2}, "findings": 1} -->
+```sh
+if [ -f a ]; then
+  for f in *; do
+    while read -r line; do # reported: nested 3 levels deep
+      echo "$line"
+    done < "$f"
+  done
+fi
+```
+
+With `{ maxFunctions: 1 }`:
+
+<!-- example: {"options": {"maxFunctions": 1}, "findings": 1} -->
+```sh
+a() { :; }
+b() { :; } # the file is reported on line 1: 2 functions
+```
+
+### Correct
+
+With `{ maxNesting: 2 }`:
+
+<!-- example: {"options": {"maxNesting": 2}} -->
+```sh
+if [ -f a ]; then
+  echo one
+elif [ -f b ]; then # an elif adds no depth
+  for f in *; do
+    echo "$f"
+  done
+fi
+
+run() { # a function's own braces add no depth
+  if true; then
+    echo ok
+  fi
+}
+```
+
+## When not to use it
+
+When your project does not hold a size policy for scripts, or when a generated script is
+legitimately large. Disable one check by setting its limit to `null` rather than the whole rule.
+
+## 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 defects in individual commands and has no check that limits a script's size,
+function count or nesting depth, so this rule overlaps none of its `SCxxxx` checks.