@eslint-sh/eslint-plugin 0.1.0

package/dist/language/shell-source-code.js

@@ -0,0 +1,318 @@
+import { ConfigCommentParser, Directive, TextSourceCodeBase, VisitNodeStep, } from '@eslint/plugin-kit';
+import { visitorKeys as shellVisitorKeys, walk } from 'sh-ast';
+/**
+ * Shared instance — `ConfigCommentParser` is stateless (see
+ * `@eslint/plugin-kit`'s implementation), so every `ShellSourceCode`
+ * instance can safely reuse one parser rather than constructing its own.
+ */
+const commentParser = new ConfigCommentParser();
+/**
+ * Builds the regex that selects which `Comment` nodes are directive/inline-
+ * config candidates at all, for a given `directivePrefix`. Mirrors
+ * `@eslint/json`'s `JSONSourceCode` `INLINE_CONFIG` constant
+ * (`/^\s*eslint(?:-enable|-disable(?:(?:-next)?-line)?)?(?:\s|$)/u`)
+ * generalized to an arbitrary prefix instead of the literal `"eslint"` —
+ * this is what makes `directivePrefix` configurable end to end rather than
+ * only in `getDisableDirectives`/`applyInlineConfig`'s own label matching.
+ */
+function buildInlineConfigPattern(directivePrefix) {
+    const escapedPrefix = directivePrefix.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+    return new RegExp(`^\\s*${escapedPrefix}(?:-enable|-disable(?:(?:-next)?-line)?)?(?:\\s|$)`, 'u');
+}
+/**
+ * Maps each of the four recognized directive labels (`<prefix>-disable`,
+ * `<prefix>-enable`, `<prefix>-disable-next-line`, `<prefix>-disable-line`)
+ * to the `DirectiveType` ESLint core expects — computed once per
+ * `directivePrefix` rather than re-templated on every comment.
+ */
+function buildDirectiveLabels(directivePrefix) {
+    return new Map([
+        [`${directivePrefix}-disable`, 'disable'],
+        [`${directivePrefix}-enable`, 'enable'],
+        [`${directivePrefix}-disable-next-line`, 'disable-next-line'],
+        [`${directivePrefix}-disable-line`, 'disable-line'],
+    ]);
+}
+/**
+ * Reads a `Comment` node's text (mvdan/sh's `syntax.Comment.Text`,
+ * normalized/lowercased to `text` — verified against a real `parseSync`
+ * call: the leading `#` is already excluded, e.g. the source
+ * `# eslint-disable-next-line sh/foo -- reason` produces
+ * `comment.text === " eslint-disable-next-line sh/foo -- reason"`).
+ * `ShNode`'s index signature types every field `unknown`, so this narrows
+ * defensively rather than assuming the shape.
+ */
+function getCommentText(comment) {
+    const { text } = comment;
+    return typeof text === 'string' ? text : '';
+}
+/**
+ * Narrows an unknown field value to a normalized `ShNode` — used while
+ * traversing (see `ShellSourceCode.traverse()` below) to tell an actual
+ * child node apart from a scalar field (e.g. `Lit.value: string`) or
+ * `undefined`.
+ * Deliberately duck-typed (checks only `type`, matching
+ * `ShellLanguage.nodeTypeKey`) rather than re-validating the full `ShNode`
+ * shape — every value reachable through a `visitorKeys` field on a bridge
+ * AST is either a normalized node or absent, by construction of
+ * `sh-ast`'s `normalize()`.
+ */
+function isShNode(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.type === 'string');
+}
+/**
+ * `ShellSourceCode` — the `SourceCode` object ESLint uses to work with a
+ * parsed shell file (design/ARCHITECTURE.md, "SourceCode and Language
+ * objects"). Extends `@eslint/plugin-kit`'s `TextSourceCodeBase`, which
+ * already implements `getLoc`/`getRange`/`getText`/`lines` (both by reading
+ * the normalized node's own `loc`/`range` fields — see
+ * `sh-ast`'s "Normalized node shape"), `getLocFromIndex`, and
+ * `getIndexFromLoc`; this class adds the two members the base class
+ * deliberately leaves unimplemented: `traverse()` (base throws "Not
+ * implemented") and `getParent()` (base throws "Not implemented", and
+ * `getAncestors()` — already implemented generically in terms of
+ * `getParent()` — falls out for free).
+ *
+ * Directive support (`getDisableDirectives`, `getInlineConfigNodes`,
+ * `applyInlineConfig`) recognizes all four disable-comment forms
+ * (`<prefix>-disable`, `<prefix>-enable`, `<prefix>-disable-line`,
+ * `<prefix>-disable-next-line`) plus whole-file inline rule config
+ * (bare `<prefix> <rule-config>`), sourced from `Comment` nodes gathered via
+ * `sh-ast`'s structural `walk()` and parsed with
+ * `@eslint/plugin-kit`'s `ConfigCommentParser` — the same building blocks
+ * `@eslint/json`'s `JSONSourceCode` uses, generalized so the `<prefix>` is
+ * configurable (default `"eslint"`; see `ShellLanguageOptions.directivePrefix`)
+ * rather than hardcoded to `"eslint"`.
+ *
+ * Selector-class support (`matchesSelectorClass`, the six launch esquery
+ * classes) is implemented on `ShellLanguage` — see `shell-language.ts` and
+ * `selector-classes.ts`.
+ *
+ * @public
+ */
+export class ShellSourceCode extends TextSourceCodeBase {
+    /**
+     * Parent-node lookup populated the first time `traverse()` runs. Keyed by
+     * node identity (not by range or any other derived key) so it works even
+     * for nodes whose range/loc coincide with another node's (e.g. a
+     * single-child wrapper).
+     */
+    #parents = new WeakMap();
+    /**
+     * Cached traversal steps — the AST never mutates after `parse()` returns
+     * it, so `traverse()` only needs to compute this once (mirroring
+     * `@eslint/json`'s `JSONSourceCode`).
+     */
+    #steps;
+    /**
+     * The prefix directive/inline-config comments must start with (see
+     * `ShellLanguageOptions.directivePrefix`; resolved/defaulted by
+     * `ShellLanguage.createSourceCode` before this constructor ever runs).
+     */
+    #directivePrefix;
+    /**
+     * `<prefix>-disable`/`-enable`/`-disable-line`/`-disable-next-line` → the
+     * `DirectiveType` ESLint core expects — computed once from
+     * `#directivePrefix` rather than re-templated per comment.
+     */
+    #directiveLabels;
+    /**
+     * Selects which `Comment` nodes are directive/inline-config candidates at
+     * all, before `ConfigCommentParser.parseDirective` is even invoked.
+     */
+    #inlineConfigPattern;
+    /**
+     * Every `Comment` node in the AST, gathered once (cached) via
+     * `sh-ast`'s `walk()` — deliberately *not* derived from
+     * `traverse()`/`visitorKeys` even though, verified against a real parse,
+     * `comments` and `last` already appear in the generated `visitorKeys`
+     * table (so `traverse()` does visit `Comment` nodes today too). `walk()`
+     * discovers children structurally rather than through that table (see its
+     * own doc comment: the hand-written table once missed a field and
+     * silently under-walked), so comment collection keeps working even if a
+     * future `visitorKeys` regeneration omits a comment-bearing field.
+     */
+    #comments;
+    /**
+     * Cached result of {@link ShellSourceCode.getInlineConfigNodes} — ESLint core calls it up
+     * to twice per lint run (once directly when warning about disabled inline
+     * config, once indirectly via `getDisableDirectives`/`applyInlineConfig`).
+     */
+    #inlineConfigNodes;
+    constructor(options) {
+        super(options);
+        // Defensive default for direct construction outside the `ShellLanguage`
+        // pipeline (e.g. unit tests) — `ShellLanguage.createSourceCode` always
+        // supplies the already-normalized, defaulted value.
+        this.#directivePrefix = options.directivePrefix ?? 'eslint';
+        this.#directiveLabels = buildDirectiveLabels(this.#directivePrefix);
+        this.#inlineConfigPattern = buildInlineConfigPattern(this.#directivePrefix);
+    }
+    /**
+     * Returns the parent of `node`, or `undefined` for the root `File` node
+     * (or any node visited before `traverse()` has run once). ESLint always
+     * calls `traverse()` before any rule can call `getParent`/`getAncestors`,
+     * so in practice the map is always populated by the time a rule observes
+     * it.
+     */
+    getParent(node) {
+        return this.#parents.get(node);
+    }
+    /**
+     * Traverses the AST pre-order, yielding a `VisitNodeStep` on node enter
+     * (`phase: 1`) and another on node exit (`phase: 2`) for every node —
+     * exactly the two-phase shape `@eslint/json`/`@eslint/css` produce, which
+     * is what lets rule listeners use `NodeType` and `NodeType:exit` esquery
+     * selectors. Children are discovered via `sh-ast`'s generated,
+     * frozen `visitorKeys` table (per node `type`) — **not** structurally
+     * (contrast `sh-ast`'s own `walk()`, which deliberately walks
+     * structurally so its correctness never depends on that table) — because
+     * ESLint's traversal contract is defined in terms of a language's
+     * declared `visitorKeys`, and this class's whole job is to honor that
+     * contract for shell ASTs.
+     */
+    traverse() {
+        if (this.#steps) {
+            return this.#steps.values();
+        }
+        const steps = [];
+        this.#steps = steps;
+        const visit = (node, parent) => {
+            if (parent) {
+                this.#parents.set(node, parent);
+            }
+            steps.push(new VisitNodeStep({ target: node, phase: 1, args: [node, parent] }));
+            const keys = shellVisitorKeys[node.type] ?? [];
+            for (const key of keys) {
+                const value = node[key];
+                if (Array.isArray(value)) {
+                    for (const child of value) {
+                        if (isShNode(child)) {
+                            visit(child, node);
+                        }
+                    }
+                }
+                else if (isShNode(value)) {
+                    visit(value, node);
+                }
+            }
+            steps.push(new VisitNodeStep({ target: node, phase: 2, args: [node, parent] }));
+        };
+        visit(this.ast, undefined);
+        return steps.values();
+    }
+    /**
+     * Returns every `Comment` node in the AST, in source order, gathering them
+     * (once, cached) via `sh-ast`'s structural `walk()` rather than
+     * `traverse()` — see `#comments`'s doc comment for why.
+     *
+     * `walk()` discovers children in AST field/insertion order (e.g.
+     * `Stmt.comments` before descending into `Stmt.cmd`'s own nested
+     * comments), which is not guaranteed to match *source* order — a comment
+     * trailing an early statement can be visited after a comment buried
+     * inside a later command substitution's own sub-tree, depending on field
+     * layout. `getDisableDirectives()`'s `disable`/`enable` ranges happen to
+     * be safe regardless (ESLint core re-sorts directives by location
+     * internally), but `applyInlineConfig()`'s "last inline-config comment
+     * wins" semantics for a repeated whole-file rule config, and any external
+     * caller of `getInlineConfigNodes()`, both depend on source order. Sorting
+     * once here — rather than requiring every consumer to re-sort — is the
+     * fix that's correct regardless of how `walk()` happens to traverse.
+     */
+    #getComments() {
+        if (!this.#comments) {
+            const comments = [];
+            walk(this.ast, (node) => {
+                if (node.type === 'Comment') {
+                    comments.push(node);
+                }
+            });
+            comments.sort((a, b) => a.range[0] - b.range[0] || a.range[1] - b.range[1]);
+            this.#comments = comments;
+        }
+        return this.#comments;
+    }
+    /**
+     * Returns every `Comment` node whose text is a directive or inline-config
+     * candidate for this source code's `directivePrefix` — the pool both
+     * {@link ShellSourceCode.getDisableDirectives} and {@link ShellSourceCode.applyInlineConfig} draw from,
+     * and the array ESLint core itself asks for directly (to warn "has no
+     * effect" when `linterOptions.noInlineConfig` is set — see
+     * `eslint`'s `lib/linter/linter.js`, the `warnInlineConfig` branch).
+     */
+    getInlineConfigNodes() {
+        this.#inlineConfigNodes ??= this.#getComments().filter((comment) => this.#inlineConfigPattern.test(getCommentText(comment)));
+        return this.#inlineConfigNodes;
+    }
+    /**
+     * Returns the disable/enable directives found among
+     * {@link ShellSourceCode.getInlineConfigNodes}'s comments, recognizing all four forms —
+     * `<prefix>-disable`, `<prefix>-enable`, `<prefix>-disable-line`,
+     * `<prefix>-disable-next-line` — with `-- justification` capture, per the
+     * `@eslint/core` `Directive` contract. Mirrors `@eslint/json`'s
+     * `JSONSourceCode.getDisableDirectives` (verified against its published
+     * source as the named ecosystem precedent), generalized to a configurable
+     * prefix instead of the hardcoded `"eslint"` label.
+     *
+     * Unlike `JSONSourceCode` (whose block comments can span multiple
+     * physical lines, making `<prefix>-disable-line` spanning lines a real,
+     * reportable problem), mvdan/sh's `#` line comments cannot contain an
+     * embedded newline — the parser always terminates a comment at end of
+     * line — so that particular problem can never arise here and is not
+     * checked for.
+     */
+    getDisableDirectives() {
+        const problems = [];
+        const directives = [];
+        for (const comment of this.getInlineConfigNodes()) {
+            const parsed = commentParser.parseDirective(getCommentText(comment));
+            if (!parsed) {
+                continue;
+            }
+            const directiveType = this.#directiveLabels.get(parsed.label);
+            if (directiveType) {
+                directives.push(new Directive({
+                    type: directiveType,
+                    node: comment,
+                    value: parsed.value,
+                    justification: parsed.justification,
+                }));
+            }
+        }
+        return { problems, directives };
+    }
+    /**
+     * Returns the whole-file inline rule configuration found among
+     * {@link ShellSourceCode.getInlineConfigNodes}'s comments — a bare `<prefix> <rule-config>`
+     * comment (e.g. `# eslint sh/rule-a: "error"`), parsed with
+     * `ConfigCommentParser.parseJSONLikeConfig`. Mirrors `@eslint/json`'s
+     * `JSONSourceCode.applyInlineConfig`. This is the surface
+     * `linterOptions.noInlineConfig: true` suppresses (ESLint core skips
+     * calling this method — and `getDisableDirectives`, together, since both
+     * are gated by the same flag in `eslint`'s own `linter.js` — and instead
+     * calls `getInlineConfigNodes` to emit a "has no effect" warning per
+     * comment; see design/ARCHITECTURE.md, "SourceCode and Language objects").
+     */
+    applyInlineConfig() {
+        const problems = [];
+        const configs = [];
+        for (const comment of this.getInlineConfigNodes()) {
+            const parsed = commentParser.parseDirective(getCommentText(comment));
+            if (parsed?.label !== this.#directivePrefix) {
+                continue;
+            }
+            const parseResult = commentParser.parseJSONLikeConfig(parsed.value);
+            const loc = this.getLoc(comment);
+            if (parseResult.ok) {
+                configs.push({ config: { rules: parseResult.config }, loc });
+            }
+            else {
+                problems.push({ ruleId: null, message: parseResult.error.message, loc });
+            }
+        }
+        return { configs, problems };
+    }
+}
+//# sourceMappingURL=shell-source-code.js.map

