@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/docs/rules/prefer-local.md

@@ -0,0 +1,221 @@
+# `sh/prefer-local`
+
+Require variables assigned inside a function to be declared `local`, so a function does not
+overwrite globals its callers rely on.
+
+| Configs          | Fixable | Languages |
+| ---------------- | ------- | --------- |
+| `agent-authored` | autofix | `sh/sh`   |
+
+## Rule details
+
+Shell variables are global by default. A helper that assigns `i`, `tmp` or `result` silently
+overwrites the same-named variable of its caller, and of the caller's caller, because shell scoping
+is dynamic. This rule reports an assignment inside a function body to a name that the function did
+not declare `local`, `declare` or `typeset`.
+
+What the rule treats as an assignment:
+
+- A plain assignment statement: `x=1`, `x+=1`, `x=$(cmd)`. An assignment that prefixes a command
+  (`x=1 cmd`) only changes that command's environment and is not reported.
+- The variables `read` assigns: `read x`, `read -r a b`, `read -a arr`. The rule skips `read`'s
+  options and their arguments (`-p "prompt: "`, `-d ''`, `-n 3`, …). A target that is not static
+  (`read "$name"`) is not guessed at.
+- The loop variable of `for x in …` and `select x in …`.
+
+What the rule does not report:
+
+- A name declared `local`, `declare` or `typeset` **earlier** in the function. A declaration after
+  the assignment does not cover it.
+- A name assigned at top level **before** the function is defined. The rule treats it as an
+  intentional global that the function is meant to share.
+- A name declared global on purpose: `export x=…`, `readonly x=…`, `declare -g x=…`,
+  `typeset -g x=…`.
+- A name listed in `allow`, or matched by `allowPattern`. By default `allowPattern` is
+  `^[A-Z][A-Z0-9_]*$`, so UPPER_CASE names, which scripts conventionally use for globals, are
+  allowed.
+- Anything in a subshell `( … )`, a command substitution `$( … )` or a process substitution, and
+  functions whose body is a subshell (`f() ( … )`): those run in a child process, so nothing leaks.
+- Anything in a pipeline element, such as `echo hi | read x` or `ls | while read -r line; do …; done`.
+  Pipeline elements run in subshells, so the assignment is lost rather than leaked. The exception is
+  a file that enables `shopt -s lastpipe` (anywhere in the file): the **last** element of each
+  pipeline then runs in the current shell, and the rule checks it like any other statement. Earlier
+  elements are still skipped.
+
+Each function is its own scope. A function defined inside another function is checked on its own.
+Only the **first** assignment to a name in a function is reported, since one declaration covers the
+rest.
+
+`local` is not part of POSIX, so under `languageOptions: { dialect: 'posix' }` the rule reports
+nothing.
+
+**Autofix.** The fix inserts one `local <name> <name> …` statement as the first statement of the
+function body, naming every name the function leaks, and leaves the assignments untouched:
+
+```sh
+# before
+f() {
+  out=$(compute)
+}
+
+# after
+f() {
+  local out
+  out=$(compute)
+}
+```
+
+The fix does not rewrite `out=$(compute)` into `local out=$(compute)` on purpose. `local` is a
+command, so its exit status is its own, not that of `compute`: `local out=$(false)` succeeds, and
+`set -e` or `|| handle_error` never sees the failure (shellcheck SC2155). A separate declaration
+keeps the assignment's exit status intact.
+
+The fix declares a variable that was global. If the function _reads_ the global before assigning it
+(`count=$((count + 1))`), declaring it `local` makes that read see an empty value instead, so
+review the function before accepting the fix. Every report in a function carries the same fix, a
+single `local` declaring all of the function's reported names, so `eslint --fix` settles the
+function in one pass however many names it leaks (`a` then `b` becomes `local a b`). Fixes that
+insert at the same point conflict, and ESLint applies one per pass and stops after 10, which is why
+one fix per name would leave a function with more than 10 names unfixed. The declaration therefore
+also covers a name whose report a user suppressed with a directive, so review the function if you
+suppress a name in it. Each report, message and suggestion is still per name. A function whose body
+is not a `{ … }` block (`f() if …; fi`) is reported without a fix.
+
+## Options
+
+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
+  configuration error. Setting it replaces the default, so `allowPattern: '^g_'` stops exempting
+  UPPER_CASE names.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/prefer-local': ['error', {
+      allow: ['result'],
+      allowPattern: '^[A-Z][A-Z0-9_]*$',
+    }],
+  },
+}
+```
+
+### Patterns run against script-controlled text
+
+`allowPattern` is tested against every variable name the linted script assigns in a function, and
+the script's author chooses that text. When you lint scripts you do not control, a pattern with
+nested or overlapping quantifiers can make the regular expression engine backtrack for a time that
+grows exponentially with the name's length. Write anchored patterns with one level of repetition
+over a character class.
+
+The rule rejects the most common accident: a pattern that repeats a group which itself repeats
+(`*`, `+`, `{n,}` or `{n,m}` with `m > 1` applied to such a group). It is not a proof that an
+accepted pattern is safe. Review every pattern you accept as if the guard were not there.
+
+**What it does not catch.** These pass the check and can still be slow on a long name. Timings are
+from Node 24 on a busy laptop and vary by machine; the shape of the growth is what matters.
+
+- Alternation branches that overlap under a repetition grow exponentially. `^([A-Z]|[A-Z0-9])+_KEY$`
+  took about 0.4 s on a 24-character name, 1.2 s at 26 and 4.7 s at 28. `(a|a)+$` took 1.6 s at
+  24 characters and 6.4 s at 26. `^(A|AA)*$` is the same shape.
+- Adjacent quantifiers that can match the same text grow polynomially. `.*.*.*x` took 0.5 s on a
+  255-character name and 0.9 s at 300; each extra `.*` raises the exponent. Nothing bounds the length
+  of a name or flag in a script, so a long enough one is slow.
+
+**What it rejects that is in fact linear.** The check does not look at what the repeated group can
+match, so it also refuses some patterns that are safe, such as `(a*b)*`,
+`^(?:[a-z]+-)*[a-z]+$` and `^(?:SECRET|TOKEN|PASSWORD)(?:_[A-Z]+)*$`. A rewrite without the nesting
+exists for some of these and not for others, so if you cannot rewrite a pattern exactly, loosen it to
+the character class you mean. The last one can be rewritten exactly with a lookahead
+(it accepts the same names; compared on every suffix of up to seven characters over `A`, `_`, `a`
+and `1` after `SECRET`, `TOKEN` and `PASSWORD`):
+
+```js
+{ allowPattern: '^(?:SECRET|TOKEN|PASSWORD)(?!.*_(?:_|$))(?:_[A-Z][A-Z_]*)?$' }
+```
+
+
+**When you see the error.** The error is thrown from the rule's `create()`, which ESLint calls for
+each file it lints, so the check does not run when the config is loaded. ESLint stops the run at the
+first file it lints with the rule enabled and prints "Error while loading rule" followed by
+"Occurred while linting <that file>" and a stack trace, and exits with code 2. A run that lints no
+file with the rule enabled never sees it.
+
+The accident the check is for, and its fix:
+
+```js
+// Rejected: `([A-Z]+_?)*` repeats a group that already repeats, so a long
+// name that does not match can take seconds.
+{ allowPattern: '^([A-Z]+_?)*_KEY$' }
+
+// Safe rewrite: one repetition over a character class.
+{ allowPattern: '^[A-Z0-9_]*_KEY$' }
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 3, "messageIds": ["preferLocal", "preferLocal", "preferLocal"]} -->
+```sh
+f() {
+  tmp=$(mktemp) # reported: tmp is global
+  read line     # reported: read assigns line
+  for i in 1 2 3; do # reported: i is global
+    :
+  done
+}
+```
+
+<!-- example: {"findings": 1} -->
+```sh
+f() {
+  x=1 # reported: the local comes after the assignment
+  local x
+}
+```
+
+### Correct
+
+```sh
+f() {
+  local tmp line i
+  tmp=$(mktemp)
+  read line
+  for i in 1 2 3; do
+    :
+  done
+}
+```
+
+```sh
+verbose=0 # assigned at top level before the function: an intentional global
+f() {
+  verbose=1
+  COUNT=2        # UPPER_CASE is allowed by default
+  declare -g seen=1
+  export LEVEL=3
+  x=1 some-command # only the command's environment
+}
+```
+
+## When not to use it
+
+Turn this rule off for scripts that target POSIX `sh` (it is already inert there), or for scripts
+that deliberately communicate through lower-case globals and don't want to list each one in
+`allow`. Within a few functions, a directive comment can mark an intentional global.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck has no check for variables that leak out of a function. Its nearest checks are about
+`local` itself: SC2155 flags `local x=$(cmd)` because it hides the command's exit status, which is
+why this rule's fix declares the variable on a separate line, and SC2168 flags `local` outside a
+function. This rule enforces the policy that function variables are declared `local` in the first
+place.

