@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/dist/rules/create-wrapper-rule.js

@@ -0,0 +1,407 @@
+/**
+ * `createWrapperRule`: the public factory for "command X must be run through
+ * wrapper Y" rules, such as network calls that must go through a retry or
+ * audit wrapper.
+ *
+ * Which commands need a wrapper, and which wrapper, is project policy, so this
+ * package ships no wrapper name. A rule pack binds both by calling the factory
+ * (`createWrapperRule({ commands: ['curl'], wrapper: 'with-retry' })`), and
+ * `sh/require-network-wrapper` is the built-in instance whose wrapper comes
+ * from the user's rule options.
+ *
+ * "Run through" is decided from `sh-ast/analyze`'s transparent-wrapper
+ * resolution, never by reading words locally: each command site's argv0 is
+ * followed through the default wrapper table (`sudo`, `env`, `nohup`, …), the
+ * bound wrapper, and any command with modeled subcommands, and the resulting
+ * chain says what runs and what it runs inside. A listed command is wrapped
+ * exactly when the bound wrapper appears earlier in that chain, so
+ * `retry curl x` and `retry sudo curl x` are wrapped, while `sudo curl x` and
+ * the `curl` in `retry echo "$(curl x)"` are not.
+ *
+ * Names are matched by basename when a static command word contains a slash,
+ * so a path cannot bypass the policy: `/usr/bin/curl x` is `curl`, and
+ * `/usr/local/bin/retry curl x` is `curl` run through `retry`. This holds for
+ * listed commands, the bound wrapper, and every transparent wrapper followed
+ * (`/usr/bin/sudo curl x` is `curl` run through `sudo`).
+ *
+ * A call to a function the file defines (anywhere in it) is not the external
+ * command, so a listed command word that names one is not reported; a listed
+ * command behind a wrapper (`command curl x`) runs the external command and
+ * still is. Invocations a pack names in `localInvocations` act only locally
+ * and are not reported either.
+ *
+ * Facts that cannot be known statically are never guessed: a site whose chain
+ * stops at a dynamic word or an unrecognized wrapper flag before reaching a
+ * listed command does not report, and neither does a subcommand that is not
+ * static. Commands inside command strings (`bash -c '…'`) are not commands to
+ * this analysis and are out of scope.
+ */
+import { DEFAULT_TRANSPARENT_WRAPPERS } from 'sh-ast/analyze';
+import { definedFunctionNames } from '../command-harvest/harvest-commands.js';
+import { createRule, packageDocsUrl } from './create-rule.js';
+/**
+ * The messages every wrapper rule reports with. Shared so that a rule which
+ * delegates to the factory (`sh/require-network-wrapper`) declares exactly the
+ * messages the factory's listeners report.
+ *
+ * @internal
+ */
+export const WRAPPER_RULE_MESSAGES = {
+    unwrappedCommand: '`{{command}}` must be run through `{{wrapper}}`.',
+};
+/**
+ * The rule name `createRule` receives for every factory-made rule. A
+ * factory-made rule is not in the registry and always passes its own
+ * `docsUrl`, so the name is never used to derive a URL.
+ */
+const WRAPPER_RULE_NAME = 'wrapper-rule';
+/** The default `meta.docs.url` of a factory-made rule: the page documenting the factory. */
+const WRAPPER_RULES_DOCS_URL = packageDocsUrl('wrapper-rules.md');
+/**
+ * `name` when it is in `names`; otherwise, when `name` contains a slash, its
+ * basename when that is in `names`; otherwise `null`. This is the one place a
+ * command word is compared with a configured name, so a path to a configured
+ * command (`/usr/bin/curl`, `./bin/curl`) can never bypass the policy.
+ */
+function matchName(name, names) {
+    if (names.has(name))
+        return name;
+    const slash = name.lastIndexOf('/');
+    if (slash === -1)
+        return null;
+    const base = name.slice(slash + 1);
+    return names.has(base) ? base : null;
+}
+/** `true` when `value` is a non-null, non-array object. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `true` when `value` is a non-empty string. */
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/** `true` when `value` is an array of non-empty strings. */
+function isStringArray(value) {
+    return (Array.isArray(value) &&
+        value.every((item) => typeof item === 'string' && item.length > 0));
+}
+/**
+ * Checks `config` and builds its lookup form. Throws `TypeError` naming the
+ * offending field, so a malformed binding fails when a rule pack is loaded
+ * rather than in the middle of linting a file.
+ */
+function compileWrapperRule(config) {
+    const { commands, wrapper, subcommands = {}, localInvocations = {}, docs = {}, } = config;
+    if (!isStringArray(commands)) {
+        throw new TypeError('createWrapperRule: `commands` must be an array of non-empty strings');
+    }
+    for (const field of ['url', 'description']) {
+        if (docs[field] !== undefined && !isNonEmptyString(docs[field])) {
+            throw new TypeError(`createWrapperRule: \`docs.${field}\` must be a non-empty string`);
+        }
+    }
+    let wrapperSpec;
+    if (typeof wrapper === 'string' && wrapper.length > 0) {
+        wrapperSpec = DEFAULT_TRANSPARENT_WRAPPERS.find((spec) => spec.names.includes(wrapper)) ?? {
+            names: [wrapper],
+        };
+    }
+    else if (typeof wrapper === 'object' &&
+        isStringArray(wrapper.names) &&
+        wrapper.names.length > 0) {
+        wrapperSpec = wrapper;
+    }
+    else {
+        throw new TypeError('createWrapperRule: `wrapper` must be a non-empty string or a WrapperSpec with non-empty `names`');
+    }
+    const subcommandSpecs = [];
+    const subcommandNames = new Map();
+    for (const [command, restriction] of Object.entries(subcommands)) {
+        if (!isStringArray(restriction.names) || restriction.names.length === 0) {
+            throw new TypeError(`createWrapperRule: \`subcommands.${command}.names\` must be a non-empty array of non-empty strings`);
+        }
+        subcommandNames.set(command, new Set(restriction.names));
+        // Modeling the command as a transparent wrapper makes `resolveArgv0`
+        // locate its subcommand exactly as it locates a wrapped command: the
+        // declared options are skipped, and an undeclared flag stops the chain.
+        subcommandSpecs.push({
+            names: [command],
+            ...(restriction.noArgFlags && { noArgFlags: restriction.noArgFlags }),
+            ...(restriction.argFlags && { argFlags: restriction.argFlags }),
+            ...(restriction.stopsChainFlags && { stopsChainFlags: restriction.stopsChainFlags }),
+        });
+    }
+    for (const [label, local] of Object.entries(localInvocations)) {
+        const where = `localInvocations.${label}`;
+        if (!isRecord(local)) {
+            throw new TypeError(`createWrapperRule: \`${where}\` must be an object`);
+        }
+        const { argLists, localOperand } = local;
+        if (argLists !== undefined &&
+            !(Array.isArray(argLists) &&
+                argLists.every((list) => Array.isArray(list) && isStringArray(list)))) {
+            throw new TypeError(`createWrapperRule: \`${where}.argLists\` must be an array of arrays of non-empty strings`);
+        }
+        if (localOperand === undefined)
+            continue;
+        if (!isRecord(localOperand)) {
+            throw new TypeError(`createWrapperRule: \`${where}.localOperand\` must be an object`);
+        }
+        for (const field of ['localPrefixes', 'noArgFlags', 'argFlags']) {
+            const value = localOperand[field];
+            const valid = field === 'localPrefixes'
+                ? isStringArray(value)
+                : value === undefined || isStringArray(value);
+            if (!valid) {
+                throw new TypeError(`createWrapperRule: \`${where}.localOperand.${field}\` must be an array of non-empty strings`);
+            }
+        }
+    }
+    // `resolveArgv0` uses the first entry whose names match, so an entry this
+    // rule supplies replaces any default entry with the same name rather than
+    // competing with it.
+    const supplied = [wrapperSpec, ...subcommandSpecs];
+    const suppliedNames = new Set(supplied.flatMap((spec) => spec.names));
+    const transparentWrappers = [
+        ...supplied,
+        ...DEFAULT_TRANSPARENT_WRAPPERS.filter((spec) => !spec.names.some((name) => suppliedNames.has(name))),
+    ];
+    const wrapperLabel = wrapperSpec.names.join('` or `');
+    const listed = commands.map((command) => `\`${command}\``).join(', ');
+    return {
+        commands: new Set(commands),
+        docsUrl: docs.url ?? WRAPPER_RULES_DOCS_URL,
+        description: docs.description ?? `Require ${listed} to be run through \`${wrapperLabel}\``,
+        wrapperNames: new Set(wrapperSpec.names),
+        wrapperLabel,
+        subcommands: subcommandNames,
+        localInvocations: new Map(Object.entries(localInvocations)),
+        transparentWrappers,
+    };
+}
+/** The static text of a chain word, or `null` when it is not static. */
+function staticText(word) {
+    return word?.static === true ? word.text : null;
+}
+/**
+ * Resolves `site`'s chain through `compiled`'s wrapper table, following a
+ * wrapper invoked by path as the wrapper it names.
+ *
+ * `resolveArgv0` matches wrapper names exactly, so a path to a wrapper
+ * (`/usr/local/bin/retry`) ends the chain as if it were the command run. When
+ * the chain ends at a static word with a slash whose basename names a table
+ * entry, the site is resolved again with that entry also recognized under the
+ * exact path text, so its options and wrapped command are located by the
+ * same analysis. Each pass adds one new name drawn from the site's own argv,
+ * so the loop ends.
+ */
+function resolveChain(compiled, site) {
+    let table = compiled.transparentWrappers;
+    for (;;) {
+        const resolution = site.resolveInvokedCommand({ transparentWrappers: table });
+        const last = staticText(resolution.chain.at(-1));
+        if (last === null || table.some((spec) => spec.names.includes(last)))
+            return resolution;
+        const spec = compiled.transparentWrappers.find((entry) => matchName(last, new Set(entry.names)) !== null);
+        if (spec === undefined)
+            return resolution;
+        table = [{ ...spec, names: [last] }, ...table];
+    }
+}
+/**
+ * Builds the listeners that enforce `compiled` for one file. Every command
+ * site in the file, including those inside command substitutions and
+ * functions, is checked once.
+ */
+function wrapperRuleListeners(compiled, context) {
+    const { sourceCode } = context;
+    return {
+        File() {
+            let functions;
+            for (const site of sourceCode.getCommandSites()) {
+                const resolution = resolveChain(compiled, site);
+                const finding = findListedCommand(compiled, resolution.chain);
+                if (finding === null || finding.wrapped)
+                    continue;
+                // A function the file defines runs instead of the external command of
+                // the same name, wherever it is defined. Only the command word itself
+                // is looked up as a function; behind a wrapper (`command curl`) the
+                // external command runs.
+                if (finding.index === 0) {
+                    functions ??= definedFunctionNames(sourceCode);
+                    if (functions.has(finding.word))
+                        continue;
+                }
+                if (isLocalInvocation(compiled, finding, resolution, site))
+                    continue;
+                context.report({
+                    node: site.node,
+                    messageId: 'unwrappedCommand',
+                    data: { command: finding.command, wrapper: compiled.wrapperLabel },
+                });
+            }
+        },
+    };
+}
+/**
+ * The first operand of `args`, once every option of `operand` has been read,
+ * or `null` when the invocation cannot be shown to use only that operand.
+ *
+ * The whole argument list up to a literal `--` is scanned, not just up to the
+ * operand, because commands such as `git clone` accept options after their
+ * operands (`git clone ./x --recurse-submodules`). Every option must be one
+ * the entry declares; an undeclared option anywhere before `--`, a dynamic word
+ * where an option or the first operand would stand, or a missing or dynamic
+ * operand gives `null`. Words after `--` are operands and are not read.
+ * `args` holds each word's static text, or `null` for a dynamic word. A dynamic
+ * word is tolerated as an option's value (`--depth "$n"`) and after the first
+ * operand (`git clone ./x "$dest"`), where it cannot change which operand
+ * comes first.
+ */
+function firstOperand(args, operand) {
+    const noArg = new Set(operand.noArgFlags ?? []);
+    const withArg = new Set(operand.argFlags ?? []);
+    let first;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === null) {
+            if (first === undefined)
+                return null;
+            continue;
+        }
+        if (arg === '--') {
+            return first === undefined ? (args[i + 1] ?? null) : first;
+        }
+        if (!arg.startsWith('-') || arg === '-') {
+            first ??= arg;
+            continue;
+        }
+        if (noArg.has(arg))
+            continue;
+        if (withArg.has(arg)) {
+            i++;
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        if (arg.startsWith('--') && equals !== -1 && withArg.has(arg.slice(0, equals)))
+            continue;
+        // A short option with its value attached (`-j4`).
+        if (!arg.startsWith('--') && arg.length > 2 && withArg.has(arg.slice(0, 2)))
+            continue;
+        return null;
+    }
+    return first ?? null;
+}
+/**
+ * Whether the invocation `finding` describes only acts locally, according to
+ * the {@link WrapperRuleLocalInvocation} bound to its command. Anything
+ * not provably local is not local.
+ */
+function isLocalInvocation(compiled, finding, resolution, site) {
+    const local = compiled.localInvocations.get(finding.command);
+    if (local === undefined)
+        return false;
+    const start = resolution.chainIndices[finding.lastIndex];
+    const args = site.argv.slice(start + 1).map((word) => (word.static ? word.text : null));
+    if (local.argLists?.some((list) => list.length === args.length && list.every((a, i) => a === args[i]))) {
+        return true;
+    }
+    if (local.localOperand === undefined)
+        return false;
+    const source = firstOperand(args, local.localOperand);
+    return (source !== null && local.localOperand.localPrefixes.some((prefix) => source.startsWith(prefix)));
+}
+/**
+ * Finds the first listed command in `chain` (outermost first) that counts,
+ * and whether the wrapper encloses it. Command and wrapper words are compared
+ * with {@link matchName}. A command restricted to subcommands counts only
+ * when the next chain word is exactly one of them. The scan stops at the
+ * first word that is not static: `resolveArgv0` never resolves past one.
+ */
+function findListedCommand(compiled, chain) {
+    for (const [index, word] of chain.entries()) {
+        const text = staticText(word);
+        if (text === null)
+            return null;
+        const name = matchName(text, compiled.commands);
+        if (name === null)
+            continue;
+        let command = name;
+        let lastIndex = index;
+        const allowed = compiled.subcommands.get(name);
+        if (allowed !== undefined) {
+            const subcommand = staticText(chain[index + 1]);
+            if (subcommand === null || !allowed.has(subcommand))
+                continue;
+            command = `${name} ${subcommand}`;
+            lastIndex = index + 1;
+        }
+        const wrapped = chain.slice(0, index).some((outer) => {
+            const outerName = staticText(outer);
+            return outerName !== null && matchName(outerName, compiled.wrapperNames) !== null;
+        });
+        return { command, wrapped, index, word: text, lastIndex };
+    }
+    return null;
+}
+/**
+ * The wrapper-rule factory, typed for this package's rules: it is what
+ * {@link createWrapperRule} returns, with the shell-specific rule type and an
+ * options tuple chosen by the caller. A built-in rule whose config comes from
+ * its own options (`sh/require-network-wrapper`) builds the factory's rule
+ * per config and calls its `create` with its own context, so the options
+ * tuple is that rule's. The factory's rule itself reads no options.
+ *
+ * @internal
+ */
+export function buildWrapperRule(config) {
+    const compiled = compileWrapperRule(config);
+    return createRule({
+        name: WRAPPER_RULE_NAME,
+        docsUrl: compiled.docsUrl,
+        meta: {
+            type: 'problem',
+            docs: { description: compiled.description },
+            schema: [],
+            messages: WRAPPER_RULE_MESSAGES,
+        },
+        create: (context) => wrapperRuleListeners(compiled, context),
+    });
+}
+/**
+ * Creates a rule that reports every listed command that is not run through
+ * `config.wrapper`, for a rule pack's "must be wrapped by X" policies:
+ *
+ * ```js
+ * import { createWrapperRule } from '@eslint-sh/eslint-plugin';
+ *
+ * export const requireAudit = createWrapperRule({
+ *   commands: ['kubectl', 'terraform'],
+ *   wrapper: 'audit-run',
+ * });
+ * ```
+ *
+ * The rule declares `meta.languages: ["sh/sh"]`, takes no options (the
+ * config is bound here), and reports with message id `unwrappedCommand`,
+ * naming the command and the wrapper. Its `meta.docs.url` and
+ * `meta.docs.description` default to this package's wrapper-rules page and a
+ * sentence naming the policy; `config.docs` overrides either. A listed
+ * command is wrapped when the wrapper encloses it in `sh-ast/analyze`'s
+ * transparent-wrapper chain, so `audit-run sudo kubectl apply` is wrapped.
+ * Command and wrapper words written as paths match by basename
+ * (`/usr/bin/kubectl`). Commands inside `$(…)`, functions, and pipelines are
+ * checked; a command whose name or subcommand is not static is not reported.
+ *
+ * @param config - The commands, the wrapper they must be run through, any
+ * subcommand restrictions, and optional `meta.docs` overrides.
+ * @returns A {@link ShellRule}: an ESLint rule for the `sh/sh` language,
+ * typed so a pack's own declarations need no `@eslint/core` import to name it.
+ * @throws TypeError when `config` is malformed (no `commands` array, an empty
+ * wrapper name, a subcommand restriction without `names`, or an empty or
+ * non-string `docs.url` / `docs.description`).
+ *
+ * @public
+ */
+export function createWrapperRule(config) {
+    return buildWrapperRule(config);
+}

