@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

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

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

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`.