package/docs/rules/quote-expansions.md

@@ -0,0 +1,157 @@
+# `sh/quote-expansions`
+
+Require double quotes around a parameter expansion or command substitution in any word the shell
+splits into fields and expands as a glob.
+
+| Configs | Fixable      | Languages |
+| ------- | ------------ | --------- |
+| `recommended` (`warn`), `agent-authored` (`error`) | suggestions | `sh/sh` |
+
+## Rule details
+
+When a parameter expansion (`$var`, `${var}`, `$@`) or command substitution (`$(cmd)`,
+`` `cmd` ``) is not inside double quotes, the shell splits its result on the characters in
+`IFS` and then expands each piece as a glob pattern. With `file='my notes.txt'`, `rm $file`
+removes `my` and `notes.txt`. With `pattern='*'`, `echo $pattern` lists the current directory.
+Quoting the expansion (`rm "$file"`) keeps its result as one word, which is almost always what
+the script means.
+
+The rule reports each `ParamExp` and `CmdSubst` that is an unquoted part of a word in one of
+these positions:
+
+- a command word or argument of a simple command, including the operands of `[` / `test` and a
+  bare declaration operand such as `local $names` or `export $vars`;
+- a word in a `for … in` or `select … in` list;
+- an element of an array literal without a key, such as `arr=($a)`;
+- a redirection target other than a here-document: `> $out`, `< $(pick)`, and the here-string
+  `<<< $x`, which bash split before version 4.4.
+
+Each expansion is reported on its own, so `$a$b` reports twice. The rule does not report these
+positions, which the shell does not split or glob:
+
+- the operands of `[[ ]]`;
+- the value of an assignment: `x=$y`, `local x=$y`, `declare x=$y`, `export x=$y`, a prefix
+  assignment such as `LC_ALL=$loc sort`, and a keyed array element such as `arr=([k]=$v)`;
+- the subject word and the patterns of a `case`;
+- arithmetic: `$(( ))`, `(( ))`, `let`, and array indexes;
+- the special parameters that always expand to one word without glob characters (`$#`, `$?`,
+  `$$`, `$!`, `$-`), and length expansions such as `${#name}`;
+- under `dialect: "bash"` and `dialect: "bats"`, the Bash variables that always hold an integer:
+  `$RANDOM`, `$SECONDS`, `$LINENO`, `$PPID`, `$OPTIND`, and `$BASH_SUBSHELL`;
+- here-document delimiters and bodies;
+- expansions already inside double quotes, and an expansion nested inside another parameter
+  expansion (`${a:-$b}` is judged as the outer expansion).
+
+`"$@"` is clean. Unquoted `$@`, `$*`, and `${arr[@]}` report. An indirect expansion such as
+`${!#}` (the last positional parameter) reports, because its value is arbitrary text.
+
+The Bash integer variables are exempt only as a bare reference (`$RANDOM`, `${RANDOM}`); an
+operator that substitutes other text (`${RANDOM/1/ }`) reports. Bash keeps each of them an integer
+however a script assigns it or the environment supplies it, and each exists in every Bash from 3.2.
+A digit in `IFS` splits these values, the same as `$?` and `$#`. They still report under
+`dialect: "posix"`, where a shell such as dash treats them as ordinary variables. `$BASHPID`,
+`$EPOCHSECONDS`, and `$SRANDOM` are not exempt: a Bash older than 4.0, 5.0, or 5.1 leaves them
+unset, and an unset unquoted variable expands to no word at all. A script that unsets one of these
+variables, or declares it `local`, removes its integer behavior; the rule does not detect that.
+`$UID` and `$EUID` are not exempt either: Bash imports them verbatim from the environment, so
+`env UID='a *' bash -c 'echo "[$UID]"'` prints `[a *]`, and an unquoted reference can split and
+glob.
+
+The rule decides from where the expansion is written, not from what it holds at run time. It does
+no dataflow analysis, so `n=3; seq $n` reports even though `$n` can never split.
+
+The positions are the same under every `languageOptions.dialect`, with one exception. Under
+`dialect: "zsh"`, the rule does not report parameter expansions, because zsh neither splits nor
+globs an unquoted parameter by default. It still reports command substitutions under zsh, because
+zsh does split those. The rule does not detect a zsh script that turns on `SH_WORD_SPLIT` or
+`GLOB_SUBST` (for example with `setopt sh_word_split`), so such a script gets no reports for its
+unquoted parameters.
+
+### Suggestion
+
+The message says the expansion undergoes field splitting and pathname expansion. Field splitting
+uses the characters in `IFS`, which are space, tab, and newline unless the script changes them.
+
+Each report offers one suggestion: wrap the reported expansion, and only that part of the word, in
+double quotes:
+
+<!-- transform: {"kind": "suggestion"} -->
+
+```sh
+cp x$a"y" dest
+# becomes
+cp x"$a""y" dest
+```
+
+The rule never autofixes, because a
+script can rely on splitting, for example `$CFLAGS` holding several compiler flags, and only its
+author knows. A backquoted substitution whose text contains `"` or `\` is reported without a
+suggestion: inside double quotes, `\` inside backquotes means something different, and POSIX
+leaves `"` inside them undefined. Rewrite it as `"$(…)"` by hand.
+
+## Options
+
+This rule has no options.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/quote-expansions': 'warn',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 9} -->
+```sh
+rm $file                  # an argument: splits on spaces and globs
+echo $(date)              # a command substitution argument
+$cmd --version            # the command word splits too
+[ $a = b ]                # `[` is a command; its operands are arguments
+for f in $files; do :; done   # a for list
+arr=($a)                  # an array literal element
+echo hi > $out            # a redirection target
+echo $@ $*                # unquoted $@ and $* split each argument again
+```
+
+### Correct
+
+```sh
+rm "$file"
+echo "$(date)"
+for f in "${files[@]}"; do :; done
+[[ $a == $b ]]            # [[ ]] does not split its operands
+x=$y                      # assignment values are not split
+case $x in $pat) ;; esac  # case words and patterns are not split
+echo $(( n + 1 )) $# $?   # arithmetic and single-word specials
+sleep $RANDOM             # a Bash integer variable (dialect: bash)
+cat <<EOF
+$x is not split inside a here-document body
+EOF
+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
+(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[@]}"`).
+
+## Relationship to shellcheck
+
+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
+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
+because it does no dataflow analysis. That is why `recommended` enables it at `warn` instead of
+`error`.

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

