@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

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.

package/docs/rules/no-secret-env-reads.md

@@ -0,0 +1,173 @@
+# `sh/no-secret-env-reads`
+
+Disallow reading secret-shaped environment variables, such as `$GITHUB_TOKEN`, outside allowed sink commands.
+
+| Configs          | Fixable     | Languages |
+| ---------------- | ----------- | --------- |
+| `agent-authored` (error) | not fixable | `sh/sh`   |
+
+## Rule details
+
+Once a secret is expanded into a command's arguments, every user on the machine can read it
+through `ps` and `/proc/<pid>/cmdline`, and it tends to land in logs and `set -x` traces. This
+rule reports a read of an environment variable whose name looks like it holds a secret.
+
+The rule inspects every parameter expansion: `$NAME`, `${NAME}`, and the forms with operators such
+as `${NAME:-x}`. A read is reported when the variable's name matches a pattern. The
+default pattern is `(_TOKEN|_SECRET|_PASSWORD|_KEY)$`. It is case-sensitive, so lower-case shell
+locals such as `cache_key` are not matched.
+
+Four things are not reported:
+
+- **Assignments.** `API_KEY=value` writes the variable; it is not a read.
+- **An assignment prefix of a command that runs.** `TOKEN=$GITHUB_TOKEN tool` expands the secret
+  into the child's environment, not its argv. This is the recommended pattern, and the message
+  suggests it. The read must sit directly in the prefix value: `T=$(echo "$GITHUB_TOKEN") tool`
+  reports, because the `echo` command reads it. A bare assignment with no command
+  (`TOKEN=$GITHUB_TOKEN`) and `export TOKEN=$GITHUB_TOKEN` still read the variable and report.
+- **Expansions that never yield the value.** A length, `${#API_KEY}`, expands to a number. An
+  alternate value, `${API_KEY:+word}` or `${API_KEY+word}`, expands to `word` when the variable is
+  set and to nothing otherwise. Neither puts the secret in argv, logs, or traces. A read written
+  inside `word` is reported on its own: `${GH_TOKEN:+-H "Authorization: $GH_TOKEN"}` reports the
+  inner `$GH_TOKEN`.
+- **Arguments of an allowed sink.** A command named in `allowedSinks` may read a secret. The
+  command is resolved through transparent wrappers (`sudo vault …` is `vault`), and a command run
+  by path matches by basename.
+
+Matching is a name pattern, not secret detection.
+
+### Expected false positives
+
+The rule is a heuristic screen. Expect reports in these classes, and suppress them with a disable
+comment that says why, narrow `patterns`, or list the command in `allowedSinks`:
+
+- Names that end in a secret-shaped suffix but hold nothing secret, such as `CACHE_KEY`,
+  `PRIMARY_KEY`, or `SORT_KEY`.
+- Presence checks such as `[ -n "${API_KEY:-}" ]`. The test command never reaches argv, but the
+  value is expanded, and a `set -x` trace prints it. `[ -n "${API_KEY+set}" ]` checks presence
+  without expanding the value.
+- Reads that copy the secret into another variable (`KEY=$API_KEY`), which the rule cannot follow.
+- Reads by a command you have already vetted but not listed in `allowedSinks`.
+
+### Expected false negatives
+
+The rule matches parameter expansions only. These reads are not reported:
+
+- Arithmetic reads, such as `$((A_KEY+1))` and `(( A_KEY > 0 ))`, where the variable is named
+  without a `$`.
+
+## Options
+
+- `patterns` (`string[]`, at least one entry). Regular-expression sources tested against each
+  variable's name. They **replace** the default list. Sources are compiled case-sensitively. An
+  invalid source fails config validation.
+
+  Default: `["(_TOKEN|_SECRET|_PASSWORD|_KEY)$"]`.
+
+- `allowedSinks` (`string[]`). Command names whose arguments may read a secret-shaped variable.
+
+  Default: `[]`.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-secret-env-reads': [
+      'error',
+      { allowedSinks: ['vault', 'gh'], patterns: ['(_TOKEN|_SECRET|_PASSWORD|_KEY|_PAT)$'] },
+    ],
+  },
+}
+```
+
+### Patterns run against script-controlled text
+
+`patterns` is tested against every variable name the linted script expands, and the script's author
+chooses that text. When you lint scripts you do not control, a pattern with nested or overlapping
+quantifiers can make the regular expression engine backtrack for a time that grows exponentially
+with the name's length. Write anchored patterns with one level of repetition over a character class.
+
+The rule rejects the most common accident: a pattern that repeats a group which itself repeats
+(`*`, `+`, `{n,}` or `{n,m}` with `m > 1` applied to such a group). It is not a proof that an
+accepted pattern is safe. Review every pattern you accept as if the guard were not there.
+
+**What it does not catch.** These pass the check and can still be slow on a long name. Timings are
+from Node 24 on a busy laptop and vary by machine; the shape of the growth is what matters.
+
+- Alternation branches that overlap under a repetition grow exponentially. `^([A-Z]|[A-Z0-9])+_KEY$`
+  took about 0.4 s on a 24-character name, 1.2 s at 26 and 4.7 s at 28. `(a|a)+$` took 1.6 s at
+  24 characters and 6.4 s at 26. `^(A|AA)*$` is the same shape.
+- Adjacent quantifiers that can match the same text grow polynomially. `.*.*.*x` took 0.5 s on a
+  255-character name and 0.9 s at 300; each extra `.*` raises the exponent. Nothing bounds the length
+  of a name or flag in a script, so a long enough one is slow.
+
+**What it rejects that is in fact linear.** The check does not look at what the repeated group can
+match, so it also refuses some patterns that are safe, such as `(a*b)*`,
+`^(?:[a-z]+-)*[a-z]+$` and `^(?:SECRET|TOKEN|PASSWORD)(?:_[A-Z]+)*$`. A rewrite without the nesting
+exists for some of these and not for others, so if you cannot rewrite a pattern exactly, loosen it to
+the character class you mean. The last one can be rewritten exactly with a lookahead
+(it accepts the same names; compared on every suffix of up to seven characters over `A`, `_`, `a`
+and `1` after `SECRET`, `TOKEN` and `PASSWORD`):
+
+```js
+{ patterns: ['^(?:SECRET|TOKEN|PASSWORD)(?!.*_(?:_|$))(?:_[A-Z][A-Z_]*)?$'] }
+```
+
+
+**When you see the error.** The error is thrown from the rule's `create()`, which ESLint calls for
+each file it lints, so the check does not run when the config is loaded. ESLint stops the run at the
+first file it lints with the rule enabled and prints "Error while loading rule" followed by
+"Occurred while linting <that file>" and a stack trace, and exits with code 2. A run that lints no
+file with the rule enabled never sees it.
+
+The accident the check is for, and its fix:
+
+```js
+// Rejected: `([A-Z]+_?)*` repeats a group that already repeats, so a long
+// name that does not match can take seconds.
+{ patterns: ['^([A-Z]+_?)*_KEY$'] }
+
+// Safe rewrite: one repetition over a character class.
+{ patterns: ['^[A-Z0-9_]*_KEY$'] }
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 3} -->
+```sh
+echo "$API_KEY"                      # expands the secret into argv and output
+curl -H "Authorization: $AUTH_TOKEN" https://x   # argv is world-readable
+[[ -z $DB_PASSWORD ]] && exit 1      # a read, even though only tested
+```
+
+### Correct
+
+```sh
+TOKEN=$GITHUB_TOKEN tool             # passed to the child's environment
+API_KEY=abc123                       # an assignment, not a read
+echo "$cache_key"                    # not matched by the default pattern
+[ -n "${API_KEY+set}" ]              # checks presence without expanding the value
+```
+
+With `allowedSinks: ['vault']`:
+
+<!-- example: {"options": {"allowedSinks": ["vault"]}} -->
+```sh
+vault login "$VAULT_TOKEN"          # an allowed sink
+```
+
+## When not to use it
+
+Turn it off when your scripts run in an environment where argv and logs are not observable by
+others and you accept the exposure, or when another secret scanner already covers the same files.
+
+## 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 check. It reports shell mistakes, not credential handling, and it has
+no notion of which variable names your project treats as secrets or which commands may receive
+them. This rule enforces that policy.