package/dist/language/shell-source-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-source-code.js","sourceRoot":"","sources":["../../src/language/shell-source-code.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reads this package's own version from its `package.json` at runtime.
+ * Never hardcoded: the plugin's `meta.version` must always reflect the
+ * published version, verified by a test asserting the two match (see
+ * `test/plugin-meta.test.ts`).
+ *
+ * Works identically whether this module runs as `src/version.ts` (vitest)
+ * or the compiled `dist/version.js` (published package), since both sit one
+ * directory below the package root that contains `package.json`.
+ *
+ * @internal
+ */
+export declare function readPackageVersion(): string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAkB3C"}

package/dist/version.js

@@ -0,0 +1,29 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Reads this package's own version from its `package.json` at runtime.
+ * Never hardcoded: the plugin's `meta.version` must always reflect the
+ * published version, verified by a test asserting the two match (see
+ * `test/plugin-meta.test.ts`).
+ *
+ * Works identically whether this module runs as `src/version.ts` (vitest)
+ * or the compiled `dist/version.js` (published package), since both sit one
+ * directory below the package root that contains `package.json`.
+ *
+ * @internal
+ */
+export function readPackageVersion() {
+    const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+    const packageJsonPath = join(packageRoot, 'package.json');
+    const raw = readFileSync(packageJsonPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === 'object' &&
+        parsed !== null &&
+        !Array.isArray(parsed) &&
+        typeof parsed.version === 'string') {
+        return parsed.version;
+    }
+    throw new Error(`@eslint-sh/eslint-plugin: package.json at ${packageJsonPath} is missing a string "version" field`);
+}
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB;IAChC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACxE,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,YAAY,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAExC,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QACtB,OAAQ,MAAkC,CAAC,OAAO,KAAK,QAAQ,EAC/D,CAAC;QACD,OAAQ,MAAkC,CAAC,OAAiB,CAAC;IAC/D,CAAC;IAED,MAAM,IAAI,KAAK,CACb,6CAA6C,eAAe,sCAAsC,CACnG,CAAC;AACJ,CAAC"}

