@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/rules/compat/posix-absent-command.js

@@ -0,0 +1,134 @@
+/**
+ * How a POSIX-only compat rule finds a use of a command word POSIX sh lacks.
+ *
+ * Under `dialect: "posix"` the parser has no `[[` clause, `let` clause or
+ * similar: it reads `[[ a ]]`, `let n=1` and `source f` as ordinary commands,
+ * so the rules recognize them by the command they run. That reading is shared
+ * here so the three rules agree on what counts as a use:
+ *
+ * - **It is the effective command**, after following transparent wrappers,
+ *   which is what actually runs (`command let n=1` fails on dash as `let n=1`
+ *   does). `command -v let` asks a question instead of running `let`, and
+ *   resolves to no such command.
+ * - **A shell without the construct can reach it.** These constructs are
+ *   commands, not syntax, so a POSIX shell only fails when it runs one. A script
+ *   meant for `sh` can hold a branch for one shell, and dash never enters it:
+ *   `if [ -n "${BASH_VERSION-}" ]; then source ~/.bashrc; fi`. Such a use is not
+ *   reported, because the finding's claim would be false.
+ *
+ * Recognizing that branch is deliberately shallow and syntactic, like the guard
+ * in `require-tty-guard`: no dataflow, and only the shapes {@link isGuarded}
+ * lists, each testing one of `BASH_VERSION`, `KSH_VERSION` or `ZSH_VERSION`
+ * directly. Anything else, including a version captured in another variable,
+ * reports.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+/**
+ * The wrappers followed to find the command an invocation runs:
+ * `sh-ast/analyze`'s defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/** `sh-ast`'s `BinCmdOperator` codes for `&&` and `||`, which the lint view preserves. */
+const AND_STMT = 11;
+const OR_STMT = 12;
+/**
+ * The source text of a word that reads a shell's own version variable: `$X`,
+ * `${X}`, `${X-}` or `${X:-}`, quoted or not. dash sets none of these variables.
+ */
+const SHELL_VERSION_WORD = /^"?\$(?:\{(?:BASH|KSH|ZSH)_VERSION(?::?-)?\}|(?:BASH|KSH|ZSH)_VERSION)"?$/u;
+/**
+ * What `stmt` tests, when it is exactly `[ -n V ]`, `test -n V` (`set`) or the
+ * `-z` forms (`unset`) for a version variable `V`, not negated. Anything else
+ * is `undefined`.
+ */
+function shellVersionTest(sourceCode, stmt) {
+    if (stmt?.type !== 'Stmt' || stmt.negated || stmt.cmd?.type !== 'CallExpr')
+        return undefined;
+    const { args } = stmt.cmd;
+    const name = sourceCode.getCommandName(stmt.cmd);
+    if (args.length !== (name === '[' ? 4 : name === 'test' ? 3 : 0))
+        return undefined;
+    if (name === '[' && sourceCode.resolveWordText(args[3]) !== ']')
+        return undefined;
+    if (!SHELL_VERSION_WORD.test(sourceCode.getText(args[2])))
+        return undefined;
+    const operator = sourceCode.resolveWordText(args[1]);
+    if (operator === '-n')
+        return 'set';
+    return operator === '-z' ? 'unset' : undefined;
+}
+/**
+ * Whether `stmt` leaves the script or function unless a version variable is
+ * set: `[ -n V ] || exit` or `[ -z V ] && exit`, with `exit` or `return`.
+ */
+function leavesUnlessVersioned(sourceCode, stmt) {
+    if (stmt.type !== 'Stmt' || stmt.cmd?.type !== 'BinaryCmd')
+        return false;
+    const { op, x, y } = stmt.cmd;
+    const test = shellVersionTest(sourceCode, x);
+    if (!((op === OR_STMT && test === 'set') || (op === AND_STMT && test === 'unset')))
+        return false;
+    if (y?.cmd?.type !== 'CallExpr')
+        return false;
+    const name = sourceCode.getCommandName(y.cmd);
+    return name === 'exit' || name === 'return';
+}
+/**
+ * Whether only a shell that sets a version variable can run `node`, because it
+ * sits in one of these:
+ *
+ * - the `then` body of `if [ -n V ]`, or the `else` body of `if [ -z V ]`;
+ * - the right side of `[ -n V ] && …` or `[ -z V ] || …`;
+ * - a statement list, after an earlier `[ -n V ] || exit` or `[ -z V ] && exit`
+ *   in that list (the file, or a `{ … }` block such as a function body).
+ */
+function isGuarded(sourceCode, node) {
+    let child = node;
+    for (let parent = sourceCode.getParent(child); parent; parent = sourceCode.getParent(child)) {
+        if (parent.type === 'IfClause' && parent.cond.length === 1) {
+            const test = shellVersionTest(sourceCode, parent.cond[0]);
+            if (test === 'set' && parent.then.some((stmt) => stmt === child))
+                return true;
+            if (test === 'unset' && parent.else === child)
+                return true;
+        }
+        else if (parent.type === 'BinaryCmd' && parent.y === child) {
+            const test = shellVersionTest(sourceCode, parent.x);
+            if ((parent.op === AND_STMT && test === 'set') ||
+                (parent.op === OR_STMT && test === 'unset')) {
+                return true;
+            }
+        }
+        else if (parent.type === 'File' || parent.type === 'Block') {
+            const index = parent.stmts.findIndex((stmt) => stmt === child);
+            if (parent.stmts.slice(0, index).some((stmt) => leavesUnlessVersioned(sourceCode, stmt))) {
+                return true;
+            }
+        }
+        child = parent;
+    }
+    return false;
+}
+/**
+ * The word that names `command` in `node`, when `command` is what `node`
+ * effectively runs and a shell without it can reach `node` (see the module
+ * comment), or `undefined` otherwise. Reporting this word rather than the whole
+ * command matters for `[[`: the parser ends that command at the first `&&` or
+ * `||`, so the node would cover an arbitrary part of the expression.
+ *
+ * @internal
+ */
+export function reachableCommandWord(sourceCode, node, command) {
+    const invoked = sourceCode.resolveInvokedCommand(node, {
+        transparentWrappers: TRANSPARENT_WRAPPERS,
+    });
+    if (invoked?.effective.static !== true || invoked.effective.text !== command)
+        return undefined;
+    if (isGuarded(sourceCode, node))
+        return undefined;
+    return node.args[invoked.chainIndices.at(-1) ?? 0];
+}

