@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

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.

package/docs/rules/no-secret-flags.md

@@ -0,0 +1,169 @@
+# `sh/no-secret-flags`
+
+Disallow secret-shaped command-line flags, such as `--password=` or `--token`, with a literal value.
+
+| Configs                                   | Fixable      | Languages |
+| ----------------------------------------- | ------------ | --------- |
+| `recommended` (warn), `agent-authored` (error) | not fixable | `sh/sh` |
+
+## Rule details
+
+A command's arguments are visible to every user on the machine: `ps` and `/proc/<pid>/cmdline`
+show them while the command runs. A secret written as a literal flag value is also committed with
+the script. This rule reports a flag whose name looks like it carries a secret when its value is
+written literally.
+
+The rule inspects the arguments of every simple command (`CallExpr`), after the command word. It
+recognizes two forms:
+
+- One word: `--token=abc`. The flag name is the text before the first `=`, and the value is the
+  rest. An empty value (`--token=`) passes nothing and is not reported.
+- Two words: `--token abc`. A flag word without `=` takes the next word as its value when that word
+  is static, non-empty, and doesn't start with `-`. So a flag followed by another flag
+  (`--auth --verbose`), by `-` (the usual "read from stdin" marker), or by nothing is valueless and
+  not reported.
+
+A value is literal only when its whole word is static. Any parameter expansion, command
+substitution, or other dynamic part makes the value fine: `--token="$TOKEN"` and
+`--password=$(cat f)` are the correct pattern. Static-ness is decided by the plugin's shared word
+resolution (`ShellSourceCode#resolveWordText`), so quoting that resolves to fixed text
+(`"--password"='hunter2'`) is still literal.
+
+Only command arguments are matched. Assignment values (`X="--token=abc"`, `export`, `local`),
+heredoc bodies, here-strings, `[[ … ]]` operands, and `case` patterns are never reported. Commands
+behind wrappers are still checked, because their flags are arguments of the same command:
+`sudo mysql --password=hunter2` reports.
+
+This is a heuristic screen on flag names, not secret detection. The default pattern matches a
+flag whose name, after its dashes, is a secret word: `password`, `passwd`, `token`, `secret`,
+`api-key` (or `apikey`), `auth`, `authkey`, or `authorization`. The word may follow an `access-`
+or `auth` qualifier (`--access-token`, `--auth-token`, `--authtoken`). It may be followed by a
+digit (`--password2`, `--token1`) or by another `-segment` (`--secret-key`,
+`--authorization-token`). The pattern leaves two kinds of name alone:
+
+- Names ending in `-stdin` or `-file`, such as `--password-stdin`, `--password-file`, and
+  `--token-file`. These flags read the secret from stdin or from a file, which are the alternatives
+  this rule recommends. In `docker login --password-stdin registry.example.com`, the next word is a
+  positional argument, not the flag's value.
+- Names with a letter directly after the secret word, such as `--author` (`auth` + `or`),
+  `--tokens`, and `--tokenizer` (`token` + a letter). These are longer words that only start
+  with a secret word.
+
+Other qualifiers aren't matched, so `--my-token` is not reported. A general prefix would also
+match negations such as `--no-password`, which take no value. Add a project's own flag names
+with the `patterns` option.
+
+Expect some false positives: a name such as `--token-type` still matches. Suppress a single false
+positive with a disable comment that says why, or narrow the `patterns` option for your project.
+
+## Options
+
+- `patterns` (`string[]`, at least one entry). Regular-expression sources tested against each flag's
+  name, without `=` or the value. They **replace** the default list. Each source is compiled
+  case-insensitively, like the default. An invalid source fails config validation with an error that
+  names the rule and the source.
+
+  Default: `["^(?!.*-(?:stdin|file)$)--?(?:access-|auth-?)?(?:password|passwd|token|secret|api-?key|auth(?:key|orization)?)(?![a-z])"]`.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-secret-flags': [
+      'error',
+      // Only these exact names, plus a project-specific flag.
+      { patterns: ['^--?(password|token|api-?key)$', '^--vault-pin$'] },
+    ],
+  },
+}
+```
+
+### Patterns run against script-controlled text
+
+`patterns` is tested against every flag name the linted script writes, 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
+curl --token=abc123 https://api.example.com   # literal value in the same word
+mysql --user=app --password hunter2            # literal value in the next word
+sudo deploy --api-key='k-123'                  # quoting doesn't make it dynamic
+```
+
+### Correct
+
+```sh
+curl --token="$API_TOKEN" https://api.example.com                          # dynamic value
+mysql --password="$(pass show db/app)"                                     # command substitution
+printf '%s' "$DB_PASSWORD" | db-cli --password -                           # read from stdin
+printf '%s' "$REG_TOKEN" | docker login --password-stdin reg.example.com   # a -stdin flag
+db-cli --password-file=/run/secrets/db                                     # a -file flag names a file
+git commit --author="Jane <jane@example.com>"                              # --author is not --auth
+mytool --auth --verbose                                                    # valueless flag
+DB_PASSWORD="$DB_PASSWORD" db-cli                                          # passed through the environment
+X="--token=abc"                                                            # not a command argument
+```
+
+## When not to use it
+
+Turn it off when literal flag values in your scripts are never real secrets, for example
+throwaway fixtures for a local test service, or when another secret scanner already covers the same
+files and you don't want duplicate reports.
+
+## 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 way to configure which flag names your project treats as secrets. This rule enforces that policy.

