@eslint-sh/eslint-plugin 0.4.0 → 0.6.0

package/docs/rules/require-shebang.md

@@ -0,0 +1,157 @@
+# `sh/require-shebang`
+
+Require line 1 of every shell file to be a shebang that runs a recognized shell.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `recommended`, `agent-authored` | autofix (missing shebang only) | `sh/sh` |
+
+## Rule details
+
+A script without a shebang runs under whichever shell happens to invoke it. A bash script
+started as `sh deploy.sh`, or by a tool that defaults to `/bin/sh`, then fails in confusing
+ways far from the real cause. A shebang makes the file's interpreter explicit.
+
+This rule reads line 1 of the file and reports two problems:
+
+- **`missingShebang`**: line 1 does not start with `#!`. A comment, a blank line, or
+  whitespace before `#!` all count as missing. An empty file is missing a shebang too.
+- **`unrecognizedInterpreter`**: line 1 is a shebang, but it does not run one of the
+  recognized shells: `bash`, `sh`, `dash`, `ksh`, `mksh`, `zsh` or `bats`. Each one is
+  accepted two ways:
+  - by absolute path: `#!/bin/bash`, `#!/usr/local/bin/bash`, with any arguments after it;
+  - through `env` named by absolute path: `#!/usr/bin/env bash`,
+    `#!/usr/bin/env -S bash -e`. The rule skips `env` options, their arguments and
+    `NAME=value` assignments to find the command `env` runs.
+
+  A relative interpreter such as `#!bash` or `#!env bash` is reported, because the kernel
+  resolves it against the caller's working directory, not `PATH`.
+
+A UTF-8 byte order mark before `#!` does not stop the shebang from counting.
+
+The rule does **not** check that the shebang agrees with `languageOptions.dialect`.
+`#!/bin/sh` in a file linted with `dialect: 'bash'` is accepted here. That mismatch belongs
+to [`sh/shebang-matches-dialect`](./shebang-matches-dialect.md), so one problem is never reported under two rule names.
+
+### Autofix
+
+For `missingShebang`, the fix inserts one line above line 1. The interpreter comes from
+`languageOptions.dialect`:
+
+| `dialect`          | Inserted with `style: 'env'` | Inserted with `style: 'absolute'` |
+| ------------------ | ---------------------------- | --------------------------------- |
+| `bash` (default)   | `#!/usr/bin/env bash`        | `#!/bin/bash`                     |
+| `posix`            | `#!/usr/bin/env sh`          | `#!/bin/sh`                       |
+| `mksh`             | `#!/usr/bin/env mksh`        | `#!/bin/mksh`                     |
+| `zsh`              | `#!/usr/bin/env zsh`         | `#!/bin/zsh`                      |
+| `bats`             | `#!/usr/bin/env bats`        | `#!/bin/bats`                     |
+
+The inserted line ends with the file's own line break (`\r\n` in a CRLF file). For an empty
+file the fix produces exactly the shebang line and a newline.
+
+`unrecognizedInterpreter` has no fix. The file names some other interpreter, and choosing a
+shell for it is a decision for a person.
+
+## Options
+
+This rule takes one options object:
+
+- `style` (`'env' | 'absolute'`, default `'env'`): how the autofix spells the shebang it
+  inserts. `'env'` writes `#!/usr/bin/env <shell>`, which finds the shell on `PATH`.
+  `'absolute'` writes `#!/bin/<shell>`. The option affects only the fix. Both spellings
+  are accepted when checking a file.
+
+Any other key, or any other `style` value, is a configuration error.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/require-shebang': ['error', { style: 'absolute' }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 1, "messageIds": ["missingShebang"]} -->
+```sh
+echo "hello"            # line 1 is a command: missingShebang
+```
+
+<!-- example: {"findings": 1, "messageIds": ["missingShebang"]} -->
+```sh
+# Deploys the site.     # line 1 is an ordinary comment: missingShebang
+echo "hello"
+```
+
+<!-- example: {"findings": 1, "messageIds": ["unrecognizedInterpreter"]} -->
+```sh
+#!/usr/bin/python3      # not a shell: unrecognizedInterpreter
+```
+
+<!-- example: {"findings": 1, "messageIds": ["unrecognizedInterpreter"]} -->
+```sh
+#!/usr/bin/env node     # env runs a non-shell: unrecognizedInterpreter
+```
+
+<!-- example: {"findings": 1, "messageIds": ["unrecognizedInterpreter"]} -->
+```sh
+#!bash                  # relative interpreter path: unrecognizedInterpreter
+```
+
+### Correct
+
+```sh
+#!/usr/bin/env bash
+echo "hello"
+```
+
+```sh
+#!/usr/local/bin/bash -euo pipefail
+echo "hello"
+```
+
+```sh
+#!/usr/bin/env -S bash -e
+echo "hello"
+```
+
+```sh
+#!/bin/sh
+# Accepted even under dialect: 'bash'; see shebang-matches-dialect.
+echo "hello"
+```
+
+## When not to use it
+
+Files that are only ever sourced (`. ./lib.sh`, `source lib.sh`) are never executed, so their
+shebang is never read. If your project keeps such libraries without a shebang, turn the rule
+off for them with `files` or `ignores` in your config:
+
+```js
+// eslint.config.js
+export default [
+  {
+    files: ['**/*.sh'],
+    ignores: ['lib/**/*.sh'],
+    rules: { 'sh/require-shebang': 'error' },
+  },
+];
+```
+
+The rule does not detect sourced libraries on its own.
+
+## 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'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.
+shellcheck's SC1008 ("This shebang was unrecognized") overlaps `unrecognizedInterpreter`.

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