package/dist/rules/compat/shopt-options.d.ts

@@ -0,0 +1,9 @@
+import type { ShellNode } from '../../language/syntax-view.js';
+import type { ShellRuleContext, ShellRuleVisitor } from '../define-shell-rule.js';
+/**
+ * Builds the listeners that call `report(word)` for each operand word of a
+ * `shopt -s` command whose static text is `option`.
+ *
+ * @internal
+ */
+export declare function shoptEnableVisitor<MessageIds extends string>(context: ShellRuleContext<[], MessageIds>, option: string, report: (word: ShellNode) => void): ShellRuleVisitor;

package/dist/rules/compat/shopt-options.js

@@ -0,0 +1,63 @@
+/**
+ * Shared detection of `shopt -s NAME`, for the compat rules that gate one
+ * `shopt` option (`lastpipe`, `globstar`).
+ *
+ * What is read: a `shopt` command (after transparent wrappers such as
+ * `builtin`) whose option words, up to the first operand, include `-s`
+ * (possibly inside a cluster such as `-sq`). Its operands are the option
+ * names it turns on. `shopt -u` turns options off (so does a `-u` beside the
+ * `-s`), `shopt -o` names `set -o` options, and an operand that is not a
+ * static word cannot be read, so none of those count.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { BUILTIN_WRAPPER } from '../transparent-wrappers.js';
+/**
+ * The wrappers followed to find the `shopt` command: `sh-ast/analyze`'s
+ * defaults (which include `command`) plus Bash's `builtin`.
+ */
+const TRANSPARENT_WRAPPERS = [
+    ...DEFAULT_TRANSPARENT_WRAPPERS,
+    BUILTIN_WRAPPER,
+];
+/**
+ * Builds the listeners that call `report(word)` for each operand word of a
+ * `shopt -s` command whose static text is `option`.
+ *
+ * @internal
+ */
+export function shoptEnableVisitor(context, option, report) {
+    const { sourceCode } = context;
+    return {
+        CallExpr(node) {
+            const invoked = sourceCode.resolveInvokedCommand(node, {
+                transparentWrappers: TRANSPARENT_WRAPPERS,
+            });
+            if (invoked?.effective.static !== true || invoked.effective.text !== 'shopt')
+                return;
+            // `chainIndices` index `node.args` directly, so slice before filtering.
+            const words = node.args.slice((invoked.chainIndices.at(-1) ?? 0) + 1);
+            let enables = false;
+            let disables = false;
+            let namesShellOptions = false;
+            let index = 0;
+            for (; index < words.length; index++) {
+                const text = sourceCode.resolveWordText(words[index]);
+                if (text === null || !/^-./u.test(text))
+                    break;
+                if (text === '--') {
+                    index++;
+                    break;
+                }
+                enables ||= text.includes('s');
+                disables ||= text.includes('u');
+                namesShellOptions ||= text.includes('o');
+            }
+            if (!enables || disables || namesShellOptions)
+                return;
+            for (const word of words.slice(index)) {
+                if (sourceCode.resolveWordText(word) === option)
+                    report(word);
+            }
+        },
+    };
+}