@@ -0,0 +1,171 @@
+# `sh/require-network-wrapper`
+
+Require network commands (`curl`, `wget`, `ssh`, `git fetch`, …) to be run through your project's
+configured wrapper, such as a retry or audit helper.
+
+| Configs | Fixable     | Languages |
+| ------- | ----------- | --------- |
+| `agent-authored` (inert until a wrapper is configured) | not fixable | `sh/sh` |
+
+## Rule details
+
+Network calls fail in ways local commands don't: timeouts, rate limits, flaky DNS. Many projects
+route every network call through one wrapper that retries, logs, or proxies it. This rule checks
+that every network command a script runs goes through that wrapper.
+
+**The wrapper has no default.** Which wrapper your project uses is your policy, and a generic
+linter must not invent it. With no wrapper configured, the rule is inert: it reports nothing.
+
+The rule checks every command in the file: top level, in functions, in pipelines, in
+conditionals, and inside command substitutions (`$(…)`). A network command is reported (message
+`unwrappedCommand`, on the whole command) unless the configured wrapper runs it. It is wrapped
+when the wrapper encloses it, directly (`retry curl x`) or through transparent wrappers such as
+`sudo`, `env`, or `nohup` (`retry sudo curl x`, `sudo retry curl x`). `sudo curl x` is not
+wrapped, and neither is the `curl` in `retry echo "$(curl x)"`: the command substitution is its
+own command. See [Wrapper rules](../wrapper-rules.md) for the full matching rules.
+
+A command run by path is matched by its basename, so `/usr/bin/curl x` and `./bin/curl x` report
+as `curl`. A wrapper run by path is the wrapper it names: `/usr/local/bin/retry curl x` is wrapped.
+
+`git` counts only for its network subcommands, `fetch`, `clone`, `pull`, and `push`. git's global
+options before the subcommand are skipped, so `git -C dir fetch` is reported as `git fetch`, and
+`git status` is not reported.
+
+Invocations that only act locally are not reported: `curl --version`, `curl --help`,
+`curl --help all`, `wget --version` and `wget --help`, and their short forms `-V` and `-h`
+(`curl -h all`). The argument list must be exactly that, so `curl --version https://example.com`
+still reports. `git clone` is not reported when its source is a literal local path (`./x`, `../x`,
+`/x`) or a `file://` URL, after any of git clone's own options (`git clone --depth 1 ./x`). Only
+the source decides: a dynamic destination (`git clone ./x "$dest"`) does not matter, but a dynamic
+source (`git clone "$src"`), a remote URL, and a clone option the rule does not know leave the
+clone reported. So do `--recurse-submodules`, `--recursive` and `--remote-submodules` (a local
+repository's `.gitmodules` can point at a remote URL, which those options fetch) and
+`--bundle-uri` (it fetches from its URL, `--bundle-uri=URL` or `--bundle-uri URL`, whatever the
+source is). `--no-recurse-submodules` and an attached or separate option value such as `-j4` or
+`-j 4` do not change that the source is local. Options are read wherever they appear before a literal `--`, so
+`git clone ./x --recurse-submodules` and `git clone ./x d --bundle-uri URL` report too, while
+`git clone ./x -- --recurse-submodules` (everything after `--` is an operand) does not. A rule pack binds
+the same kind of exemptions in [`createWrapperRule`](../wrapper-rules.md) with
+`localInvocations`; the factory itself names no command.
+
+A call to a function the file defines is not reported, even when the function is defined after the
+call, because it runs the function and not the network client. A real invocation inside the
+function (`command curl x`) is reported.
+
+The rule never guesses. A dynamic command word (`"$client" x`), an option your wrapper does not
+declare (`retry -n 3 curl x` when `retry` is configured as a plain name), and a dynamic git
+subcommand (`git "$op"`) leave the command unknown, and nothing is reported. Command strings run
+by another shell (`bash -c 'curl x'`) are not checked.
+
+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
+  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:
+  `{ names: ['retry'], argFlags: ['-n'] }` makes `retry -n 3 curl x` wrapped. Its fields are
+  `names` (required; any of them counts as the wrapper), `noArgFlags`, `argFlags`,
+  `stopsChainFlags`, `unresolvableFlags`, `positionalOperandsBeforeCommand`, and
+  `assignmentOperands`, as in `sh-ast/analyze`'s `WrapperSpec`.
+- `commands` (`string[]`, default `["curl", "wget", "nc", "ssh", "scp", "rsync", "git"]`): the
+  network commands. Setting it replaces the default list. `git` keeps its subcommand restriction
+  wherever it is listed.
+- `alsoTreatAsNetwork` (`string[]`, default `[]`): more commands to check, added to `commands` (or
+  to its default).
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/require-network-wrapper': ['error', { wrapper: 'retry', alsoTreatAsNetwork: ['aws'] }],
+  },
+}
+```
+
+### Declaring the wrapper once: `settings.sh.networkWrapper`
+
+`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:
+
+```js
+// eslint.config.js
+{
+  settings: { sh: { declarationConvention: commentPragma, networkWrapper: 'with-retry' } },
+  rules: { 'sh/require-network-wrapper': 'error' }, // or extend sh.configs['agent-authored']
+}
+```
+
+`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.
+
+## Examples
+
+### Incorrect
+
+With `{ wrapper: 'retry' }`:
+
+<!-- example: {"options": {"wrapper": "retry"}, "findings": 6} -->
+
+```sh
+curl -fsSL https://example.com/install.sh   # curl is not wrapped
+retry echo start; curl x                    # retry wraps echo, not curl
+sudo curl x                                 # sudo is not the configured wrapper
+git -C repo fetch                           # reported as `git fetch`
+/usr/bin/curl x                             # a path to curl is still curl
+body="$(wget -qO- https://example.com)"     # commands inside $(…) are checked
+```
+
+An in-file function does not hide the real call inside it:
+
+<!-- example: {"options": {"wrapper": "retry"}, "findings": 1} -->
+
+```sh
+curl() { command curl "$@"; }               # `command curl` runs the external curl
+```
+
+### Correct
+
+With `{ wrapper: 'retry' }`:
+
+<!-- example: {"options": {"wrapper": "retry"}} -->
+
+```sh
+retry curl -fsSL https://example.com/install.sh
+retry sudo rsync -a src/ host:dst/   # retry encloses sudo, which runs rsync
+/usr/local/bin/retry curl x          # a path to the wrapper is the wrapper
+git status                           # not a network subcommand
+body="$(retry wget -qO- https://example.com)"
+echo curl                            # an argument, not a command
+curl --version                       # prints a version, touches no network
+git clone ./vendor/lib copy          # a local source
+wget() { :; }; wget x                # a function the file defines, not the client
+```
+
+## When not to use it
+
+Leave the rule off if your project has no single wrapper for network calls, or if network
+resilience is handled outside your scripts (for example by a proxy or by the CI runner). For a
+policy about commands other than network clients, define your own rule with
+[`createWrapperRule`](../wrapper-rules.md) rather than overloading `alsoTreatAsNetwork`.
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+shellcheck has no equivalent. It checks how commands are written, not which wrapper a project
+requires around them, and has no way to configure a project-specific wrapper. This rule exists
+because that requirement is a project contract, not a shell gotcha.