@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

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.

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

@@ -0,0 +1,139 @@
+# `sh/no-dynamic-invocation`
+
+Disallow commands whose executed command cannot be statically determined, so that every command
+a script can run is readable from its source.
+
+| Configs | Fixable      | Languages |
+| ------- | ------------ | --------- |
+| `agent-authored` | not fixable | `sh/sh` |
+
+## Rule details
+
+To vouch for a script, a reviewer has to know every command it can run. A command word whose
+value is only known at run time defeats that: `"$cmd" args`, `${tool} x`, `$(pick-tool) x`, and
+`"${cmd[@]}"` can each run anything. So can a string of shell code handed to another shell:
+`bash -c "$x"` and `sh -c '…'` run code that is a string to the reader, not commands.
+
+The rule checks every simple command in the file, wherever it appears: top level, functions,
+loops, conditionals, pipelines, and command and process substitutions. So in
+`echo "$("$cmd")"`, the inner `"$cmd"` reports.
+
+For each command, the rule finds the command that actually runs by following _transparent
+wrappers_: commands that run the word after them. `time ls` runs `ls`, and
+`sudo -u deploy "$prog"` runs `"$prog"`. The wrappers followed are:
+
+- `command`, `exec`, `env`, `nohup`, `nice`, `time`, `timeout`, and `sudo`, with their own
+  options skipped (`timeout 10 ls`, `env FOO=1 ls`). `command -v name` only looks `name` up, so
+  it runs nothing else.
+- Bash's `builtin`.
+- Shells invoked as commands: `bash`, `sh`, `dash`, `ksh`, `mksh`, and `zsh`.
+  `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`.
+
+A command then reports in one of two ways:
+
+- **`dynamicInvocation`**: the command that runs is not a static word. A word is static only when
+  its text is fully known from the source, with no parameter expansion, command substitution,
+  tilde, glob, or brace expansion. So `~/bin/tool` reports, because `~` depends on `$HOME`. An
+  option a wrapper doesn't recognize, such as `sudo -D /tmp rm x`, also reports: the rule never
+  guesses which word is the command.
+- **`embeddedCommand`**: the command runs code embedded in a string, as with `bash -c …`,
+  `sh -c …`, or `env -S '…'`. It reports even when the string is a literal, because the string is
+  never checked as commands. Analyzing the string's contents is out of scope.
+
+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.
+
+It does not depend on `languageOptions`.
+
+## Options
+
+- `allowInFunctions` (`string[]`, default `[]`): names of dispatcher functions. A
+  `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.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-dynamic-invocation': [
+      'error',
+      { allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] },
+    ],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 10, "messageIds": ["dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "dynamicInvocation", "embeddedCommand", "embeddedCommand"]} -->
+```sh
+"$cmd" args               # the command word is a parameter expansion
+${tool} x                 # same, braced
+$(pick-tool) x            # the command is computed by a command substitution
+"${cmd[@]}"               # array splat: the first element is the command
+exec "$@"                 # exec runs its first argument
+sudo -u deploy "$prog"    # sudo runs a dynamic target
+echo "$("$cmd")"          # a dynamic command nested in a substitution
+~/bin/tool x              # the path depends on $HOME
+bash -c "$script"         # embeddedCommand: a string of shell code
+sh -c 'make test'         # embeddedCommand, even for a literal string
+```
+
+With `{ allowWrappers: ['with-retry'] }`:
+
+<!-- example: {"options": {"allowWrappers": ["with-retry"]}, "findings": 1, "messageIds": ["dynamicInvocation"]} -->
+```sh
+with-retry "$c"           # the wrapped command is dynamic
+```
+
+### Correct
+
+```sh
+ls -la "$dir"             # dynamic arguments are fine; the command is `ls`
+time ls                   # time is transparent; it runs `ls`
+nohup env FOO=1 make      # wrappers are followed to `make`
+command -v "$tool"        # looks a name up; runs nothing
+bash ./build.sh           # runs the literal script `./build.sh`
+alias ll='ls -l'
+ll                        # an alias name is a static command word
+```
+
+With `{ allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] }`:
+
+<!-- example: {"options": {"allowInFunctions": ["dispatch"], "allowWrappers": ["with-retry"]}} -->
+```sh
+dispatch() {
+  "$@"                    # allowed inside the dispatcher
+}
+with-retry curl https://example.com   # with-retry runs `curl`
+```
+
+## When not to use it
+
+Turn the rule off for scripts nobody needs to vouch for, where running a computed command is the
+point, such as a generic task runner. Prefer `allowInFunctions` for one dispatcher function over
+disabling the rule for the whole file, and prefer a line-level
+`# eslint-disable-next-line sh/no-dynamic-invocation` with a reason over a file-level disable,
+so new dynamic commands still report.
+
+## 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 equivalent. It treats a dynamic command word as legitimate shell, and only
+warns about how it is written, such as unquoted expansions (SC2086) or a string used where an
+array belongs (SC2089/SC2090). It can't express the policy that every command must be
+statically enumerable, which is what makes a script reviewable as a whole.

