@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/reading-nodes.md

@@ -0,0 +1,159 @@
+# Reading nodes
+
+A rule's listeners receive **lint-view nodes**: the plugin's own projection of the parsed script,
+typed so you can read a node's fields without a cast or a hand-written guard. This page is the
+field reference and one worked rule.
+
+## The shape of a node
+
+Every node has:
+
+- `type` — the syntax kind (`'Stmt'`, `'CallExpr'`, `'Word'`, `'Lit'`, …). It is the discriminator.
+- `range` — a half-open `[start, end]` span of UTF-16 offsets into the source text.
+- `loc` — the same span as ESLint `{ start: { line, column }, end: { line, column } }`, both
+  one-based.
+
+A listener keyed by a node type, with or without `:exit`, receives exactly that node type, so its
+fields are typed with nothing to check first:
+
+```ts
+CallExpr(node) {
+  node.args; // readonly Word nodes
+  node.assigns; // readonly Assign nodes
+}
+```
+
+Any other selector (`*`, `CallExpr[args.0.parts.0.value='jq']`, `:command`, `Stmt > CallExpr`)
+can match nodes of more than one type, so its listener receives `ShellNode`, the union of every
+node type. **Narrow it on `type`** and the node's own fields appear, typed:
+
+```ts
+':command'(node) {
+  if (node.type !== 'CallExpr') return;
+  node.args;
+}
+```
+
+`ShellNodeOf<'Stmt'>` names one node type (for a helper's parameter), and `ShellNodeType` is the
+union of every `type` value. Field access that does not exist is a compile error, so a typo or a
+field from another node type is caught by the compiler.
+
+## Where the fields come from
+
+The nodes mirror [mvdan/sh](https://github.com/mvdan/sh)'s syntax tree, as `sh-ast` exposes it.
+An upstream field `Cmd` on `Stmt` is `stmt.cmd` on the node: **the same name, lowercased**. The
+rules that turn an upstream record into a lint-view node are fixed:
+
+| Upstream field                | On the node                                                      |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `Type`                        | `type`, the discriminator                                        |
+| a child (`Stmt.Cmd`)          | the child node, or **absent** (`undefined`) when there is none   |
+| a slice (`CallExpr.Args`)     | a read-only array of nodes; **always present**, empty when none  |
+| a string (`Lit.Value`)        | a JavaScript `string` (decoded from Go bytes)                    |
+| a boolean (`Stmt.Background`) | a `boolean`                                                      |
+| an operator (`BinaryCmd.Op`)  | a number; compare with the constants from `…/syntax` (`AndStmt`) |
+| a position (`Stmt.Semicolon`) | none: use `range` and `loc`                                      |
+
+A child that may be absent is an **optional** property, so the compiler makes you check it before
+use (`stmt.cmd?.type`). A slice is never absent and never holds a missing entry, so
+`call.args.length` and `for (const word of call.args)` need no check.
+
+To find a field, hover the narrowed node in your editor, or read the `sh-ast` record of the same
+name: its field list is the node's field list, minus positions, lowercased.
+
+## What the view adapts
+
+The types describe the view as it is, not the raw parse:
+
+- `range` and `loc` are in UTF-16 units of the file's text, not the parser's byte offsets.
+- A CRLF file reads like its LF twin. The parser treats only `\n` as a line break, so it keeps the
+  `\r` before it as part of whatever ends the line. The view ends such a node **before** the `\r`,
+  and a text field of that node (`Lit.value`) loses that one trailing `\r`. A quoted string or
+  here-document that continues past the line break is left alone.
+- Some nodes have no source extent of their own (`Expansion`, `Replace`, `Slice` are parts of a
+  parameter expansion). Their range covers their children.
+
+For anything the view leaves out (token positions, the exact bytes of a non-UTF-8 string), reach
+the parser's own record with `context.sourceCode.getSyntax(node)`; see the [custom-rule
+tutorial](./custom-rule-tutorial.md).
+
+## `range` goes straight into `fixer`
+
+`range` has the type ESLint's fixer methods take, so `node.range` is accepted by
+`insertTextBeforeRange`, `insertTextAfterRange`, `removeRange` and `replaceTextRange` as is.
+Treat it as read-only.
+
+## Example: quote the variables `rm` receives
+
+`docs/examples/no-unquoted-rm-variable-rule.ts`:
+
+```ts
+/**
+ * The TypeScript example rule from "Reading nodes" (`../reading-nodes.md`).
+ * This package's test suite asserts the page's code fence matches this
+ * file byte-for-byte, type-checks it against the package's published
+ * declarations, and runs it, with its fix, through a real `eslint` `Linter`.
+ *
+ * It reports an `rm` argument that is a lone, unquoted variable (`rm -rf $dir`)
+ * and quotes it. Every field it reads is typed by `ShellNode`: narrowing on
+ * `type` is the only thing between a listener's node and its fields.
+ *
+ * @see ../reading-nodes.md — the page this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noUnquotedRmVariable = defineShellRule({
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    docs: { description: 'require the variable operands of `rm` to be quoted' },
+    schema: [],
+    messages: {
+      unquoted: 'Quote `${{name}}`: unquoted, it is split and globbed before `rm` runs.',
+    },
+  },
+  create(context) {
+    return {
+      CallExpr(node) {
+        // A listener keyed by a node type receives that node type: `args`, `assigns`, … are typed.
+        if (context.sourceCode.getCommandName(node) !== 'rm') return;
+
+        // `args` is always an array of `Word`s (the command word first), never null.
+        for (const word of node.args.slice(1)) {
+          // A `Word` is a list of parts; a lone `$name` is a single `ParamExp` part.
+          const [part] = word.parts;
+          if (word.parts.length !== 1 || part.type !== 'ParamExp') continue;
+
+          context.report({
+            node: word,
+            messageId: 'unquoted',
+            // `param` is optional: a `ParamExp` with no name (rare) has no `param` child.
+            data: { name: part.param?.value ?? '' },
+            // `word.range` is the tuple ESLint's fixer methods take, so it needs no cast.
+            fix: (fixer) => [
+              fixer.insertTextBeforeRange(word.range, '"'),
+              fixer.insertTextAfterRange(word.range, '"'),
+            ],
+          });
+        }
+      },
+    };
+  },
+});
+
+export default noUnquotedRmVariable;
+```
+
+Enable it like any rule in step 3 of the [tutorial](./custom-rule-tutorial.md#3-wire-it-into-a-flat-config).
+For `rm -rf $dir "$kept" ${base}/x` it reports only `$dir`: `"$kept"` is a `DblQuoted` part, and
+`${base}/x` has two parts. Its fix produces `rm -rf "$dir" "$kept" ${base}/x`.
+
+What the rule reads, in order: the `CallExpr` key gives the listener a `CallExpr` node, so
+`node.args` is its `Word`s; `word.parts` is a `Word`'s pieces, which `part.type` narrows again
+(`'ParamExp'`); `part.param` is optional, so it is read with `?.`.
+
+## Staying current with mvdan/sh
+
+The node types are computed from `sh-ast`'s generated typings; nothing in this package restates a
+field list. When the pinned `sh-ast` moves to a new mvdan/sh, the types follow it, and a rule that
+reads a field the new version removed stops compiling instead of reading `undefined` at run time.

package/docs/rules/README.md

@@ -0,0 +1,79 @@
+# Built-in rules
+
+eslint-sh enforces shell script conventions and contracts. Run shellcheck alongside it for
+general shell correctness checks. Start with `sh.configs.recommended`; use
+`sh.configs['agent-authored']` for machine-written scripts that people review, and
+`sh.configs['bash-3.2']` or `sh.configs['posix-portable']` for a Bash 3.2 or POSIX `sh`
+deployment target. Every preset includes the shell language and plugin registration; extend them
+under your own `files` globs. See [running eslint-sh beside shellcheck](../shellcheck.md).
+See the [canonical quickstart](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md).
+
+| Rule | Configs | Autofix | Suggestions | Purpose |
+| ---- | ------- | ------- | ----------- | ------- |
+| [`sh/compat/no-append-all-redirect`](./compat/no-append-all-redirect.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow the `&>>` redirection when the target shell lacks it, suggesting `>> file 2>&1`. |
+| [`sh/compat/no-associative-arrays`](./compat/no-associative-arrays.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `declare -A` / `typeset -A` when the target shell lacks associative arrays. |
+| [`sh/compat/no-brace-sequence-padding-step`](./compat/no-brace-sequence-padding-step.md) | `bash-3.2`, `posix-portable` | No | No | Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`) brace sequences when the target shell lacks them, pointing at a counting loop. |
+| [`sh/compat/no-case-attributes`](./compat/no-case-attributes.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `declare -l` / `declare -u` (and `typeset`, `local`) when the target shell lacks them, pointing at `tr`. |
+| [`sh/compat/no-case-fallthrough`](./compat/no-case-fallthrough.md) | `bash-3.2`, `posix-portable` | No | No | Disallow the `case` terminators `;&` and `;;&` when the target shell lacks them. |
+| [`sh/compat/no-case-modification`](./compat/no-case-modification.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `${v^^}`, `${v,,}` and variants when the target shell lacks them, pointing at `tr`. |
+| [`sh/compat/no-coproc`](./compat/no-coproc.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `coproc` when the target shell lacks it. |
+| [`sh/compat/no-declare-g`](./compat/no-declare-g.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `declare -g` / `typeset -g` when the target shell lacks the option. |
+| [`sh/compat/no-double-bracket`](./compat/no-double-bracket.md) | `posix-portable` | No | No | Disallow `[[ … ]]` when the target shell is POSIX sh, pointing at `[` and `case`. |
+| [`sh/compat/no-epoch-variables`](./compat/no-epoch-variables.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `$EPOCHSECONDS` / `$EPOCHREALTIME` when the target shell lacks them. |
+| [`sh/compat/no-fd-variable`](./compat/no-fd-variable.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `{varname}` descriptor redirections (`exec {fd}>file`) when the target shell lacks them. |
+| [`sh/compat/no-globstar`](./compat/no-globstar.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `shopt -s globstar` when the target shell lacks the option, pointing at `find`. |
+| [`sh/compat/no-lastpipe-semantics`](./compat/no-lastpipe-semantics.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `shopt -s lastpipe` when the target shell lacks the option. |
+| [`sh/compat/no-let`](./compat/no-let.md) | `posix-portable` | No | No | Disallow `let` when the target shell is POSIX sh, pointing at arithmetic expansion. |
+| [`sh/compat/no-mapfile`](./compat/no-mapfile.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow `mapfile` / `readarray` when the target shell lacks them, suggesting a read loop. |
+| [`sh/compat/no-nameref`](./compat/no-nameref.md) | `bash-3.2`, `posix-portable` | No | No | Disallow namerefs (`declare -n`, `local -n`) when the target shell lacks them. |
+| [`sh/compat/no-negative-array-index`](./compat/no-negative-array-index.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow negative array subscripts when the target shell lacks them, suggesting a length-based index. |
+| [`sh/compat/no-nounset-empty-array`](./compat/no-nounset-empty-array.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow whole-array expansions under `set -u` when the target shell aborts on an empty array, suggesting a guarded form. |
+| [`sh/compat/no-parameter-transformation`](./compat/no-parameter-transformation.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `${v@op}` transformations when the target shell lacks the operator. |
+| [`sh/compat/no-pipe-all`](./compat/no-pipe-all.md) | `bash-3.2`, `posix-portable` | No | Yes | Disallow the stderr-merging pipe (pipe-ampersand) when the target shell lacks it, suggesting an explicit `2>&1` before the pipe. |
+| [`sh/compat/no-printf-time-format`](./compat/no-printf-time-format.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `printf`'s `%(fmt)T` date format when the target shell lacks it. |
+| [`sh/compat/no-source`](./compat/no-source.md) | `posix-portable` | No | Yes | Disallow `source` when the target shell is POSIX sh, suggesting `.`. |
+| [`sh/compat/no-test-v`](./compat/no-test-v.md) | `bash-3.2`, `posix-portable` | No | No | Disallow the `-v name` test (`[[ -v x ]]`, `test -v x`) when the target shell lacks it. |
+| [`sh/compat/no-unicode-escape`](./compat/no-unicode-escape.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `\u` / `\U` escapes in `$'…'` when the target shell does not decode them to UTF-8. |
+| [`sh/compat/no-wait-n`](./compat/no-wait-n.md) | `bash-3.2`, `posix-portable` | No | No | Disallow `wait -n` when the target shell lacks it. |
+| [`sh/max-script-complexity`](./max-script-complexity.md) | `agent-authored` | No | No | Cap a script's function count, nesting depth and statement count. |
+| [`sh/no-dynamic-invocation`](./no-dynamic-invocation.md) | `agent-authored` | No | No | Require each executed command to be statically identifiable, including through wrappers. |
+| [`sh/no-eval`](./no-eval.md) | `recommended`, `agent-authored` | No | No | Disallow `eval` and sourcing a path that is not a static literal. |
+| [`sh/no-masked-exit-status`](./no-masked-exit-status.md) | `agent-authored` | No | Yes | Disallow `local`, `declare`, `typeset`, `export` and `readonly` with a value taken from a command substitution, which hides the command's exit status. |
+| [`sh/no-secret-env-reads`](./no-secret-env-reads.md) | `agent-authored` | No | No | Flag reads of secret-shaped environment variables outside allowed sinks. |
+| [`sh/no-secret-flags`](./no-secret-flags.md) | `recommended`, `agent-authored` | No | No | Flag literal secrets passed through command-line flags. |
+| [`sh/no-unchecked-cd`](./no-unchecked-cd.md) | `recommended`, `agent-authored` | No | Yes | Require the failure of `cd`, `pushd` and `popd` to be checked. |
+| [`sh/no-undeclared-commands`](./no-undeclared-commands.md) | `agent-authored` | No | No | Require external command usage to be declared through your convention. |
+| [`sh/no-unused-declarations`](./no-unused-declarations.md) | `agent-authored` | Yes (when the convention provides an edit hook) | No | Remove command declarations that a fully understood script does not use. |
+| [`sh/prefer-local`](./prefer-local.md) | `agent-authored` | Yes (declaration inserted at the top of the function body) | No | Require variables assigned in a function to be declared `local`. |
+| [`sh/quote-expansions`](./quote-expansions.md) | `recommended`, `agent-authored` | No | Yes | Require double quotes around expansions in words the shell splits and globs. |
+| [`sh/require-network-wrapper`](./require-network-wrapper.md) | `agent-authored` | No | No | Require network commands to run through your configured wrapper. |
+| [`sh/require-shebang`](./require-shebang.md) | `recommended`, `agent-authored` | Yes (missing shebang only) | No | Require a recognized shell interpreter on line 1. |
+| [`sh/require-strict-mode`](./require-strict-mode.md) | `recommended`, `agent-authored`, `posix-portable` (with set -eu) | Yes (when insertion satisfies the rule) | No | Require strict-mode options near the start of the script. |
+| [`sh/require-tty-guard`](./require-tty-guard.md) | `agent-authored` | No | Yes | Require `read`, `select` and configured interactive commands to be guarded by a TTY test or supplied input. |
+| [`sh/shebang-matches-dialect`](./shebang-matches-dialect.md) | `recommended`, `agent-authored`, `posix-portable` | No | No | Require the shebang to name the same kind of shell (bash or POSIX) as `languageOptions.dialect`. |
+
+`recommended` enables `no-secret-flags` and `quote-expansions` at `warn` and its other rules at
+`error`. `agent-authored` enables every rule above except the gated `compat/*` rules, all at `error`. `compat/no-append-all-redirect`, `compat/no-mapfile`,
+`compat/no-negative-array-index`, `compat/no-nounset-empty-array`, `compat/no-pipe-all`, `compat/no-source`, `no-masked-exit-status`, `no-unchecked-cd`, `quote-expansions` and `require-tty-guard`
+offer editor suggestions, which you apply one at a time from your editor; the Autofix column
+describes edits available through `eslint --fix`. `quote-expansions` suggests quoting instead of
+fixing because only the script's author knows whether the splitting was intended.
+
+The version-gated `compat/*` rules (`compat/no-append-all-redirect`, `compat/no-associative-arrays`, `compat/no-brace-sequence-padding-step`, `compat/no-case-attributes`, `compat/no-case-fallthrough`, `compat/no-case-modification`, `compat/no-coproc`, `compat/no-declare-g`, `compat/no-epoch-variables`, `compat/no-fd-variable`, `compat/no-globstar`, `compat/no-lastpipe-semantics`, `compat/no-mapfile`, `compat/no-nameref`, `compat/no-negative-array-index`, `compat/no-nounset-empty-array`, `compat/no-parameter-transformation`, `compat/no-pipe-all`, `compat/no-printf-time-format`, `compat/no-test-v`, `compat/no-unicode-escape`, `compat/no-wait-n`) report
+shell features that your target shell lacks, as set by `languageOptions.shellVersion` and
+`dialect`. They report nothing when `shellVersion` is unset, so the `bash-3.2` preset sets it to `3.2`
+and the `posix-portable` preset sets `dialect: "posix"`; each enables all of them.
+See [version compatibility](../compat.md). `compat/*` means target gates only; `shebang-matches-dialect`
+compares the file with your config whatever the target, so it lives outside that namespace. `posix-portable` also enables
+`shebang-matches-dialect`, `require-strict-mode` (as `set -eu`) and the POSIX-only gates
+`compat/no-double-bracket`, `compat/no-let` and `compat/no-source`, which report those constructs
+under `dialect: "posix"` because they fail on dash. It does not report `local`, `echo -e` or the
+other constructs listed under
+[what `posix-portable` does not report](../compat.md#what-posix-portable-does-not-report).
+To run these rules beside shellcheck, see [shellcheck](../shellcheck.md).
+
+`no-undeclared-commands` and `no-unused-declarations` report nothing until you bind
+`settings.sh.declarationConvention` (see [declaration conventions](../declaration-conventions.md)).
+`require-network-wrapper` reports nothing until you set its `wrapper` option (see
+[wrapper rules](../wrapper-rules.md)). Each linked rule page documents its options, limitations,
+and relationship to shellcheck.

package/docs/rules/_template.md

@@ -0,0 +1,83 @@
+# `sh/<rule-name>`
+
+<!--
+  Template for a built-in rule's docs page. Copy it to `docs/rules/<rule-name>.md`
+  (the same name the rule is registered under in `src/rules/index.ts`), replace
+  every `<...>` placeholder, and delete these comments. The rule's `meta.docs.url`
+  already points at that path. A test fails if a registered rule has no page here,
+  or a page here has no registered rule; this template is the only exception.
+
+  Examples are executed. Every `sh` fence under `### Incorrect` must make this rule report
+  at least one finding, and every one under `### Correct` must report none, when linted with
+  only this rule enabled through the built plugin. A fence that needs options, a dialect or
+  a declaration convention says so in an HTML comment on the line above it. The comment is
+  the opening "angle bracket, bang, two hyphens", the word `example:`, a JSON object such as
+  `{"options": {"maxNesting": 2}, "dialect": "bash"}`, then the usual closing. See any
+  existing page, e.g. `max-script-complexity.md`, for the exact spelling.
+
+  Keys: `options` (the rule's options value), `dialect`, `shellVersion`, `convention`
+  (`"commentPragma"`) and `filename`. Under `### Incorrect` you may also state what the prose
+  claims exactly: `findings` (a count), `messageIds` (in report order), `output` (the source
+  after autofix) and `suggestionOutputs`. A typo in the annotation fails the test.
+
+  A before/after pair shown elsewhere on the page (a suggestion or autofix result) goes in a
+  fence with a `# becomes` line between the two, under a comment spelled like the one above
+  but with `transform:` and a `"kind"` of `"suggestion"` or `"fix"` (see `quote-expansions.md`).
+
+  The first table's `Configs` and `Fixable` cells are checked against the presets and the
+  rule's `meta`: start `Fixable` with `not fixable`, `suggestions` or `autofix`.
+-->
+
+<One sentence: what the rule reports, phrased as the policy it enforces.>
+
+| Configs          | Fixable                                | Languages |
+| ---------------- | -------------------------------------- | --------- |
+| <`recommended`…> | <autofix / suggestions / not fixable> | `sh/sh`   |
+
+## Rule details
+
+<Why this policy matters for shell scripts, and exactly what the rule reports. Say which
+node types or constructs it inspects and which it deliberately ignores. If the rule depends on
+`languageOptions` (`dialect`, `shellVersion`), say how.>
+
+## Options
+
+<Each option: name, type, default, and effect. If the rule has no options, say so:>
+
+This rule has no options.
+
+```js
+// eslint.config.js
+{
+  rules: {
+    'sh/<rule-name>': ['error', { /* <options> */ }],
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+```sh
+# <code this rule reports, with a comment on each reported line saying why>
+```
+
+### Correct
+
+```sh
+# <code this rule accepts, including the edge cases it intentionally allows>
+```
+
+## When not to use it
+
+<The situations where turning this rule off is the right call, for example a policy your
+project does not hold, or another tool already enforcing it.>
+
+## Relationship to shellcheck
+
+eslint-sh is a convention and contract linter: a policy layer, where shellcheck is the gotcha
+layer. Run shellcheck beside it.
+
+<Name any shellcheck check (`SCxxxx`) this rule overlaps, and why this rule exists anyway, or
+state that shellcheck has no equivalent and why it cannot express this policy.>

package/docs/rules/compat/no-append-all-redirect.md

@@ -0,0 +1,87 @@
+# `sh/compat/no-append-all-redirect`
+
+Disallow the `&>>` redirection, which appends both stdout and stderr to a file, in scripts whose
+target shell lacks it: Bash older than 4.0, including the Bash 3.2 that macOS ships as
+`/bin/bash`, and POSIX sh.
+
+| Configs | Fixable | Languages |
+| ------- | ------- | --------- |
+| `bash-3.2`, `posix-portable` | suggestions | `sh/sh`   |
+
+## Rule details
+
+`&>>` arrived in Bash 4.0 (Bash NEWS for 4.0). Bash 3.2 rejects it as a syntax error (``syntax error near unexpected token `>'``), so the whole script fails to run, however rarely the line runs.
+
+The rule reports a redirection whose operator is `&>>`; the report is on the whole redirection. The two-way `&>` (which Bash 3.2 has), `>>`, `2>>`, `>&` and `2>&1` are other operators and are not reported, and neither is any of them in quotes.
+
+The portable spelling is `>> file 2>&1`, which the Bash manual defines `&>>` to mean. The rule offers it as a suggestion: the operator becomes `>>` and ` 2>&1` follows the target word, so the redirection keeps its place among the command's other redirections (`&>> log 2>/dev/null` becomes `>> log 2>&1 2>/dev/null`, which still sends stderr to `/dev/null`).
+
+Under `dialect: "posix"` the parser itself rejects `&>>`, so a POSIX file that uses it fails to parse and this rule does not run on it.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+### Suggestion
+
+A suggestion rewrites the redirection:
+
+<!-- transform: {"kind": "suggestion", "dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+build &>> build.log
+# becomes
+build >> build.log 2>&1
+```
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-append-all-redirect': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 1} -->
+```sh
+build &>> build.log
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+build >> build.log 2>&1
+build &> build.log
+echo "use &>> on Bash 4"
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, `&>>` is fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## 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 0.11.0 reports nothing for `cmd &>> log` under either `-s sh` or `-s bash`. (`cmd &> log` is different: it reports SC3020 under `-s sh`.) So shellcheck gives no finding for `&>>` in a POSIX sh script or in a Bash 3.2 target. This rule exists for both.

package/docs/rules/compat/no-associative-arrays.md

@@ -0,0 +1,95 @@
+# `sh/compat/no-associative-arrays`
+
+Disallow associative arrays (`declare -A`, `typeset -A`) in scripts whose target shell lacks
+them: Bash older than 4.0, including the Bash 3.2 that macOS ships as `/bin/bash`, and POSIX sh.
+
+| Configs | Fixable     | Languages |
+| ------- | ----------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Associative arrays arrived in Bash 4.0. Bash 3.2 rejects `declare -A` as an invalid option, so
+the script fails where the array is declared. Worse, if the script keeps going, every later
+`${map[key]}` silently indexes an ordinary array by the arithmetic value of `key`, so lookups
+return the wrong values without an error.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
+- `dialect: "posix"`: reports at any `shellVersion`, because POSIX sh has no arrays.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+The rule reads the options of every `declare` and `typeset` command, up to the first operand,
+as the builtin itself does. Option processing stops at a variable name, at `--`, and at a word
+that is not static. An option word reports when it is a `-` cluster containing `A`, such as
+`-A`, `-gA`, or `-Ar`. The report is on that option word. Commands written through `builtin`
+or `command` are recognized too, and so is `declare` under `dialect: "posix"`, where it parses
+as an ordinary command.
+
+The rule deliberately ignores:
+
+- `local -A`, `readonly -A`, and `export -A`;
+- `declare -a` (indexed arrays exist in every Bash) and `declare +A`;
+- an `-A` after the first operand (`declare m -A`) or after `--`.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-associative-arrays': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 4} -->
+```sh
+declare -A ports            # associative arrays need Bash 4.0
+typeset -A ports            # the same declaration through typeset
+declare -gA ports=([web]=80) # `A` inside an option cluster
+builtin declare -A ports    # reached through the builtin wrapper
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+```sh
+# Keep the mapping as JSON and look keys up with jq.
+port=$(jq -r --arg k "$service" '.[$k]' ports.json)
+
+declare -a hosts            # indexed arrays exist in Bash 3.2
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "4.0"} -->
+```sh
+declare -A ports
+```
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## 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 0.11.0 reports the command, not the option: under `-s sh`, `declare -A` draws SC3044 (`declare` is undefined in POSIX sh), and `local -A` draws SC3043. Under `-s bash` it reports nothing. It has no way to target a Bash version, so it reports nothing for `declare -A` in a script that must run on Bash 3.2. This rule exists for that target.

package/docs/rules/compat/no-brace-sequence-padding-step.md

@@ -0,0 +1,90 @@
+# `sh/compat/no-brace-sequence-padding-step`
+
+Disallow zero-padded (`{01..10}`) and stepped (`{1..10..2}`, `{a..e..2}`) brace sequences in scripts
+whose target shell lacks them: Bash older than 4.0, including the Bash 3.2 that macOS ships as
+`/bin/bash`, and POSIX sh.
+
+| Configs                      | Fixable     | Languages |
+| ---------------------------- | ----------- | --------- |
+| `bash-3.2`, `posix-portable` | not fixable | `sh/sh`   |
+
+## Rule details
+
+Both forms arrived in Bash 4.0, and neither fails on Bash 3.2, which is what makes them easy to miss. On Bash 3.2.57, `echo {01..03} {1..9..4}` prints `1 2 3 {1..9..4}` and exits 0: the padding is dropped and the stepped sequence stays as a literal word. The script carries on with different words. POSIX does not specify brace expansion, so what a POSIX target does with these words depends on the shell: dash prints `{01..03} {1..9..4}`, macOS's `/bin/sh` prints `1 2 3` for `{01..03}`, and Bash 5.3 under `--posix` prints `01 02 03`. A plain `{1..3}` is as shell-dependent, but this rule reports only the two forms Bash 4.0 added.
+
+The parser keeps a brace sequence as literal text inside a word, so the rule reads the literal text of the words the shell brace-expands. It reports a `{…}` that holds nothing but a sequence:
+
+- two integer endpoints (an optional sign and digits) or two single ASCII letters, with an optional third `..` field that is an integer step. A step makes the sequence stepped, for numbers and letters alike, and the step may be `0` or negative.
+- integer endpoints are padded when either has more than one digit and starts with `0` after an optional `-`: `{01..10}`, `{1..03}`, `{-01..1}`, `{00..10}`. A lone `0` (`{0..3}`) and `{-0..2}` are not padded, and neither is a `+01` endpoint, which Bash 5.3 expands without padding, as Bash 3.2 does.
+
+Everything else is left alone, because it is the same on every Bash or is not a sequence at all: `{1..3}`, `{a..c}`, a descending `{3..1}`, a comma list (`{01,02}`, `{01..03,x}`), mixed endpoints (`{a..5..2}`), multi-character endpoints, a variable endpoint (`{01..$n}`, which the shell never expands), and a malformed one (`{01..}`, `{1..9..x}`, spaces inside). Quoting and escaping are honoured: `"{01..10}"`, `'{01..10}'`, `$'{01..10}'`, `\{01..10}` and `{01..10\}` are plain text.
+
+Only code the parser sees is read: a sequence inside a quoted string that is run later (`eval '...'`, `trap '...'`) is not seen. A sequence is read where the shell brace-expands: command words and arguments, `for` and `select` lists, the elements of an array literal without an index (`a=({01..03})`), and the operands of `declare`, `local`, `export` and `readonly` (also the value in `declare d={01..03}`). It is not read where the shell does no brace expansion: a plain assignment (`a={01..03}`), a `case` subject or pattern, the operands of `[[ ]]`, here-strings and here-documents, parameter-expansion words (`${v:-{01..03}}`), and a keyed array element (`a=([5]={01..03})`). A redirection target (`: > out{01..01}`) is read only when the sequence provably yields one word. With several words the target is an "ambiguous redirect" error on Bash 5.3 (and for a padded sequence on 3.2 too), so the script is broken on every Bash that has the feature and there is nothing to port. With one word the shells disagree silently: `out{01..01}` writes `out1` on Bash 3.2.57 and `out01` on 5.3.9, and `out{1..3..5}` writes a file literally named `out{1..3..5}` on 3.2.57 and `out1` on 5.3.9. A sequence is always static text, so its length is always known; a target that also holds another brace group (`out{01..01}{a,b}`) is not read, because the product cannot be counted here, so a redirect target with more than one brace group is skipped. The same selection applies under `dialect: "posix"`, although the system `dash` creates a literal file such as `out{01..02}` for any of them without an error: a several-word target is still a sequence that no Bash accepts. A here-string or here-document word is never read. A descriptor duplication whose whole target is a one-word sequence is read only where the shells differ (checked on 3.2.57 and 5.3.9). A padded non-negative number names the same descriptor on both (`>&{01..01}`, `2>&{02..02}`, `<&{00..00}`, and `>&{-00..-00}`, which is 0), so it is not reported. A negative number in a descriptor position (`2>&{-01..-01}`, `<&{-01..-01}`, `3>&{-01..-01}`) is an "ambiguous redirect" error on both, so it is not reported either. A stepped sequence still differs (`>&{1..3..5}`, `3>&{1..3..5}` and `<&{0..0..2}` are an error or a literal word on 3.2.57 and descriptor 1 or 0 on 5.3.9), and a bare `>&` with a negative number writes a file named `-1` on 3.2.57 and `-01` on 5.3.9, as does `&>{-01..-01}`, so those are reported. The report is on the whole word, once per word, for the first sequence in it.
+
+Numbers are bounded the way Bash 5.3 bounds them, because a word outside the bounds stays literal on every Bash and nothing differs: each endpoint and the distance between them must fit a signed 64-bit integer, and so must the step's magnitude (a step of `-9223372036854775808` is not a step). Leading zeros do not count towards the value, so `{1..00000000000000000003}` is a sequence. `{1..3..999999999999999999999}`, `{1..99999999999999999999}` and `{-1..9223372036854775807..9223372036854775807}` are not reported. These bounds were measured on Bash 5.3.9 and 3.2.57 only; the 4.x releases' bounds were not measured.
+
+The portable alternative is to count in a loop and format with `printf`, for example `i=1; while [ "$i" -le 3 ]; do printf '%02d\n' "$i"; i=$((i + 1)); done` for a padded sequence, or `i=1; while [ "$i" -le 9 ]; do echo "$i"; i=$((i + 4)); done` for a stepped one. Both run on Bash 3.2 and on dash.
+
+This is a version-compat rule. Whether it reports depends only on `languageOptions`, as
+described in [version compatibility](../../compat.md):
+
+- `shellVersion` unset: never reports. An unset version means the newest Bash.
+- `dialect: "bash"` (the default) or `"bats"`: reports when `shellVersion` is older than `4.0`.
+- `dialect: "posix"`: reports at any `shellVersion`, because POSIX does not specify brace expansion.
+- `dialect: "mksh"` or `"zsh"`: never reports.
+
+## Options
+
+This rule has no options. Set the target through `languageOptions`:
+
+```js
+// eslint.config.js
+{
+  languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+  rules: {
+    'sh/compat/no-brace-sequence-padding-step': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 3} -->
+
+```sh
+for n in {01..12}; do echo "report-$n"; done
+echo {1..9..4}
+cp backup{a..e..2}.tar /tmp
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+n=1
+while [ "$n" -le 12 ]; do printf 'report-%02d\n' "$n"; n=$((n + 1)); done
+echo {1..3} {a..c}
+echo '{01..12}'
+a={01..03}
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, both forms are fine.
+
+## When not to use it
+
+Turn the rule off when your scripts never run on Bash older than 4.0, or leave `shellVersion`
+unset, which makes the rule report nothing.
+
+## 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 0.11.0 reports SC3009 (brace expansion is undefined in POSIX sh) under `-s sh` for every brace expansion, a plain `{1..3}` and `{a,b}` included. Under `-s bash` it reports nothing for these sequences. It does not know which Bash release a script must run on, so it cannot report the padded and stepped forms for a Bash 3.2 target. This rule exists for that target.