@@ -0,0 +1,253 @@
+# `sh/require-strict-mode`
+
+Require a script to turn on its strict-mode shell options (`set -euo pipefail` by default, or
+`set -eu` for POSIX `sh`) within its first few statements.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `recommended`, `agent-authored`, `posix-portable` (with set -eu) | autofix | `sh/sh` |
+
+## Rule details
+
+A script without strict mode keeps going after things fail. A command that fails, a variable that
+was never set, or a failed stage in the middle of a pipeline does not stop the script, so one
+failed step turns into wrong output or a damaged state further down. This rule enforces the policy
+once, at the top of the file: by default `errexit` (`-e`), `nounset` (`-u`) and `pipefail` must be
+on within the first 5 statements. Under the `posix` dialect, the default leaves out `pipefail` (see
+[Dialects](#dialects)).
+
+The rule checks the **set of options turned on**, not the literal text. All of these satisfy the
+Bash default:
+
+```sh
+set -euo pipefail
+set -o errexit -o nounset -o pipefail
+set -e; set -u; set -o pipefail
+set -ue -o pipefail
+```
+
+How the rule reads the file:
+
+- **Statements, not lines.** The window counts top-level statements from the top of the file.
+  Comments and blank lines are not statements, and `set -e; set -u` on one line is two
+  statements.
+- **Order matters.** Statements in the window apply in order, and the rule checks which options
+  are on after the last one. A `set +e` (or `set +o errexit`) in the window turns `errexit` off
+  again, so the file is reported unless a later statement in the window turns it back on. A
+  `set +e` after the window is not checked. Turning `errexit` off around one command later in the
+  script is a common, deliberate pattern.
+- **Only plain top-level `set` commands count.** A `set` in a subshell, a pipeline, or a background
+  job (`set -e &`) runs in a child process and never changes the script's options. A `set` inside a
+  function, an `if`, a loop, a `{ …; }` group or an `&&`/`||` list does not count either, even
+  though the shell may apply it there. The rule reads only plain top-level statements, so put the
+  prologue on its own line.
+- **Arguments must be static.** The rule reads `set`'s arguments as the shell does: flag clusters
+  (`-eu`, `+e`), `-o name` / `+o name`, and an `o` inside a cluster (`-euo pipefail`) that takes the
+  next word as an option name. `--` and the first argument that is not a flag end the options. When
+  an argument's value is only known at run time (`set -e "$flags"`), the rule stops reading that
+  `set` command there. Options turned on before that argument still count.
+
+The report is placed at line 1, column 1 and lists the required options that are not on.
+
+**Autofix.** The fix inserts the prologue on its own line right after the shebang, or at line 1 when
+the file has no shebang:
+
+<!-- transform: {"kind": "fix"} -->
+
+```sh
+#!/bin/bash
+cd "$1"
+# becomes
+#!/bin/bash
+set -euo pipefail
+cd "$1"
+```
+
+It uses the file's own line ending, so a CRLF file stays CRLF. The fix is
+offered only when inserting the prologue would satisfy the rule. For example, `set -e` followed by
+`set +e` in the window is reported with no fix, because the `set +e` would turn `errexit` off
+again. Decide what that `set +e` is for, then edit the file by hand.
+
+### Dialects
+
+When `mode` is not configured, the required prologue depends on `languageOptions.dialect`:
+
+| `dialect`                                    | Default prologue    |
+| -------------------------------------------- | ------------------- |
+| `bash` (the default), `bats`, `mksh`, `zsh`  | `set -euo pipefail` |
+| `posix`                                      | `set -eu`           |
+
+`pipefail` became part of POSIX only in POSIX.1-2024, and older `dash` and BusyBox `ash` builds
+still reject `set -o pipefail`. An autofix that inserted it would break a working `#!/bin/sh` script
+on those shells, so under `posix` the default requires and inserts only `set -eu`. A `posix` file
+may still turn `pipefail` on; the rule just doesn't require it.
+
+A configured `mode` always wins, whatever the dialect. To require `pipefail` in POSIX scripts too,
+configure it (see below).
+
+The dialect comes from `languageOptions`, not from the shebang. A `#!/bin/sh` file linted under the
+default `bash` dialect gets the `set -euo pipefail` default. That mismatch is reported at the
+shebang by [`sh/shebang-matches-dialect`](./shebang-matches-dialect.md); set
+`languageOptions.dialect` to `posix` for such files so the `pipefail` note above does not apply.
+
+## Options
+
+This rule takes one options object:
+
+- `mode` (`string | string[]`, default `"set -euo pipefail"`, or `"set -eu"` under the `posix`
+  dialect): the required prologue.
+  - A **string** must be a `set` command that only turns options on, such as `"set -eu"` or
+    `"set -o errexit -o nounset"`. The options it turns on are what the rule requires, and the
+    string is the exact text the autofix inserts. A string that is not such a command (for example
+    `"set +e"` or `"echo hi"`) is a configuration error.
+  - A **list** names the required options by their long names (`errexit`, `nounset`, `pipefail`,
+    `noclobber`, …, any name `set -o` accepts). The autofix inserts a `set` command built from the
+    list. Options with a one-letter flag go into one cluster in list order. The first option with no
+    letter is attached to that cluster with `o`, and any others follow as `-o <name>`. So
+    `["errexit", "nounset", "pipefail"]` inserts `set -euo pipefail` and `["errexit", "nounset"]`
+    inserts `set -eu`.
+
+    <!-- transform: {"kind": "fix", "options": {"mode": ["errexit", "nounset", "pipefail"]}} -->
+
+    ```sh
+    echo hi
+    # becomes
+    set -euo pipefail
+    echo hi
+    ```
+
+    <!-- transform: {"kind": "fix", "options": {"mode": ["errexit", "nounset"]}} -->
+
+    ```sh
+    echo hi
+    # becomes
+    set -eu
+    echo hi
+    ```
+- `withinStatements` (integer ≥ 1, default `5`): how many top-level statements from the top of the
+  file the prologue may take to appear.
+- `allowShebangOnly` (`boolean`, default `false`): when `true`, options passed to the shell on the
+  shebang line count as turned on, so a shebang alone can satisfy the rule. Shebang options combine
+  with `set` statements in the window. Only spellings the operating system passes to the shell as
+  written are read:
+  - `#!/usr/bin/env -S bash -euo pipefail`: `env -S` splits the rest of the line into words, so
+    every word after the shell name is read.
+  - `#!/bin/bash -eu`: the kernel passes everything after the interpreter as **one** argument, so
+    exactly one flag word is read. `#!/bin/bash -e -u` arrives as the single argument `-e -u`,
+    which the shell rejects, so it counts as nothing.
+  - `#!/usr/bin/env bash -e` counts as nothing. Without `-S`, Linux passes `bash -e` to `env` as
+    one command name.
+
+  It is off by default because shebang options are ignored when the script is run as
+  `bash script.sh`, so a `set` line is the only prologue that applies however the script is
+  started.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/require-strict-mode': ['error', {
+      mode: 'set -euo pipefail',
+      withinStatements: 5,
+      allowShebangOnly: false,
+    }],
+  },
+}
+```
+
+For POSIX `sh` scripts that only run on shells with `pipefail` support, and should require it:
+
+```js
+// eslint.config.js
+{
+  files: ['**/*.sh'],
+  languageOptions: { dialect: 'posix' },
+  rules: {
+    'sh/require-strict-mode': ['error', { mode: ['errexit', 'nounset', 'pipefail'] }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 1, "messageIds": ["missingStrictMode"]} -->
+```sh
+#!/bin/bash
+# reported: no strict-mode options are turned on
+cd "$1"
+rm -rf build
+```
+
+<!-- example: {"findings": 1, "messageIds": ["missingStrictMode"]} -->
+```sh
+#!/bin/bash
+# reported: pipefail is not turned on
+set -eu
+```
+
+<!-- example: {"findings": 1, "messageIds": ["missingStrictMode"]} -->
+```sh
+#!/bin/bash
+# reported: the set +e in the window turns errexit off again (no autofix)
+set -euo pipefail
+set +e
+```
+
+<!-- example: {"findings": 1, "messageIds": ["missingStrictMode"]} -->
+```sh
+#!/bin/bash
+# reported: a set inside a function doesn't apply to the script's top level
+main() { set -euo pipefail; }
+main "$@"
+```
+
+### Correct
+
+```sh
+#!/bin/bash
+set -euo pipefail
+cd "$1"
+```
+
+```sh
+#!/bin/bash
+# the options may be spread over statements and spelled long-form
+set -e
+set -o nounset -o pipefail
+```
+
+```sh
+#!/bin/bash
+# errexit is off for one command and back on inside the window
+set -euo pipefail
+set +e
+grep -q pattern file
+set -e
+```
+
+<!-- example: {"dialect": "posix"} -->
+```sh
+#!/bin/sh
+# with languageOptions: { dialect: 'posix' } and no configured mode
+set -eu
+```
+
+## When not to use it
+
+Turn this rule off if your project does not hold the strict-mode policy. For example, you may have
+scripts that handle every error explicitly, or files that are sourced into another shell rather
+than run, where a `set -e` would change the caller's shell. For a few files that are meant to be
+lenient, disable it with a directive comment or a `files`-scoped config entry instead.
+
+## 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 that requires strict mode. It warns about the _consequences_ of not
+having it, case by case. For example, SC2164 flags a `cd` whose failure isn't handled, and SC2155
+flags a `local x=$(cmd)` that hides the command's exit status. This rule enforces the _policy_
+that prevents that whole class of problem, once, at the top of the file, which shellcheck's
+per-construct checks cannot express.

package/docs/rules/require-tty-guard.md

@@ -0,0 +1,128 @@
+# `sh/require-tty-guard`
+
+Require interactive commands such as `read` and `select` to be guarded by a `[ -t 0 ]` test, or to
+have their input supplied explicitly.
+
+| Configs          | Fixable                      | Languages |
+| ---------------- | ---------------------------- | --------- |
+| `agent-authored` | suggestions (wrap in a guard) | `sh/sh`   |
+
+## Rule details
+
+A prompt that waits on the terminal hangs forever when a script runs without one: in CI, from
+cron, or from an agent's tool call. In automation it also reads whatever happens to be on stdin.
+This rule reports `read` and `select` (and any command you add with `commands`) that are not
+guarded.
+
+The check is **purely syntactic**. The rule never follows data or control flow, so what it treats
+as guarded is exactly the following.
+
+A command is guarded by a test when it is:
+
+- lexically inside the `then` or `else` body of an `if` whose condition contains a TTY test, or
+- on the right of an `&&` whose left side contains a TTY test (`[ -t 0 ] && [ -n "$X" ] && read x`).
+
+A TTY test is `[ -t 0 ]`, `test -t 0` or `[[ -t 0 ]]`. Only file descriptor `0` counts, and the
+test may sit anywhere in the condition: `[ ! -t 0 ]` is also recognized as a TTY test, because
+the rule does not interpret negation.
+
+A command has its input supplied explicitly, and is not reported, when:
+
+- it, or any statement that encloses it, redirects fd 0 from a file, here-document or
+  here-string (`read x < file`, `read x <<< "$v"`, `while read l; do …; done < file`), or from
+  another descriptor (`read x <&3`);
+- it is on the right of a pipe (`echo a | read x`, `cat f | while read l; do …; done`);
+- it is inside a `coproc`, which reads its own input pipe;
+- it is `read -u N` for a descriptor other than `0` (`read -u 3 x`, `read -ru3 x`). A descriptor
+  that is not a static value is also treated as not stdin.
+
+A `read` with `-p` is still reported: the prompt does not make it safe without a terminal.
+
+### Limits
+
+The rule is honest about what it cannot see:
+
+- **A guard in a calling function is not seen.** If `ask() { read x; }` is only ever called as
+  `[ -t 0 ] && ask`, the `read` is still reported.
+- **Early exits are not seen.** `[ -t 0 ] || exit 1` followed by `read x` does not guard the
+  `read`; neither does a guard in an earlier statement, a `||` list, or a `while` condition.
+- **Negation is not interpreted.** `if [ ! -t 0 ]; then read x; fi` counts as guarded.
+- **Variables are not tracked.** `is_tty=$([ -t 0 ] && echo 1)` is not a guard.
+- **Command names are read as written.** A command reached through a wrapper (`command read x`)
+  or with a dynamic name is not matched.
+
+## Options
+
+- `commands` (`string[]`, default `['read', 'select']`): the interactive commands to check. A
+  configured list **replaces** the default, as with `sh/require-network-wrapper`; include `read`
+  and `select` to keep them. `select` is parsed as a loop, not a command, and is checked whenever
+  the list contains `select`.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/require-tty-guard': ['error', { commands: ['read', 'select', 'confirm'] }],
+  },
+}
+```
+
+## Suggestion
+
+The rule offers one suggestion per report: wrap the statement in `if [ -t 0 ]; then … fi`:
+
+<!-- transform: {"kind": "suggestion"} -->
+
+```sh
+read name
+# becomes
+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 &`)
+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
+changes which way the construct goes. The suggestion is
+never applied by `--fix`; whether the script should skip the prompt or fail when there is no
+terminal is your decision.
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"findings": 4, "messageIds": ["unguardedInteractive", "unguardedInteractive", "unguardedInteractive", "unguardedInteractive"]} -->
+```sh
+read name                      # waits on stdin with no terminal check
+read -p "Name: " name          # a prompt does not make it safe
+select opt in a b; do :; done  # select reads the terminal too
+[ -t 0 ] || read x             # `||` is not a guard
+```
+
+### Correct
+
+```sh
+if [ -t 0 ]; then read name; fi
+[ -t 0 ] && read -p "Name: " name
+read name < answers.txt
+read name <<< "$default"
+cat answers.txt | while read -r line; do :; done
+read -u 3 name                 # from descriptor 3, not stdin
+```
+
+## When not to use it
+
+Turn the rule off for scripts that are interactive by definition and never run unattended, such
+as a local setup wizard.
+
+## 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 check: it does not report a `read` that can run without a terminal.
+Its `read` diagnostics (for example SC2162, `read` without `-r`) concern how input is parsed, not
+where it comes from.

package/docs/rules/shebang-matches-dialect.md

@@ -0,0 +1,120 @@
+# `sh/shebang-matches-dialect`
+
+Require the shebang to name the same kind of shell, bash or POSIX, as `languageOptions.dialect`.
+
+| Configs                         | Fixable     | Languages |
+| ------------------------------- | ----------- | --------- |
+| `recommended`, `agent-authored`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Dialect-sensitive rules read `languageOptions.dialect` from your config, not the file. When the
+two disagree they advise for the wrong shell. A `#!/bin/sh` script linted under the default
+`bash` dialect is told, by [`sh/require-strict-mode`](./require-strict-mode.md), to turn on
+`pipefail`, which dash and older BusyBox `ash` reject. This rule reports the disagreement once,
+at the shebang (line 1, in full), so the fix is one config entry or one line.
+
+It reports two cases:
+
+- **`posixShebangBashDialect`**: the shebang runs a POSIX shell (`sh`, `dash` or `ash`) but the
+  dialect is `bash` (the default).
+- **`bashShebangPosixDialect`**: the shebang runs `bash` but the dialect is `posix`.
+
+The shell is found the way [`sh/require-shebang`](./require-shebang.md) finds it: an absolute
+interpreter path (`#!/bin/sh`, `#!/usr/local/bin/bash`), or an absolute-path `env` and the command
+it runs (`#!/usr/bin/env sh`, `#!/usr/bin/env -S bash -e`). A relative interpreter such as
+`#!sh` is not read; `sh/require-shebang` reports it.
+
+Nothing else is reported. A file with no shebang is clean here (that is `sh/require-shebang`'s
+concern), as is a shebang that names another interpreter, and any file whose dialect is `mksh`,
+`zsh` or `bats`. A shebang and dialect that already agree are clean: `#!/usr/bin/env bash` under
+`bash`, `#!/bin/sh` under `posix`.
+
+The message tells you to set the dialect for these files, or to change the shebang. To set it,
+scope `languageOptions.dialect` to the files that use that shell:
+
+```js
+// eslint.config.js
+export default [
+  {
+    files: ['scripts/posix/**/*.sh'],
+    languageOptions: { dialect: 'posix' },
+  },
+];
+```
+
+## Options
+
+This rule has no options.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/shebang-matches-dialect': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+<!-- example: {"dialect": "bash", "messageIds": ["posixShebangBashDialect"], "findings": 1} -->
+```sh
+#!/bin/sh
+# dialect: 'bash' (the default): posixShebangBashDialect
+echo "hello"
+```
+
+<!-- example: {"dialect": "bash", "messageIds": ["posixShebangBashDialect"], "findings": 1} -->
+```sh
+#!/usr/bin/env dash
+# dialect: 'bash': posixShebangBashDialect
+echo "hello"
+```
+
+<!-- example: {"dialect": "posix", "messageIds": ["bashShebangPosixDialect"], "findings": 1} -->
+```sh
+#!/usr/bin/env bash
+# dialect: 'posix': bashShebangPosixDialect
+echo "hello"
+```
+
+### Correct
+
+<!-- example: {"dialect": "bash"} -->
+```sh
+#!/usr/bin/env bash
+# dialect: 'bash'
+echo "hello"
+```
+
+<!-- example: {"dialect": "posix"} -->
+```sh
+#!/bin/sh
+# dialect: 'posix'
+echo "hello"
+```
+
+```sh
+echo "no shebang: sh/require-shebang's concern, not this rule's"
+```
+
+## When not to use it
+
+Turn it off if your project deliberately lints POSIX-shebang scripts as bash, for example
+because every `sh` on your targets is bash. Also turn it off for files you only source, whose
+shebang is never read.
+
+## 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 chooses its dialect from the shebang (or a `shell=` directive) and then checks the file
+against it, so it has no notion of a mismatch between the shebang and a separately configured
+dialect. Its SC3xxx checks report bash-only features in a `#!/bin/sh` script, which is
+a different question: that the syntax is wrong for the shebang, not that your lint configuration
+disagrees with it. This rule keeps eslint-sh's own dialect-sensitive rules honest about the
+shell they are advising for.

package/docs/selectors.md

@@ -5,8 +5,8 @@
 classes** against shell ASTs, in addition to matching bare node type names
 (`CallExpr`, `IfClause`, ...). Selector-first rule authoring — writing a rule as a selector string
 rather than a `create()` full of manual type checks — is a headline feature of this plugin; this
-page is a copy-paste cookbook of real selectors, each backed by a passing test (see
-`test/selectors-cookbook.test.ts`) so the examples can't silently rot as the plugin evolves.
+page is a copy-paste cookbook of real selectors, each backed by a passing test in this package's
+test suite so the examples can't silently rot as the plugin evolves.
 
 Looking for a complete, runnable `create()` that uses one of these selectors — the full
 `{ meta, create(context) }` rule module, `context.report`, and the `eslint.config.mjs`