package/docs/rules/no-eval.md

@@ -0,0 +1,106 @@
+# `sh/no-eval`
+
+Disallow `eval`, and `source` or `.` of a path that is not a static literal, so that every line
+of code a script runs can be reviewed before it runs.
+
+| Configs | Fixable      | Languages |
+| ------- | ------------ | --------- |
+| `recommended`, `agent-authored` | not fixable | `sh/sh` |
+
+## Rule details
+
+A script you can review is a script whose code is all in front of you. Two constructs defeat
+that by building the code to run at run time:
+
+- **`eval`** re-parses its arguments as shell code when the line executes. The code a reviewer
+  reads is a string, not commands. That holds even for `eval "literal"`: the literal is a second
+  layer of shell parsing that no static tool, this linter included, treats as commands. So the
+  rule reports **every** `eval`, whatever its arguments.
+- **`source <path>` and `. <path>`** run another file in the current shell. When the path is
+  only known at run time, a reviewer cannot tell which file, and so which code, runs.
+
+The rule inspects every `CallExpr` (simple command), wherever it appears: top level, inside
+functions, loops, conditionals, and command substitutions.
+
+- **`eval`** (message `noEval`) is reported on the whole command. It is recognized as the
+  command that actually runs after transparent wrappers are followed, so `command eval …`,
+  `builtin eval …`, and `exec eval …` all report. `command -v eval` does not: it only looks
+  `eval` up.
+- **`source` / `.`** (message `dynamicSource`) is reported on its path word when that word is not
+  static. A word is static only when its text is fully known from the source, with no parameter
+  expansion, command substitution, tilde, glob, or brace expansion. So `source ~/lib.sh` reports,
+  because `~` depends on `$HOME`. Words after the path are positional parameters for the sourced
+  file and are not checked. Like `eval`, `source` and `.` are recognized as the command that
+  actually runs after transparent wrappers are followed, so `command source "$p"` and
+  `builtin . "$p"` report exactly as `source "$p"` does, and `command source ./static.sh` is
+  clean. The path is the word right after the effective command.
+
+The rule deliberately ignores:
+
+- the word `eval` anywhere other than the command position (`echo eval`), and in comments;
+- a command word that is itself dynamic (`"$cmd" args`), and command strings passed to another
+  shell (`bash -c "$x"`, `sh -c …`).
+
+It does not depend on `languageOptions`.
+
+## Options
+
+This rule has no options.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-eval': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 10, "messageIds": ["noEval", "noEval", "noEval", "noEval", "noEval", "dynamicSource", "dynamicSource", "dynamicSource", "dynamicSource", "dynamicSource"]} -->
+```sh
+eval "echo hi"            # eval, even of a literal string
+eval "$cmd"               # eval of a value assembled at run time
+command eval "$cmd"       # eval reached through the `command` wrapper
+builtin eval "$cmd"       # eval reached through the `builtin` wrapper
+exec eval "$cmd"          # eval reached through the `exec` wrapper
+source "$DIR/lib.sh"      # the path depends on $DIR
+. $(pick)                 # the path is computed by a command substitution
+source ~/lib.sh           # the path depends on $HOME
+command source "$p"       # source reached through the `command` wrapper
+builtin . "$p"            # `.` reached through the `builtin` wrapper
+```
+
+### Correct
+
+```sh
+source ./lib.sh           # a literal relative path
+. "/etc/profile"          # a quoted literal path
+source ./lib.sh "$1"      # only the path word must be static
+command source ./lib.sh   # a literal path stays clean behind a wrapper
+echo eval                 # `eval` is an argument here, not a command
+command -v eval           # looks `eval` up; never runs it
+```
+
+## When not to use it
+
+Turn the rule off for a script whose purpose is to run generated code, for example a bootstrap
+step that `eval`s the output of a tool like `ssh-agent -s` or `brew shellenv`, where the tool,
+not the script, is the reviewed artifact. Prefer disabling it on that line
+(`# eslint-disable-next-line sh/no-eval`) over disabling it for the whole file, so new uses
+still report.
+
+## Relationship to shellcheck
+
+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
+`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
+can't be statically reviewed doesn't ship, so it reports every `eval`, including the uses
+shellcheck accepts. If you run shellcheck and only want its narrower checks, disable this rule.

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

@@ -0,0 +1,239 @@
+# `sh/no-masked-exit-status`
+
+Disallow `local`, `declare`, `typeset`, `export` and `readonly` with a value taken from a command substitution, because the builtin's exit status replaces the command's.
+
+| Configs          | Fixable                                   | Languages |
+| ---------------- | ----------------------------------------- | --------- |
+| `agent-authored` | suggestions (split into two statements) | `sh/sh`   |
+
+## Rule details
+
+`local x=$(cmd)` runs `cmd`, then runs `local`, and the statement's exit status is the status of
+`local`, which succeeds. A failing `cmd` therefore does not stop a script under `set -e`, and in
+`local x=$(cmd) && next` the `next` runs anyway. `export X=$(cmd)`, `readonly X=$(cmd)`,
+`declare x=$(cmd)` and `typeset x=$(cmd)` behave the same way. This is the most common way a
+script that sets `set -euo pipefail` still swallows a failure, which is why
+[`require-strict-mode`](./require-strict-mode.md) alone does not close the hole.
+
+The rule reports a `local`, `declare`, `typeset`, `export` or `readonly` operand of the form
+`name=value` whose value contains a command substitution, `$(…)` or backticks. The substitution
+can be the whole value, part of a larger word (`export DIR=/opt/$(basename "$p")`), inside double
+quotes, or inside a parameter expansion (`"${y:-$(z)}"`, `${y:$(n):1}`, `${a[$(i)]}`) or an
+arithmetic expansion (`$(( $(count) + 1 ))`). In a plain assignment a failing substitution in any of
+those places fails the assignment, so `set -e` stops the script in Bash, dash, zsh and ksh93; behind a
+declaration builtin none of them does. The rule reads the builtins behind
+`builtin` and `command` too. It reports once per operand, on the operand, and the message names the
+builtin and the variable.
+
+What the rule does not report:
+
+- A value with no command substitution: `local x=$y`, `local x="${y:-z}"`, `local n=$((a + b))`.
+- A declaration with no value: `local x`, `export X`, `readonly X`.
+- A plain assignment: `x=$(cmd)`. Its exit status is the command's.
+- The split forms: `local x; x=$(cmd)` and `X=$(cmd); export X`. `export X; X=$(cmd)` is not reported
+  either, but it exports the old value to the command, which the original did not.
+- A process substitution used as a value (`local p=<(cmd)`). It expands to a path, so there is no
+  status to lose.
+- An array value (`local -a a=($(cmd))`). shellcheck does not report SC2155 for it either.
+
+**On purpose, and noisy for some code.** `export PATH="$(dirname "$0"):$PATH"` is reported. The
+substitution's failure is hidden there like anywhere else, and the split
+(`PATH="$(dirname "$0"):$PATH"` then `export PATH`) is safe because `export` creates no scope. To quiet
+it, split the line as suggested, add an ESLint disable comment for the line, or set
+`builtins: ["local"]` to stop checking `export`, `readonly`, `declare` and `typeset`.
+
+The corpus the rule was measured on shows how much of the output is worth acting on. Of 40 evenly
+spaced reports in eight open-source projects, 25 were real masked failures (`mktemp`, `get_*`
+functions, `cd … && pwd`, `docker ls`) and 15 were low value: a `date`, a `$(cat)`, a command ending
+in `|| true`, or a pipeline whose last stage already decides the status (`… | awk`, `| wc -l`). So
+about one report in three is a correct finding that you may not want to fix. That is
+the same noise as shellcheck's SC2155, which the rule matches on the shared constructs. In
+`agent-authored` the rule is an `error`, because the preset's contract is that a failure stops
+the script. A team that wants a gentler start can set it to `warn`, or use `onlyWithErrexit`, which
+drops the findings in files and functions where errexit is not on.
+
+**Suggestion.** There is no autofix. Splitting the declaration changes behavior on purpose: under
+`set -e` a failure of `cmd` now stops the script. The editor suggestion declares the names first
+and assigns each substituted one in its own statement. It keeps the builtin's flags, the
+indentation and a trailing comment.
+
+<!-- transform: {"kind": "suggestion"} -->
+
+```sh
+f() {
+  local -i n=$(count) # lines
+}
+# becomes
+f() {
+  local -i n
+  n=$(count) # lines
+}
+```
+
+With several operands, every name is declared first and then each substituted one is assigned:
+`local APP="" REMOTE="$(fn-get-remote)" HOST=""` becomes `local APP="" REMOTE HOST=""` followed by
+`REMOTE="$(fn-get-remote)"`. `export` goes the other way, because exporting first would give the
+command the old value in its environment: `export X=$(cmd)` becomes `X=$(cmd)`, `export X`. When the
+declaration forbids a later assignment (`readonly`, or `-r`),
+the suggestion assigns first and makes the variable read-only afterwards:
+`declare -r x=$(cmd)` becomes `declare x`, `x=$(cmd)`, `readonly x`.
+
+The suggestion is withheld where the split would not mean the same thing, and the report stays:
+
+- The value reads a name that the split moves before it. For `local`, `declare` and `typeset`
+  inside a function that includes the variable itself: `local P=$(echo "$P" | cut -d. -f1)`
+  would read the new, empty local after the split. `export PATH="$(…):$PATH"` is safe to split,
+  because `export` creates no new scope. For every builtin it also includes the other operands of
+  the same declaration. Any mention of such a name in the value counts, because a command can read a
+  variable by name: `local x=$([ -v x ] && echo set)`, `local x=$(declare -p x)` and
+  `export A=1 B=$(printenv A)` are withheld. So can an unrelated word, as in
+  `local name=$(git config user.name)`. Under `-i` the builtin evaluates each value as arithmetic,
+  so this reaches the values without a substitution too: `local -i a=$(cmd) b=a+1` is withheld. So
+  does `export`, which runs after the assignments: `export A=$(cmd) B=$A` is withheld. **Limit:** a
+  command that dumps every variable names none of them, so `local n=$(declare -p | wc -l)` and
+  `local n=$(set | wc -l)` keep their suggestion and see one more variable after the split.
+- A scoped declaration of a variable the shell or its commands consult, such as `PATH`, `IFS`, `HOME`,
+  `LANG`, `TERM`, `PWD` or `TMPDIR`. `local PATH; PATH=$(cmd)` empties `PATH` first, so `cmd` is not found.
+  **Limit:** any other exported variable can be read by a command too, and that is not visible in the
+  script: after `export X=1`, a command in `local X=$(cmd)` that reads `X` sees a different environment
+  once the line is split. The same goes for `export A=$(c1) B=$(./tool)` when `A` is already exported:
+  `./tool` sees the new `A` after the split, and the old one before it.
+- The value runs code the rule cannot read, and that code could read a name the split declares
+  earlier. That means the substitution runs `eval`, `source` or `.`, a command whose name is not
+  static (`$($cmd)`), or a function defined in the same file:
+  `g() { echo "$x"; }; f() { local x=$(g); }` is withheld, as is `local y=1 x=$(g)` when `g` reads
+  `y`. This applies where the split changes what is visible: `local`, `declare` or `typeset` inside a
+  function, a declaration with several operands, or one with any flag. A lone `export x=$(g)` keeps
+  its suggestion. **Limit:** a function defined in another file, such as one from a script that
+  is sourced, cannot be seen, so the rule cannot tell that a call to it reads the variable. The
+  suggestion may then change what that function sees. Read a suggestion before applying it.
+- The statement has prefix assignments, as in `A=1 export x=$(cmd)`. The replacement covers the
+  whole command and would delete them.
+- A flag changes what the split means or is not valid with an assignment. `declare -g x=$(cmd)`
+  writes the global, while the split writes the nearest local, so any `-g` is withheld (`-gx` too).
+  `local -x x=$(cmd)` would export the name to the command before it runs, so `-x` is withheld. After
+  `declare -n r`, the assignment in the split writes through `r` where the original rebinds it, so
+  `-n` is withheld on `local`, `declare` and `typeset`.
+  `-f`, `-F`, `-p` and flags the builtin does not have (`export -x`) are withheld as well, so the
+  suggestion never turns an error into an assignment. `local` outside a function is an error and
+  is also withheld. The flags kept are `-a -A -i -l -r -t -u` (`-n` for `export`).
+- The declaration is not a standalone statement: part of an `&&`/`||` list or a pipeline (including
+  `[[ … ]] && local x=$(cmd)`), an `if` or `while` condition, negated, in the background, or
+  redirected.
+- The builtin is reached through `builtin` or `command`.
+- An operand is an append (`x+=$(cmd)`) or has a subscript (`a[1]=$(cmd)`), or `readonly` has flags.
+
+Under `dialect: "posix"` the parser has no declaration clause and reads `local x=$(cmd)` as an
+ordinary command; the rule reads it the same way and offers the same suggestion. Otherwise the rule
+does not depend on `languageOptions`.
+
+## Options
+
+| Option            | Type       | Default                                                 | Effect                                                                                                                                                                                               |
+| ----------------- | ---------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onlyWithErrexit`  | `boolean`  | `false`                                                 | Report only where `errexit` is known to be on (below). |
+| `allowShebangOnly` | `boolean`  | `false`                                                 | With `onlyWithErrexit`, count options on the shebang line (`#!/bin/bash -e`, `#!/bin/sh -e`, `#!/usr/bin/env -S bash -e`) as enabled. Same meaning and default as the option of that name in [`require-strict-mode`](./require-strict-mode.md), and read by the same code. |
+| `builtins`         | `string[]` | `["local", "declare", "typeset", "export", "readonly"]` | Which declaration builtins to check, for example `["local"]` for teams that accept `export X=$(…)` at the top level. |
+
+**Where `errexit` is on.** The rule reads the plain top-level `set` statements (`set -e`,
+`set -euo pipefail`, `set -o errexit`, `set +e`) in order, with the same reading
+`require-strict-mode` uses for each one. A statement is checked when they leave `errexit` on
+before it. So `export x=$(cmd)` followed by `set -e` is not checked, and a `set -e` after five
+statements counts for the code after it. Unlike `require-strict-mode` there is no five-statement
+window, because the order is tracked. A function body is read at the point where it is defined, so
+`set -e` before `f() { … }` covers `f`.
+
+`allowShebangOnly` is off by default for the reason it is off in `require-strict-mode`: options on the
+shebang line apply only when the script is run directly, and `bash script.sh` ignores them. Turn it
+on if your scripts are always executed directly.
+
+Under `dialect: "bats"` a statement written directly in an `@test` body, or directly in a top-level
+`setup`, `teardown`, `setup_file` or `teardown_file` function, counts as on, because bats runs
+those bodies with `errexit` on, until the body runs `set +e`. This is the reading `no-unchecked-cd`
+uses. A declaration nested deeper in an `@test` (inside an `if` or a loop) falls back to the
+file-level reading, so it is not checked.
+
+What is not tracked: a `set` inside a function, a `{ … }` group, a condition or a loop; `set -e` in a
+file that is sourced; `errexit` given on the command line (`bash -e script.sh`, `sh -e`); and a
+`set -e` or `set +e` between the definition of a function and a call to it. So
+`f() { local x=$(cmd); }; set -e; f` is not checked. A function called on the left of `||` runs with
+`errexit` off, which is not followed either, so `set -e; f() { local x=$(cmd); echo ok; }; f || g` is
+reported.
+
+`onlyWithErrexit` does not apply where the script reads the status explicitly, because there the
+status is always the builtin's. Those positions are the left side of `&&` or `||`, the right side of
+one that is itself read (so `true && export x=$(false) && echo c` reports the `export`), and the last
+command of an `if`, `elif`, `while` or `until` condition, including the middle of an `&&` chain
+inside that condition (`if a && export x=$(false); then`). They are reported in every file. Status
+read further away is not followed: the caller of a function (`f || echo failed`), the last command
+of an `if` or `case` body, or a later `$?`.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-masked-exit-status': ['error', { onlyWithErrexit: true, builtins: ['local'] }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 6, "messageIds": ["maskedExitStatus", "maskedExitStatus", "maskedExitStatus", "maskedExitStatus", "maskedExitStatus", "maskedExitStatus"]} -->
+
+```sh
+f() {
+  local image=$(get_image "$1")    # reported: local's status replaces get_image's
+  local dir="$(dirname "$1")" ver=1 # reported: the quoted form too
+  declare -r token=$(read_token)   # reported: -r does not help
+}
+export LE_DIR="$(echo "$2" | sed 's|/$||')" # reported: export
+readonly N_CACHE="$(mktemp -d)"             # reported: readonly
+[ -n "$x" ] && export Y=`date`              # reported: backticks, after &&
+```
+
+### Correct
+
+```sh
+f() {
+  local image dir
+  image=$(get_image "$1")      # the assignment keeps get_image's status
+  dir=$(dirname "$1")
+  local n=$((1 + 2)) y=$z      # no command substitution
+  local -a files=($(ls))       # array values are not reported
+  local p=<(sort file)         # a process substitution is a path
+}
+LE_DIR=$(pwd); export LE_DIR
+readonly VERSION=1.2
+```
+
+## When not to use it
+
+Turn the rule off, or set `onlyWithErrexit`, for scripts whose failures are never meant to stop
+them and where the declaration idiom is accepted house style. `builtins: ["local"]` suits teams that
+accept `export X=$(…)` at the top level and only want function variables split.
+
+## 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 SC2155 ("Declare and assign separately to avoid masking return
+values") and offers no fix for it. The rule exists anyway for three reasons. `require-strict-mode`
+makes `set -euo pipefail` a contract, and this construct is the most common way a script that
+honours the contract still swallows a failure, so `agent-authored`, which requires strict mode,
+closes the hole. eslint-sh can offer the split as an editor suggestion, which shellcheck cannot. And
+`onlyWithErrexit` and `builtins` limit the policy to the files and builtins where the status matters.
+
+It is not enabled in `recommended`, which is meant to run beside shellcheck, because the two would
+report the same line twice. Where both run, disable SC2155 or this rule. The two agree on scalar
+values for all five builtins. The rule reports more than shellcheck 0.11.0 in three places: a
+substitution inside a parameter expansion operand, a substring offset, an array subscript or an
+arithmetic expansion (`local x="${y:-$(cmd)}"`, `local n=$(( $(cmd) + 1 ))`), which shellcheck does
+not look into although real shells mask their status the same way, and `local -r x=$(cmd)` or
+`declare -r x=$(cmd)`, which shellcheck exempts. The rule's
+suggestion handles the second by assigning first and then running `readonly`. It also reads the
+`builtin` and `command` forms, and honours neither a `# shellcheck disable=SC2155` directive nor
+`.shellcheckrc`; use an ESLint disable comment instead.