@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/require-strict-mode.d.ts

@@ -0,0 +1,52 @@
+import type { ShellFile, ShellNodeOf } from '../language/syntax-view.js';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+import type { SetOptionChange } from './set-options.js';
+/**
+ * The rule's single options object.
+ *
+ * @internal
+ */
+export interface RequireStrictModeOptions {
+    /**
+     * The required prologue: either a `set` command (`"set -euo pipefail"`),
+     * whose enabled options become the requirement and whose text is what the
+     * autofix inserts, or the list of required long option names
+     * (`["errexit", "nounset"]`), for which the autofix inserts a `set` command
+     * spelled from that list. When omitted, it is `"set -eu"` for a file
+     * whose dialect is `posix` and `"set -euo pipefail"` for every other
+     * dialect.
+     */
+    readonly mode?: string | readonly string[];
+    /**
+     * When `true`, options passed to the shell on the shebang line
+     * (`#!/bin/bash -e`, `#!/usr/bin/env -S bash -euo pipefail`) count as
+     * enabled, so a shebang alone can satisfy the rule. Off by default, because
+     * those options are ignored when the script is run as `bash script.sh`.
+     */
+    readonly allowShebangOnly?: boolean;
+    /** How many top-level statements, from the top, the prologue may take to appear. */
+    readonly withinStatements?: number;
+}
+/**
+ * Whether `stmt` is a plain, foreground, top-level `set` command, and if so
+ * the option changes its arguments make (read through `sourceCode`, so a
+ * non-static argument ends the reading).
+ *
+ * @internal
+ */
+export declare function setStatementChanges(stmt: ShellNodeOf<'Stmt'>, sourceCode: ShellSourceCode): readonly SetOptionChange[];
+/**
+ * The options a file's prologue leaves enabled: the state after the first
+ * `withinStatements` top-level statements of `file`, plus the shebang's
+ * options when `allowShebangOnly` is set. This is the single definition of
+ * "what the prologue enables", shared with other rules (such as
+ * `no-unchecked-cd`) that need to know whether strict mode is in force.
+ *
+ * @internal
+ */
+export declare function prologueEnabledOptions(file: ShellFile, sourceCode: ShellSourceCode, config?: {
+    readonly allowShebangOnly?: boolean;
+    readonly withinStatements?: number;
+}): ReadonlySet<string>;
+/** Built-in rule `sh/require-strict-mode`. @internal */
+export declare const requireStrictMode: import("./define-shell-rule.js").ShellRule<[RequireStrictModeOptions], "missingStrictMode">;

package/dist/rules/require-strict-mode.js