package/dist/rules/compat/version-gates.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The version-gate table every `compat/*` rule reads, and the one function
+ * that decides whether a gated feature is available to a file.
+ *
+ * A gate is data: a feature name mapped to the oldest Bash release that has
+ * it and whether POSIX sh has it. A new gate is a new row here, not new
+ * decision logic in a rule. The semantics of `languageOptions.shellVersion`
+ * and `languageOptions.dialect` for gating are defined once, by
+ * {@link isFeatureAvailable}, and documented for users in `docs/compat.md`.
+ *
+ * Every row is checked against real shells by `scripts/compat-matrix/run.sh`,
+ * which builds each Bash release and dash from source and runs one probe per
+ * feature on each; the observed results are the Evidence table in
+ * `docs/compat.md`. A changed row needs a probe there that shows the new
+ * boundary.
+ *
+ * @see https://tiswww.case.edu/php/chet/bash/NEWS — Bash release notes, the
+ *   source of every minimum version below
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap02.html
+ *   — POSIX Shell Command Language: section 2.4 (reserved words) and section
+ *   2.9.1.4 (command search) leave the results of the `doubleBracket`,
+ *   `letCommand` and `sourceCommand` rows unspecified
+ */
+import type { ShellLanguageOptions } from '../../language/shell-language-options.js';
+/**
+ * The name of a gated feature: a row of {@link FEATURE_GATES}.
+ *
+ * @internal
+ */
+export type CompatFeature = 'appendAllRedirect' | 'associativeArrays' | 'braceSequencePaddingStep' | 'caseAttributes' | 'caseFallthrough' | 'caseModification' | 'coproc' | 'declareGlobal' | 'doubleBracket' | 'epochVariables' | 'fdVariable' | 'globstar' | 'lastpipe' | 'letCommand' | 'mapfile' | 'nameref' | 'negativeArrayIndex' | 'nounsetEmptyArray' | 'parameterTransformation' | 'parameterTransformationCase' | 'parameterTransformationKeys' | 'parameterTransformationQuotedKeys' | 'pipeAll' | 'printfTimeFormat' | 'sourceCommand' | 'testVariableSet' | 'unicodeEscape' | 'unicodeEscapeLatin1' | 'waitNext';
+/**
+ * The two `languageOptions` fields gating reads. Both the raw and the
+ * normalized options satisfy it; an unset `dialect` means `"bash"`, as it
+ * does for the parser.
+ *
+ * @internal
+ */
+export type GateLanguageOptions = Pick<ShellLanguageOptions, 'dialect' | 'shellVersion'>;
+/**
+ * Whether `feature` is available to a file linted with `languageOptions`.
+ *
+ * - `dialect: "posix"`: available only when the gate's `posix` is `true`,
+ *   at any `shellVersion` (a Bash-only feature is never available).
+ * - `dialect: "bash"` (the default) or `"bats"`: an unset `shellVersion`
+ *   means the newest Bash, so every Bash feature is available. A set
+ *   `shellVersion` makes the feature available when it is the gate's `bash`
+ *   minimum or newer, comparing major then minor numerically (`"4"` is
+ *   `4.0`; `"3.10"` is newer than `"3.2"`). A `null` minimum is available at
+ *   every version.
+ * - `dialect: "mksh"` or `"zsh"`: the table carries no data for these
+ *   shells, and their `shellVersion` numbers their own releases, not Bash's,
+ *   so no gate applies and every feature is available.
+ *
+ * @internal
+ */
+export declare function isFeatureAvailable(feature: CompatFeature, languageOptions: GateLanguageOptions): boolean;
+/**
+ * Human-readable words for a gate's report: what the feature needs
+ * (`required`, such as `bash 4.0 or newer`) and what the file targets
+ * (`target`, such as `bash 3.2` or `POSIX sh`). Compat rule messages
+ * interpolate both as `{{required}}` and `{{target}}`.
+ *
+ * @internal
+ */
+export interface GateDescription {
+    readonly required: string;
+    readonly target: string;
+}
+/**
+ * Describes why `feature` is unavailable under `languageOptions`, for a
+ * report's message data. Call it only when {@link isFeatureAvailable} is
+ * `false`.
+ *
+ * @internal
+ */
+export declare function describeGate(feature: CompatFeature, languageOptions: GateLanguageOptions): GateDescription;