package/dist/rules/define-shell-rule.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The public rule-authoring helper: the one place a shell rule, built-in or
+ * third-party, gets its `meta.languages` and its shell-specific types.
+ *
+ * ESLint (≥ 10.2) refuses to run a rule on a language its `meta.languages`
+ * does not list, which turns "a shell rule was enabled for a JavaScript file"
+ * (usually a config entry missing `language: 'sh/sh'`) into a configuration
+ * error naming the rule. A rule that omits `meta.languages` fails open: ESLint
+ * applies it everywhere and the user sees a misleading JavaScript `Parsing
+ * error` instead. {@link defineShellRule} therefore owns the field, so no rule
+ * built with it can omit or mistype it, and the types forbid an author from
+ * writing it at all.
+ *
+ * It also fixes the types a rule sees, so authors need no `@eslint/core`
+ * import of their own: `context.sourceCode` is {@link ShellSourceCode} and
+ * visitors receive {@link ShellNode} lint-view nodes — `type` discriminators,
+ * lowercase field names, UTF-16 `range`/`loc` — never the faithful `sh-ast`
+ * records the view is built from.
+ *
+ * The plugin's own built-in rules are built through this same helper (via the
+ * internal `createRule`, which only adds their docs URLs), so the guarantee a
+ * third-party rule gets is the one the built-in rules are tested against.
+ */
+import type { RuleContext, RuleDefinition, RulesMeta } from '@eslint/core';
+import type { NormalizedShellLanguageOptions } from '../language/shell-language-options.js';
+import type { ShellSourceCode } from '../language/shell-source-code.js';
+import type { ShellNode, ShellNodeOf, ShellNodeType } from '../language/syntax-view.js';
+/**
+ * A listener for a node of type `Node`. It is declared with method syntax on
+ * purpose: method parameters are checked bivariantly, which lets a listener
+ * for one node type sit alongside the union-typed listener every other
+ * selector key gets (see {@link ShellRuleVisitor}) without a type error.
+ *
+ * Exported so a helper that builds listeners for several rules can name the
+ * type it returns; `node` is the matched node and `parent` its parent
+ * (`undefined` for the root `File`).
+ *
+ * @public
+ */
+export type ShellListener<Node extends ShellNode = ShellNode> = {
+    listener(node: Node, parent: ShellNode | undefined): void;
+}['listener'];
+/**
+ * The listeners whose key names one node type, or that node type with the
+ * `:exit` suffix, each receiving exactly that node type. The key is
+ * unambiguous in both forms (`CallExpr`, `CallExpr:exit`), so a listener
+ * needs no `node.type` guard. Wildcard (`*`, `*:exit`) and attribute or
+ * class selectors name no single type and fall under the index signature.
+ *
+ * Exported because {@link ShellRuleVisitor} extends it.
+ *
+ * @public
+ */
+export type ShellTypedListeners = {
+    [Type in ShellNodeType as Type | `${Type}:exit`]?: ShellListener<ShellNodeOf<Type>>;
+};
+/**
+ * The listener map a shell rule's `create()` returns. Keys are node types or
+ * esquery selectors written against the lint view's spelling (for example
+ * `CallExpr[args.0.parts.0.value='jq']` or the `:command` selector class),
+ * optionally suffixed with `:exit`. ESLint calls each listener with the
+ * matched node and its parent (the parent is `undefined` for the root
+ * `File`).
+ *
+ * A key that is exactly a node type, with or without `:exit` (`CallExpr`,
+ * `Word:exit`), types its listener's node as that node type, so
+ * `CallExpr(node) { node.args }` reads `args` with no `type` check. Any other
+ * selector string (`*`, `CallExpr[…]`, `:command`, `Stmt > CallExpr`) matches
+ * nodes of more than one type, or of one type the key does not state, so its
+ * listener receives the whole {@link ShellNode} union: narrow it on `type`.
+ *
+ * @public
+ */
+export interface ShellRuleVisitor extends ShellTypedListeners {
+    [selector: string]: ShellListener | undefined;
+}
+/**
+ * The `context` a shell rule's `create()` receives: ESLint's rule context
+ * specialized to the shell language, so `context.sourceCode` is
+ * {@link ShellSourceCode}, `context.languageOptions` is
+ * {@link NormalizedShellLanguageOptions}, `context.options` is `RuleOptions`,
+ * and `context.report` takes {@link ShellNode}s and only the `MessageIds` the
+ * rule declares. Name it when a helper outside `create()` needs the context.
+ *
+ * `context.languageOptions` is the object `ShellLanguage.normalizeLanguageOptions`
+ * returned, not the user's config input, so `dialect` is always set (`"bash"`
+ * by default) and needs no fallback. `context.sourceCode.dialect` carries that
+ * same normalized value; read whichever is closer to hand.
+ *
+ * @public
+ */
+export type ShellRuleContext<RuleOptions extends unknown[] = [], MessageIds extends string = string> = RuleContext<{
+    LangOptions: NormalizedShellLanguageOptions;
+    Code: ShellSourceCode;
+    RuleOptions: RuleOptions;
+    Node: ShellNode;
+    MessageIds: MessageIds;
+}>;
+/**
+ * The `meta` a rule author writes: every field ESLint's rule `meta` accepts
+ * (`type`, `docs`, `schema`, `messages`, `fixable`, `defaultOptions`, …)
+ * except the language fields, which {@link defineShellRule} owns. `languages`
+ * and its deprecated singular predecessor `language` are typed `never`, so
+ * writing either — in particular a language other than `sh/sh` — is a
+ * compile error rather than a value the helper silently replaces.
+ *
+ * @public
+ */
+export type ShellRuleMeta<RuleOptions extends unknown[] = [], MessageIds extends string = string> = Omit<RulesMeta<MessageIds, RuleOptions>, 'languages' | 'language'> & {
+    readonly languages?: never;
+    readonly language?: never;
+};
+/**
+ * What a rule author hands to {@link defineShellRule}: the rule's `meta` and
+ * its `create()`, exactly as in any ESLint rule, minus `meta.languages`. It is
+ * the rule before the helper finishes it; {@link ShellRule} is the finished
+ * rule (ESLint's `RuleDefinition`), so the input is named a spec, not a
+ * definition.
+ *
+ * @public
+ */
+export interface ShellRuleSpec<RuleOptions extends unknown[] = [], MessageIds extends string = string> {
+    /** The rule's metadata; see {@link ShellRuleMeta}. */
+    readonly meta: ShellRuleMeta<RuleOptions, MessageIds>;
+    /** Builds the rule's listeners for one file from the shell-typed context. */
+    readonly create: (context: ShellRuleContext<RuleOptions, MessageIds>) => ShellRuleVisitor;
+}
+/**
+ * A finished shell rule, as {@link defineShellRule} returns it: an ordinary
+ * ESLint rule definition (it goes in a plugin's `rules` like any other)
+ * specialized to the shell language, whose `meta.languages` is always exactly
+ * `["sh/sh"]`. The `meta.languages` requirement is part of the type, so a
+ * hand-written object that omits it, or names another language, is not a
+ * `ShellRule`.
+ *
+ * @public
+ */
+export type ShellRule<RuleOptions extends unknown[] = [], MessageIds extends string = string> = Omit<RuleDefinition<{
+    LangOptions: NormalizedShellLanguageOptions;
+    Code: ShellSourceCode;
+    RuleOptions: RuleOptions;
+    Visitor: ShellRuleVisitor;
+    Node: ShellNode;
+    MessageIds: MessageIds;
+    ExtRuleDocs: unknown;
+}>, 'meta'> & {
+    readonly meta: Omit<RulesMeta<MessageIds, RuleOptions>, 'languages'> & {
+        languages: ['sh/sh'];
+    };
+};
+/**
+ * Builds a shell rule from its spec, setting `meta.languages` to
+ * exactly `["sh/sh"]` so ESLint refuses to run the rule on any other language.
+ * Everything else in `meta`, and `create`, is kept as written; message ids
+ * and option types are inferred from `meta` or may be given explicitly
+ * (`defineShellRule<[], 'found'>(…)`).
+ *
+ * The language fields are written last, so a JavaScript caller that bypasses
+ * the types and supplies its own `languages` or `language` still gets
+ * exactly `["sh/sh"]` (and no `language`). A JavaScript caller that omits
+ * `meta`, which ESLint allows for a rule, is treated as having written
+ * `meta: {}`.
+ *
+ * @example
+ * ```ts
+ * import { defineShellRule } from '@eslint-sh/eslint-plugin';
+ *
+ * export const noEval = defineShellRule({
+ *   meta: { type: 'problem', schema: [], messages: { evalUsed: 'Avoid eval.' } },
+ *   create(context) {
+ *     return {
+ *       CallExpr(node) {
+ *         if (context.sourceCode.getCommandName(node) === 'eval') {
+ *           context.report({ node, messageId: 'evalUsed' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function defineShellRule<RuleOptions extends unknown[] = [], MessageIds extends string = string>(spec: ShellRuleSpec<RuleOptions, MessageIds>): ShellRule<RuleOptions, MessageIds>;

package/dist/rules/define-shell-rule.js

@@ -0,0 +1,56 @@
+/**
+ * The `"<plugin namespace>/<language key>"` identifier this plugin's language
+ * is selected by in a flat config (`language: "sh/sh"`), and therefore the
+ * only entry a shell rule's `meta.languages` holds. ESLint also accepts the
+ * plugin's `meta.namespace` as the plugin part, so the value still matches
+ * when a consumer registers the plugin under another key.
+ */
+const SHELL_LANGUAGE_ID = 'sh/sh';
+/**
+ * Builds a shell rule from its spec, setting `meta.languages` to
+ * exactly `["sh/sh"]` so ESLint refuses to run the rule on any other language.
+ * Everything else in `meta`, and `create`, is kept as written; message ids
+ * and option types are inferred from `meta` or may be given explicitly
+ * (`defineShellRule<[], 'found'>(…)`).
+ *
+ * The language fields are written last, so a JavaScript caller that bypasses
+ * the types and supplies its own `languages` or `language` still gets
+ * exactly `["sh/sh"]` (and no `language`). A JavaScript caller that omits
+ * `meta`, which ESLint allows for a rule, is treated as having written
+ * `meta: {}`.
+ *
+ * @example
+ * ```ts
+ * import { defineShellRule } from '@eslint-sh/eslint-plugin';
+ *
+ * export const noEval = defineShellRule({
+ *   meta: { type: 'problem', schema: [], messages: { evalUsed: 'Avoid eval.' } },
+ *   create(context) {
+ *     return {
+ *       CallExpr(node) {
+ *         if (context.sourceCode.getCommandName(node) === 'eval') {
+ *           context.report({ node, messageId: 'evalUsed' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export function defineShellRule(spec) {
+    // The type requires `meta`, but ESLint accepts a rule without one, so an
+    // untyped (JavaScript) caller's missing `meta` is read as empty rather than
+    // crashing. The types cannot see that caller, hence the suppression.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    const meta = spec.meta ?? {};
+    // Drop the deprecated singular key an untyped caller may have supplied, so
+    // the only language declaration ESLint sees is the one set here.
+    const { language: _language, ...authorMeta } = meta;
+    const { create } = spec;
+    return {
+        meta: { ...authorMeta, languages: [SHELL_LANGUAGE_ID] },
+        create,
+    };
+}

package/dist/rules/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The built-in rule registry: the one and only place this package's rules are
+ * listed. The plugin object's `rules` is this record, so a rule is shipped
+ * exactly when it appears here.
+ *
+ * Adding a rule means one line here (`'<rule-name>': <ruleModule>,`, keyed by
+ * the same name passed to `createRule`) plus the rule's own files: its module
+ * under `src/rules/`, its tests, and its docs page at
+ * `docs/rules/<rule-name>.md` (a test fails if a registered rule has no docs
+ * page, or a docs page has no registered rule). A namespaced name such as
+ * `compat/no-mapfile` keeps its namespace as a directory: the module is
+ * `src/rules/compat/no-mapfile.ts` and the page `docs/rules/compat/no-mapfile.md`.
+ *
+ * Every entry is built with `createRule` (see `./create-rule.ts`), so every
+ * entry declares `meta.languages: ["sh/sh"]` and a `meta.docs.url` pointing at
+ * its docs page. An empty registry is a valid state: the plugin then ships
+ * `rules: {}` and remains usable for consumer-supplied rules.
+ */
+import type { RuleDefinition } from '@eslint/core';
+/**
+ * Built-in rules keyed by rule name (without the `sh/` namespace a user writes
+ * in their config).
+ *
+ * @internal
+ */
+export declare const rules: Record<string, RuleDefinition>;