@eslint-sh/eslint-plugin 0.7.0 → 0.8.0

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

package/docs/rules/prefer-local.md

@@ -88,9 +88,11 @@ This rule takes one options object:
 - `allow` (`string[]`, default `[]`): variable names that may be assigned in a function without
   `local`.
 - `allowPattern` (`string`, default `"^[A-Z][A-Z0-9_]*$"`): a regular expression, compiled with the
-  `u` flag, that exempts every name it matches. A value that is not a valid regular expression is a
+  `u` flag (Unicode, case-sensitive), that exempts every name it matches. A value that is not a valid regular expression is a
   configuration error. Setting it replaces the default, so `allowPattern: '^g_'` stops exempting
-  UPPER_CASE names.
+  UPPER_CASE names. For example, `'^g_'` exempts `g_cache` but not `G_cache`.
+  See [regular-expression options](./README.md#regular-expression-options) for the shared
+  compilation and configuration-error contract.
 
 ```js
 // eslint.config.js
@@ -104,6 +106,22 @@ This rule takes one options object:
 }
 ```
 
+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; a finding means the assignment needs `local`.
+Option values below are JSON.
+
+| Option value | Shell input | Findings |
+| --- | --- | --- |
+| `{"allowPattern":"^g_"}` | `f(){ g_cache=1; }` | 0 |
+| `{"allowPattern":"^g_"}` | `f(){ G_cache=1; }` | 1 |
+| `{"allowPattern":"^\\p{Lu}+$"}` | `f(){ CACHE=1; }` | 0 |
+| `{"allowPattern":"^\\p{Lu}+$"}` | `f(){ cache=1; }` | 1 |
+
 ### Patterns run against script-controlled text
 
 `allowPattern` is tested against every variable name the linted script assigns in a function, and

package/docs/rules/quote-expansions.md

@@ -137,7 +137,8 @@ exec "$@"                 # "$@" keeps every argument intact
 
 ## When not to use it
 
-Disable the rule if you run shellcheck, which already reports the same problem as SC2086
+Disable the rule if you run shellcheck and want to avoid double reports. This also drops
+its checks in command-name position and `for … in` lists, which SC2086 does not report
 (see below). For one line that relies on splitting on purpose, such as passing `$CFLAGS` to a
 compiler, disable it on that line (`# eslint-disable-next-line sh/quote-expansions`) or rewrite
 the value as an array (`"${cflags[@]}"`).
@@ -147,11 +148,13 @@ the value as an array (`"${cflags[@]}"`).
 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. It covers the same
+This rule is one of eslint-sh's
+[deliberate overlaps with shellcheck](../shellcheck.md#deliberate-overlaps). It covers the same
 problem as SC2086 (double quote to prevent globbing and word splitting), and SC2068 for unquoted
 `$@`. It exists for teams that run eslint-sh without shellcheck, so that this common mistake is
-still caught. **If you run shellcheck, disable this rule**, so the same line is not reported
-twice. The rule does not try to match SC2086's heuristics: shellcheck skips some expansions it
-can prove are safe, such as a variable it saw assigned a number, and this rule reports them
+still caught. **Disabling this rule when you run shellcheck avoids double reports**, but also
+drops checks in command-name position (`$cmd arg`) and `for … in` lists (`for x in $LIST`),
+which SC2086 never reports. The rule does not try to match SC2086's heuristics: shellcheck skips
+some expansions it can prove are safe, such as a variable it saw assigned a number, and this rule reports them
 because it does no dataflow analysis. That is why `recommended` enables it at `warn` instead of
 `error`.

package/docs/rules/require-network-wrapper.md

@@ -62,7 +62,7 @@ It does not depend on `languageOptions`.
 ## Options
 
 - `wrapper` (`string` or `WrapperSpec` object, no default): the wrapper network commands must be
-  run through. When it is unset, the rule uses `settings.sh.networkWrapper` (below); with
+  run through. When it is unset, the rule uses `settings: { sh: { networkWrapper: 'with-retry' } }` (below); with
   neither, the rule reports nothing. A string names a wrapper that takes no options
   (or one of the default transparent wrappers, such as `timeout`, whose options are known). An
   object declares the wrapper's options so the command after them is found:
@@ -85,31 +85,36 @@ It does not depend on `languageOptions`.
 }
 ```
 
-### Declaring the wrapper once: `settings.sh.networkWrapper`
+### Declaring the wrapper once
 
-`sh/no-undeclared-commands` and `sh/no-unused-declarations` also need to know about your wrapper:
-in `with-retry curl x` the script runs `curl`, and only a rule that looks through `with-retry` sees
-that. ESLint doesn't let one rule read another rule's options, so a wrapper set only as this rule's
-`wrapper` option is invisible to them, and an undeclared `curl` behind it goes unreported.
-
-Set the wrapper in shared settings instead, and all three rules read it:
+Set the network policy in shared settings so every wrapper-following rule sees the
+same command chain, including the declaration rules, `sh/no-eval`, and
+`sh/no-dynamic-invocation`:
 
 ```js
 // eslint.config.js
 {
   settings: { sh: { declarationConvention: commentPragma, networkWrapper: 'with-retry' } },
-  rules: { 'sh/require-network-wrapper': 'error' }, // or extend sh.configs['agent-authored']
+  rules: { 'sh/require-network-wrapper': 'error' },
 }
 ```
 
-`networkWrapper` takes the same values as the `wrapper` option, a name or a `WrapperSpec` object,
-and the declaration rules follow a spec's options too (`with-retry -n 3 curl`). This rule's
-`wrapper` option, when set, takes precedence for this rule only. A malformed value stops linting
-with an error starting `Invalid settings.sh.networkWrapper:`.
-
-The setting names your **network** wrapper, a policy. Other wrappers that run a command, such as
-a `with-lock` helper, aren't network policy: list those in the declaration rules'
-`transparentWrappers` option.
+`networkWrapper` accepts a name or a JSON-expressible `WrapperSpec` object, like the
+`wrapper` rule option. A custom spec for a default wrapper name takes effect in every
+consumer. Absolute and relative utility wrapper paths match by basename:
+`/opt/bin/with-retry curl x` and `./bin/with-retry curl x` both run `curl` through
+`with-retry`, and an undeclared `curl` is reported by the declaration rule.
+
+A `wrapper` option that disagrees with the shared network policy now throws a clear
+configuration error. Equivalent values are accepted; there is no silent override.
+A wrapper set only as a rule option remains local to this network policy because other
+rules cannot read its options. Prefer the shared setting. Malformed settings also stop linting.
+
+Other project wrappers belong in
+`settings: { sh: { transparentWrappers: ['with-lock'] } }`. This factory-based rule
+reads those facts too, so `with-lock curl x` cannot hide an unwrapped network call.
+[Shared transparent wrappers](../transparent-wrappers.md) documents the common resolver,
+conflicting specs, path matching, and migration from the removed per-rule options.
 
 ## Examples
 

package/docs/rules/require-shebang.md

@@ -24,6 +24,11 @@ This rule reads line 1 of the file and reports two problems:
     `#!/usr/bin/env -S bash -e`. The rule skips `env` options, their arguments and
     `NAME=value` assignments to find the command `env` runs.
 
+  The space-separated long form `#!/usr/bin/env --split-string bash -eu` is reported:
+  GNU env receives `--split-string bash -eu` as one option name and rejects it. GNU
+  `--split-string=bash -eu` is accepted here, but macOS env does not support the long form;
+  use `-S` across both systems.
+
   A relative interpreter such as `#!bash` or `#!env bash` is reported, because the kernel
   resolves it against the caller's working directory, not `PATH`.
 
@@ -150,8 +155,9 @@ eslint-sh is a convention and contract linter: a policy layer, where shellcheck
 layer. Run shellcheck beside it.
 
 shellcheck's SC2148 ("Tips depend on target shell and yours is unknown") fires when a file has
-no shebang and no `shell=` directive. shellcheck's aim is to know which shell to analyze for,
-so a `# shellcheck shell=bash` directive or a `--shell` flag silences it. This rule enforces
-the policy that the script itself names its interpreter, which a directive or a command-line
-flag does not satisfy. It also autofixes the missing line from your configured dialect.
+no shebang and it cannot otherwise infer the shell. A `.bash`, `.bats` or `.ksh` extension,
+a `# shellcheck shell=bash` directive or a `--shell` flag supplies that information and
+silences SC2148. This rule requires the script itself to name its interpreter, so it still
+reports a missing shebang in those files. It also autofixes the missing line from your configured
+dialect.
 shellcheck's SC1008 ("This shebang was unrecognized") overlaps `unrecognizedInterpreter`.

package/docs/rules/require-strict-mode.md

@@ -142,6 +142,12 @@ This rule takes one options object:
   `bash script.sh`, so a `set` line is the only prologue that applies however the script is
   started.
 
+Relative interpreters such as `#!env -S bash -eu` receive no credit. Neither does
+`#!/usr/bin/env --split-string bash -eu`: GNU env rejects the space-separated long
+option when invoked through a kernel shebang. GNU's equals form
+`#!/usr/bin/env --split-string=bash -eu` receives credit; macOS env does not support that long
+option. Use an absolute env path and `-S` for both systems.
+
 ```js
 // eslint.config.js
 {

package/docs/shellcheck.md

@@ -32,8 +32,8 @@ For a complete GitHub Actions job, exit codes, a pre-commit hook and editor setu
 [`eslint-sh` README](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md#continuous-integration).
 
 Give them the same target shell, since each reads its own configuration. shellcheck takes it
-from the shebang or a `# shellcheck shell=…` directive; eslint-sh takes it from
-`languageOptions.dialect` and `languageOptions.shellVersion`. The `bash-3.2` and
+from the shebang, a `# shellcheck shell=…` directive, or a `.bash`, `.bats` or `.ksh` extension;
+eslint-sh takes it from `languageOptions.dialect` and `languageOptions.minBashVersion`. The `bash-3.2` and
 `posix-portable` presets set the latter for you, and
 [`sh/shebang-matches-dialect`](./rules/shebang-matches-dialect.md) reports a
 shebang that disagrees with the configured dialect, so the two tools do not end up advising for
@@ -68,10 +68,10 @@ reason given, and each rule's page has a "Relationship to shellcheck" section. T
 
 | eslint-sh rule | Overlapping shellcheck code | Why the rule exists anyway |
 | -------------- | --------------------------- | -------------------------- |
-| [`sh/quote-expansions`](./rules/quote-expansions.md) | SC2086, SC2068 | Makes unquoted expansions a project policy with a severity you choose, and offers a quoting suggestion. It is `warn` in `recommended`; disable it if you already enforce SC2086. |
+| [`sh/quote-expansions`](./rules/quote-expansions.md) | SC2086, SC2068 | Makes unquoted expansions a project policy with a severity you choose, and offers a quoting suggestion. It is `warn` in `recommended`; disabling it when you enforce SC2086 avoids double reports, but also drops checks in command-name position and `for … in` lists, which SC2086 never reports. |
 | [`sh/no-eval`](./rules/no-eval.md) | SC2294 (`eval` on arrays), SC1090 (non-literal `source`) | shellcheck flags `eval` only in specific misuse patterns. The rule treats every `eval` and every non-literal `source` as a reviewable exception. |
-| [`sh/no-unchecked-cd`](./rules/no-unchecked-cd.md) | SC2164 | Kept for files that run without `set -e`; the two agree on the common cases. |
-| [`sh/require-shebang`](./rules/require-shebang.md) | SC2148, SC1008 | A required, recognized shebang is a rule of the repository, not a hint about the target shell. |
+| [`sh/no-unchecked-cd`](./rules/no-unchecked-cd.md) | SC2164 | Offers a suggestion and covers `pushd` and `popd` too. shellcheck suppresses SC2164 for shebang errexit flags; `ignoreWhenErrexit` reads only prologue `set` statements, so the rule still reports those unchecked directory changes. |
+| [`sh/require-shebang`](./rules/require-shebang.md) | SC2148, SC1008 | Requires a recognized shebang even when shellcheck infers the shell from a `.bash`, `.bats` or `.ksh` extension, a directive or a command-line flag and emits no SC2148. |
 | [`sh/no-masked-exit-status`](./rules/no-masked-exit-status.md) | SC2155 | `require-strict-mode` makes `set -euo pipefail` a contract, and `local x=$(cmd)` is the most common way a script that honours it still swallows a failure. shellcheck offers no fix; the rule offers the split as an editor suggestion and can be limited to files where errexit is on. It is not in `recommended`, because that preset runs beside shellcheck. |
 | [`sh/prefer-local`](./rules/prefer-local.md) | SC2155 (a related check) | Requires `local` declarations, and its fix declares the variable on a separate line, which avoids SC2155. |
 | [`sh/compat/no-associative-arrays`](./rules/compat/no-associative-arrays.md), [`no-case-modification`](./rules/compat/no-case-modification.md), [`no-negative-array-index`](./rules/compat/no-negative-array-index.md), [`no-mapfile`](./rules/compat/no-mapfile.md) | SC3044 (the `declare` or `mapfile` command, not the `-A` option), SC3043 (`local -A`), SC3054 (`${a[-1]}`), SC3059 (case modification) | shellcheck reports these only for scripts it treats as POSIX `sh`. These rules report them for a Bash version you name. |
@@ -85,3 +85,7 @@ reason given, and each rule's page has a "Relationship to shellcheck" section. T
 | [`sh/compat/no-lastpipe-semantics`](./rules/compat/no-lastpipe-semantics.md) | SC2030, SC2031 | shellcheck explains the subshell effect of lastpipe; the rule reports `shopt -s lastpipe` on a Bash that lacks it. |
 | [`sh/shebang-matches-dialect`](./rules/shebang-matches-dialect.md) | SC3xxx | shellcheck judges the syntax against the shebang. This rule compares the shebang with your configured dialect, a different question. |
 | [`sh/require-strict-mode`](./rules/require-strict-mode.md) | none directly (SC2164, an unchecked `cd`, is one consequence) | shellcheck has no check that requires strict mode. |
+
+`sh/compat/no-nounset-empty-array` requires explicit opt-in for `bash-3.2`. Enable it when a
+script runs with `set -u` on Bash below 4.4 and its arrays can really be empty. Local checks
+cannot prove safety across every caller or helper contract. `posix-portable` still enables it.

package/docs/transparent-wrappers.md

@@ -0,0 +1,97 @@
+# Shared transparent wrappers
+
+A transparent wrapper runs a command named in its arguments. Declare that project fact
+once so every wrapper-following rule sees the same command chain:
+
+```js
+{
+  settings: {
+    sh: {
+      transparentWrappers: ['with-retry', { names: ['audit-run'], argFlags: ['--ticket'] }],
+    },
+  },
+}
+```
+
+Entries are non-empty names or JSON-expressible `WrapperSpec` objects. A name preserves
+the known option shape of a default wrapper such as `timeout`; an unfamiliar name
+takes no flags. A spec can declare `names`, `noArgFlags`, `argFlags`,
+`unresolvableFlags`, `stopsChainFlags`, `positionalOperandsBeforeCommand`,
+`assignmentOperands` (`shell-identifier`, `env`, or `sudo`), and `shellBuiltin`.
+`names` is required and non-empty. Regex fields and functions are not accepted.
+An unknown flag stops analysis rather than guessing which operand is the command.
+
+Project specs precede each rule's built-in table, including when a project spec names a
+default wrapper. Replaced names are removed from lower-priority entries while their
+unrelated aliases remain available; a builtin override cannot regain utility path semantics.
+Duplicate project names and malformed entries are configuration errors.
+The shared network policy, for example
+`settings: { sh: { networkWrapper: 'with-retry' } }`, also supplies a transparent-wrapper
+fact. Overlapping names must have the same option shape; extra transparent aliases do
+not become approved network wrappers. Different option shapes for shared names are
+configuration errors. A network rule's `wrapper` option must agree with both the option
+shape and the full approved name set of a configured shared network policy. It cannot
+override that policy silently. Omitted flag lists and empty flag lists are equivalent;
+object key order and flag-list order do not matter.
+
+Both comparisons use the published matcher's effective grammar: omitted flag lists
+are empty, `shellBuiltin: false` means utility matching, and
+`positionalOperandsBeforeCommand: 0` consumes no positional operand. Assignment
+handling uses the selected grammar; the internal legacy alias means
+`shell-identifier` only when no explicit grammar was supplied. Expanded built-in
+flag patterns compare by source and flags, including presence versus absence.
+This is structural grammar comparison, not arbitrary regex-language equivalence.
+Explicit specs remain complete replacements: a patternless `nice` spec does not
+inherit the built-in numeric-priority pattern, and conflicts with the string default
+when both are configured for the same name. Internal regex fields remain forbidden
+in settings; the accepted JSON fields above are unchanged.
+
+Utility wrappers invoked by absolute or relative path match by basename:
+`/opt/bin/with-retry curl x` and `./bin/with-retry curl x` both run `curl`.
+An explicit path spec takes precedence over a basename fallback in either list order.
+Path aliases are also built for a rule's built-in table when no shared setting is present.
+The written wrapper path remains a dependency in declaration harvesting. Specs with
+`shellBuiltin: true` require exact names: `/tmp/command` cannot acquire the shell
+builtin's semantics. Unused-declaration completeness uses the resolved table too,
+without restoring overridden built-in path semantics. These are syntactic declarations; no wrapper or corpus script is
+executed or inspected to infer its behavior.
+
+Every built-in that follows wrappers reads these facts: `no-undeclared-commands`,
+`no-unused-declarations`, `no-dynamic-invocation`, `no-eval`, `no-unchecked-cd`,
+`no-secret-env-reads`, `no-masked-exit-status`, and the command-based compatibility
+rules. `require-network-wrapper` and rules made with `createWrapperRule` do too.
+Rules retain their own built-in scopes and reporting policies. `quote-expansions`
+checks expansion positions directly and does not follow wrappers.
+
+Allowed-secret-sink exemptions apply only to argument words after the final resolved
+command. In `with-retry --log "$API_TOKEN" sink`, the secret is owned by the wrapper
+and is checked normally, even if `sink` is approved. In
+`with-retry --log audit.log sink "$API_TOKEN"`, it is an actual sink argument and can
+be exempt. The same boundary applies to default wrappers such as `env -u`.
+
+## Migration
+
+Remove the `transparentWrappers` option from `no-undeclared-commands` and
+`no-unused-declarations`, and remove `allowWrappers` from `no-dynamic-invocation`.
+Move the list to `settings: { sh: { transparentWrappers: ['with-retry'] } }`.
+Removed rule options fail ESLint schema validation; no per-rule override exists.
+
+`allowWrappers` added checks: it made the rule follow the wrapper and report a
+dynamic operand such as `with-retry "$cmd"`. Moving its list preserves that check
+and makes every other wrapper-following rule see it too. To suppress a dynamic
+dispatcher, use `allowInFunctions` or a justified ESLint disable comment.
+
+Findings can change on unchanged scripts once project wrappers are configured:
+wrapped `eval`, unchecked `cd`, dynamic invocations, compatibility features, and
+unwrapped network commands become visible. An allowed secret sink behind a project
+wrapper can become recognized, and incomplete usage behind a wrapper can prevent an
+unsafe unused-declaration fix.
+
+## Rule packs
+
+Call `resolveTransparentWrappers(context, builtIns)` from a rule's `create()` and
+pass its result as the analysis `transparentWrappers` table. Omit `builtIns` to use
+the default table. The resolver composes shared facts with that scope, validates
+configuration, and adds path spellings from the linted file without mutating inputs.
+Both `eslint-sh` and `@eslint-sh/eslint-plugin` export it and
+`TransparentWrappersBindingContext`.

package/docs/wrapper-rules.md

@@ -9,6 +9,10 @@ Which commands need a wrapper, and which wrapper, is your project's policy. This
 wrapper name. You bind both, either in a rule pack with `createWrapperRule` or in your config
 with [`sh/require-network-wrapper`](./rules/require-network-wrapper.md)'s `wrapper` option.
 
+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).
+
 ## `createWrapperRule`
 
 ```ts
@@ -204,3 +208,8 @@ command runs after its own options, located the way a wrapped command is located
 `noArgFlags` and `argFlags` are skipped, and an option in `stopsChainFlags` means no subcommand
 runs. The message names the command with its subcommand: `` `git fetch` must be run through
 `retry`. ``
+
+A `WrapperSpec` may set `shellBuiltin: true` for a wrapper that runs inside the current shell.
+Such entries match exact names: an executable such as `/tmp/command` is not the `command`
+builtin and its argument words remain opaque. Omitted or false retains utility-wrapper path
+matching. The same boolean field is accepted in the network-wrapper option and setting.