package/dist/rules/compat/version-gates.js

@@ -0,0 +1,205 @@
+/**
+ * Every gated feature, keyed by the name rules pass to
+ * {@link isFeatureAvailable}.
+ */
+const FEATURE_GATES = Object.freeze({
+    /**
+     * The `&>>` redirection, appending both stdout and stderr: Bash 4.0 NEWS,
+     * "the new `&>>` redirection operator". Bash 3.2 rejects it as a syntax
+     * error, so the whole script fails to parse.
+     */
+    appendAllRedirect: Object.freeze({ bash: '4.0', posix: false }),
+    /** `declare -A` / `typeset -A`: Bash 4.0 NEWS, "associative arrays". */
+    associativeArrays: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * Zero-padded (`{01..10}`) and stepped (`{1..10..2}`, `{a..e..2}`) brace
+     * sequences: Bash 4.0 NEWS (brace expansion gained zero-padding and an
+     * increment). Bash 3.2 expands the padded form without the padding and
+     * leaves the stepped form as a literal word; POSIX sh has no brace
+     * expansion.
+     */
+    braceSequencePaddingStep: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * The case-modifying expansions `${v^}`, `${v^^}`, `${v,}`, `${v,,}`: Bash
+     * 4.0 NEWS, "new case-modifying word expansions".
+     */
+    caseModification: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * The case-converting attributes `declare -l` / `-u` (and through
+     * `typeset` and `local`): Bash 4.0 NEWS, "new `-l` and `-u` options to
+     * declare/typeset/local".
+     */
+    caseAttributes: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * The `case` terminators `;&` (fall through) and `;;&` (test the next
+     * pattern): Bash 4.0 NEWS. POSIX.1-2024 adds `;&`, but dash 0.5.12 still
+     * rejects it, so a POSIX target does not have it.
+     */
+    caseFallthrough: Object.freeze({ bash: '4.0', posix: false }),
+    /** The `coproc` reserved word: Bash 4.0 NEWS, "a new `coproc` reserved word". */
+    coproc: Object.freeze({ bash: '4.0', posix: false }),
+    /**
+     * `declare -g` / `typeset -g`: Bash 4.2 NEWS, "declare/typeset has a new
+     * `-g` option".
+     */
+    declareGlobal: Object.freeze({ bash: '4.2', posix: false }),
+    /**
+     * The `[[ … ]]` conditional. POSIX section 2.4 lists `[[` and `]]` among the
+     * words whose results are unspecified; every Bash has it, and dash runs it
+     * as a command that does not exist.
+     */
+    doubleBracket: Object.freeze({ bash: null, posix: false }),
+    /** `$EPOCHSECONDS` and `$EPOCHREALTIME`: Bash 5.0 NEWS. */
+    epochVariables: Object.freeze({ bash: '5.0', posix: false }),
+    /**
+     * A `{varname}` redirection that allocates a descriptor into a variable
+     * (`exec {fd}>file`): Bash 4.1 NEWS. Bash 4.0 runs `{fd}` as a command.
+     */
+    fdVariable: Object.freeze({ bash: '4.1', posix: false }),
+    /** `shopt -s globstar` (recursive `**`): Bash 4.0 NEWS. */
+    globstar: Object.freeze({ bash: '4.0', posix: false }),
+    /** `shopt -s lastpipe`: Bash 4.2 NEWS, "a new `lastpipe` shell option". */
+    lastpipe: Object.freeze({ bash: '4.2', posix: false }),
+    /**
+     * The `let` builtin. POSIX section 2.9.1.4 lists `let` among the command
+     * names whose results are unspecified; every Bash has it, and dash has no
+     * such command.
+     */
+    letCommand: Object.freeze({ bash: null, posix: false }),
+    /** The `mapfile` builtin and its `readarray` synonym: Bash 4.0 NEWS. */
+    mapfile: Object.freeze({ bash: '4.0', posix: false }),
+    /** Namerefs, `declare -n` / `typeset -n` / `local -n`: Bash 4.3 NEWS. */
+    nameref: Object.freeze({ bash: '4.3', posix: false }),
+    /**
+     * Negative indexed-array subscripts (`${a[-1]}`, `a[-1]=x`): Bash 4.3 NEWS,
+     * "assigning, referencing, and unsetting elements of indexed arrays using
+     * negative subscripts". Bash 4.2 already reads `${a[-1]}`, but rejects the
+     * element length `${#a[-1]}`, assignment and unset, so 4.3 is the first
+     * release where every use works.
+     */
+    negativeArrayIndex: Object.freeze({ bash: '4.3', posix: false }),
+    /**
+     * Expanding an empty array (`"${a[@]}"`, `${a[*]}`) while `set -u` is on:
+     * the syntax is in every Bash, but through 4.3 it aborts with "unbound
+     * variable"; Bash 4.4 is the first release where it expands to nothing.
+     */
+    nounsetEmptyArray: Object.freeze({ bash: '4.4', posix: false }),
+    /**
+     * The parameter transformations `${v@Q}`, `${v@E}`, `${v@P}`, `${v@A}` and
+     * `${v@a}`: Bash 4.4 NEWS.
+     */
+    parameterTransformation: Object.freeze({ bash: '4.4', posix: false }),
+    /** The case transformations `${v@U}`, `${v@u}` and `${v@L}`: Bash 5.1 NEWS. */
+    parameterTransformationCase: Object.freeze({ bash: '5.1', posix: false }),
+    /** `${a[@]@k}`, key-value pairs as separate words: Bash 5.2 NEWS. */
+    parameterTransformationKeys: Object.freeze({ bash: '5.2', posix: false }),
+    /** `${a[@]@K}`, quoted key-value pairs: Bash 5.1 NEWS. */
+    parameterTransformationQuotedKeys: Object.freeze({ bash: '5.1', posix: false }),
+    /**
+     * The `|&` pipe, shorthand for `2>&1 |`: Bash 4.0 NEWS. Bash 3.2 rejects
+     * it as a syntax error.
+     */
+    pipeAll: Object.freeze({ bash: '4.0', posix: false }),
+    /** `printf`'s `%(fmt)T` date format: Bash 4.2 NEWS. */
+    printfTimeFormat: Object.freeze({ bash: '4.2', posix: false }),
+    /**
+     * The `source` builtin, Bash's name for `.`. POSIX section 2.9.1.4 lists
+     * `source` among the command names whose results are unspecified; every Bash
+     * has it, and dash has no such command.
+     */
+    sourceCommand: Object.freeze({ bash: null, posix: false }),
+    /**
+     * The `-v name` test (`[[ -v x ]]`, `test -v x`, `[ -v x ]`): Bash 4.2
+     * NEWS. In older Bash, `[[ -v x ]]` is a syntax error.
+     */
+    testVariableSet: Object.freeze({ bash: '4.2', posix: false }),
+    /**
+     * The `\u`/`\U` escapes in `$'…'` strings: Bash 4.2 NEWS. Earlier releases
+     * leave the escape as literal text. See `unicodeEscapeLatin1` for the one
+     * range the 4.2 release decodes wrongly.
+     */
+    unicodeEscape: Object.freeze({ bash: '4.2', posix: false }),
+    /**
+     * A `\u`/`\U` escape for a code point from U+0080 to U+00FF: the Bash 4.2
+     * release tarball writes these as a single Latin-1 byte even in a UTF-8
+     * locale (observed: `e9` for U+00E9, where UTF-8 is `c3 a9`), while every
+     * other code point is UTF-8. Bash 4.3 is the first release that writes all
+     * of them as UTF-8.
+     */
+    unicodeEscapeLatin1: Object.freeze({ bash: '4.3', posix: false }),
+    /** `wait -n`, waiting for the next job to finish: Bash 4.3 NEWS. */
+    waitNext: Object.freeze({ bash: '4.3', posix: false }),
+});
+/**
+ * Splits a `MAJOR[.MINOR]` string into numbers, so `"4"` is `[4, 0]` and
+ * `"3.10"` is `[3, 10]`. Returns `undefined` for any other shape; the
+ * language's option validation already rejects those, so the gate never
+ * sees one from a real config.
+ */
+function parseVersion(version) {
+    if (!/^\d+(?:\.\d+)?$/u.test(version))
+        return undefined;
+    const [major, minor = '0'] = version.split('.');
+    return [Number(major), Number(minor)];
+}
+/**
+ * Compares two `MAJOR[.MINOR]` versions numerically, major first, then minor:
+ * negative when `a` is older, `0` when equal, positive when `a` is newer. So
+ * `"3.10"` is newer than `"3.2"`, and `"4"` equals `"4.0"`.
+ */
+function compareVersions(a, b) {
+    return a[0] !== b[0] ? a[0] - b[0] : a[1] - b[1];
+}
+/**
+ * The dialects whose `shellVersion` is a Bash version. `bats` test files run
+ * under Bash, so they are gated exactly like `bash` files.
+ */
+const BASH_DIALECTS = new Set(['bash', 'bats']);
+/**
+ * Whether `feature` is available to a file linted with `languageOptions`.
+ *
+ * - `dialect: "posix"`: available only when the gate's `posix` is `true`,
+ *   at any `shellVersion` (a Bash-only feature is never available).
+ * - `dialect: "bash"` (the default) or `"bats"`: an unset `shellVersion`
+ *   means the newest Bash, so every Bash feature is available. A set
+ *   `shellVersion` makes the feature available when it is the gate's `bash`
+ *   minimum or newer, comparing major then minor numerically (`"4"` is
+ *   `4.0`; `"3.10"` is newer than `"3.2"`). A `null` minimum is available at
+ *   every version.
+ * - `dialect: "mksh"` or `"zsh"`: the table carries no data for these
+ *   shells, and their `shellVersion` numbers their own releases, not Bash's,
+ *   so no gate applies and every feature is available.
+ *
+ * @internal
+ */
+export function isFeatureAvailable(feature, languageOptions) {
+    const gate = FEATURE_GATES[feature];
+    const dialect = languageOptions.dialect ?? 'bash';
+    if (dialect === 'posix')
+        return gate.posix;
+    if (!BASH_DIALECTS.has(dialect))
+        return true;
+    const { shellVersion } = languageOptions;
+    if (shellVersion === undefined || gate.bash === null)
+        return true;
+    const target = parseVersion(shellVersion);
+    const minimum = parseVersion(gate.bash);
+    if (target === undefined || minimum === undefined)
+        return true;
+    return compareVersions(target, minimum) >= 0;
+}
+/**
+ * Describes why `feature` is unavailable under `languageOptions`, for a
+ * report's message data. Call it only when {@link isFeatureAvailable} is
+ * `false`.
+ *
+ * @internal
+ */
+export function describeGate(feature, languageOptions) {
+    const gate = FEATURE_GATES[feature];
+    const required = gate.bash === null ? 'bash' : `bash ${gate.bash} or newer`;
+    const target = (languageOptions.dialect ?? 'bash') === 'posix'
+        ? 'POSIX sh'
+        : `bash ${languageOptions.shellVersion ?? ''}`.trim();
+    return { required, target };
+}