@@ -0,0 +1,177 @@
+import { createRule } from './create-rule.js';
+import { SET_OPTION_NAMES, applySetOptionChanges, formatSetCommand, parseSetArguments, shebangOptionChanges, } from './set-options.js';
+import { lineBreakOf } from '../language/line-breaks.js';
+/**
+ * The prologue an unconfigured `mode` falls back to for every dialect except
+ * `posix`.
+ */
+const DEFAULT_PROLOGUE = 'set -euo pipefail';
+/**
+ * The prologue an unconfigured `mode` falls back to under the `posix`
+ * dialect: strict mode without `pipefail`, so the autofix never inserts a
+ * line that a pre-POSIX.1-2024 `sh` rejects. `pipefail` stays available
+ * there by configuring `mode`.
+ */
+const POSIX_DEFAULT_PROLOGUE = 'set -eu';
+/**
+ * The prologue used when `mode` is not configured, chosen by the file's
+ * dialect. Only `posix` differs; `bats` files run under Bash and keep the
+ * Bash default.
+ */
+function defaultPrologueFor(dialect) {
+    return dialect === 'posix' ? POSIX_DEFAULT_PROLOGUE : DEFAULT_PROLOGUE;
+}
+/** How many top-level statements `withinStatements` defaults to. */
+const DEFAULT_WITHIN_STATEMENTS = 5;
+/**
+ * Turns the `mode` option into a {@link StrictModeRequirement}. A string mode
+ * must be a `set` command whose arguments only enable known options (no `+`
+ * flags, no positional parameters); anything else is a configuration error,
+ * reported by throwing so ESLint surfaces it instead of linting against a
+ * requirement nobody wrote.
+ */
+function resolveRequirement(mode) {
+    if (typeof mode !== 'string') {
+        return { required: [...new Set(mode)], prologue: formatSetCommand(mode) };
+    }
+    const prologue = mode.trim();
+    const [command, ...args] = prologue.split(/\s+/u);
+    const parsed = parseSetArguments(args);
+    if (command !== 'set' ||
+        parsed.stoppedBy !== undefined ||
+        parsed.changes.length === 0 ||
+        parsed.changes.some((change) => !change.enable)) {
+        throw new TypeError(`sh/require-strict-mode: \`mode\` must be a \`set\` command that only enables options ` +
+            `(for example "${DEFAULT_PROLOGUE}") or a list of option names; got ${JSON.stringify(mode)}.`);
+    }
+    return { required: [...new Set(parsed.changes.map((change) => change.option))], prologue };
+}
+/**
+ * Whether `stmt` is a plain, foreground, top-level `set` command, and if so
+ * the option changes its arguments make (read through `sourceCode`, so a
+ * non-static argument ends the reading).
+ *
+ * @internal
+ */
+export function setStatementChanges(stmt, sourceCode) {
+    if (stmt.background)
+        return [];
+    const { cmd } = stmt;
+    if (cmd?.type !== 'CallExpr' || sourceCode.getCommandName(cmd) !== 'set')
+        return [];
+    const args = cmd.args.slice(1);
+    return parseSetArguments(args.map((word) => sourceCode.resolveWordText(word))).changes;
+}
+/**
+ * The options enabled after applying `seed`, then each statement's `set`
+ * changes in order.
+ */
+function enabledAfter(seed, statementChanges) {
+    const enabled = applySetOptionChanges(new Set(), seed);
+    for (const changes of statementChanges)
+        applySetOptionChanges(enabled, changes);
+    return enabled;
+}
+/**
+ * The options a file's prologue leaves enabled: the state after the first
+ * `withinStatements` top-level statements of `file`, plus the shebang's
+ * options when `allowShebangOnly` is set. This is the single definition of
+ * "what the prologue enables", shared with other rules (such as
+ * `no-unchecked-cd`) that need to know whether strict mode is in force.
+ *
+ * @internal
+ */
+export function prologueEnabledOptions(file, sourceCode, config = {}) {
+    const shebangChanges = config.allowShebangOnly === true ? shebangOptionChanges(sourceCode.text) : [];
+    const statements = file.stmts.slice(0, config.withinStatements ?? DEFAULT_WITHIN_STATEMENTS);
+    return enabledAfter(shebangChanges, statements.map((stmt) => setStatementChanges(stmt, sourceCode)));
+}
+/** Built-in rule `sh/require-strict-mode`. @internal */
+export const requireStrictMode = createRule({
+    name: 'require-strict-mode',
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'require the configured strict-mode options (`set -euo pipefail` by default, `set -eu` for POSIX) near the top of the file',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    mode: {
+                        oneOf: [
+                            { type: 'string', minLength: 1 },
+                            {
+                                type: 'array',
+                                items: { enum: [...SET_OPTION_NAMES] },
+                                minItems: 1,
+                                uniqueItems: true,
+                            },
+                        ],
+                    },
+                    allowShebangOnly: { type: 'boolean' },
+                    withinStatements: { type: 'integer', minimum: 1 },
+                },
+                additionalProperties: false,
+            },
+        ],
+        // `mode` has no static default: an unconfigured `mode` resolves per file
+        // from the dialect (see `defaultPrologueFor`), so it must stay absent here
+        // for the rule to tell "not configured" apart from a configured value.
+        defaultOptions: [
+            {
+                allowShebangOnly: false,
+                withinStatements: DEFAULT_WITHIN_STATEMENTS,
+            },
+        ],
+        messages: {
+            missingStrictMode: 'Enable strict mode with `{{prologue}}` within {{window}}; not enabled: {{missing}}.',
+        },
+    },
+    create(context) {
+        const [options] = context.options;
+        const { sourceCode } = context;
+        const { required, prologue } = resolveRequirement(options.mode ?? defaultPrologueFor(sourceCode.dialect));
+        const withinStatements = options.withinStatements ?? DEFAULT_WITHIN_STATEMENTS;
+        return {
+            File(node) {
+                const text = sourceCode.text;
+                const shebangChanges = options.allowShebangOnly === true ? shebangOptionChanges(text) : [];
+                const statements = node.stmts.slice(0, withinStatements);
+                const statementChanges = statements.map((stmt) => setStatementChanges(stmt, sourceCode));
+                const enabled = enabledAfter(shebangChanges, statementChanges);
+                const missing = required.filter((option) => !enabled.has(option));
+                if (missing.length === 0)
+                    return;
+                // With the prologue inserted as the new first statement, the window
+                // holds one fewer original statement. Fix only if that would pass.
+                const prologueChanges = required.map((option) => ({ option, enable: true }));
+                const fixedEnabled = enabledAfter([...shebangChanges, ...prologueChanges], statementChanges.slice(0, withinStatements - 1));
+                const fixSatisfies = required.every((option) => fixedEnabled.has(option));
+                context.report({
+                    loc: { line: 1, column: 1 },
+                    messageId: 'missingStrictMode',
+                    data: {
+                        prologue,
+                        window: withinStatements === 1
+                            ? 'the first statement'
+                            : `the first ${String(withinStatements)} statements`,
+                        missing: missing.join(', '),
+                    },
+                    fix: fixSatisfies
+                        ? (fixer) => {
+                            const eol = lineBreakOf(text);
+                            if (!text.startsWith('#!'))
+                                return fixer.insertTextBeforeRange([0, 0], prologue + eol);
+                            const shebangEnd = text.search(/\r\n|\n|\r/u);
+                            return shebangEnd === -1
+                                ? fixer.insertTextAfterRange([0, text.length], eol + prologue)
+                                : fixer.insertTextAfterRange([0, shebangEnd], eol + prologue);
+                        }
+                        : null,
+                });
+            },
+        };
+    },
+});

