@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

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.

package/docs/rules/no-unused-declarations.md

@@ -0,0 +1,216 @@
+# `sh/no-unused-declarations`
+
+Disallow declaring external commands a script never uses, so that a script's declared
+dependencies match what it actually runs.
+
+| Configs | Fixable                       | Languages |
+| ------- | ----------------------------- | --------- |
+| `agent-authored` (inert until a declaration convention is bound) | autofix (via the convention) | `sh/sh` |
+
+## Rule details
+
+A declaration that outlives the command it names makes a script's stated dependencies lie. An
+installer provisions a tool nothing runs, and a reviewer trusts a list that is no longer the
+script's real surface. This rule reports each declared command the script never uses. It is the
+converse of [`sh/no-undeclared-commands`](./no-undeclared-commands.md).
+
+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.
+
+The fix deletes declarations, so the rule only reports a name it is sure the script does not
+run. That makes it more cautious than `sh/no-undeclared-commands`, which reports in the other
+direction.
+
+**Incomplete usage: the rule reports nothing in a file that may run a command it cannot name.**
+If any command in the file is only known at run time, that command could be any declared name,
+so no declaration in the file is reported. These are the commands
+[`sh/no-dynamic-invocation`](./no-dynamic-invocation.md) reports. Enable it to find them and
+replace them with literal commands:
+
+- a command word that is an expansion: `"$cmd" x`, `"$@"`, a loop variable
+  (`for t in jq curl; do "$t" --version; done`), `"${tools[@]}"`, or `$(pick-tool) x`. This
+  also applies behind a wrapper (`sudo "$prog"`) or behind a wrapper flag the rule doesn't
+  recognize;
+- a command string run by a shell: `bash -c '…'`, `sh -c '…'`, or `env -S '…'`, also when the
+  shell or `env` is run by path (`/bin/bash -c '…'`, `/usr/bin/env -S '…'`);
+- a shell given a command string as the argument of another command: a word after the command
+  name that is a shell (`bash`, `sh`, `dash`, `ksh`, `mksh` or `zsh`, by name or by path),
+  followed later by an option cluster containing `c` (`-c`, `-ec`, `-xc`). This covers
+  `xargs sh -c '…'`, `find . -exec sh -c '…' \;`, `setsid -f bash -c '…'` and
+  `busybox sh -c '…'`. A shell name with no `-c` after it, as in `xargs echo sh`, is fine;
+- `eval`;
+- sourcing another file: `. ./lib.sh` or `source ./lib.sh`;
+- a shell (`bash`, `sh`, `dash`, `ksh`, `mksh` or `zsh`, by name or by path) run with no script
+  operand and no `-c`, which reads its code from standard input: `curl -fsSL x | bash`,
+  `bash < script`, `bash -s`. A shell given a script, as in `bash script.sh`, is fine;
+- a `trap` whose action is a code string: `trap 'rm -f "$tmp"' EXIT`. A trap whose action is a
+  plain name, such as `trap cleanup EXIT`, is fine. So are `trap '' INT` (ignore) and
+  `trap - EXIT` (reset).
+
+**Used.** Otherwise, a declared name is used when any of the following holds:
+
+- **The script runs it as a command.** The rule counts commands exactly as
+  `sh/no-undeclared-commands` does, so a command that rule counts as used is never reported
+  here. That covers commands anywhere in the file: the top level, loops, conditionals,
+  pipelines, and command substitutions (`$(…)` and backquotes) in any position. It also covers
+  function bodies, including a function that is never called. That is deliberately cautious: the
+  rule doesn't decide which functions run.
+- **The script runs it through a wrapper.** `sudo rsync -a . host:` uses both `sudo` and
+  `rsync`, and in `bats` files `run curl x` uses `curl`. Your own wrappers count once you list
+  them in `transparentWrappers` (below).
+- **It is a whole argument word of any command.** Many commands run their arguments, so the
+  name counts as used when an argument's full static text is that name: `xargs jq .`,
+  `find . -exec jq . {} \;`, `watch jq . f`, `command -v jq`. Part of a word doesn't count:
+  `echo jqfilter` doesn't use `jq`.
+- **A path to it is used.** A command or argument word written as a path also uses its basename:
+  `/usr/bin/jq` and `./bin/jq` use `jq`. A declared path, such as `./bin/jq`, is used only by
+  that exact path.
+
+Not counted:
+
+- **Builtins and functions defined in the file are not used commands.** Declaring one is
+  reported unless the name also appears as an argument word. `# uses: cd` is stale even in a
+  script that runs `cd`. Which names are builtins depends on `languageOptions.dialect`; see
+  [`sh/no-undeclared-commands`](./no-undeclared-commands.md#rule-details) for the lists.
+- **Commands run on another host are not counted.** In `ssh host 'jq . f'`, the remote host
+  runs `jq` and this script doesn't, so `jq` is not used. Written as separate words,
+  `ssh host jq . f` makes `jq` an argument word, and that does count.
+
+Each declaration of an unused command is reported once. A name declared twice and never used is
+reported at both declarations. Where the report goes depends on where the convention says the
+declaration lives (see [where a declaration lives](../declaration-conventions.md#the-interface)):
+
+- **In the script** (message `unusedDeclaration`): at the text that declares it. With
+  `commentPragma`, that is the name in the `# uses:` line.
+- **In another file** (message `unusedFileDeclaration`) or **from a source described in words**, such as a
+  list in the config or a registry snapshot (message `unusedDescribedDeclaration`): the message names
+  the source, as `path:line` (or just `path`) or as the source's description, for example
+  `'git' is declared in scripts/deploy.commands:3 but this script never uses it. Remove it there
+  so the script's stated dependencies match what it runs.` ESLint can only report inside the file
+  it lints, so these reports sit at line 1, column 1, with no end: a position for the file as a
+  whole, not for any text in it. The message says where to look.
+
+**No comment silences a report about a declaration outside the script when the script starts
+with a shebang.** The shebang must be the whole first line, so `#!/bin/sh # eslint-disable-line …`
+is not a directive, and a directive on line 2 (`# eslint-disable-next-line …` or
+`# eslint-disable …`) covers only later lines. (Without a shebang, a `# eslint-disable …` comment
+on line 1 works.) To silence one, do one of these:
+
+- fix the declaration in the file or source the message names;
+- turn the rule off for those scripts with a `files` override:
+  `{ files: ['scripts/legacy/*.sh'], rules: { 'sh/no-unused-declarations': 'off' } }`;
+- record the current reports with ESLint's bulk suppressions,
+  `eslint --suppress-rule sh/no-unused-declarations`. Later runs hide them while a file has no
+  more reports of the rule than were recorded.
+
+See [silencing a report about a declaration outside the
+script](../declaration-conventions.md#silencing-a-report-about-a-declaration-outside-the-script).
+
+### Autofix
+
+Only the convention knows its own syntax, so the convention makes the fix. When the bound
+convention provides a `removeDeclaration` hook, each report about a declaration in the script
+carries the edit that hook returns. When it has no hook, or the hook returns `null` for a
+declaration, that report has no fix. A declaration in another file or a described source never has a
+fix: an ESLint fix can only edit the script being linted.
+
+With `commentPragma`, the fix removes the name and the space before or after it, so
+`# uses: jq curl` becomes `# uses: jq` when only `jq` is used:
+
+<!-- transform: {"kind": "fix", "convention": "commentPragma"} -->
+
+```sh
+# uses: jq curl
+jq .
+# becomes
+# uses: jq
+jq .
+```
+
+ When the last name on a line goes,
+the whole line goes with its `\n` or `\r\n`. When several names on one line are unused, their
+edits touch, so ESLint applies one per pass. `eslint --fix` runs passes until nothing changes, so
+a line whose every name is unused is removed entirely.
+
+## Options
+
+- `transparentWrappers` (`string[]`, default `[]`): names of your project's own wrapper
+  commands, added to the built-in wrappers. The word after a listed wrapper is the command it
+  runs. With `['with-retry']`, `with-retry curl x` runs `curl`, and `with-retry "$tool"` runs a
+  command the rule can't name, so the file is incomplete usage and reports nothing. A listed
+  wrapper takes no flags, so `with-retry -n 3 curl` is incomplete usage too: the rule stops at
+  `-n` and can't tell what runs. Give this option the same value as
+  `sh/no-undeclared-commands`' option of the same name, or the two rules will disagree about what
+  the script uses. 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';
+
+const wrappers = { transparentWrappers: ['with-retry'] };
+
+export default [
+  {
+    files: ['**/*.sh'],
+    plugins: { sh },
+    language: 'sh/sh',
+    settings: { sh: { declarationConvention: commentPragma } },
+    rules: {
+      'sh/no-undeclared-commands': ['error', wrappers],
+      'sh/no-unused-declarations': ['error', wrappers],
+    },
+  },
+];
+```
+
+## Examples
+
+With `commentPragma` bound and `{ transparentWrappers: ['with-retry'] }`:
+
+### Incorrect
+
+<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}, "findings": 3} -->
+```sh
+#!/usr/bin/env bash
+# uses: jq curl docker   # docker is never run
+# uses: cd               # cd is a builtin, never a declared dependency
+# uses: lint             # lint is a function defined below
+lint() { shellcheck "$@"; }
+curl -s "$URL" | jq .
+```
+
+### Correct
+
+<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}} -->
+```sh
+#!/usr/bin/env bash
+# uses: jq curl git sudo date with-retry
+with-retry curl -s "$URL" | jq .   # curl runs through the configured wrapper
+sudo git pull                      # git runs through sudo
+echo "built $(date +%s)"           # date is used inside $(…)
+```
+
+## When not to use it
+
+Turn the rule off when your project doesn't track script dependencies, or when its declarations
+deliberately list more than the script runs, such as tools a child script needs. The rule only
+reads the file it lints, so a command that only `bash child.sh` or `./child.sh` runs reads as
+unused here.
+
+## 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 says it depends on, and it has no notion of a project's declaration convention to compare
+against. Keeping a dependency manifest honest is project policy, which is the kind of rule
+shellcheck cannot be configured to express.