package/dist/rules/create-rule.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The factory for this plugin's built-in rules: the public
+ * {@link defineShellRule} plus the one piece of metadata that only built-in
+ * rules share.
+ *
+ * `meta.docs.url` is derived from the rule name and always points at the
+ * rule's committed docs page, so the link a user follows from a lint report
+ * can never be hand-mistyped or left stale after a rename. Everything else —
+ * `meta.languages: ["sh/sh"]` and the shell-typed context, nodes and visitor —
+ * comes from `defineShellRule`, so built-in and third-party rules share one
+ * implementation of that guarantee.
+ *
+ * This module is internal (not re-exported from the package entry point): the
+ * docs URL scheme is this repository's. Rule packs use `defineShellRule` and
+ * write their own `meta.docs.url`.
+ */
+import type { RulesMetaDocs } from '@eslint/core';
+import type { ShellRule, ShellRuleContext, ShellRuleMeta, ShellRuleVisitor } from './define-shell-rule.js';
+/**
+ * The canonical documentation URL for the built-in rule `name`. This is the
+ * single place the URL scheme is spelled; the factory uses it to fill
+ * `meta.docs.url`, and the docs-page tests use it to check each registered
+ * rule points at its own committed page.
+ *
+ * @internal
+ */
+export declare function ruleDocsUrl(name: string): string;
+/**
+ * The documentation URL for `page`, a path relative to this package's `docs/`
+ * directory (`wrapper-rules.md` is the committed file
+ * `packages/eslint-plugin/docs/wrapper-rules.md`). Used for rules that are not
+ * in the registry, which have no `docs/rules/<name>.md` page of their own.
+ *
+ * @internal
+ */
+export declare function packageDocsUrl(page: string): string;
+/**
+ * The `meta.docs` an author writes: everything ESLint accepts except `url`,
+ * which the factory derives from the rule name. Typed `never` so supplying a
+ * URL by hand is a compile error rather than a silently-overwritten value.
+ *
+ * @internal
+ */
+export type BuiltInRuleDocs = Omit<RulesMetaDocs, 'url'> & {
+    readonly url?: never;
+};
+/**
+ * The `meta` a built-in rule writes: {@link ShellRuleMeta} (so the language
+ * fields are already forbidden), with `docs` narrowed to
+ * {@link BuiltInRuleDocs} because the factory derives `docs.url`.
+ *
+ * @internal
+ */
+export type BuiltInRuleMeta<RuleOptions extends unknown[], MessageIds extends string> = Omit<ShellRuleMeta<RuleOptions, MessageIds>, 'docs'> & {
+    readonly docs?: BuiltInRuleDocs;
+};
+/**
+ * What an author hands to {@link createRule}: the rule's registry name (used
+ * to derive its docs URL), its author-owned metadata, and its `create()`.
+ *
+ * @internal
+ */
+export interface BuiltInRuleSpec<RuleOptions extends unknown[], MessageIds extends string> {
+    /**
+     * The rule's name without the plugin namespace (`require-shebang`, not
+     * `sh/require-shebang`). For a built-in rule it must equal the rule's key in
+     * the registry and the basename of its docs page.
+     */
+    readonly name: string;
+    /**
+     * The docs URL of a rule that is not in the registry. A rule made by one of
+     * this package's public factories (for example `createWrapperRule`) has no
+     * `docs/rules/<name>.md` page: it links its factory's page
+     * ({@link packageDocsUrl}), or the page its rule pack supplies. Omit it for
+     * a built-in rule, whose page is always `docs/rules/<name>.md`.
+     */
+    readonly docsUrl?: string;
+    readonly meta: BuiltInRuleMeta<RuleOptions, MessageIds>;
+    /** Builds the rule's listeners for one file; receives the shell-typed context. */
+    readonly create: (context: ShellRuleContext<RuleOptions, MessageIds>) => ShellRuleVisitor;
+}
+/**
+ * Builds a built-in shell rule from its spec with {@link defineShellRule},
+ * after setting `meta.docs.url` to the rule's docs page ({@link ruleDocsUrl},
+ * or the spec's `docsUrl` for a rule outside the registry). The URL is
+ * written after the author's `docs`, so even an untyped caller cannot
+ * override it; `defineShellRule` does the same for `meta.languages`.
+ *
+ * @internal
+ */
+export declare function createRule<RuleOptions extends unknown[] = [], MessageIds extends string = string>(spec: BuiltInRuleSpec<RuleOptions, MessageIds>): ShellRule<RuleOptions, MessageIds>;

