@eslint-sh/eslint-plugin 0.5.0 → 0.6.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,78 @@
+# 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-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-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-case-attributes.md

@@ -0,0 +1,82 @@
+# `sh/compat/no-case-attributes`
+
+Disallow the case-converting attributes `declare -l` and `declare -u` (also through `typeset` and
+`local`) 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
+
+The `-l` and `-u` attributes arrived in Bash 4.0 (Bash NEWS for 4.0), with the case-modifying expansions that [`sh/compat/no-case-modification`](./no-case-modification.md) reports. Bash 3.2 rejects the option with `declare: -l: invalid option`, so the declaration fails and the variable is left unset.
+
+The rule reads the options of every `declare`, `typeset` and `local` command, up to the first operand, as the builtin does. An option word reports when it is a `-` cluster containing `l` or `u` (`-l`, `-u`, `-lx`); the report is on that word. A cluster with both (`-lu`) gets its own message: where the attributes exist, the two cancel out and leave the value as written (observed on Bash 4.0 and 5.3), so the fix is to drop both letters. `-u` of another command (`read -u 3`) and an option after the first operand or after `--` are not read.
+
+The portable alternative is to convert the value when it is assigned, with `tr`: `v=$(printf '%s' "$v" | tr '[:upper:]' '[:lower:]')` for `-l`, and `tr '[:lower:]' '[:upper:]'` for `-u`. An attribute converts every later assignment too, so convert at each assignment that needs 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: "posix"`: reports at any `shellVersion`, because POSIX sh has no `declare`.
+- `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-case-attributes': 'error',
+  },
+}
+```
+
+## Examples
+
+### Incorrect
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2", "findings": 2} -->
+
+```sh
+declare -l answer=$1
+f() {
+  local -u code=$2
+}
+```
+
+### Correct
+
+With `shellVersion: "3.2"`:
+
+<!-- example: {"dialect": "bash", "shellVersion": "3.2"} -->
+
+```sh
+answer=$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')
+f() {
+  local code
+  code=$(printf '%s' "$2" | tr '[:lower:]' '[:upper:]')
+}
+```
+
+With `shellVersion: "4.0"` or newer, or with no `shellVersion`, the attributes 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.
+
+Under `-s sh`, shellcheck 0.11.0 reports the command, not the option: `declare -l` and `declare -u` draw SC3044 (`declare` is undefined in POSIX sh), and `local -l` and `local -u` draw SC3043. Under `-s bash` it reports nothing for these options. It does not know which Bash release a script must run on, so it reports nothing for `declare -l` in a Bash 3.2 target. This rule exists for that target.