package/dist/rules/require-tty-guard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The options of `sh/require-tty-guard`.
+ *
+ * @internal
+ */
+export interface RequireTtyGuardOptions {
+    /** Replaces the default interactive commands (`read`, `select`). */
+    readonly commands?: readonly string[];
+}
+/** Message ids of this rule. @internal */
+export type RequireTtyGuardMessageId = 'unguardedInteractive' | 'wrapInTtyGuard';
+/** Built-in rule `sh/require-tty-guard`. @internal */
+export declare const requireTtyGuard: import("./define-shell-rule.js").ShellRule<[RequireTtyGuardOptions?], RequireTtyGuardMessageId>;

package/dist/rules/require-tty-guard.js

@@ -0,0 +1,318 @@
+/**
+ * `sh/require-tty-guard`: a command that waits for input from the terminal
+ * (`read`, `select`, or any configured command) must be guarded by a
+ * check that stdin is a terminal, or must have its input supplied explicitly.
+ *
+ * An unguarded interactive prompt hangs forever when a script runs without a
+ * terminal (CI, cron, an agent's tool call), and in automation it reads
+ * whatever happens to be on stdin. The rule is **purely syntactic**: it never
+ * tracks data or control flow, so its notion of "guarded" is deliberately
+ * shallow and exactly this:
+ *
+ * - **Guarded by a test.** The command is lexically inside the `then`/`else`
+ *   body of an `if` whose condition contains a TTY test, or it is the right
+ *   side of an `&&` whose left side contains one. A TTY test is `[ -t 0 ]`,
+ *   `test -t 0` or `[[ -t 0 ]]`; only file descriptor `0` counts. A guard
+ *   anywhere else (an earlier statement, a calling function, a `||` exit, a
+ *   `while` condition) is not seen.
+ * - **Input supplied explicitly.** The command, or any enclosing statement
+ *   (so `while read …; done < file` is covered), redirects fd 0 from a file,
+ *   here-document, or here-string; or it is the right side of a pipe; or it is
+ *   a `read -u N` from a descriptor other than 0.
+ *
+ * `select` is parsed as a loop, not a command, so it is recognized from the
+ * loop node. Command names are read through `ShellSourceCode.getCommandName`,
+ * so a dynamic command word is never matched.
+ *
+ * The suggestion wraps the offending statement in `if [ -t 0 ]; then … fi`.
+ * It is withheld when another command shares the line that opens the
+ * statement's here-document, because the statement's source range runs on to
+ * that here-document's terminator and would carry the other command into the
+ * guard.
+ */
+import { DashHdoc, Hdoc } from 'sh-ast/analyze';
+import { createRule } from './create-rule.js';
+import { lineBreakOf } from '../language/line-breaks.js';
+/** Registry name of this rule. */
+const RULE_NAME = 'require-tty-guard';
+/** The interactive commands checked when `commands` is not configured. */
+const DEFAULT_COMMANDS = ['read', 'select'];
+/**
+ * Operator codes of the faithful syntax tree (`sh-ast`'s `BinCmdOperator` and
+ * `RedirOperator` values, which the lint view preserves as numbers).
+ */
+const AND_STMT = 11;
+const OR_STMT = 12;
+const PIPE = 13;
+const PIPE_ALL = 14;
+const REDIRECT_INPUT_OPS = new Set([
+    65, // `<`
+    66, // `<>`
+    67, // `<&`
+    71, // `<<`
+    72, // `<<-`
+    73, // `<<<`
+]);
+const DUP_INPUT = 67;
+/** The `-t` unary test operator (`sh-ast`'s `TsFdTerm`). */
+const TS_FD_TERM = 123;
+/**
+ * Read options that consume an argument, so the next word is not a variable
+ * name or another option cluster.
+ */
+const READ_ARG_FLAGS = new Set(['a', 'd', 'i', 'n', 'N', 'p', 't', 'u']);
+/** The static text of `node` if it is a `Word` with a known value. */
+function textOf(sourceCode, node) {
+    return node?.type === 'Word' ? sourceCode.resolveWordText(node) : null;
+}
+/**
+ * Whether `call` is a `[ … -t 0 … ]` or `test … -t 0 …` command. `-t 0` must
+ * appear as two adjacent static words.
+ */
+function isCommandTtyTest(call, sourceCode) {
+    const name = sourceCode.getCommandName(call);
+    if (name !== '[' && name !== 'test')
+        return false;
+    const words = call.args.map((word) => textOf(sourceCode, word));
+    return words.some((word, i) => word === '-t' && words[i + 1] === '0');
+}
+/** Whether `test` is a `[[ -t 0 ]]` unary test. */
+function isClauseTtyTest(test, sourceCode) {
+    return test.op === TS_FD_TERM && textOf(sourceCode, test.x) === '0';
+}
+/** Whether `inner` lies within `outer`, by source range. */
+function within(inner, outer) {
+    return inner.range[0] >= outer[0] && inner.range[1] <= outer[1];
+}
+/** The source range covering a list of statements, or `null` if empty. */
+function listRange(stmts) {
+    if (stmts.length === 0)
+        return null;
+    return [stmts[0].range[0], stmts[stmts.length - 1].range[1]];
+}
+/**
+ * Whether a redirect on a statement feeds fd 0 from an explicit source:
+ * `< file`, `0< file`, `<<`, `<<<`, `<> file`, or `<&N` for `N` other than 0.
+ */
+function redirectsStdin(stmt, sourceCode) {
+    return stmt.redirs.some((redir) => {
+        if (!REDIRECT_INPUT_OPS.has(redir.op))
+            return false;
+        const fd = redir.n === undefined ? '0' : redir.n.value;
+        if (fd !== '0')
+            return false;
+        return redir.op !== DUP_INPUT || textOf(sourceCode, redir.word) !== '0';
+    });
+}
+/**
+ * Whether a `read` takes input from a descriptor other than 0 (`-u 3`,
+ * `-u3`, `-ru 3`). A non-static descriptor counts as non-zero, because the
+ * rule cannot show it is stdin. Option parsing stops at `--` or the first
+ * non-option word.
+ */
+function readsFromOtherFd(call, sourceCode) {
+    const words = call.args.slice(1);
+    for (let i = 0; i < words.length; i += 1) {
+        const text = textOf(sourceCode, words[i]);
+        if (text === null || !text.startsWith('-') || text === '-' || text === '--')
+            return false;
+        for (let j = 1; j < text.length; j += 1) {
+            const flag = text.charAt(j);
+            if (!READ_ARG_FLAGS.has(flag))
+                continue;
+            const rest = text.slice(j + 1);
+            if (flag === 'u') {
+                const fd = rest === '' ? textOf(sourceCode, words[i + 1]) : rest;
+                return fd !== '0';
+            }
+            if (rest === '')
+                i += 1;
+            break;
+        }
+    }
+    return false;
+}
+/**
+ * Whether the exit status of `stmt` steers control flow: it is a condition of
+ * `if`/`while`/`until`, or an operand of `&&`/`||`. Wrapping such a statement
+ * in `if … fi` would replace its status with the `if`'s (0 when the guard
+ * fails), changing which way the construct goes, so no suggestion is offered.
+ */
+function isControlFlowOperand(stmt, sourceCode) {
+    const parent = sourceCode.getParent(stmt);
+    if (parent === undefined)
+        return false;
+    if (parent.type === 'BinaryCmd')
+        return parent.op === AND_STMT || parent.op === OR_STMT;
+    if (parent.type === 'IfClause' || parent.type === 'WhileClause') {
+        return [...parent.cond, ...parent.condlast].includes(stmt);
+    }
+    return false;
+}
+/** Redirection operators that open a here-document (`<<`, `<<-`), whose body follows the line. */
+const HEREDOC_OPERATORS = new Set([Hdoc, DashHdoc]);
+/**
+ * Whether other source shares the line that opens one of `stmt`'s
+ * here-documents. A here-document's body follows that line, so the statement's
+ * range reaches the body's terminator and covers whatever else sits on the
+ * opener line (`read x 3<<EOF; echo hi`, a trailing comment): wrapping the
+ * range would put that source inside the guard, where it runs only on a
+ * terminal. A bare `;` after the opener belongs to the statement and does not
+ * count. The opener line is read from the end of the statement's inline
+ * tokens (its command, its redirections' operators and words), so the
+ * statement's own further redirections on that line are not foreign.
+ */
+function sharesHeredocOpenerLine(stmt, text) {
+    const heredocs = stmt.redirs.filter((redir) => HEREDOC_OPERATORS.has(redir.op));
+    if (heredocs.length === 0)
+        return false;
+    const inlineEnd = Math.max(...(stmt.cmd === undefined ? [] : [stmt.cmd.range[1]]), ...stmt.redirs.map((redir) => HEREDOC_OPERATORS.has(redir.op) ? (redir.word?.range[1] ?? redir.range[1]) : redir.range[1]));
+    const lineEnd = text.indexOf('\n', inlineEnd);
+    const tail = text.slice(inlineEnd, lineEnd === -1 ? text.length : lineEnd);
+    return !/^[ \t]*;?[ \t]*\r?$/u.test(tail);
+}
+/**
+ * The text that replaces `stmtText` (a statement starting at `start`) with
+ * the statement inside `if [ -t 0 ]; then … fi`.
+ *
+ * A statement that starts its own line and spans several is wrapped on lines
+ * of its own. Anywhere else no line break goes before the statement: an
+ * earlier command on the same line may have opened a here-document, whose
+ * body begins at the next line break, so one inserted there would make the
+ * rest of the wrapper part of that body. A line break goes before `fi` only
+ * when the statement ends with a here-document of its own, whose terminator
+ * must stay alone on its line.
+ */
+function wrapInGuard(text, start, stmtText, endsInHeredoc) {
+    const eol = lineBreakOf(text);
+    const startsLine = /^[ \t]*$/u.test(text.slice(text.lastIndexOf('\n', start - 1) + 1, start));
+    if (startsLine && stmtText.includes('\n'))
+        return `if [ -t 0 ]; then${eol}${stmtText}${eol}fi`;
+    return `if [ -t 0 ]; then ${stmtText}${endsInHeredoc ? eol : '; '}fi`;
+}
+/** Built-in rule `sh/require-tty-guard`. @internal */
+export const requireTtyGuard = createRule({
+    name: RULE_NAME,
+    meta: {
+        type: 'suggestion',
+        docs: {
+            description: 'Require interactive commands such as `read` to be guarded by `[ -t 0 ]`',
+        },
+        hasSuggestions: true,
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    commands: { type: 'array', items: { type: 'string', minLength: 1 } },
+                },
+                additionalProperties: false,
+            },
+        ],
+        messages: {
+            unguardedInteractive: '`{{command}}` waits for terminal input and hangs when stdin is not a terminal. Guard it with `[ -t 0 ]` or supply its input with a redirection.',
+            wrapInTtyGuard: 'Wrap the statement in `if [ -t 0 ]; then … fi`.',
+        },
+    },
+    create(context) {
+        const { sourceCode } = context;
+        const commands = new Set(context.options[0]?.commands ?? DEFAULT_COMMANDS);
+        // Interactive commands found in the file, checked once every guard is known.
+        const candidates = [];
+        const guards = [];
+        /** Whether any TTY test lies inside `range`. */
+        const guardIn = (range) => range !== null && guards.some((guard) => within(guard, range));
+        /** Whether `node` is a statement-list child inside a guarding `if`/`&&`. */
+        const isGuarded = (node) => {
+            let child = node;
+            for (let parent = sourceCode.getParent(child); parent; parent = sourceCode.getParent(child)) {
+                if (parent.type === 'IfClause') {
+                    const cond = listRange([...parent.cond, ...parent.condlast]);
+                    const inCond = cond !== null && within(child, cond);
+                    if (!inCond && guardIn(cond))
+                        return true;
+                }
+                else if (parent.type === 'BinaryCmd' && parent.op === AND_STMT) {
+                    if (parent.y === child && parent.x !== undefined && guardIn(parent.x.range))
+                        return true;
+                }
+                child = parent;
+            }
+            return false;
+        };
+        /** Whether stdin is supplied to `node` by a redirect or a pipe. */
+        const hasExplicitInput = (node) => {
+            let child = node;
+            for (let parent = sourceCode.getParent(child); parent; parent = sourceCode.getParent(child)) {
+                if (parent.type === 'Stmt' && redirectsStdin(parent, sourceCode))
+                    return true;
+                // A coprocess body reads the coprocess's own input pipe, never the
+                // terminal, so a terminal guard is meaningless there.
+                if (parent.type === 'CoprocClause')
+                    return true;
+                if (parent.type === 'BinaryCmd' &&
+                    (parent.op === PIPE || parent.op === PIPE_ALL) &&
+                    parent.y === child) {
+                    return true;
+                }
+                child = parent;
+            }
+            return false;
+        };
+        return {
+            CallExpr(node) {
+                if (isCommandTtyTest(node, sourceCode))
+                    guards.push(node);
+                const name = sourceCode.getCommandName(node);
+                if (name === null || !commands.has(name))
+                    return;
+                if (name === 'read' && readsFromOtherFd(node, sourceCode))
+                    return;
+                candidates.push({ node, name });
+            },
+            UnaryTest(node) {
+                if (isClauseTtyTest(node, sourceCode))
+                    guards.push(node);
+            },
+            ForClause(node) {
+                if (node.select && commands.has('select')) {
+                    candidates.push({ node, name: 'select' });
+                }
+            },
+            'File:exit'() {
+                for (const { node, name } of candidates) {
+                    if (hasExplicitInput(node) || isGuarded(node))
+                        continue;
+                    const stmt = sourceCode.getParent(node);
+                    // A statement that runs in the background cannot be wrapped without
+                    // changing what is backgrounded, so it gets no suggestion.
+                    // A statement sharing its here-document's opener line with another
+                    // command gets none either (see `sharesHeredocOpenerLine`).
+                    const wrappable = stmt?.type === 'Stmt' &&
+                        !stmt.background &&
+                        !isControlFlowOperand(stmt, sourceCode) &&
+                        !sharesHeredocOpenerLine(stmt, sourceCode.text);
+                    context.report({
+                        node,
+                        messageId: 'unguardedInteractive',
+                        data: { command: name },
+                        suggest: wrappable
+                            ? [
+                                {
+                                    messageId: 'wrapInTtyGuard',
+                                    fix: (fixer) => {
+                                        // A statement's own range also covers a trailing `;`, which
+                                        // must stay outside the wrapper, so the end is taken from
+                                        // the command and its redirections.
+                                        const end = Math.max(...(stmt.cmd === undefined ? [] : [stmt.cmd.range[1]]), ...stmt.redirs.map((redir) => redir.range[1]));
+                                        const body = wrapInGuard(sourceCode.text, stmt.range[0], sourceCode.text.slice(stmt.range[0], end), stmt.redirs.some((redir) => HEREDOC_OPERATORS.has(redir.op)));
+                                        return fixer.replaceTextRange([stmt.range[0], end], body);
+                                    },
+                                },
+                            ]
+                            : [],
+                    });
+                }
+            },
+        };
+    },
+});