package/docs/rules/no-unchecked-cd.md

@@ -0,0 +1,146 @@
+# `sh/no-unchecked-cd`
+
+Require the failure of `cd`, `pushd` and `popd` to be checked, so a script never carries on in the wrong directory.
+
+| Configs                         | Fixable                      | Languages |
+| ------------------------------- | ---------------------------- | --------- |
+| `recommended`, `agent-authored` | suggestions (append `\|\| exit`) | `sh/sh`   |
+
+## Rule details
+
+When `cd` fails, the script keeps running in the directory it was already in, and every relative
+path after it silently means something else. `cd "$build"; rm -rf *` is the classic disaster.
+`pushd` and `popd` change the directory (and the directory stack) and fail the same way.
+
+A directory-changing command is **checked** when its exit status decides what runs next:
+
+- it is the left side of `&&` or `||` (`cd x || exit`, `cd x || return`, `cd x && make`);
+- it is the last command of an `if`, `elif`, `while` or `until` condition;
+- it is the right side of a list, or the last command of a `{ …; }` group or `( … )` subshell,
+  whose own status is checked in one of these ways (`a && cd x || exit`, `{ cd x; } || exit`).
+
+Everything else reports: a bare `cd`, `cd` in a function, loop or `case` body, a pipeline stage, a
+background job, and `cd` inside a subshell (`( cd x; make )`). The subshell keeps the script's own
+directory intact, but the commands after a failed `cd` inside it still run in the wrong place, so
+it must be checked there too. A negated `! cd x` is only as checked as the position it sits in.
+
+The command is recognized after transparent wrappers, so `builtin cd x` and `command cd x` are
+read as `cd`.
+
+**Files running under `set -e`.** A file whose prologue enables `errexit` stops at a failed `cd`
+by itself, so the rule is quiet there. "Prologue" is read exactly as
+[`require-strict-mode`](./require-strict-mode.md) reads it: the first five top-level statements,
+tracked in order, so a later `set +e` undoes an earlier `set -e`, and a `set -e` outside that
+window does not count. Set `ignoreWhenErrexit` to `false` to report anyway.
+
+**Files run by bats.** With `languageOptions.dialect` set to `"bats"`, a bare `cd` (or `pushd` or
+`popd`) written directly in the body of a `@test` block, or of a top-level `setup`, `teardown`,
+`setup_file` or `teardown_file` function, is not reported: bats runs those bodies with `errexit`
+on, so a failed `cd` fails the test. The same holds for a `cd` directly in a `( … )` subshell that
+is itself a statement of such a body (`( cd "$dir"; make )`), because the subshell inherits
+`errexit` and its failing status fails the test. A `$( … )` command substitution does not count: it
+is reported as before.
+
+The rule reads the body in order. After a plain `set +e` (or `set +o errexit`) in the same body,
+`errexit` is off, and a later `cd` is reported again, because the test carries on after the failed
+`cd`. A later plain `set -e` turns it back on, so `set +e; set -e; cd x` is not reported while
+`set +e; set -e; set +e; cd x` is. A `cd` written before the `set +e` is still covered.
+
+What the rule cannot tell: a `set +e` (or `shopt`, `eval 'set +e'`, `set "$flags"`) that is nested
+in an `if`, loop or function, that lives in a file the test `load`s or `source`s or in a helper it
+calls, or that ran in `setup` before the test starts. It reads each body on its own, assuming
+`errexit` starts on, so none of these are seen, and a `cd` after one of them is not reported.
+For example, bats runs `setup` in the same shell as the test, so after
+`setup() { set +e; }` a bare `cd` in a `@test` has no `errexit` either, yet it is not reported.
+Likewise a `cd` nested in an `if`, loop or `case` inside the body, a negated `! cd x`, a `cd` in
+any other function of the same file, and a `cd` in a file read under another dialect (a `.sh` file)
+are reported as usual. `run cd x` is not reported either, as before: `run` is not one of the
+wrappers this rule follows, so the command it sees is `run`.
+
+**Suggestion.** The editor suggestion appends ` || exit` after the command and its redirections.
+
+<!-- transform: {"kind": "suggestion"} -->
+
+```sh
+cd "$build" > /dev/null
+# becomes
+cd "$build" > /dev/null || exit
+```
+
+It is not offered where appending would change the meaning: when the `cd` is already part of an
+`&&`/`||` list or a pipeline, negated, in the background, or followed by a here-document.
+
+The rule reads `languageOptions.dialect` only for the bats exemption above; no other option affects it.
+
+## Options
+
+| Option              | Type      | Default | Effect                                                                      |
+| ------------------- | --------- | ------- | --------------------------------------------------------------------------- |
+| `ignoreWhenErrexit` | `boolean` | `true`  | Skip files whose prologue enables `errexit` (for example `set -euo pipefail`). |
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/no-unchecked-cd': ['error', { ignoreWhenErrexit: false }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 5} -->
+
+```sh
+cd "$build"                 # a failure goes unnoticed
+rm -rf ./*                  # ...and this runs in the wrong directory
+
+pushd /tmp                  # pushd and popd fail the same way
+popd
+
+( cd "$dir"; make )         # inside a subshell, still unchecked
+
+f() {
+  cd "$1"                   # a function body does not check it
+}
+```
+
+### Correct
+
+```sh
+cd "$build" || exit 1
+cd "$build" || return
+cd "$build" && make
+
+if cd "$build"; then make; fi
+while ! cd "$build"; do sleep 1; done
+
+( cd "$dir" || exit; make )
+```
+
+With `errexit` in the prologue (the first five top-level statements), a bare `cd` is fine:
+
+```sh
+set -euo pipefail
+cd "$build"
+```
+
+## When not to use it
+
+Turn the rule off when every script already starts with `set -e` and you would rather not think
+about the distinction (the default `ignoreWhenErrexit` already covers that), or when a project
+deliberately tolerates a failed `cd`, such as `cd "$dir" 2>/dev/null; true`. Prefer writing the
+`|| true` so the intent is explicit.
+
+## 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 overlaps with SC2164 ("Use `cd ... || exit` in case `cd` fails"), and this rule
+enforces the same practice. It exists anyway because it offers a suggestion, covers `pushd` and
+`popd`, can be turned off per file by `set -e` detection that follows the same prologue reading as
+`require-strict-mode`, and is part of the shipped presets, so the policy applies without running
+shellcheck. If you already run shellcheck with SC2164 enabled, the two agree on the common cases.

