@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/custom-rule-tutorial.md

@@ -5,25 +5,29 @@ one of those selectors to a complete, runnable ESLint rule: a `{ meta, create(co
 a `context.report` call with a message and location, and the exact flat-config (`eslint.config.mjs`)
 wiring — `plugins`, `rules`, `language` — needed to run it.
 
-Every code block on this page is the literal, shipped file it names — not a paraphrase — and both
-files are executed verbatim in CI (`test/custom-rule-tutorial.test.ts` imports
-[`examples/no-rm-rf-rule.mjs`](./examples/no-rm-rf-rule.mjs) and
-[`examples/eslint.config.mjs`](./examples/eslint.config.mjs) directly and runs them through a real
-`eslint` `Linter.verify()`): the rule fires on a fixture script and does not fire on a clean one,
-so this tutorial cannot silently drift from working code. Both example files ship with this
-package (`docs/examples/`), so you can copy them into your own project as-is. Both use the `.mjs`
-extension deliberately: they are ES modules (`import`/`export`), and a default `npm init -y`
-project is CommonJS, so a plain `.js` extension would make Node — and ESLint's own config
-loader — try to parse them as CommonJS and fail with `SyntaxError: Cannot use import statement
-outside a module`. `.mjs` marks each file as an ES module regardless of the surrounding project's
-`"type"` field.
+Every rule on this page is built with `defineShellRule`, the plugin's rule-authoring helper (step
+2 explains what it does). Every code block that names a file is the literal, shipped file it
+names, not a paraphrase, and every one is executed by this package's own test suite, which imports
+the files in [`examples/`](./examples/) directly and runs them through a real `eslint`
+`Linter.verify()`, and type-checks the TypeScript example in step 10 against the published
+declarations. A rule fires on a fixture script and does not fire on a clean one, so this tutorial
+cannot silently drift from working code. To write the same kind of test for your own rule, see
+[step 11](#11-test-your-rule), whose example [`no-backticks-rule-tester.mjs`](./examples/no-backticks-rule-tester.mjs)
+you can run yourself. All example files ship with this package
+(`docs/examples/`), so you can copy them into your own project as-is. The JavaScript examples use
+the `.mjs` extension deliberately: they are ES modules (`import`/`export`), and a default
+`npm init -y` project is CommonJS, so a plain `.js` extension would make Node — and ESLint's own
+config loader — try to parse them as CommonJS and fail with `SyntaxError: Cannot use import
+statement outside a module`. `.mjs` marks each file as an ES module regardless of the surrounding
+project's `"type"` field.
 
 ## 1. Pick a selector from the cookbook
 
 The cookbook's `:command` [launch class](./selectors.md#the-six-launch-classes) matches every
 `CallExpr` node — every shell command invocation. That's the selector this tutorial's rule listens
-on; `create()` then narrows further (is the command `rm`? does it pass a combined `-rf`/`-fr`
-flag?) the same way a hand-written rule narrows any other selector-first ESLint rule.
+on; `create()` then narrows further (is the command `rm`? does it pass recursive and force short
+flags, such as `-rf`, `-fr`, or `-r -f`?) the same way a hand-written rule narrows any other
+selector-first ESLint rule.
 
 ## 2. Write the rule module
 
@@ -34,10 +38,13 @@ flag?) the same way a hand-written rule narrows any other selector-first ESLint
  * The complete "flag `rm -rf`" custom rule from the custom-rule tutorial
  * (`../custom-rule-tutorial.md`). Plain, directly-runnable JavaScript (no
  * compile step) — this file *is* the tutorial's rule-module code fence,
- * copy-paste-verbatim; `test/custom-rule-tutorial.test.ts` imports this
+ * copy-paste-verbatim; this package's test suite imports this
  * exact file (not a reconstruction) and asserts the markdown fence matches
  * it byte-for-byte, so the two can't silently drift.
  *
+ * Built with `defineShellRule`, which declares `meta.languages: ['sh/sh']`
+ * for it, so ESLint refuses to run the rule on a file of any other language.
+ *
  * Built on the `:command` launch class from the selector cookbook
  * (`../selectors.md`) — `:command` matches every `CallExpr`, so `create()`
  * narrows further by inspecting the command word and its flag arguments,
@@ -48,12 +55,16 @@ flag?) the same way a hand-written rule narrows any other selector-first ESLint
  *
  * Flag words are resolved with `@eslint-sh/eslint-plugin`'s view-aware
  * `resolveWord` (backed by `sh-ast/analyze`) rather than a
- * hand-rolled scan: a word is only ever treated as the literal text
- * `-rf`/`-fr` when it is *statically* that string (bare or quoted literal
- * concatenations); a word containing a `ParamExp`/`CmdSubst`/`ArithmExp`/
- * `ProcSubst` resolves to `null` ("unknown") rather than being silently
- * erased into a static match or a static non-match — the same static-word
- * contract `design/PACKAGES.md` documents for `resolveWordText`. Importing
+ * hand-rolled scan: a word is only treated as a short-option cluster
+ * when it is *statically* that string (bare or
+ * quoted literal concatenations). Recursive (`r`/`R`) and force (`f`)
+ * flags accumulate across words before `--`; uppercase `F` is not force.
+ * Options are matched anywhere before `--`, GNU-style, even after operands.
+ * This teaching example does not model long options or option precedence.
+ * A word containing a `ParamExp`/`CmdSubst`/`ArithmExp`/
+ * `ProcSubst` resolves to `{ static: false, reason }` (`'expansion'`,
+ * `'tilde'`, `'glob'`, …) rather than being silently erased into a static
+ * match — see `resolveWord`'s API docs. Importing
  * it from the plugin package (rather than `sh-ast/analyze` directly) means
  * a project that installs only `@eslint-sh/eslint-plugin` has everything
  * this rule needs, with no separate `sh-ast` install or npm-hoisting
@@ -62,13 +73,13 @@ flag?) the same way a hand-written rule narrows any other selector-first ESLint
  * @see ../custom-rule-tutorial.md — the tutorial this rule backs
  * @see ../selectors.md — the `:command` launch class
  */
-import { resolveWord } from '@eslint-sh/eslint-plugin';
+import { defineShellRule, resolveWord } from '@eslint-sh/eslint-plugin';
 
-const noRmRf = {
+const noRmRf = defineShellRule({
   meta: {
     type: 'problem',
     docs: {
-      description: 'disallow `rm -rf`/`rm -fr` invocations',
+      description: 'disallow recursive-force `rm` invocations',
     },
     schema: [],
     messages: {
@@ -94,11 +105,15 @@ const noRmRf = {
         const endOfOptions = words.indexOf('--');
         const flagCandidates = words.slice(1, endOfOptions === -1 ? undefined : endOfOptions);
 
-        const isRecursiveForce = flagCandidates.some(
-          (word) =>
-            word !== null &&
-            (/^-[a-z]*r[a-z]*f[a-z]*$/i.test(word) || /^-[a-z]*f[a-z]*r[a-z]*$/i.test(word)),
+        // Only static short-option clusters contribute flags; operands,
+        // long options, and unresolved words supply no evidence. Recursive
+        // and force may occur in the same word or in separate words.
+        const shortOptions = flagCandidates.filter(
+          (word) => word !== null && /^-[a-zA-Z]+$/.test(word),
         );
+        const hasRecursive = shortOptions.some((word) => /[rR]/.test(word));
+        const hasForce = shortOptions.some((word) => word.includes('f'));
+        const isRecursiveForce = hasRecursive && hasForce;
 
         if (isRecursiveForce) {
           context.report({ node, loc: node.loc, messageId: 'rmRf' });
@@ -106,13 +121,25 @@ const noRmRf = {
       },
     };
   },
-};
+});
 
 export default noRmRf;
 ```
 