package/docs/custom-rule-tutorial.md

@@ -0,0 +1,169 @@
+# Custom-rule tutorial: from a cookbook selector to a firing rule
+
+The [selector cookbook](./selectors.md) is a reference for selector strings; this page bridges
+one of those selectors to a complete, runnable ESLint rule: a `{ meta, create(context) }` module,
+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.js`](./examples/no-rm-rf-rule.js) 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.
+
+## 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.
+
+## 2. Write the rule module
+
+`docs/examples/no-rm-rf-rule.js`:
+
+```js
+/**
+ * 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
+ * exact file (not a reconstruction) and asserts the markdown fence matches
+ * it byte-for-byte, so the two can't silently drift.
+ *
+ * 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,
+ * exactly the pattern the cookbook's intro describes ("writing a rule as a
+ * selector string rather than a `create()` full of manual type checks" —
+ * here the selector does the node-type narrowing, `create()` only does the
+ * domain-specific check).
+ *
+ * Flag words are resolved with `sh-ast/analyze`'s `resolveWord` 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`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ * @see ../selectors.md — the `:command` launch class
+ */
+import { resolveWord } from 'sh-ast/analyze';
+
+const noRmRf = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow `rm -rf`/`rm -fr` invocations',
+    },
+    schema: [],
+    messages: {
+      rmRf: 'Avoid `rm -rf`; it silently deletes data with no confirmation. Prefer a scoped, reviewed removal.',
+    },
+  },
+  create(context) {
+    return {
+      ':command'(node) {
+        const args = node.args ?? [];
+        const words = args.map((arg) => {
+          const resolved = resolveWord(arg, { context: 'command-argument' });
+          return resolved.static ? resolved.text : null;
+        });
+
+        if (words[0] !== 'rm') {
+          return;
+        }
+
+        // `rm -- -rf` and `rm build -- -rf` are not `rm -rf` — everything
+        // after a `--` end-of-options marker is an operand (a filename),
+        // never a flag (POSIX Utility Syntax Guidelines, guideline 10).
+        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)),
+        );
+
+        if (isRecursiveForce) {
+          context.report({ node, loc: node.loc, messageId: 'rmRf' });
+        }
+      },
+    };
+  },
+};
+
+export default noRmRf;
+```
+
+A few things worth calling out:
+
+- 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
+  exactly like any other selector key such as `CallExpr` or `CallExpr[args.0.parts.0.value='jq']`.
+- `resolveWord(arg, { context: 'command-argument' })` — from `sh-ast/analyze` — is the correct way
+  to ask "is this word statically the string X": it returns `{ static: true, text }` for a bare or
+  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.
+- `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
+  message needs.
+
+## 3. Wire it into a flat config
+
+`docs/examples/eslint.config.mjs`:
+
+```js
+// eslint.config.mjs
+//
+// The custom-rule tutorial's exact flat-config wiring
+// (`../custom-rule-tutorial.md`, step 3). `test/custom-rule-tutorial.test.ts`
+// 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.
+import sh from '@eslint-sh/eslint-plugin'; // or the umbrella: import sh from 'eslint-sh'
+import noRmRf from './no-rm-rf-rule.js';
+
+export default [
+  {
+    files: ['**/*.sh', '**/*.bash'],
+    plugins: {
+      sh,
+      'my-rules': { rules: { 'no-rm-rf': noRmRf } },
+    },
+    language: 'sh/sh',
+    rules: {
+      'my-rules/no-rm-rf': 'error',
+    },
+  },
+];
+```
+
+- `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
+  module from step 2 under a name (`no-rm-rf`); any plugin key works, `'my-rules'` is just a
+  placeholder for your own project's or plugin's namespace.
+- `rules['my-rules/no-rm-rf']` turns the rule on, the same as any other ESLint rule entry.
+
+## 4. What "firing" looks like
+
+Given
+
+```sh
+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
+`docs/examples/eslint.config.mjs` shown in step 3.