package/docs/rules/no-undeclared-commands.md

@@ -0,0 +1,141 @@
+# `sh/no-undeclared-commands`
+
+Require every external command a script uses to be declared, so that a script's dependencies
+are stated up front instead of discovered when a command is missing.
+
+| Configs | Fixable     | Languages |
+| ------- | ----------- | --------- |
+| `agent-authored` (inert until a declaration convention is bound) | not fixable | `sh/sh` |
+
+## Rule details
+
+A script depends on every external command it runs, and any of them can be missing on the
+machine it lands on. When your project states each script's dependencies, this rule keeps that
+statement complete: it reports each command the script uses but does not declare.
+
+The rule needs a **declaration convention**, which says how your project declares commands. Bind
+one with `settings.sh.declarationConvention`. The plugin ships one, `commentPragma`, which reads
+`# uses: jq curl` comments from a script's header. See
+[Declaration conventions](../declaration-conventions.md) to write your own. **With no convention
+bound, the rule reports nothing**, so turning it on is safe until your project picks a convention.
+
+A command is **used** when the script runs it by a name known from the source. The rule looks
+at every simple command in the file, wherever it is: the top level, function bodies, loops,
+conditionals, pipelines, and command substitutions (`$(…)` and backquotes) in any position,
+including arguments, assignment values, redirect targets, `for` lists, and `case` subjects.
+
+- **Wrappers are followed to the command they run.** `sudo`, `env`, `nohup`, `nice`, `timeout`,
+  `time`, `command`, and `exec` run the command named after them, so that command is used. A
+  wrapper is also used itself when it is an external command: `sudo rsync -a . host:` uses both
+  `sudo` and `rsync`. `command` and `exec` are builtins, so `exec rsync …` uses only `rsync`.
+  `time` is a keyword in bash, so `time rsync …` uses only `rsync` there; in a `posix` file it
+  is the `time` utility and is used too. `command -v jq` only looks `jq` up, so it does not use
+  `jq`. In `bats` files, bats' `run` is a wrapper too, with its options (`-N`,
+  `!`, `--keep-empty-lines`, `--separate-stderr`, `--`), so `run ! curl x` uses `curl`.
+- **Builtins don't count.** The builtin list depends on `languageOptions.dialect`. `bash` and
+  `bats` files use the bash builtins (`cd`, `echo`, `local`, `mapfile`, `source`, …). `bats`
+  files also leave out the helpers bats-core defines for every test file: `run`, `load`, `skip`,
+  `bats_pipe`, `bats_load_safe`, `bats_load_library`, `bats_require_minimum_version`, and
+  `bats_test_function`. Helpers from separate libraries, such as bats-assert's
+  `assert_success`, are not bats-core's and are still reported. `posix`
+  files use the POSIX special and regular built-ins plus `echo`, `printf`, `test` and `[`. So
+  `mapfile` is a command in a `posix` file. `mksh` and `zsh` files use the POSIX list for now,
+  so their own builtins (`print`, `whence`, `setopt`, …) are reported until they get lists of
+  their own.
+- **Functions defined in the file don't count**, wherever they are defined, including after the
+  call or inside another function. A function named like a command (`curl() { … }`) shadows it.
+- **Dynamic command words don't count.** `"$cmd" args`, `${tool} x`, and `$(pick) x` name no
+  command the rule can know. `sh/no-dynamic-invocation` reports them. A static wrapper in front
+  of one is still used: `sudo "$prog"` uses `sudo`.
+- **Commands inside strings don't count.** `bash -c 'jq .'` uses `bash`, not `jq`.
+
+Each undeclared command is reported once (message `undeclaredCommand`), at the word that names
+it in its first use. The message says how to declare it, in the convention's own syntax when
+the convention has a `declarationHint`. With `commentPragma`:
+
+```text
+'curl' is used but not declared. Add `# uses: curl` on a line below the shebang.
+```
+
+In a file without a shebang, the message says to add the line as the first line of the file
+instead. A convention without a hint ends the message with the generic sentence
+"Declare it with the project's declaration convention." A command run by path (`./build.sh`) is reported by that path.
+
+## Options
+
+- `transparentWrappers` (`string[]`, default `[]`): names of your project's own wrapper
+  commands, added to the built-in wrappers above. The word after a listed wrapper is the command
+  it runs, so with `['with-retry']`, `with-retry curl x` uses both `with-retry` and `curl`. A
+  listed wrapper takes no flags: in `with-retry -n 3 curl`, the rule stops at `-n` and does not
+  count `curl`. If the wrapper is a function defined in the same file, only the wrapped command
+  needs declaring. Your network wrapper doesn't need listing here when it is set in
+  `settings.sh.networkWrapper`: this rule looks through it, with the options its spec declares
+  (see [`sh/require-network-wrapper`](./require-network-wrapper.md#declaring-the-wrapper-once-settingsshnetworkwrapper)).
+
+The convention is not a rule option. Bind it in `settings`, because ESLint copies rule options
+with `structuredClone`, which cannot copy a convention's methods.
+
+```js
+// eslint.config.js
+import sh, { commentPragma } from '@eslint-sh/eslint-plugin';
+
+export default [
+  {
+    files: ['**/*.sh'],
+    plugins: { sh },
+    language: 'sh/sh',
+    settings: { sh: { declarationConvention: commentPragma } },
+    rules: {
+      'sh/no-undeclared-commands': ['error', { transparentWrappers: ['with-retry'] }],
+    },
+  },
+];
+```
+
+## Examples
+
+With `commentPragma` bound and `{ transparentWrappers: ['with-retry'] }`:
+
+### Incorrect
+
+<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}, "findings": 6} -->
+```sh
+#!/usr/bin/env bash
+# uses: jq
+curl -s "$URL" | jq .        # curl is not declared
+echo "built $(date +%s)"     # date, inside $(…), is not declared
+sudo systemctl restart app   # neither sudo nor systemctl is declared
+with-retry git pull          # git, run by the wrapper, is not declared (nor is with-retry)
+```
+
+### Correct
+
+<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}} -->
+```sh
+#!/usr/bin/env bash
+# uses: curl jq date
+log() { printf '%s\n' "$*"; }   # a function defined here, using only builtins
+log "fetching"
+curl -s "$URL" | jq .
+echo "built $(date +%s)"
+cd /tmp && read -r answer       # builtins need no declaration
+"$cmd" --version                # a dynamic command word: see sh/no-dynamic-invocation
+command -v docker               # looks docker up without running it
+```
+
+## When not to use it
+
+Turn the rule off when your project doesn't track script dependencies, or tracks them somewhere
+this rule can't read, such as a container image or a system package list. It is also noisy for
+scripts that run many repository-local programs by path, since each path is reported until it is
+declared.
+
+## 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 checks how a script uses commands, not which commands the
+script may depend on, and it has no notion of a project's declaration convention to compare
+against. A dependency manifest is project policy, which is the kind of rule shellcheck cannot be
+configured to express.