+`defineShellRule` takes the `{ meta, create(context) }` object you would write for any ESLint rule
+and returns it as an ordinary ESLint rule, with one addition: `meta.languages: ['sh/sh']`. That
+declaration is what makes ESLint refuse to run the rule on a file of another language. Without it,
+a rule enabled for a file that ESLint treats as JavaScript (typically because its config entry is
+missing `language: 'sh/sh'`) runs without error and never matches, so nothing tells you it was
+misconfigured. With it, ESLint stops with a configuration error naming the rule:
+`The following rules do not support the language "js/js"`. The helper always sets the field, so a
+rule built with it can't forget it, and in TypeScript writing `meta.languages` yourself is a
+compile error. Everything else in `meta`, including your own `docs.url`, is kept as you wrote it.
+
 A few things worth calling out:
 
+- `defineShellRule` and `resolveWord` both come from `@eslint-sh/eslint-plugin` (or the umbrella
+  `eslint-sh`). A rule needs no other package: not `sh-ast`, and not `@eslint/core`.
 - The listener key, `':command'`, is a selector string — one of the [six launch
   classes](./selectors.md#the-six-launch-classes) — not a bare node-type name. ESLint's
   `esquery`-based rule-listener matching (via `ShellLanguage.matchesSelectorClass`) treats it
@@ -123,6 +150,12 @@ A few things worth calling out:
   quoted literal (`rm`, `'r'm`, `"-rf"` all resolve), and `{ static: false, reason }` the moment any
   part of the word depends on a `ParamExp`/`CmdSubst`/`ArithmExp`/`ProcSubst` — never inventing a
   value for a dynamic word.
+- Short flags accumulate across static words before the first `--`: `rm -rf build`,
+  `rm -r -f build`, and `rm -R -f build` all report, while `rm -r build`, `rm -f build`,
+  and `rm -r -- -f` do not. Recursive accepts `r` or `R`; force is lowercase `f`, so `-rF`
+  does not supply both flags. Options are matched anywhere before `--`, GNU-style, even after
+  operands (for example, `rm build -rf` reports). This example focuses on short options; it does not
+  model long options or option precedence (such as a later `-i` overriding `-f`).
 - `context.report({ node, loc: node.loc, messageId: 'rmRf' })` reports with both a message (via
   `meta.messages.rmRf`) and an explicit location (`node.loc`, `ShellSourceCode`'s
   `{ start: { line, column }, end: { line, column } }` shape) — the two pieces every ESLint lint
@@ -136,7 +169,7 @@ A few things worth calling out:
 // eslint.config.mjs
 //
 // The custom-rule tutorial's exact flat-config wiring
-// (`../custom-rule-tutorial.md`, step 3). `test/custom-rule-tutorial.test.ts`
+// (`../custom-rule-tutorial.md`, step 3). This package's test suite
 // imports this file's default export directly and runs it through a real
 // `eslint` `Linter.verify()` — not a reconstruction of this shape — so the
 // documented wiring is genuinely tested.
@@ -145,7 +178,8 @@ import noRmRf from './no-rm-rf-rule.mjs';
 
 export default [
   {
-    files: ['**/*.sh', '**/*.bash'],
+    // Extensionless scripts need `bin/?*`: ESLint never lints a file matched only by `bin/*` or `bin/**`.
+    files: ['**/*.sh', '**/*.bash', 'bin/?*'],
     plugins: {
       sh,
       'my-rules': { rules: { 'no-rm-rf': noRmRf } },
@@ -158,6 +192,9 @@ export default [
 ];
 ```
 
+- `files` covers `.sh`/`.bash` files and the extensionless scripts directly in `bin/`. Use
+  `bin/?*`, not `bin/*` or `bin/**`: ESLint skips a file that only a pattern ending in `*` or
+  `/**` matches. The `eslint-sh` README's Troubleshooting section lists other patterns that work.
 - `plugins.sh` supplies `languages.sh` (the `ShellLanguage`/`ShellSourceCode` core) — required for
   `language: 'sh/sh'` to resolve.
 - `plugins['my-rules']` is a second, minimal plugin object whose only job is to register the rule
@@ -174,7 +211,716 @@ rm -rf "$BUILD_DIR"
 ```
 
 the rule reports once, at the `CallExpr`'s location, with the message text from
-`meta.messages.rmRf`. Given a clean script with no `rm -rf`/`rm -fr` invocation, the rule produces
-no messages at all — both cases are asserted in `test/custom-rule-tutorial.test.ts` against a real
-`eslint` `Linter.verify()` run (not a hand-built approximation of one), using the real
+`meta.messages.rmRf`. Given a clean script with no `rm` invocation combining recursive and force
+short flags, the rule produces no messages at all — both cases are asserted in
+this package's test suite against a real `eslint` `Linter.verify()` run (not a hand-built approximation of one), using the real
 `docs/examples/eslint.config.mjs` shown in step 3.
+
+## 5. Every command in the file
+
+The `:command` listener above sees one `CallExpr` at a time. Some rules need every command in the
+file together with how each one is reached: inside which function, inside `$(…)`, in which
+pipeline stage. `context.sourceCode.getCommandSites()` returns that list, one entry per command in
+source order, from `enumerateCommands` (in `@eslint-sh/eslint-plugin/syntax/analyze`). Each
+entry has:
+
+- `node`: the `CallExpr` node, the same object a `CallExpr` listener receives, so you can report
+  on it.
+- `context`: the frames that lead to the command, outermost first. `date` in
+  `f() { echo "$(date)"; }` has `[{ kind: 'function', name: 'f' }, { kind: 'cmdSubst' }]`.
+- `argv0` and `argv`: the command's words, resolved like `resolveWord` resolves them.
+- `resolveInvokedCommand()`: the command that actually runs after transparent wrappers such as
+  `sudo` or `env`. Its `chainIndices` say where each word of that chain sits in the site's `argv`,
+  so the command's own arguments are `site.argv.slice(chainIndices.at(-1) + 1)`. `site.argv` is
+  the whole command line, wrappers included, so slicing from `0` or `1` would hand you
+  `sudo`'s arguments for `sudo chmod 777 x`.
+
+An assignment-only statement such as `FOO=1` runs no command and has no entry.
+
+`docs/examples/no-curl-in-functions-rule.mjs` reports `curl` anywhere inside a shell function:
+
+```mjs
+/**
+ * The "every command in the file" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 5). Plain, directly-runnable
+ * JavaScript; this package's test suite imports this exact file and
+ * asserts the tutorial's code fence matches it byte-for-byte.
+ *
+ * It reports `curl` run anywhere inside a shell function, including through a
+ * wrapper (`sudo curl …`) or inside a command substitution in that function.
+ * Instead of tracking "am I inside a function?" while visiting nodes, it reads
+ * every command once from `context.sourceCode.getCommandSites()`, whose
+ * `context` frames (outermost first) already say how each command is reached.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noCurlInFunctions = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow `curl` inside shell functions',
+    },
+    schema: [],
+    messages: {
+      curlInFunction: 'Function `{{name}}` runs `curl`; fetch data before calling it.',
+    },
+  },
+  create(context) {
+    return {
+      File() {
+        for (const site of context.sourceCode.getCommandSites()) {
+          const { effective } = site.resolveInvokedCommand();
+          if (!effective.static || effective.text !== 'curl') {
+            continue;
+          }
+
+          // Frames run outermost first, so the last `function` frame is the
+          // function that directly contains this command.
+          const fn = site.context.findLast((frame) => frame.kind === 'function');
+          if (fn) {
+            context.report({
+              node: site.node,
+              messageId: 'curlInFunction',
+              data: { name: fn.name },
+            });
+          }
+        }
+      },
+    };
+  },
+});
+
+export default noCurlInFunctions;
+```
+
+Register it the same way as the rule in step 3. For
+
+```sh
+fetch() {
+  sudo curl -fsSL "$1"
+}
+curl -fsSL https://example.com
+```
+
+it reports once, on line 2: the `curl` in `fetch` runs through `sudo`, and the top-level `curl` is
+outside any function. This package's test suite runs this case through a real `eslint`
+`Linter`.
+
+## 6. Report on an operator
+
+Lint view nodes carry a `range` and `loc` for the whole node, but not the positions of the tokens
+inside it, such as the `&&` of a `BinaryCmd`. Those live on the original sh-ast record:
+
+- `context.sourceCode.getSyntax(node)` returns the sh-ast record a view node was parsed from, with
+  upstream field names (`X`, `Y`, `OpPos`, …). Treat it as read-only: every rule and helper linting
+  the file shares it.
+- `context.sourceCode.getIndexFromSyntaxPos(pos)` and `getLocFromSyntaxPos(pos)` convert one of that
+  record's positions into the UTF-16 index and one-based location ESLint uses. sh-ast positions count
+  UTF-8 bytes, so use these instead of the raw `Offset` or `Col` whenever text before the position
+  might not be ASCII.
+- `context.sourceCode.getViewNode(record)` goes the other way, from a record back to the view node
+  you can pass to `context.report({ node })`.
+
+`docs/examples/no-and-or-as-if-rule.mjs` reports `A && B || C`, which reads like if-then-else but
+also runs `C` when `B` fails, and puts the report on the `&&`:
+
+```mjs
+/**
+ * The "report on an operator" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 6). Plain, directly-runnable
+ * JavaScript; this package's test suite imports this exact file and
+ * asserts the tutorial's code fence matches it byte-for-byte.
+ *
+ * It reports `A && B || C`, which reads like if-then-else but is not: `C`
+ * also runs when `A` succeeds and `B` fails. The report sits on the `&&`
+ * itself. The lint view has no operator positions, so the rule reads the
+ * original sh-ast record with `getSyntax` and converts its byte position
+ * `OpPos` to ESLint coordinates with `getIndexFromSyntaxPos` and
+ * `getLocFromSyntaxPos`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noAndOrAsIf = defineShellRule({
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow `A && B || C` used as if-then-else',
+    },
+    schema: [],
+    messages: {
+      andOr: '`A && B || C` is not if-then-else: C also runs when B fails. Use `if A; then B; else C; fi`.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+
+    /** The two-character operator a `BinaryCmd` record's `OpPos` points at. */
+    const operatorOf = (binaryCmd) => {
+      const start = sourceCode.getIndexFromSyntaxPos(binaryCmd.OpPos);
+      return sourceCode.text.slice(start, start + 2);
+    };
+
+    return {
+      BinaryCmd(node) {
+        // `a && b || c` parses as `(a && b) || c`: the `||` command's left
+        // statement holds the `&&` command.
+        const or = sourceCode.getSyntax(node);
+        const and = or.X?.Cmd;
+        if (operatorOf(or) !== '||' || and?.Type !== 'BinaryCmd' || operatorOf(and) !== '&&') {
+          return;
+        }
+
+        const start = sourceCode.getIndexFromSyntaxPos(and.OpPos);
+        context.report({
+          loc: {
+            start: sourceCode.getLocFromSyntaxPos(and.OpPos),
+            end: sourceCode.getLocFromIndex(start + 2),
+          },
+          messageId: 'andOr',
+        });
+      },
+    };
+  },
+});
+
+export default noAndOrAsIf;
+```
+
+Register it the same way as the rule in step 3. For
+
+```sh
+[ -f "$f" ] && rm "$f" || echo missing
+```
+
+it reports once, on line 1 from column 13 to column 15: exactly the `&&`. A plain `A && B` or
+`A || B` is not reported. This package's test suite runs this case through a real
+`eslint` `Linter`.
+
+## 7. Using sh-ast's own operations and types
+
+The records `getSyntax` returns are sh-ast records. A rule that needs sh-ast's own operations or
+types for them (to `walk` a record, print an edited copy with `printSync`, run `enumerateCommands`
+over a tree, or name a record type such as `BinaryCmd`) imports them from the plugin's subpaths,
+never from `sh-ast` directly:
+
+- `@eslint-sh/eslint-plugin/syntax` (or `eslint-sh/syntax`) has the complete public surface of
+  `sh-ast`: `parseSync`, `walk`, `printSync`, `PrintOptions`, and the record types such as `Node`,
+  `Word`, `CallExpr`, `SyntaxPos` and `GoString`.
+- `@eslint-sh/eslint-plugin/syntax/analyze` (or `eslint-sh/syntax/analyze`) has the complete
+  public surface of `sh-ast/analyze`: `enumerateCommands`, `resolveArgv0` (its `chainIndices`
+  locate a resolved command's arguments in the site's `argv`), `DEFAULT_TRANSPARENT_WRAPPERS`,
+  `WrapperSpec`, the named operator constants with `rawOperator`, and a raw `resolveWord` that
+  takes a sh-ast `Node` rather than a lint-view `ShellNode`.
+
+Both come from the plugin's own `sh-ast` dependency, the same module instance the language parses
+with, so you don't install `sh-ast` and its version always matches the records `getSyntax` returns.
+They track the plugin's pinned `sh-ast` minor: an `sh-ast` 0.x minor bump is a minor release of the
+plugin.
+
+## 8. Printed fixes
+
+Some fixes are easier to describe as an edit to the syntax than as new text. Turning
+`` `date` `` into `$(date)` by hand means re-escaping any nested backticks and backslashes; on the
+syntax it is one field, `CmdSubst.Backquotes`. Two `context.sourceCode` methods turn such an edit
+into an ESLint fix:
+
+- `getEditableSyntax(node)` returns an independent copy of the sh-ast record `node` was parsed
+  from. It is an ordinary `structuredClone` of that record, which sh-ast documents as the supported
+  way to get an editable copy. Edit the copy freely: the original record that `getSyntax` returns,
+  the lint view, and helpers such as `resolveWord` keep seeing the original source. It throws a
+  `TypeError` for a node that has no record of its own, such as one you built yourself.
+- `getPrintedReplacement(node, edited, options)` prints `edited` with sh-ast's `printSync` and
+  returns `{ range, text }`, ready for `fixer.replaceTextRange(range, text)`. The range is
+  `node.range`, or the whole file when `edited` is a `File`. `edited` must be a root `printSync`
+  accepts (`File`, `Stmt`, `Word`, `Assign`, a `Command` or a `WordPart`), and output that is not
+  valid UTF-8 throws a `TypeError` instead of becoming a fix.
+
+`docs/examples/no-backticks-rule.mjs` reports backtick command substitution and fixes it to `$(…)`:
+
+```mjs
+/**
+ * The "printed fix" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 8). Plain, directly-runnable
+ * JavaScript; this package's test suite imports this exact file and
+ * asserts the tutorial's code fence matches it byte-for-byte.
+ *
+ * It reports backtick command substitution (`` `date` ``) and fixes it to
+ * `$(date)`. Instead of rewriting text by hand, which would have to re-escape
+ * nested backticks and backslashes, the fix edits a copy of the substitution's
+ * sh-ast record from `getEditableSyntax` and lets sh-ast's printer write the
+ * new text with `getPrintedReplacement`. The original syntax every other rule
+ * reads stays unchanged.
+ *
+ * @import { PrintOptions } from '@eslint-sh/eslint-plugin/syntax'
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+/**
+ * Prints nested lines with two spaces per level instead of the printer's
+ * default tabs.
+ * @type {PrintOptions}
+ */
+const printOptions = { Indent: 2 };
+
+const noBackticks = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description: 'prefer `$(…)` over backtick command substitution',
+    },
+    schema: [],
+    messages: {
+      backticks: 'Use `$(…)` instead of backticks for command substitution.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+    return {
+      CmdSubst(node) {
+        if (!node.backquotes) {
+          return;
+        }
+        // An independent copy: editing it changes neither the lint view nor
+        // the syntax other rules read.
+        const copy = sourceCode.getEditableSyntax(node);
+        copy.Backquotes = false;
+        const { range, text } = sourceCode.getPrintedReplacement(node, copy, printOptions);
+        context.report({
+          node,
+          messageId: 'backticks',
+          fix: (fixer) => fixer.replaceTextRange(range, text),
+        });
+      },
+    };
+  },
+});
+
+export default noBackticks;
+```
+
+Register it the same way as the rule in step 3. For
+
+```sh
+now=`date +%s`
+echo "uid: `id -u` 🎉"
+```
+
+it reports both substitutions, and `eslint --fix` rewrites the file to
+
+```sh
+now=$(date +%s)
+echo "uid: $(id -u) 🎉"
+```
+
+leaving every other character of the file as it was. This package's test suite runs this
+case through a real `eslint` `Linter`.
+
+The printer formats the node it prints; it does not copy the original text. Its output starts at
+column 0, and nested lines are indented with tabs, or with `Indent` spaces when `options.Indent` is
+set, as the example does. A `Word` or `WordPart` root, like the `CmdSubst` above, is usually a
+single line, so the fix changes only that node. Replacing a multi-line root nested inside other
+code, such as an `if` statement in a function body, keeps the shell meaning but may change the
+formatting of its lines:
+
+```sh
+f() {
+  if true; then
+	echo new
+fi
+}
+```
+
+Prefer `Word` and `WordPart` roots for surgical fixes. For a `Stmt` root, the printed text leaves
+out the statement's own leading and trailing comments, which lie outside its range, and keeps its
+`;` terminator, so `a; b` never becomes `a b`. When the edit is to a few tokens of a larger,
+hand-formatted construct, step 9's position-based text edit is the better tool.
+
+`PrintOptions`, `Node` and the record types (`CmdSubst`, `Word`, …) are the types of
+`@eslint-sh/eslint-plugin/syntax` (step 7), and so is `printSync`, if you want to print a record
+yourself, for example to compare it with the source before reporting:
+
+```ts
+import { printSync } from '@eslint-sh/eslint-plugin/syntax';
+import type { Node, PrintOptions } from '@eslint-sh/eslint-plugin/syntax';
+```
+
+## 9. Position-based text edits
+
+A printed fix replaces a node's whole range with the printer's rendering of it. That is the right
+trade when the new text is hard to write by hand, as with re-escaping nested backticks. It is the
+wrong one when the edit touches a few tokens of a node that spans several lines, because the
+printer reflows everything else in that range:
+
+- nested lines, `\` continuation lines included, are re-indented with tabs by default or
+  `options.Indent` spaces, whatever the original used;
+- spacing the printer has its own opinion about is normalized, such as the gap before a trailing
+  comment;
+- every line in the range changes, so the fix shows up in a diff as a rewrite of the whole node.
+
+Use a position-based text edit instead whenever you know which characters to change: replace or
+remove just that span with `fixer.replaceTextRange` or `fixer.removeRange`, and leave the rest of
+the file byte-for-byte as it was. The positions come from the sh-ast record (step 6):
+`getSyntax(node)` gives the record, and `getIndexFromSyntaxPos(pos)` converts each of its
+UTF-8-byte positions into the string offset a fixer takes.
+
+`docs/examples/no-function-keyword-rule.mjs` rewrites the bash-only `function name {` to the
+portable `name() {` by replacing only the text from `function` through the name:
+
+```mjs
+/**
+ * The "position-based text edit" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 9). Plain, directly-runnable
+ * JavaScript; this package's test suite imports this exact file and
+ * asserts the tutorial's code fence matches it byte-for-byte.
+ *
+ * It reports the bash-only `function name {` form and fixes it to the
+ * portable `name() {`. The fix replaces only the text from the `function`
+ * keyword through the name, so the body keeps its exact layout, comments and
+ * all; printing the whole edited function would re-indent the body instead.
+ * The two ends of that text come from the sh-ast record's own positions,
+ * converted to string offsets with `getIndexFromSyntaxPos` (sh-ast positions
+ * count UTF-8 bytes).
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noFunctionKeyword = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description: 'prefer `name() { … }` over the `function` keyword',
+    },
+    schema: [],
+    messages: {
+      useParens: 'Declare `{{name}}` as `{{name}}() { … }`, without the `function` keyword.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+    return {
+      FuncDecl(node) {
+        const decl = sourceCode.getSyntax(node);
+        // Only `function name {`: not `function name() {`, `name() {`, or
+        // zsh's several-name form.
+        if (!decl.RsrvWord || decl.Parens || decl.Name === null || decl.Names !== null) {
+          return;
+        }
+        // A name that is not valid UTF-8 arrives as bytes, not a string.
+        const name = decl.Name.Value;
+        if (typeof name !== 'string') {
+          return;
+        }
+        const start = sourceCode.getIndexFromSyntaxPos(decl.Position);
+        const end = sourceCode.getIndexFromSyntaxPos(decl.Name.ValueEnd);
+        context.report({
+          node,
+          messageId: 'useParens',
+          data: { name },
+          fix: (fixer) => fixer.replaceTextRange([start, end], `${name}()`),
+        });
+      },
+    };
+  },
+});
+
+export default noFunctionKeyword;
+```
+
+Register it the same way as the rule in step 3. For
+
+```sh
+function greet {
+    # Say hello.
+    printf '%s\n' \
+        "hello, $1"   # to stdout
+}
+```
+
+`eslint --fix` changes only the first line:
+
+```sh
+greet() {
+    # Say hello.
+    printf '%s\n' \
+        "hello, $1"   # to stdout
+}
+```
+
+The printed-fix version of the same rule (flip `RsrvWord` and `Parens` on a `getEditableSyntax`
+copy, then `getPrintedReplacement(node, copy, { Indent: 4 })`) replaces the whole function, and
+even with `Indent` matching the source it does not keep the original layout (with the default
+options, the four-space indentation would also become tabs):
+
+```sh
+greet() {
+    # Say hello.
+    printf '%s\n' \
+        "hello, $1" # to stdout
+}
+```
+
+This package's test suite runs both versions through a real `eslint` `Linter`, including
+on a file whose function name and body contain multibyte text.
+
+## 10. Writing rules in TypeScript
+
+`defineShellRule` and the types around it are exported from `@eslint-sh/eslint-plugin`, so a
+TypeScript rule needs no `@eslint/core` import and no rule types of its own:
+
+- `defineShellRule<Options, MessageIds>(…)` takes the options tuple and message ids as type
+  arguments, or infers the message ids from `meta.messages` when you leave them out. Either way,
+  `context.options` has your options' type, and `context.report` accepts only declared message ids.
+- `context.sourceCode` is `ShellSourceCode`, so `getCommandSites()`, `getSyntax()` and the other
+  helpers are typed without a cast, and a listener keyed by a node type (`CallExpr`, `Word:exit`)
+  receives that node type, so its fields (`args`, `parts`, `cmd`, …) are typed; other selectors
+  receive `ShellNode`, which you narrow on `type`. See [Reading nodes](./reading-nodes.md).
+- `ShellRuleContext<Options, MessageIds>` names the context for a helper outside `create()`, and
+  `ShellRule<Options, MessageIds>` names what `defineShellRule` returns. A `ShellRule` always
+  declares `meta.languages: ['sh/sh']`: an object written by hand without it is a type error.
+- `ShellRuleSpec` names the object you pass to `defineShellRule`: the rule before the helper adds
+  `meta.languages`. (`ShellRule`, the finished rule, is what ESLint calls a rule definition.)
+  `ShellRuleMeta` and `ShellRuleVisitor` name its `meta` and the listener map, if you need to
+  spell them.
+
+`docs/examples/no-listed-commands-rule.ts`:
+
+```ts
+/**
+ * The TypeScript custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 10). This package's test suite
+ * asserts the tutorial's code fence matches this file byte-for-byte,
+ * type-checks it against the package's published declarations, and runs it
+ * through a real `eslint` `Linter`.
+ *
+ * It reports any command named in its `commands` option, including through a
+ * wrapper such as `sudo`. Every type comes from `@eslint-sh/eslint-plugin`:
+ * the options and message ids passed to `defineShellRule` flow into
+ * `context.options` and `context.report`, and `ShellRuleContext` types the
+ * helper that reports outside `create()`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+import type { ShellCommandSite, ShellRuleContext } from '@eslint-sh/eslint-plugin';
+
+/** The rule's one options object; `commands` defaults to `[]`. */
+type Options = [{ commands?: string[] }?];
+
+/** Reports `site` when the command it runs, after wrappers, is in `listed`. */
+function reportIfListed(
+  context: ShellRuleContext<Options, 'listed'>,
+  site: ShellCommandSite,
+  listed: ReadonlySet<string>,
+): void {
+  const { effective } = site.resolveInvokedCommand();
+  if (effective.static && listed.has(effective.text)) {
+    context.report({ node: site.node, messageId: 'listed', data: { name: effective.text } });
+  }
+}
+
+const noListedCommands = defineShellRule<Options, 'listed'>({
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow the commands named in the `commands` option',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: { commands: { type: 'array', items: { type: 'string' } } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      listed: '`{{name}}` is not allowed in this project.',
+    },
+  },
+  create(context) {
+    const listed = new Set(context.options[0]?.commands ?? []);
+    return {
+      File() {
+        for (const site of context.sourceCode.getCommandSites()) {
+          reportIfListed(context, site, listed);
+        }
+      },
+    };
+  },
+});
+
+export default noListedCommands;
+```
+
+Enable it with its options, the same way as the rule in step 3:
+`'my-rules/no-listed-commands': ['error', { commands: ['telnet'] }]`. For `sudo telnet example.com`
+it reports `` `telnet` is not allowed in this project. ``, because `resolveInvokedCommand()` sees
+through `sudo`.
+
+## 11. Test your rule
+
+ESLint's `RuleTester` runs a rule against `valid` and `invalid` code, and it works with this plugin.
+[`docs/examples/no-backticks-rule-tester.mjs`](./examples/no-backticks-rule-tester.mjs) tests the
+step 8 rule, including its fix, and a second rule that only offers a suggestion:
+
+```mjs
+/**
+ * The "test your rule" example from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 11). It tests the step 8 rule
+ * (`./no-backticks-rule.mjs`) with ESLint's own `RuleTester`, and a small
+ * inline rule that offers a suggestion rather than an automatic fix.
+ *
+ * `RuleTester` needs two settings to run shell rules: the plugin registered
+ * under `plugins`, and `language: 'sh/sh'`. Leaving either out
+ * makes `RuleTester` throw a configuration error before it checks any case;
+ * the tutorial quotes both messages.
+ *
+ * Run it with `node no-backticks-rule-tester.mjs`. `RuleTester` uses
+ * `describe`/`it` when the test runner defines them, and otherwise throws on
+ * the first failing case, so a quiet exit means every case passed.
+ *
+ * This file and `./no-backticks-rule.mjs` ship in the `@eslint-sh/eslint-plugin`
+ * package only (`docs/examples/`); the umbrella `eslint-sh` package does not
+ * include them. To import from the umbrella instead, change the plugin import
+ * below and the one in `./no-backticks-rule.mjs` to `eslint-sh`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this example backs
+ * @see https://eslint.org/docs/latest/integrate/nodejs-api#ruletester
+ */
+import { RuleTester } from 'eslint';
+import sh, { defineShellRule } from '@eslint-sh/eslint-plugin';
+import noBackticks from './no-backticks-rule.mjs';
+
+const tester = new RuleTester({
+  plugins: { sh },
+  language: 'sh/sh',
+});
+
+tester.run('no-backticks', noBackticks, {
+  valid: [
+    // An empty file, and a command substitution that already uses `$(…)`.
+    { code: '' },
+    { code: 'now=$(date +%s)\n' },
+  ],
+  invalid: [
+    {
+      code: 'now=`date +%s`\n',
+      // `messageId` checks which message fired; `line` and `column` check where.
+      errors: [{ messageId: 'backticks', line: 1, column: 5 }],
+      // `output` is the file after ESLint applies the fix.
+      output: 'now=$(date +%s)\n',
+    },
+    {
+      // Multibyte text before and inside the substitutions.
+      code: 'echo "héllo `id -u` 🎉" `date`\n',
+      errors: [{ messageId: 'backticks' }, { messageId: 'backticks' }],
+      output: 'echo "héllo $(id -u) 🎉" $(date)\n',
+    },
+  ],
+});
+
+/**
+ * A rule that only suggests: it reports `which` and offers `command -v`, which
+ * the reader chooses to apply. A rule with suggestions declares
+ * `hasSuggestions: true`.
+ */
+const noWhich = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    hasSuggestions: true,
+    docs: { description: 'prefer `command -v` over `which`' },
+    schema: [],
+    messages: {
+      noWhich: '`which` is not portable.',
+      useCommandV: 'Use `command -v` instead.',
+    },
+  },
+  create(context) {
+    return {
+      CallExpr(node) {
+        const [name] = node.args ?? [];
+        if (name === undefined || context.sourceCode.getText(name) !== 'which') {
+          return;
+        }
+        context.report({
+          node: name,
+          messageId: 'noWhich',
+          suggest: [
+            { messageId: 'useCommandV', fix: (fixer) => fixer.replaceText(name, 'command -v') },
+          ],
+        });
+      },
+    };
+  },
+});
+
+tester.run('no-which', noWhich, {
+  valid: [{ code: 'command -v ls\n' }],
+  invalid: [
+    {
+      code: 'which ls\n',
+      // `output: null` asserts that the rule has no automatic fix.
+      output: null,
+      errors: [
+        {
+          messageId: 'noWhich',
+          suggestions: [{ messageId: 'useCommandV', output: 'command -v ls\n' }],
+        },
+      ],
+    },
+  ],
+});
+
+```
+
+Run it with `node no-backticks-rule-tester.mjs` from a folder that has `eslint`, the plugin and the
+example files installed or copied in. `RuleTester` uses `describe` and `it` when your test runner
+defines them (Vitest with `globals: true`, Mocha, Jest), and otherwise runs each case in turn and
+throws on the first failure, so a quiet exit means every case passed. Each `tester.run(name, rule,
+cases)` takes:
+
+- `valid`: code the rule must not report.
+- `invalid`: code the rule must report. `errors` lists each report by `messageId`, and may add
+  `line`, `column` and the other location fields. `output` is the file after ESLint applies the
+  rule's fix, and is how you test a fixer; for a rule with no fix, set `output: null`.
+- `suggestions` inside an error lists the suggestions that report offers, each with its `messageId`
+  and the `output` that applying it produces. A rule with suggestions must declare
+  `meta.hasSuggestions: true`.
+
+Put multibyte text (`é`, `🎉`) in at least one case of a rule that edits text, as the example does:
+ESLint measures fix ranges in string offsets, and a rule that confuses them with bytes passes on
+ASCII and breaks on anything else.
+
+### The two options to get right
+
+`RuleTester` takes the same options as a flat-config entry, and a shell rule needs both of these:
+
+```js
+const tester = new RuleTester({
+  plugins: { sh }, // register the plugin, so `sh/sh` resolves
+  language: 'sh/sh', // parse each case as shell, not JavaScript
+});
+```
+
+Leaving out `language` is the easier mistake: `RuleTester` falls back to JavaScript, and the first
+case fails with
+
+```text
+TypeError: ESLint configuration in rule-tester is invalid: Key "rules": The following rules do not support the language "js/js":
+	- "rule-to-test/no-backticks"
+```
+
+Leaving out `plugins: { sh }` fails with
+
+```text
+TypeError: ESLint configuration in rule-tester is invalid: Key "language": Could not find "sh" in plugin "sh".
+```
+
+Both appear when the test file runs, before any case is checked. A rule built with `defineShellRule`
+declares `meta.languages: ['sh/sh']`, so ESLint refuses to run it under any other language.