@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

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

@@ -0,0 +1,166 @@
+import type { WrapperSpec } from 'sh-ast/analyze';
+import type { ShellRule } from './define-shell-rule.js';
+/**
+ * Restricts a listed command to some of its subcommands, for commands such as
+ * `git` where only some subcommands are in scope (`git fetch` is a network
+ * call, `git status` is not).
+ *
+ * The flag fields are `WrapperSpec`'s own, picked from it so the two cannot
+ * drift, and describe the command's options that may appear before the
+ * subcommand (`git -C dir fetch`): `noArgFlags` take no operand (`--bare`),
+ * `argFlags` take one (`-C <dir>`), and `stopsChainFlags` mean the command
+ * runs no subcommand at all (`git --version fetch` prints the version, and is
+ * never reported). The subcommand is found the way a wrapped command is:
+ * declared options are skipped, and a flag the command does not declare
+ * leaves the subcommand unknown, so the invocation is not reported.
+ *
+ * @public
+ */
+export interface WrapperRuleSubcommands extends Pick<WrapperSpec, 'noArgFlags' | 'argFlags' | 'stopsChainFlags'> {
+    /** The subcommands that make an invocation of the command count, such as `['fetch', 'push']`. */
+    readonly names: readonly string[];
+}
+/**
+ * Names the operand of a listed command whose value decides whether the
+ * invocation can leave the machine, such as the source of `git clone`.
+ *
+ * The flags describe the options that may precede the operand, with the same
+ * meaning as {@link WrapperRuleSubcommands}'s: `noArgFlags` take no value and
+ * `argFlags` take one (as `--depth 1`, or `--depth=1` in one word). The
+ * operand is the first word after them, or after a `--`. A flag that is not
+ * declared leaves the operand unknown, and an unknown operand is never taken
+ * as local.
+ *
+ * @public
+ */
+export interface WrapperRuleLocalOperand extends Pick<WrapperSpec, 'noArgFlags' | 'argFlags'> {
+    /**
+     * The operand counts as local when it is a static word starting with one
+     * of these, such as `['./', '../', '/', 'file://']`.
+     */
+    readonly localPrefixes: readonly string[];
+}
+/**
+ * Ways to invoke one listed command that only act locally, so the policy has
+ * nothing to guard. An invocation matching either field is not reported.
+ *
+ * @public
+ */
+export interface WrapperRuleLocalInvocation {
+    /**
+     * Complete argument lists, after the command (and its subcommand, if it has
+     * one), that make the invocation local. They match exactly: with
+     * `[['--version']]`, `curl --version` is local and
+     * `curl --version https://example.com` is not.
+     */
+    readonly argLists?: readonly (readonly string[])[];
+    /** Local when the command's source operand is a local path. */
+    readonly localOperand?: WrapperRuleLocalOperand;
+}
+/**
+ * What a "must be run through a wrapper" rule enforces. Passed to
+ * {@link createWrapperRule}.
+ *
+ * @public
+ */
+export interface WrapperRuleConfig {
+    /**
+     * The command names that must be run through the wrapper. A static command
+     * word matches a name when it equals it, or when it contains a slash and
+     * its basename equals it (`/usr/bin/curl` and `./bin/curl` match `curl`).
+     */
+    readonly commands: readonly string[];
+    /**
+     * The wrapper the commands must be run through. A string names a wrapper
+     * that takes no options of its own (`retry curl x`), unless it names one of
+     * `sh-ast/analyze`'s default transparent wrappers (`timeout`, `nice`, …),
+     * whose known option shape is used. A `WrapperSpec` declares the wrapper's
+     * option shape, so that `retry -n 3 curl x` is recognized as `curl` run
+     * through `retry`; any of its `names` counts as the wrapper. Like
+     * `commands`, a wrapper run by path matches by basename
+     * (`/usr/local/bin/retry curl x`).
+     */
+    readonly wrapper: string | WrapperSpec;
+    /**
+     * Listed commands that count only with some subcommands, keyed by command
+     * name. A listed command with no entry here counts with any arguments.
+     */
+    readonly subcommands?: Readonly<Record<string, WrapperRuleSubcommands>>;
+    /**
+     * Invocations of a listed command that only act locally and so are not
+     * reported, keyed by the command as the rule's message names it: the listed
+     * name (`curl`), or the name with its subcommand (`git clone`).
+     */
+    readonly localInvocations?: Readonly<Record<string, WrapperRuleLocalInvocation>>;
+    /**
+     * The rule's `meta.docs` fields a rule pack owns. `url` defaults to this
+     * package's wrapper-rules docs page, and `description` to a sentence naming
+     * the commands and the wrapper. Set them to point users at the pack's own
+     * documentation.
+     */
+    readonly docs?: {
+        readonly url?: string;
+        readonly description?: string;
+    };
+}
+/**
+ * The message ids a wrapper rule reports with: `unwrappedCommand` names the
+ * command (with its subcommand, when one was matched) and the wrapper.
+ *
+ * @internal
+ */
+export type WrapperRuleMessageId = 'unwrappedCommand';
+/**
+ * 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 declare const WRAPPER_RULE_MESSAGES: Readonly<Record<WrapperRuleMessageId, string>>;
+/**
+ * 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 declare function buildWrapperRule<RuleOptions extends unknown[] = []>(config: WrapperRuleConfig): ShellRule<RuleOptions, WrapperRuleMessageId>;
+/**
+ * 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 declare function createWrapperRule(config: WrapperRuleConfig): ShellRule<[], 'unwrappedCommand'>;

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);
+}