package/docs/examples/eslint.config.mjs

@@ -0,0 +1,23 @@
+// eslint.config.mjs
+//
+// The custom-rule tutorial's exact flat-config wiring
+// (`../custom-rule-tutorial.md`, step 3). `test/custom-rule-tutorial.test.ts`
+// 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.
+import sh from '@eslint-sh/eslint-plugin'; // or the umbrella: import sh from 'eslint-sh'
+import noRmRf from './no-rm-rf-rule.js';
+
+export default [
+  {
+    files: ['**/*.sh', '**/*.bash'],
+    plugins: {
+      sh,
+      'my-rules': { rules: { 'no-rm-rf': noRmRf } },
+    },
+    language: 'sh/sh',
+    rules: {
+      'my-rules/no-rm-rf': 'error',
+    },
+  },
+];

package/docs/examples/no-rm-rf-rule.js

@@ -0,0 +1,74 @@
+/**
+ * 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
+ * exact file (not a reconstruction) and asserts the markdown fence matches
+ * it byte-for-byte, so the two can't silently drift.
+ *
+ * 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,
+ * exactly the pattern the cookbook's intro describes ("writing a rule as a
+ * selector string rather than a `create()` full of manual type checks" —
+ * here the selector does the node-type narrowing, `create()` only does the
+ * domain-specific check).
+ *
+ * Flag words are resolved with `sh-ast/analyze`'s `resolveWord` 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`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ * @see ../selectors.md — the `:command` launch class
+ */
+import { resolveWord } from 'sh-ast/analyze';
+
+const noRmRf = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow `rm -rf`/`rm -fr` invocations',
+    },
+    schema: [],
+    messages: {
+      rmRf: 'Avoid `rm -rf`; it silently deletes data with no confirmation. Prefer a scoped, reviewed removal.',
+    },
+  },
+  create(context) {
+    return {
+      ':command'(node) {
+        const args = node.args ?? [];
+        const words = args.map((arg) => {
+          const resolved = resolveWord(arg, { context: 'command-argument' });
+          return resolved.static ? resolved.text : null;
+        });
+
+        if (words[0] !== 'rm') {
+          return;
+        }
+
+        // `rm -- -rf` and `rm build -- -rf` are not `rm -rf` — everything
+        // after a `--` end-of-options marker is an operand (a filename),
+        // never a flag (POSIX Utility Syntax Guidelines, guideline 10).
+        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)),
+        );
+
+        if (isRecursiveForce) {
+          context.report({ node, loc: node.loc, messageId: 'rmRf' });
+        }
+      },
+    };
+  },
+};
+
+export default noRmRf;