package/dist/rules/resolve-declaration-convention.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Binding resolution for the declaration-convention extension point: the one
+ * place a rule finds out which {@link DeclarationConvention} the consumer has
+ * bound, if any.
+ *
+ * Every rule that consumes a convention calls
+ * {@link resolveDeclarationConvention} from its `create()`, so all of them
+ * agree on precedence, on what "not configured" means, and on how a
+ * misconfiguration is reported. The precedence is:
+ *
+ * 1. the rule's own `declarationConvention` option (its first options
+ *    object), so one rule can be pointed at a different convention. ESLint
+ *    flat config copies rule options with `structuredClone`, so a convention
+ *    whose methods are own properties is rejected there by ESLint itself
+ *    ("could not be cloned"), and a class instance arrives with its methods
+ *    stripped and fails the check below. In practice consumers bind through
+ *    settings;
+ * 2. the shared `settings.sh.declarationConvention`, bound once for every
+ *    consuming rule;
+ * 3. otherwise `null`: no convention is bound and the consuming rule is
+ *    inert — it reports nothing. Shipping a default would smuggle one
+ *    project's declaration policy into every project.
+ *
+ * Only an absent (`undefined`) value falls through to the next source. Any
+ * other value is the consumer's explicit choice and must be a convention; if
+ * it is not, resolution throws an error that names the offending setting, so
+ * the misconfiguration surfaces as a readable configuration message rather
+ * than a `TypeError` from deep inside a rule.
+ *
+ * The resolver is public so a rule pack can write its own consumer of the
+ * bound convention and get exactly the precedence, validation and error text
+ * the built-in consumers (`sh/no-undeclared-commands`,
+ * `sh/no-unused-declarations`) use, instead of re-implementing them.
+ */
+import type { SettingsConfig } from '@eslint/core';
+import type { DeclarationConvention } from '../declaration-conventions/declaration-convention.js';
+/**
+ * The slice of an ESLint rule context that binding resolution reads: the rule
+ * id (for error messages), its configured options, and the shared settings.
+ * Any rule `context` satisfies it, so a rule passes its own `context`.
+ *
+ * @public
+ */
+export interface DeclarationConventionBindingContext {
+    /** The rule id as configured (`pack/my-rule`), named in an option-binding error. */
+    readonly id: string;
+    /** The rule's configured options; the first may carry `declarationConvention`. */
+    readonly options: readonly unknown[];
+    /** The shared settings; `settings.sh.declarationConvention` is the usual binding. */
+    readonly settings: SettingsConfig;
+}
+/**
+ * Resolves the declaration convention bound for the rule running in
+ * `context`: the rule's `declarationConvention` option, else
+ * `settings.sh.declarationConvention`, else `null` (the rule is inert).
+ *
+ * Throws an `Error` naming the offending setting when the configured value is
+ * present but does not implement `declaredCommands` (or has a non-function
+ * `removeDeclaration`). The message names where the value came from and what
+ * it was, for example one beginning
+ * `Invalid settings.sh.declarationConvention: expected a declaration convention`
+ * and ending `but got string "jq".` Call it from `create()`, so the error
+ * surfaces as ESLint's
+ * configuration message for the file being linted.
+ *
+ * A rule that receives `null` should register no listeners: with no
+ * convention bound, a convention consumer has nothing to check.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   defineShellRule,
+ *   readDeclaredCommands,
+ *   resolveDeclarationConvention,
+ * } from '@eslint-sh/eslint-plugin';
+ *
+ * export const maxDeclaredCommands = defineShellRule({
+ *   meta: { schema: [], messages: { tooMany: 'Declare at most 5 commands.' } },
+ *   create(context) {
+ *     const convention = resolveDeclarationConvention(context);
+ *     if (convention === null) return {};
+ *     return {
+ *       File(node) {
+ *         // Validated declarations for the file `context` is linting.
+ *         if (readDeclaredCommands(convention, context).length > 5) {
+ *           context.report({ node, messageId: 'tooMany' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function resolveDeclarationConvention(context: DeclarationConventionBindingContext): DeclarationConvention | null;