@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

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

@@ -0,0 +1,131 @@
+# `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 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
+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`

package/docs/shellcheck.md

@@ -0,0 +1,87 @@
+# Running eslint-sh beside shellcheck
+
+Run both. They answer different questions, and each is blind to what the other checks.
+
+- **shellcheck** is the general-correctness tool. It finds shell gotchas: quoting and
+  word-splitting mistakes, constructs that behave differently from how they read, and
+  portability problems for the shell named in the shebang. It works from a fixed catalog of
+  checks and has no plugin system, so it cannot learn your project's rules.
+- **eslint-sh** is the policy tool. It enforces conventions and contracts that shellcheck
+  treats as style or cannot express: a required strict-mode prologue, declared commands,
+  network wrappers, and the shell version or dialect you deploy to.
+
+eslint-sh does not aim to reproduce shellcheck's diagnostic catalog. If a check is only about
+whether a construct is a bug, shellcheck owns it.
+
+## Running both
+
+They are independent commands with independent exit codes. Run them side by side in CI and in
+your editor:
+
+```sh
+git ls-files -z '*.sh' '*.bash' 'bin/*' | xargs -0 sh -c '[ "$#" -eq 0 ] || exec shellcheck -- "$@"' sh
+npx eslint . --max-warnings 0
+```
+
+The first command checks every tracked shell script, including extensionless ones under `bin/`,
+and does nothing in a project with no such files. Adapt the pathspecs to where your scripts live.
+
+`eslint .` lints the files your config's `files` patterns select, including extensionless
+scripts when the config lists `bin/?*`. A CLI glob such as `'scripts/**/*.sh'` would skip them.
+For a complete GitHub Actions job, exit codes, a pre-commit hook and editor setup, see the
+[`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
+`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
+different shells.
+
+Silence each tool with its own directive: `# shellcheck disable=SC2086` for shellcheck and
+`# eslint-disable-next-line sh/quote-expansions -- reason` for eslint-sh. One does not
+silence the other.
+
+## Who owns what
+
+| Concern | Owner | Notes |
+| ------- | ----- | ----- |
+| Quoting and word splitting in general (SC2086, SC2068, …) | shellcheck | eslint-sh's [`quote-expansions`](./rules/quote-expansions.md) covers only the list contexts it documents, deliberately. |
+| Unreachable code, useless commands, misuse of `[` / `[[` / `test`, `$?` mistakes | shellcheck | Correctness gotchas with no policy dimension. |
+| Bugs caused by subshells, pipelines, and `read` without `-r` | shellcheck | Parsing and scoping behavior. |
+| `source` of a path shellcheck cannot follow (SC1090, SC1091) | shellcheck | Configure its `source-path`. eslint-sh only objects to a non-literal path as a policy. |
+| Bash-only syntax in a script whose shebang says `sh` (SC3xxx) | shellcheck | It judges the file against its own shebang. eslint-sh reports only the few constructs [`posix-portable`](./compat.md#presets) names, and leaves `local`, `echo -e` and [the rest](./compat.md#what-posix-portable-does-not-report) here. |
+| Bash-only features on a specific Bash version, such as the 3.2 macOS ships | eslint-sh | shellcheck cannot be pointed at a Bash version. See [version compatibility](./compat.md). |
+| Whether the shebang agrees with the dialect you lint for | eslint-sh | [`shebang-matches-dialect`](./rules/shebang-matches-dialect.md). |
+| A strict-mode prologue every script must start with | eslint-sh | shellcheck only warns about the consequences of lacking one. |
+| Which commands a script may run, and that each is declared | eslint-sh | [`no-dynamic-invocation`](./rules/no-dynamic-invocation.md), [`no-undeclared-commands`](./rules/no-undeclared-commands.md), [`no-unused-declarations`](./rules/no-unused-declarations.md). Needs your declaration convention. |
+| Network commands going through your wrapper | eslint-sh | [`require-network-wrapper`](./rules/require-network-wrapper.md). Needs your wrapper name. |
+| Secrets passed as flags or read from environment variables | eslint-sh | [`no-secret-flags`](./rules/no-secret-flags.md), [`no-secret-env-reads`](./rules/no-secret-env-reads.md). |
+| Size and structure caps on a script | eslint-sh | [`max-script-complexity`](./rules/max-script-complexity.md). |
+| Guarding interactive `read` with a TTY check | eslint-sh | [`require-tty-guard`](./rules/require-tty-guard.md). shellcheck's `read` checks concern how input is parsed. |
+
+## Deliberate overlaps
+
+Some eslint-sh rules report the same code as a shellcheck check. They exist anyway for the
+reason given, and each rule's page has a "Relationship to shellcheck" section. The shellcheck findings for the version-compat rules below were observed with shellcheck 0.11.0 under `-s sh` and `-s bash`.
+
+| 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/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-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. |