package/dist/rules/create-rule.js

@@ -0,0 +1,51 @@
+import { defineShellRule } from './define-shell-rule.js';
+/**
+ * Where this package's shipped docs live in the source repository: the
+ * committed `packages/eslint-plugin/docs/` directory.
+ */
+const PACKAGE_DOCS_BASE_URL = 'https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/';
+/**
+ * Where built-in rule docs pages live in the source repository. A rule named
+ * `foo` is documented at `<this>/foo.md`, i.e. the committed file
+ * `packages/eslint-plugin/docs/rules/foo.md`.
+ */
+const RULE_DOCS_BASE_URL = `${PACKAGE_DOCS_BASE_URL}rules/`;
+/**
+ * The canonical documentation URL for the built-in rule `name`. This is the
+ * single place the URL scheme is spelled; the factory uses it to fill
+ * `meta.docs.url`, and the docs-page tests use it to check each registered
+ * rule points at its own committed page.
+ *
+ * @internal
+ */
+export function ruleDocsUrl(name) {
+    return `${RULE_DOCS_BASE_URL}${name}.md`;
+}
+/**
+ * The documentation URL for `page`, a path relative to this package's `docs/`
+ * directory (`wrapper-rules.md` is the committed file
+ * `packages/eslint-plugin/docs/wrapper-rules.md`). Used for rules that are not
+ * in the registry, which have no `docs/rules/<name>.md` page of their own.
+ *
+ * @internal
+ */
+export function packageDocsUrl(page) {
+    return `${PACKAGE_DOCS_BASE_URL}${page}`;
+}
+/**
+ * Builds a built-in shell rule from its spec with {@link defineShellRule},
+ * after setting `meta.docs.url` to the rule's docs page ({@link ruleDocsUrl},
+ * or the spec's `docsUrl` for a rule outside the registry). The URL is
+ * written after the author's `docs`, so even an untyped caller cannot
+ * override it; `defineShellRule` does the same for `meta.languages`.
+ *
+ * @internal
+ */
+export function createRule(spec) {
+    const { name, docsUrl, meta, create } = spec;
+    const url = docsUrl ?? ruleDocsUrl(name);
+    return defineShellRule({
+        meta: { ...meta, docs: { ...meta.docs, url } },
+        create,
+    });
+}