@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

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/rules/require-tty-guard.md

@@ -82,7 +82,10 @@ if [ -t 0 ]; then read name; fi
 A multi-line statement that starts its own line is wrapped on lines of its own. Anywhere else the
 wrapper goes around it in place, because an earlier command on the line may have opened a
 here-document whose body begins at the next line break; a line break goes before `fi` only when the
-statement ends in a here-document of its own. A statement run in the background (`read x &`)
+statement ends in a here-document of its own. A statement whose here-document opener shares its
+line with another command (`read x 3<<EOF; echo hi`, or a trailing comment) gets no suggestion: the
+statement's source runs on to the terminator, so wrapping it would pull that command into the guard
+and it would run only on a terminal. A statement run in the background (`read x &`)
 gets no suggestion, because wrapping it would change what is backgrounded. A statement whose exit
 status steers control flow (an `if`/`while`/`until` condition, or an operand of `&&` or `||`) is
 reported without a suggestion too: the wrapper would exit 0 when there is no terminal, which

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,19 +68,24 @@ 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. |
 | [`sh/compat/no-double-bracket`](./rules/compat/no-double-bracket.md), [`no-let`](./rules/compat/no-let.md), [`no-source`](./rules/compat/no-source.md) | SC3010 (`[[`), SC3039 (`let`), SC3046 (`source`), under `-s sh` only | Under `-s bash` shellcheck reports nothing for `[[` or `source`, and for `let` only SC2219, a style note that prefers `(( ))`. These rules report them for the dialect you configure, because they fail on dash and would otherwise defeat a preset named for portability. |
 | [`sh/compat/no-test-v`](./rules/compat/no-test-v.md), [`no-wait-n`](./rules/compat/no-wait-n.md), [`no-globstar`](./rules/compat/no-globstar.md), [`no-pipe-all`](./rules/compat/no-pipe-all.md), [`no-fd-variable`](./rules/compat/no-fd-variable.md), [`no-unicode-escape`](./rules/compat/no-unicode-escape.md) | SC3016 (`test -v`, with SC3010 for `[[`), SC3045 (`wait -n`), SC3044 (`shopt`), SC3029 (`\|&`), SC3022 (`{fd}`), SC3003 (`$'…'`) | shellcheck reports these Bash features only for scripts it treats as POSIX `sh`. These rules report them for a Bash version you name. |
 | [`sh/compat/no-nameref`](./rules/compat/no-nameref.md), [`no-case-attributes`](./rules/compat/no-case-attributes.md) | SC3043 (`local`), SC3044 (`declare`, `typeset`): the command, not the `-n`, `-l` or `-u` option | Under `-s sh` shellcheck reports the command that carries the option; under `-s bash` it reports nothing for either. These rules report the option for a Bash version you name. |
+| [`sh/compat/no-brace-sequence-padding-step`](./rules/compat/no-brace-sequence-padding-step.md) | SC3009 (brace expansion, under `-s sh` only) | Under `-s sh` shellcheck reports every brace expansion, a plain `{1..3}` and `{a,b}` too, as undefined in POSIX sh. Under `-s bash` it reports nothing, so a Bash older than 4.0 gets no finding for the padded and stepped forms. The rule reports only those two forms, for a Bash version you name. |
 | [`sh/compat/no-case-fallthrough`](./rules/compat/no-case-fallthrough.md) | SC2127 (an error, not an SC3xxx check) | Under `-s sh` shellcheck asks for a bash or ksh shebang; under `-s bash` it reports nothing. The rule reports `;&` and `;;&` for a Bash version you name. |
 | [`sh/compat/no-epoch-variables`](./rules/compat/no-epoch-variables.md) | SC3028 (`$EPOCHSECONDS`, `$EPOCHREALTIME`, under `-s sh` only) | Under `-s bash` shellcheck reports nothing, so a Bash older than 5.0 gets no finding. The rule reports them for a Bash version you name. |
 | [`sh/compat/no-append-all-redirect`](./rules/compat/no-append-all-redirect.md), [`no-parameter-transformation`](./rules/compat/no-parameter-transformation.md), [`no-printf-time-format`](./rules/compat/no-printf-time-format.md), [`no-nounset-empty-array`](./rules/compat/no-nounset-empty-array.md) | none | shellcheck reports nothing for `&>>`, `${v@op}`, `printf '%(…)T'` or an empty array under `set -u`, under `-s sh` or `-s bash` (it reports only the array syntax, SC3030 and SC3054, under `-s sh`). |
 | [`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`.