@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

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

@@ -24,19 +24,19 @@ The portable alternative is `[ -n "${name+set}" ]`. `${name+set}` expands to `se
 This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
 described in [version compatibility](../../compat.md):
 
-- `shellVersion` unset: never reports. An unset version means the newest Bash.
-- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.2`.
-- `dialect: "posix"`: reports `test -v` and `[ -v ]` at any `shellVersion`; dash has no `-v` test.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.2`.
+- `dialect: "posix"`: reports `test -v` and `[ -v ]` regardless of Bash releases; dash has no `-v` test.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-test-v': 'error',
   },
@@ -47,9 +47,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 3} -->
 ```sh
 if [[ -v CI ]]; then echo ci; fi
 if test -v HOME; then echo home; fi
@@ -58,20 +58,20 @@ if test -v HOME; then echo home; fi
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 if [ -n "${CI+set}" ]; then echo ci; fi
 [ "$flag" = -v ] && verbose=1
 grep -v '^#' config
 ```
 
-With `shellVersion: "4.2"` or newer, or with no `shellVersion`, the `-v` test is fine.
+With `minBashVersion: "4.2"` or newer, or with no `minBashVersion`, the `-v` test is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.2, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.2, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -79,4 +79,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck reports `[[` and `test -v` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `[[ -v x ]]` for a Bash 3.2 target. This rule exists for that target.
+shellcheck reports `[[` and `test -v` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `[[ -v x ]]` for a script that must support Bash 3.2. This rule checks that support requirement.

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

@@ -27,18 +27,18 @@ Under `dialect: "posix"` the parser reads `$'…'` as a literal `$` followed by
 This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
 described in [version compatibility](../../compat.md):
 
-- `shellVersion` unset: never reports. An unset version means the newest Bash.
-- `dialect: "bash"` (the default) or `"bats"`: reports an escape when `shellVersion` is older than its release (4.2, or 4.3 for U+0080 to U+00FF).
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports an escape when `minBashVersion` is older than its release (4.2, or 4.3 for U+0080 to U+00FF).
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-unicode-escape': 'error',
   },
@@ -49,17 +49,17 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 2} -->
 ```sh
 ok=$'\u2713'
 printf '%s\n' $'caf\u00e9'
 ```
 
-With `shellVersion: "4.2"`, only the Latin-1 range reports:
+With `minBashVersion: "4.2"`, only the Latin-1 range reports:
 
-<!-- example: {"dialect": "bash", "shellVersion": "4.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "4.2", "findings": 1} -->
 ```sh
 ok=$'\u2713'
 printf '%s\n' $'caf\u00e9'
@@ -67,20 +67,20 @@ printf '%s\n' $'caf\u00e9'
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 ok=$'\342\234\223'
 printf '%s\n' $'caf\303\251'
 echo '\u00e9 is written literally here'
 ```
 
-With `shellVersion: "4.3"` or newer, or with no `shellVersion`, every escape is fine.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, every escape is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.3, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -88,4 +88,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck reports `$'…'` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report a `\u` escape for a Bash 3.2 or 4.2 target. This rule exists for that target.
+shellcheck reports `$'…'` only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report a `\u` escape for a script that must support Bash 3.2 or 4.2. This rule checks that support requirement.

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

@@ -1,6 +1,6 @@
 # `sh/compat/no-wait-n`
 
-Disallow `wait -n` in scripts whose target shell lacks it: Bash older than 4.3, including the
+Disallow `wait -n` in scripts that must support a shell lacking it: Bash older than 4.3, including the
 Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
 
 | Configs | Fixable | Languages |
@@ -20,19 +20,19 @@ The portable alternative is to wait for one job at a time by its PID: keep each
 This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
 described in [version compatibility](../../compat.md):
 
-- `shellVersion` unset: never reports. An unset version means the newest Bash.
-- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.3`.
-- `dialect: "posix"`: reports at any `shellVersion`; POSIX `wait` has no options.
+- `minBashVersion` unset: no Bash version constraint, so no report under `bash` or `bats`.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `minBashVersion` is older than `4.3`.
+- `dialect: "posix"`: reports regardless of Bash releases; POSIX `wait` has no options.
 - `dialect: "mksh"` or `"zsh"`: never reports.
 
 ## Options
 
-This rule has no options. Set the target through `languageOptions`:
+This rule has no options. Set the required support through `languageOptions`:
 
 ```js
 // eslint.config.js
 {
-  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  languageOptions: { dialect: 'bash', minBashVersion: '3.2' },
   rules: {
     'sh/compat/no-wait-n': 'error',
   },
@@ -43,9 +43,9 @@ This rule has no options. Set the target through `languageOptions`:
 
 ### Incorrect
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2", "findings": 1} -->
 ```sh
 for job in a b c d; do
   run "$job" &
@@ -56,9 +56,9 @@ wait
 
 ### Correct
 
-With `shellVersion: "3.2"`:
+With `minBashVersion: "3.2"`:
 
-<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+<!-- example: {"dialect": "bash", "minBashVersion": "3.2"} -->
 ```sh
 pids=
 for job in a b c d; do
@@ -70,11 +70,11 @@ for pid in $pids; do
 done
 ```
 
-With `shellVersion: "4.3"` or newer, or with no `shellVersion`, `wait -n` is fine.
+With `minBashVersion: "4.3"` or newer, or with no `minBashVersion`, `wait -n` is fine.
 
 ## When not to use it
 
-Turn the rule off when your scripts never run on Bash older than 4.3, or leave `shellVersion`
+Turn the rule off when your scripts never run on Bash older than 4.3, or leave `minBashVersion`
 unset, which makes the rule report nothing.
 
 ## Relationship to shellcheck
@@ -82,4 +82,4 @@ unset, which makes the rule report nothing.
 eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
 layer. Run shellcheck beside it.
 
-shellcheck reports `wait` options only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `wait -n` for a Bash 4.2 target. This rule exists for that target.
+shellcheck reports `wait` options only for a script it treats as POSIX `sh` (its SC3xxx portability checks). It does not know which Bash release a script must run on, so it cannot report `wait -n` for a script that must support Bash 4.2. This rule checks that support requirement.

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

@@ -30,7 +30,8 @@ wrappers_: commands that run the word after them. `time ls` runs `ls`, and
   `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`.
+- Project wrappers declared in `settings: { sh: { transparentWrappers: ['with-retry'] } }`,
+  and the shared network wrapper. See [shared transparent wrappers](../transparent-wrappers.md).
 
 A command then reports in one of two ways:
 
@@ -45,8 +46,9 @@ A command then reports in one of two ways:
 
 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.
+static command word. Utility wrappers match absolute paths by basename, so `/bin/bash -c …` runs an
+embedded command. Configured utility wrappers also match relative paths; builtin specs
+require exact names.
 
 It does not depend on `languageOptions`.
 
@@ -56,18 +58,20 @@ It does not depend on `languageOptions`.
   `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.
+Project wrapper facts belong in shared settings, with no rule override. The former
+`allowWrappers` option is rejected. It added checks rather than suppressing them:
+move its list to shared settings to preserve those checks across all wrapper-following
+rules. Use `allowInFunctions` or a justified ESLint disable comment for an actual allowance.
+See [migration](../transparent-wrappers.md#migration).
 
 ```js
 // eslint.config.js
 {
+  settings: { sh: { transparentWrappers: ['with-retry'] } },
   rules: {
     'sh/no-dynamic-invocation': [
       'error',
-      { allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] },
+      { allowInFunctions: ['dispatch'] },
     ],
   },
 }
@@ -91,9 +95,9 @@ bash -c "$script"         # embeddedCommand: a string of shell code
 sh -c 'make test'         # embeddedCommand, even for a literal string
 ```
 
-With `{ allowWrappers: ['with-retry'] }`:
+With `settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
-<!-- example: {"options": {"allowWrappers": ["with-retry"]}, "findings": 1, "messageIds": ["dynamicInvocation"]} -->
+<!-- example: {"settings": {"sh": {"transparentWrappers": ["with-retry"]}}, "findings": 1, "messageIds": ["dynamicInvocation"]} -->
 ```sh
 with-retry "$c"           # the wrapped command is dynamic
 ```
@@ -110,9 +114,10 @@ alias ll='ls -l'
 ll                        # an alias name is a static command word
 ```
 
-With `{ allowInFunctions: ['dispatch'], allowWrappers: ['with-retry'] }`:
+With `{ allowInFunctions: ['dispatch'] }` and
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
-<!-- example: {"options": {"allowInFunctions": ["dispatch"], "allowWrappers": ["with-retry"]}} -->
+<!-- example: {"options": {"allowInFunctions": ["dispatch"]}, "settings": {"sh": {"transparentWrappers": ["with-retry"]}}} -->
 ```sh
 dispatch() {
   "$@"                    # allowed inside the dispatcher

package/docs/rules/no-eval.md

@@ -7,6 +7,10 @@ of code a script runs can be reviewed before it runs.
 | ------- | ------------ | --------- |
 | `recommended`, `agent-authored` | not fixable | `sh/sh` |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 A script you can review is a script whose code is all in front of you. Two constructs defeat
@@ -98,7 +102,8 @@ still report.
 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
+This rule is one of eslint-sh's
+[deliberate overlaps with shellcheck](../shellcheck.md#deliberate-overlaps). 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

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

@@ -6,6 +6,10 @@ Disallow `local`, `declare`, `typeset`, `export` and `readonly` with a value tak
 | ---------------- | ----------------------------------------- | --------- |
 | `agent-authored` | suggestions (split into two statements) | `sh/sh`   |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 `local x=$(cmd)` runs `cmd`, then runs `local`, and the statement's exit status is the status of

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

@@ -6,6 +6,10 @@ Disallow reading secret-shaped environment variables, such as `$GITHUB_TOKEN`, o
 | ---------------- | ----------- | --------- |
 | `agent-authored` (error) | not fixable | `sh/sh`   |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 Once a secret is expanded into a command's arguments, every user on the machine can read it
@@ -34,6 +38,13 @@ Four things are not reported:
   command is resolved through transparent wrappers (`sudo vault …` is `vault`), and a command run
   by path matches by basename.
 
+Only arguments actually passed after the final resolved sink command receive this
+exemption. Wrapper-owned options and operands are checked normally. With an approved
+`sink` and `settings: { sh: { transparentWrappers: [{ names: ['with-retry'], argFlags: ['--log'] }] } }`,
+`with-retry --log "$API_TOKEN" sink` reports, while
+`with-retry --log audit.log sink "$API_TOKEN"` stays clean. Likewise, the secret in
+`env -u "$API_TOKEN" sink` is owned by `env`, so approving `sink` does not exempt it.
+
 Matching is a name pattern, not secret detection.
 
 ### Expected false positives
@@ -59,12 +70,16 @@ The rule matches parameter expansions only. These reads are not reported:
 ## 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.
+  variable's name. They **replace** the default list. Sources use `u` (Unicode, case-sensitive):
+  `patterns: ['token']` does not catch `$GITHUB_TOKEN`, while `patterns: ['TOKEN']` does.
+  Lowercase names such as `$sort_key` do not match the uppercase default patterns.
+  See [regular-expression options](./README.md#regular-expression-options) for compilation and
+  configuration errors, which name the rule, option index and source.
 
   Default: `["(_TOKEN|_SECRET|_PASSWORD|_KEY)$"]`.
 
-- `allowedSinks` (`string[]`). Command names whose arguments may read a secret-shaped variable.
+- `allowedSinks` (`string[]`). Command names whose own arguments may read a secret-shaped variable. Wrapper-owned
+  operands are not exempt.
 
   Default: `[]`.
 
@@ -80,6 +95,22 @@ The rule matches parameter expansions only. These reads are not reported:
 }
 ```
 
+Regex syntax errors fail when this rule first runs on a file, naming the rule, option and
+pattern. `--print-config` will not catch any regex syntax errors. See the
+[shared compilation contract](./README.md#regular-expression-options).
+
+### Matching examples
+
+These examples use only this rule; `patterns` replaces the defaults. Option values below are JSON.
+
+| Option value | Shell input | Findings |
+| --- | --- | --- |
+| `{"patterns":["token"]}` | `echo "$GITHUB_TOKEN"` | 0 |
+| `{"patterns":["TOKEN"]}` | `echo "$GITHUB_TOKEN"` | 1 |
+| `{}` | `echo "$sort_key"` | 0 |
+| `{"patterns":["^\\p{Lu}+$"]}` | `echo "$TOKEN"` | 1 |
+| `{"patterns":["^\\p{Lu}+$"]}` | `echo "$token"` | 0 |
+
 ### Patterns run against script-controlled text
 
 `patterns` is tested against every variable name the linted script expands, and the script's author

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

@@ -60,8 +60,10 @@ positive with a disable comment that says why, or narrow the `patterns` option f
 
 - `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.
+  with `iu` (Unicode, case-insensitive), like the default. For example, `patterns: ['token']`
+  catches `cli --TOKEN=abc`; capitals in a custom pattern also match lowercase flag names.
+  See [regular-expression options](./README.md#regular-expression-options) for compilation and
+  configuration errors, which name the rule, option index and source.
 
   Default: `["^(?!.*-(?:stdin|file)$)--?(?:access-|auth-?)?(?:password|passwd|token|secret|api-?key|auth(?:key|orization)?)(?![a-z])"]`.
 
@@ -78,6 +80,21 @@ positive with a disable comment that says why, or narrow the `patterns` option f
 }
 ```
 
+Regex syntax errors fail when this rule first runs on a file, naming the rule, option and
+pattern. `--print-config` will not catch any regex syntax errors. See the
+[shared compilation contract](./README.md#regular-expression-options).
+
+### Matching examples
+
+These examples use only this rule; `patterns` replaces the defaults. Option values below are JSON.
+
+| Option value | Shell input | Findings |
+| --- | --- | --- |
+| `{"patterns":["token"]}` | `cli --TOKEN=abc` | 1 |
+| `{"patterns":["TOKEN"]}` | `cli --token=abc` | 1 |
+| `{"patterns":["token"]}` | `cli --other=abc` | 0 |
+| `{"patterns":["^--\\p{Lu}+$"]}` | `cli --TOKEN=abc` | 1 |
+
 ### Patterns run against script-controlled text
 
 `patterns` is tested against every flag name the linted script writes, and the script's author

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

@@ -6,6 +6,10 @@ Require the failure of `cd`, `pushd` and `popd` to be checked, so a script never
 | ------------------------------- | ---------------------------- | --------- |
 | `recommended`, `agent-authored` | suggestions (append `\|\| exit`) | `sh/sh`   |
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](../transparent-wrappers.md).
+
 ## Rule details
 
 When `cd` fails, the script keeps running in the directory it was already in, and every relative
@@ -31,7 +35,8 @@ read as `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.
+window does not count. Only `set` statements count; shebang flags do not. 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`,
@@ -143,4 +148,6 @@ shellcheck overlaps with SC2164 ("Use `cd ... || exit` in case `cd` fails"), and
 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.
+shellcheck. The checks differ when errexit comes from a shebang such as `#!/bin/bash -e`:
+shellcheck treats it as `set -e` and suppresses SC2164, while `ignoreWhenErrexit` reads only
+`set` statements in the prologue, so this rule still reports an unchecked `cd`.

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

@@ -14,7 +14,7 @@ machine it lands on. When your project states each script's dependencies, this r
 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
+one with `settings: { sh: { declarationConvention: commentPragma } }`. 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.
@@ -61,16 +61,17 @@ In a file without a shebang, the message says to add the line as the first line
 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
+## Shared settings
 
-- `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)).
+This rule has no options. Declare project wrapper facts once with
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`.
+Every wrapper-following rule reads that setting, including the other declaration rule.
+Entries accept names or flag-bearing specs, for example
+`settings: { sh: { transparentWrappers: [{ names: ['with-retry'], argFlags: ['-n'] }] } }`.
+Then `with-retry -n 3 curl` uses both `with-retry` and `curl`.
+The shared network wrapper is also followed automatically. Utility wrappers invoked
+by absolute or relative path count by basename; builtin specs require exact names.
+See [shared transparent wrappers](../transparent-wrappers.md) for precedence and migration.
 
 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.
@@ -84,9 +85,9 @@ export default [
     files: ['**/*.sh'],
     plugins: { sh },
     language: 'sh/sh',
-    settings: { sh: { declarationConvention: commentPragma } },
+    settings: { sh: { declarationConvention: commentPragma, transparentWrappers: ['with-retry'] } },
     rules: {
-      'sh/no-undeclared-commands': ['error', { transparentWrappers: ['with-retry'] }],
+      'sh/no-undeclared-commands': 'error',
     },
   },
 ];
@@ -94,11 +95,11 @@ export default [
 
 ## Examples
 
-With `commentPragma` bound and `{ transparentWrappers: ['with-retry'] }`:
+With `commentPragma` bound and `settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
 ### Incorrect
 
-<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}, "findings": 6} -->
+<!-- example: {"convention": "commentPragma", "settings": {"sh": {"transparentWrappers": ["with-retry"]}}, "findings": 6} -->
 ```sh
 #!/usr/bin/env bash
 # uses: jq
@@ -110,7 +111,7 @@ with-retry git pull          # git, run by the wrapper, is not declared (nor is
 
 ### Correct
 
-<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}} -->
+<!-- example: {"convention": "commentPragma", "settings": {"sh": {"transparentWrappers": ["with-retry"]}}} -->
 ```sh
 #!/usr/bin/env bash
 # uses: curl jq date

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

@@ -15,7 +15,7 @@ script's real surface. This rule reports each declared command the script never
 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
+one with `settings: { sh: { declarationConvention: commentPragma } }`. 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.
@@ -135,18 +135,17 @@ the whole line goes with its `\n` or `\r\n`. When several names on one line are
 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
+## Shared settings
 
-- `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)).
+This rule has no options. Declare project wrapper facts once with
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`.
+Every wrapper-following rule reads that setting, including the other declaration rule.
+Entries accept names or flag-bearing specs, for example
+`settings: { sh: { transparentWrappers: [{ names: ['with-retry'], argFlags: ['-n'] }] } }`.
+Then `with-retry -n 3 curl` uses both `with-retry` and `curl`.
+The shared network wrapper is also followed automatically. Utility wrappers invoked
+by absolute or relative path count by basename; builtin specs require exact names.
+See [shared transparent wrappers](../transparent-wrappers.md) for precedence and migration.
 
 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.
@@ -155,17 +154,15 @@ with `structuredClone`, which cannot copy a convention's methods.
 // 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 } },
+    settings: { sh: { declarationConvention: commentPragma, transparentWrappers: ['with-retry'] } },
     rules: {
-      'sh/no-undeclared-commands': ['error', wrappers],
-      'sh/no-unused-declarations': ['error', wrappers],
+      'sh/no-undeclared-commands': 'error',
+      'sh/no-unused-declarations': 'error',
     },
   },
 ];
@@ -173,11 +170,11 @@ export default [
 
 ## Examples
 
-With `commentPragma` bound and `{ transparentWrappers: ['with-retry'] }`:
+With `commentPragma` bound and `settings: { sh: { transparentWrappers: ['with-retry'] } }`:
 
 ### Incorrect
 
-<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}, "findings": 3} -->
+<!-- example: {"convention": "commentPragma", "settings": {"sh": {"transparentWrappers": ["with-retry"]}}, "findings": 3} -->
 ```sh
 #!/usr/bin/env bash
 # uses: jq curl docker   # docker is never run
@@ -189,7 +186,7 @@ curl -s "$URL" | jq .
 
 ### Correct
 
-<!-- example: {"convention": "commentPragma", "options": {"transparentWrappers": ["with-retry"]}} -->
+<!-- example: {"convention": "commentPragma", "settings": {"sh": {"transparentWrappers": ["with-retry"]}}} -->
 ```sh
 #!/usr/bin/env bash
 # uses: jq curl git sudo date with-retry