@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/untrusted-code.md

@@ -0,0 +1,440 @@
+# Linting code you don't control
+
+eslint-sh is often a policy gate: CI lints a pull request, an agent's output, or a vendored
+repository whose author does not own the policy. In that setting, the author controls the scripts
+under review and every other file in the checkout. This page covers what that lets them change, how
+to run the lint from a directory outside those files, so that they can't change its configuration
+or its exit code, and what a passing run still doesn't tell you:
+
+- [What a script's comments can switch off](#what-a-scripts-comments-can-switch-off)
+- [A policy config that ignores them](#a-policy-config-that-ignores-them)
+- [Run ESLint from outside the checkout](#run-eslint-from-outside-the-checkout)
+- [Declaration conventions that read files](#declaration-conventions-that-read-files)
+- [Which files get linted](#which-files-get-linted)
+- [What this does not cover](#what-this-does-not-cover)
+
+Everything below was run against ESLint 10.2.0, the oldest version this plugin's peer range allows,
+and against 10.7.0.
+
+## What a script's comments can switch off
+
+ESLint's inline comments work in shell scripts the same way they do in JavaScript, with `#` as the
+comment marker. With the default `linterOptions`, a script can silence any rule for itself, and
+neither `sh/recommended` nor `sh/agent-authored` changes that. Each of these scripts lints with no
+`sh/no-eval` report under `sh.configs.recommended`:
+
+```sh
+#!/bin/bash
+# eslint-disable-next-line sh/no-eval
+eval "$x"
+```
+
+| Comment                                      | Effect                                       |
+| -------------------------------------------- | -------------------------------------------- |
+| `# eslint-disable-next-line sh/no-eval`      | Silences the rule on the next line.          |
+| `eval "$x" # eslint-disable-line sh/no-eval` | Silences the rule on its own line.           |
+| `# eslint-disable` … `# eslint-enable`       | Silences every rule between the two.         |
+| `# eslint sh/no-eval: off`                   | Turns the rule off for the whole file.       |
+
+The `eslint` prefix is the default `languageOptions.directivePrefix`. A config that sets it, for
+example to `shellcheck-sh`, makes `# shellcheck-sh-disable-next-line sh/no-eval` the working form
+and turns `# eslint-disable-next-line` into an ordinary comment. The prefix is chosen by the config,
+not by the script, and it does not stop directives, it only renames them.
+
+## A policy config that ignores them
+
+Set `linterOptions.noInlineConfig` in the config you lint with. The `globalIgnores` line and the
+`checkout/` in `files` belong to [the recipe](#run-eslint-from-outside-the-checkout), which explains
+them.
+
+```js
+// policy/eslint.config.mjs
+import { defineConfig, globalIgnores } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig([
+  globalIgnores(['!**/node_modules/', 'checkout/.git/']),
+  {
+    files: ['**/*.sh', '**/*.bash', 'checkout/**/bin/?*'],
+    extends: [sh.configs.recommended],
+    linterOptions: { noInlineConfig: true },
+  },
+]);
+```
+
+`noInlineConfig: true` makes ESLint ignore every comment in the table above, whatever the
+`directivePrefix`. The rule reports as if the comment were not there, and ESLint adds a warning with
+no rule id at the comment itself. For the script above, with its other report:
+
+```text
+1:1  error    Enable strict mode with `set -euo pipefail` within the first 5 statements; not enabled: errexit, nounset, pipefail                      sh/require-strict-mode
+2:1  warning  '# eslint-disable-next-line sh/no-eval' has no effect because you have 'noInlineConfig' setting in your config
+3:1  error    `eval` runs text as shell code at run time, so the code it executes cannot be statically reviewed. Write the commands directly instead  sh/no-eval
+```
+
+The plugin returns its directives to ESLint through the language's `getDisableDirectives` and
+`getInlineConfigNodes` hooks, and ESLint applies `noInlineConfig` to them as it does to
+JavaScript comments. Under `--max-warnings 0`, that warning fails the
+run on its own: a contributed script that contains any directive fails the gate, even one that would
+have suppressed nothing. If you would rather let those through, run without `--max-warnings 0` and
+read the warnings, but then no other warning fails the run either (see the
+[continuous integration exit codes](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md#continuous-integration)).
+
+**If you accept directives instead.** `linterOptions.reportUnusedDisableDirectives` sets the
+severity of a disable comment that suppressed nothing. ESLint 10's default is `"warn"`; `"error"`
+fails the run on one:
+
+```js
+// policy/eslint.config.mjs, directives allowed
+import { defineConfig, globalIgnores } from 'eslint/config';
+import sh from '@eslint-sh/eslint-plugin';
+
+export default defineConfig([
+  globalIgnores(['!**/node_modules/', 'checkout/.git/']),
+  {
+    files: ['**/*.sh', '**/*.bash', 'checkout/**/bin/?*'],
+    extends: [sh.configs.recommended],
+    linterOptions: { reportUnusedDisableDirectives: 'error' },
+  },
+]);
+```
+
+This keeps stale directives out of the tree, but it is not a gate: the `# eslint-disable-next-line
+sh/no-eval` above still silences `sh/no-eval`, because it did suppress something. Setting both
+options is allowed, but `reportUnusedDisableDirectives` then reports nothing, because
+`noInlineConfig` has already discarded every directive.
+
+## Run ESLint from outside the checkout
+
+`linterOptions` only helps if the contributor can't replace the config, ESLint or the plugin, and
+can't change the result some other way. ESLint finds several of its inputs in the directory it runs
+in, and Node looks through that directory's parents for packages. When that directory is the
+checkout, every one of these belongs to the contributor:
+
+- **The config.** `eslint .` without `--config` imports the `eslint.config.mjs` in the directory it
+  runs in, as JavaScript, with your job's environment variables. ESLint 10 also loads an
+  `eslint.config.*` from a subdirectory for the files under it, so a nested config in the checkout
+  runs, and replaces your policy for its directory, even if your config sits at the root.
+- **Where the config's imports resolve.** `import sh from '@eslint-sh/eslint-plugin'` resolves
+  from the config file's own location. A copy of your config placed inside the checkout imports
+  the checkout's `node_modules`.
+- **Which ESLint runs.** `npx eslint` in the checkout runs the checkout's
+  `node_modules/.bin/eslint`.
+- **The formatter.** ESLint resolves a formatter name, including the default `stylish`, as the
+  package `eslint-formatter-stylish` from the directory it runs in and then from each of its parents,
+  with or without `--config`. That package is code in your job. It can print what it likes and set
+  the exit code.
+- **The suppressions file.** ESLint applies `eslint-suppressions.json` from the directory it runs in
+  whenever that file exists, with no flag, and neither `--config` nor `noInlineConfig` affects it.
+  An error listed in the file is hidden, and the run exits 0.
+- **The cache file.** With `--cache`, ESLint reads `.eslintcache` from the directory it runs in and
+  reuses the results recorded there. The default `--cache-strategy metadata` trusts a recorded size
+  and modification time. `--cache-strategy content` doesn't help either, because the hash it
+  compares against is in the same file.
+- **Your job's own relative paths.** A relative entry in `PATH`, or a relative file in
+  `NODE_OPTIONS`, resolves against the directory ESLint runs in, so either can run a file from the
+  checkout. A version manager may read its settings from there too: `nodenv` runs ESLint under the
+  Node version named in a `.node-version` in the checkout or any parent. Other version managers were
+  not tested.
+
+Installing the checkout is a separate hazard: `npm ci` and `npm install` run the package's lifecycle
+scripts, such as `preinstall`. The lint needs none of the checkout's dependencies, so don't install
+them.
+
+The recipe is to run ESLint somewhere else and pass the checkout as an argument. Keep the policy
+where the contributor can't change it in the same change, such as a separate repository or a path
+your CI provides, with `eslint` and `@eslint-sh/eslint-plugin` installed there from its own lockfile.
+If `policy` is a link to such a path, the rule below applies to the parents of its real location
+too, and the guards don't look there.
+Put it beside the checkout, in a directory your job creates and the contributor can't write to.
+Neither that directory nor any of its parents may be inside the contributor's files: a CI job often
+starts in a clone of the repository under review, so don't create it there. The recipe refuses a
+`node_modules` in a parent, but it has no guard for the rest of that rule, such as a `.node-version`
+there.
+
+```text
+job-directory/
+  policy/      eslint.config.mjs and its own node_modules
+  checkout/    the code under review
+```
+
+Create `checkout` yourself, so that nothing of the contributor's lands beside it. From a repository:
+
+```sh
+git clone URL checkout
+```
+
+From a tarball, keep the input archive outside `job-directory` (here, `../x.tar`) and unpack only
+into `checkout`. Keep every path as archived: the policy covers files directly inside any `bin/`
+directory under `checkout`, so wrappers and siblings need no special handling.
+
+```sh
+[ ! -e checkout ] && [ ! -L checkout ] || { printf 'checkout already exists\n' >&2; exit 1; }
+mkdir checkout && tar -xf ../x.tar -C checkout || exit 1
+```
+
+Stop the job if this fails: a failed `tar` can leave only some of the files. Don't strip path
+components or move files out of a wrapper; stripping can silently discard top-level files.
+
+Then, from `job-directory`, not from inside the checkout:
+
+```sh
+[ "$(ls -A | wc -l)" -eq 2 ] && [ -d policy ] && [ -d checkout ] || {
+  printf 'the job directory must hold only checkout and policy\n' >&2
+  exit 1
+}
+dir=$(pwd -P)
+while :; do
+  if [ -e "$dir/node_modules" ]; then
+    printf 'node_modules in or above the job directory: %s\n' "$dir" >&2
+    exit 1
+  fi
+  [ "$dir" != / ] || break
+  dir=$(dirname "$dir")
+done
+policy/node_modules/.bin/eslint \
+  --config policy/eslint.config.mjs \
+  --max-warnings 0 \
+  checkout
+```
+
+- The working directory is what closes the list above. `eslint-suppressions.json`, `.eslintcache`
+  and any relative path in your job's environment resolve in `job-directory`, the formatter name
+  resolves there and in its parents, and the checkout's copies are never consulted.
+- The first guard refuses anything else in `job-directory`, because ESLint reads its inputs from
+  there: a tarball unpacked here rather than as above can leave an `eslint-suppressions.json` beside
+  the checkout. It can't catch such a tarball writing into `policy/`, which only unpacking elsewhere
+  prevents.
+- The second guard refuses a `node_modules` in `job-directory` or any parent, because Node looks
+  there for the formatter and for a package ESLint's own dependencies ask for on every run, whatever
+  `--format` says, and a package found there runs in your job and can set the exit code. If it
+  refuses a `node_modules` of your own, such as one in your home directory, make the job directory
+  with `mktemp -d` instead.
+- `--config` loads only the policy, and its imports resolve from `policy/node_modules`.
+- The checkout has to be under the working directory. With `--config`, ESLint matches the config's
+  `files` and `ignores` against the directory it runs in and treats anything outside it as ignored:
+  running from inside `policy/` with `../checkout`, or from elsewhere with an absolute path, exits 2
+  with `all of the files matching the glob pattern ... are ignored`. The policy's
+  `checkout/**/bin/?*` matches files directly in a `bin` at any depth under `checkout`.
+- `!**/node_modules/` in `globalIgnores` turns off ESLint's default ignore of `**/node_modules/`.
+  Without it, a script under any directory named `node_modules`, at any depth, is not linted, and
+  the contributor can commit a directory of that name anywhere. A wrapper named `node_modules`
+  or starting with a dot is covered too. `node_modules/.bin` is not a directory named `bin`:
+  regular files there need a `.sh` or `.bash` extension to match; its usual symlinks fail the check.
+- `checkout/.git/` in `globalIgnores` keeps the lint out of the clone's repository data, because
+  ESLint's default ignores only a `.git` in the directory it runs in, and a branch called
+  `fix/deploy.sh` is a file there that matches `files`.
+- `--max-warnings 0` makes warnings, including the "has no effect" warnings above, fail the run.
+  The exit codes are the ones in the
+  [continuous integration table](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md#continuous-integration).
+- Leave `--cache` off. The recipe needs no cache, and if you add one, it must not come from the
+  checkout or from anything else the contributor could write.
+
+To find what was left, this command was run with every `fs` call, module load and child process
+logged, against a checkout holding each ESLint input named on this page and a marker-writing copy
+of every package in the policy's install. Under the checkout, ESLint only listed directories and read the
+files it lints. It loaded no module from there and started no process. That is a result for the
+ESLint versions above, not a promise from ESLint; this page's tests repeat the trace on the version
+the repository uses.
+
+The workflow that runs this command is part of the gate too: keep it, like the policy, where the
+contributor's change can't edit it. Nothing of the contributor's should have run on the machine
+before it, either: an install, build or test run in the same job can change any file the job can
+write, including the policy.
+
+## Declaration conventions that read files
+
+A [`DeclarationConvention`](./declaration-conventions.md) is code in your config, and one that reads
+files reads whatever path it is given. When linting code you don't control, read only paths you
+control: a file built from the policy config's own location (`new URL('./commands.txt',
+import.meta.url)`), or data in the config itself. Don't read a file located from the linted script's
+path, such as the per-script sidecars in
+[declarations outside the script](./declaration-conventions.md#declarations-outside-the-script) or
+`scriptSidecarCommands()` in the repository's
+[container-entrypoint example pack](https://github.com/mike-north/eslint-sh/tree/main/examples/container-entrypoint-pack):
+in a checkout under review, every file next to a script belongs to the contributor.
+
+## Which files get linted
+
+ESLint lints the files the policy's `files` patterns match, and the contributor chooses file names.
+With the policy above, a checkout with a clean `ok.sh` and these scripts, each starting `#!/bin/bash`
+and containing `eval "$x"`, exits 0 with no report from the recipe:
+
+- `ci/run` and `deploy`: no extension, outside any `bin/`.
+- `build.SH`: the patterns are case-sensitive.
+- `x.zsh`: the extension is not in the patterns.
+- `script.sh.txt`: the pattern needs the name to end in `.sh`.
+
+Naming a script differently is enough to avoid being linted. Widening the patterns does not close
+this, because any list of names is a list the contributor can step around. What you can do is
+check the checkout for files that start with a shell shebang and that the patterns do not match,
+and fail the job when there are any. Run this from `job-directory`, before the lint, from a workflow
+the contributor can't edit:
+
+```sh
+[ -d checkout ] && [ ! -L checkout ] || { printf 'no checkout directory here\n' >&2; exit 2; }
+status=0
+while IFS= read -r -d '' file; do
+  if [ -L "$file" ] || [ ! -f "$file" ] || [ ! -r "$file" ]; then
+    printf 'symlink, special or unreadable file: %q\n' "$file" >&2
+    status=1
+    continue
+  fi
+  case "$file" in
+    *.sh | *.bash) continue ;;
+  esac
+  # The policy covers direct children of every bin, regardless of wrappers.
+  case "${file%/*}" in
+    */bin) continue ;;
+  esac
+  if head -c 1024 "$file" | head -n 1 | LC_ALL=C grep -Eiq '^#!.*sh'; then
+    printf 'not linted, but has a shell shebang: %q\n' "$file" >&2
+    status=1
+  fi
+done < <(find checkout -path checkout/.git -type d -prune -o ! -type d -print0)
+[ "$status" -eq 0 ] || exit "$status"
+```
+
+This needs `bash` (it uses `read -d` and process substitution). It exits non-zero when it finds
+something and otherwise falls through, so it can sit above the recipe in one script or run as its
+own step. Its first line exits 2 without a real `checkout` directory, because a failing `find`
+wouldn't fail the check, and a check run from the wrong directory would pass every time. The first
+`case` covers the extensions; the second checks the parent directory, so it covers direct children
+of every `bin/` without accidentally accepting `bin/sub/run`. Keep these checks in sync with the
+policy's `files`.
+
+To rename `checkout`, change it everywhere. Left behind in the guards or the recipe's argument, the
+old name stops the run, and in `globalIgnores` it can only add failures. The policy's `files`, the
+`case` and the `find` must change together: if only `files` is left behind, `.sh` files are still
+linted, so nothing looks wrong, but `bin/` silently isn't.
+
+The check looks everywhere in the checkout except a top-level `.git` directory, including under
+`node_modules`. The lint skips that directory too, and only a tarball can put files of its own there,
+so don't run anything from it. The check names every file in the example above except `ok.sh`, and it
+fails on any symlink, special file or file it can't read (see [symlinks](#what-this-does-not-cover)),
+so an installed `node_modules`, whose `.bin` holds symlinks, fails it too. A directory it can't read
+only makes `find` print an error, and the recipe then exits 2 on it. It flags any first line starting `#!` that contains `sh` in any
+case, so `#!/usr/local/bin/publish` fails it as well. When it fails, either fix the name or extend
+the policy's `files` to cover the file.
+
+It uses `find` where `git ls-files` would be shorter, because git reads the checkout's own repository
+configuration, which a checkout you did not clone yourself can set, and that configuration can run
+commands. Don't run git in such a checkout, including to list changed files.
+
+It is not a complete answer. A script with no shebang, outside every `bin/` and without a `.sh` or
+`.bash` extension, passes both the lint and this check, even if something runs it as `sh deploy` or
+`source`s it. So does one whose
+shebang doesn't contain `sh`, such as a wrapper with another name. The check narrows what a
+contributor can hide; it does not make the set of linted files equal to the set of scripts the
+project runs.
+
+The lint sees the files on disk, not the commit, so run it on a file system that keeps every name
+apart, such as Linux's: on macOS's default, a commit with both `A.sh` and `a.sh` clones to one file,
+and only that file is linted. The same goes for names that differ only in Unicode normal form,
+which collide on APFS even on a case-sensitive volume. Lint what you will run, too. A plain clone leaves a submodule's directory empty, so use
+`git clone --recurse-submodules` if anything later fetches submodules. And the contributor's
+`.gitattributes` can mark a file `export-ignore`, which keeps it out of a `git archive` tarball, so
+a tarball can lint clean while a clone of the same commit holds the file.
+
+An honest repository can also fail the recipe. ESLint lints `*.js`, `*.mjs` and `*.cjs` by default,
+whatever the policy's `files` say, and `checkout/**/bin/?*` covers everything directly in any `bin/`
+under `checkout`, including vendored binaries. Those files are linted as shell, and can fail with
+parse errors or shell policy findings. A JavaScript file with a disable comment, a JavaScript file
+that ESLint's default parser rejects, or a
+Python script in `bin/` each exits 1. So does any JavaScript file directly in `bin/`, however valid,
+with a message telling you to add a `files` entry that is already there, and an empty `bin/.gitkeep`.
+A checkout with nothing to lint exits 2 with `all of the files matching the glob pattern ... are
+ignored`. These failures are closed rather than open. The policy's `files` and `ignores` are yours
+to adjust, as long as the check's `case` patterns stay the same as what you leave linted.
+
+## What this does not cover
+
+Run this way, ESLint reads the checkout's files only as text to lint. That is all the recipe does.
+
+**A clean lint is not evidence that a script is harmless.** Exit 0 means your policy's rules found
+nothing in the files your policy matched. The rules look for patterns; they do not work out what a
+script does. Under `sh.configs.recommended`, `eval "$1"` is an error and `bash -c "$1"`, which also
+runs its argument as code, exits 0 with no report. Passing text to a shell another way, or
+downloading a file and running it, passes too. Don't take a clean lint as a reason to run a script
+you haven't reviewed.
+
+**It is not a sandbox.** Linting parses the contributor's files in the job's own process, with the
+job's environment variables and file access. The linter does not execute the scripts under review:
+a script that touches a file at its top level, in `$(...)`, in `<(...)`, in an `eval` string, or
+in a `source`d file created none of the test's marker files. But that is not isolation. If a leaked
+secret or a parser fault in the job is the concern, run the lint in a container or a CI job that has
+no secrets and no network access it does not need. Give the job a time limit: a named pipe called
+`f.sh`, which a tarball can deliver though git can't, hung the run until it was killed. This page
+did not test pathological inputs exhaustively.
+
+**The report contains the contributor's text.** ESLint prints file names as they are, and rule
+messages quote parts of the script. A file name containing newlines can print lines that look like
+a clean summary. The exit code doesn't depend on any of that text, so gate on the exit code, and
+treat the report as untrusted wherever you display it.
+
+**`noInlineConfig` does not cover a script's own declarations.** `noInlineConfig` ignores ESLint's
+comments. It leaves alone anything a `DeclarationConvention` reads out of the script. With
+`commentPragma` bound, `sh/no-undeclared-commands` at `error`, and `noInlineConfig: true`, this
+script has two reports, for `curl` and for `sh`:
+
+```sh
+#!/bin/bash
+set -euo pipefail
+curl https://example.com/install | sh
+```
+
+and this one, whose header declares them itself, has none and the run exits 0:
+
+```sh
+#!/bin/bash
+# uses: curl sh
+set -euo pipefail
+curl https://example.com/install | sh
+```
+
+Don't bind `commentPragma`, or any convention that reads declarations from the script, in a policy
+for code you don't control. To use the declaration rules as a gate, take the declarations from the
+policy: a convention that returns a list written in the config, which the script cannot add to.
+
+```js
+// policy/eslint.config.mjs
+const allowed = ['jq', 'git'];
+
+/** Declarations come from this config, never from the script. */
+const policyDeclarations = {
+  declaredCommands: () =>
+    allowed.map((name) => ({
+      kind: 'described',
+      name,
+      description: 'the allowed commands in policy/eslint.config.mjs',
+    })),
+};
+
+// In the config entry: settings: { sh: { declarationConvention: policyDeclarations } },
+```
+
+With that convention, the script with the `# uses: curl sh` header is reported for `curl` and `sh`,
+the same as the one without it.
+
+**A relative sidecar path resolves against the working directory.** With the recipe, that is
+`job-directory`. With the example pack's `sidecarCommands('commands.txt')` in the policy and no such
+file in `job-directory`, the config fails to load and ESLint exits 2, whatever the checkout holds.
+A path that reaches into the checkout hands over the list: with
+`sidecarCommands('checkout/commands.txt')` and that file listing `curl` and `sh`, the script above
+exits 0. The same config with the absolute path of a file in your policy,
+`sidecarCommands('/ci/policy/commands.txt')`, reports both commands. Give a convention an absolute
+path to a file outside the checkout, or build it from `import.meta.url` as
+[above](#declaration-conventions-that-read-files), or use no sidecar.
+
+**A symlink in the checkout can point outside it.** A file symlink whose name matches the policy's
+`files`, or ESLint's default JavaScript patterns, is followed: ESLint lints the file it points at,
+wherever that is. A `leak.sh` linking to a
+text file outside the checkout printed that file's parse error, such as ``Parsing error: `if` must
+be followed by a statement list``, and a link to a script outside the checkout printed rule
+messages naming its unquoted variables and their line numbers. If the report is posted where the
+contributor can read it, that leaks a little of whatever the link points to, and text inside an
+unquoted `$(...)` prints verbatim. Other symlinked directories are not followed: files behind a link
+to a directory were not linted or reported. A link to a directory or to nothing stops the run with
+exit 2 if its own name matches `files` or ESLint's default JavaScript patterns, and is skipped
+otherwise. The check above rejects every symlink under the checkout, including one named
+`node_modules` or `.git`, which closes the file case when it runs before the lint.

package/docs/wrapper-rules.md

@@ -0,0 +1,206 @@
+# Wrapper rules
+
+Many projects require some commands to run through a wrapper: network calls through a retry
+helper, infrastructure changes through an audit logger, deploys through a lock. These are
+"command X must be run through wrapper Y" policies. `createWrapperRule` builds a rule that
+enforces one, and `sh/require-network-wrapper` is the built-in rule made with it.
+
+Which commands need a wrapper, and which wrapper, is your project's policy. This plugin ships no
+wrapper name. You bind both, either in a rule pack with `createWrapperRule` or in your config
+with [`sh/require-network-wrapper`](./rules/require-network-wrapper.md)'s `wrapper` option.
+
+## `createWrapperRule`
+
+```ts
+import type { RuleDefinition } from '@eslint/core';
+import type { WrapperSpec } from '@eslint-sh/eslint-plugin';
+
+interface WrapperRuleConfig {
+  /** Command names that must be run through the wrapper. */
+  readonly commands: readonly string[];
+  /** The wrapper: a name, or a WrapperSpec that declares its options. */
+  readonly wrapper: string | WrapperSpec;
+  /** Listed commands that count only with some subcommands, keyed by command name. */
+  readonly subcommands?: Readonly<Record<string, WrapperRuleSubcommands>>;
+  /** Invocations that only act locally and are not reported, keyed by the command as the message names it. */
+  readonly localInvocations?: Readonly<Record<string, WrapperRuleLocalInvocation>>;
+  /** Overrides the rule's meta.docs.url and meta.docs.description. */
+  readonly docs?: { readonly url?: string; readonly description?: string };
+}
+
+/** The command's own options before the subcommand use WrapperSpec's flag fields. */
+interface WrapperRuleSubcommands
+  extends Pick<WrapperSpec, 'noArgFlags' | 'argFlags' | 'stopsChainFlags'> {
+  /** The subcommands that make an invocation count. */
+  readonly names: readonly string[];
+}
+
+interface WrapperRuleLocalInvocation {
+  /** Complete argument lists (after the command and its subcommand) that are local. */
+  readonly argLists?: readonly (readonly string[])[];
+  /** Local when the first operand is a static word starting with one of `localPrefixes`. */
+  readonly localOperand?: Pick<WrapperSpec, 'noArgFlags' | 'argFlags'> & {
+    readonly localPrefixes: readonly string[];
+  };
+}
+
+function createWrapperRule(config: WrapperRuleConfig): RuleDefinition;
+```
+
+The returned rule:
+
+- declares `meta.languages: ["sh/sh"]`, so ESLint applies it only to files linted with this
+  plugin's shell language;
+- takes no options, because the config is bound when the rule is made;
+- reports message id `unwrappedCommand` on each command that should be wrapped and is not, naming
+  the command and the wrapper: `` `kubectl` must be run through `audit-run`. ``
+- has a `meta.docs.url` pointing at this page and a `meta.docs.description` naming the commands
+  and the wrapper, unless `docs` overrides them. Set `docs.url` to your pack's own documentation,
+  so the link in a lint report leads your users to your policy.
+
+`createWrapperRule` throws a `TypeError` when the config is malformed: no `commands` array, an
+empty wrapper name, a `WrapperSpec` with no `names`, a subcommand entry with no `names`, or a
+`docs.url` or `docs.description` that is not a non-empty string, or a malformed `localInvocations`
+entry.
+
+## Example: a rule pack
+
+This pack requires `kubectl` and `terraform apply`/`terraform destroy` to be run through its
+`audit-run` wrapper. `audit-run` takes a `--ticket <id>` option, and terraform's `-no-color` may
+come before its subcommand. This file ships with the package as
+`docs/examples/audit-wrapper-pack.mjs`, and CI runs it.
+
+```mjs
+/**
+ * A rule pack that requires infrastructure CLIs to be run through its
+ * `audit-run` wrapper. From `../wrapper-rules.md`, and run in CI.
+ */
+import { createWrapperRule } from '@eslint-sh/eslint-plugin';
+
+const requireAudit = createWrapperRule({
+  commands: ['kubectl', 'terraform'],
+  wrapper: { names: ['audit-run'], argFlags: ['--ticket'] },
+  subcommands: {
+    terraform: { names: ['apply', 'destroy'], noArgFlags: ['-no-color'] },
+  },
+});
+
+export default { rules: { 'require-audit': requireAudit } };
+```
+
+Register the pack beside this plugin and turn the rule on:
+
+```js
+// eslint.config.js
+import sh from '@eslint-sh/eslint-plugin';
+import acme from './audit-wrapper-pack.mjs';
+
+export default [
+  {
+    files: ['**/*.sh'],
+    plugins: { sh, acme },
+    language: 'sh/sh',
+    rules: { 'acme/require-audit': 'error' },
+  },
+];
+```
+
+```sh
+kubectl apply -f app.yaml                        # reported: kubectl is not wrapped
+terraform -no-color apply                        # reported as `terraform apply`
+audit-run --ticket OPS-1 kubectl apply -f a.yaml # clean
+terraform plan                                   # clean: plan is not a listed subcommand
+```
+
+## What counts as wrapped
+
+Every command in the file is checked: top level, in functions, in pipelines, in conditionals,
+and inside command substitutions (`$(…)`).
+
+For each command, the rule follows its command word through transparent wrappers, the way
+`ShellSourceCode.resolveInvokedCommand` does. The default wrappers (`command`, `exec`, `env`,
+`nohup`, `nice`, `time`, `timeout`, `sudo`) are followed, and so is your wrapper. The result is a
+chain, outermost first: `retry sudo curl x` runs `retry`, then `sudo`, then `curl`.
+
+- A listed command is **wrapped** when your wrapper appears earlier in its chain. So
+  `retry curl x` and `retry sudo curl x` are wrapped, and so is `sudo retry curl x`.
+- `sudo curl x` is **not** wrapped: `sudo` is not your wrapper.
+- A command substitution is a separate command. In `retry echo "$(curl x)"`, `retry` wraps `echo`,
+  and the `curl` inside `$(…)` is reported.
+- `retry echo; curl x` is two commands, and `curl x` is reported.
+
+### Declaring the wrapper's options
+
+A wrapper given as a string is assumed to take no options of its own, so the word after it is
+the command it runs. When your wrapper has options, give a `WrapperSpec` (from `sh-ast/analyze`,
+re-exported by this package) that declares them:
+
+```js
+wrapper: { names: ['retry'], argFlags: ['-n'] }  // retry -n 3 curl x  →  curl, wrapped
+```
+
+`noArgFlags` lists options without an operand and `argFlags` options with one. An `argFlags`
+option is recognized as `-n 3` and `-n3`, and a `--long` one also as `--long=value`. Every listed
+`names` entry counts as the wrapper. A wrapper string that names one of the default wrappers,
+such as `timeout`, uses that wrapper's known option shape (`timeout 10 curl x`).
+
+### What is never guessed
+
+The rule reports only what it can determine from the source:
+
+- A dynamic command word (`"$client" x`) is not a listed command.
+- When the chain reaches an option your wrapper does not declare, the command it runs is unknown,
+  and nothing is reported. Declare the option to have the command checked.
+- When a command restricted to subcommands has an undeclared option or a dynamic word before
+  its subcommand (`git "$op"`), the subcommand is unknown, and nothing is reported.
+- Command strings run by another shell (`bash -c 'curl x'`) are text, not commands, and are not
+  checked.
+
+### Functions the file defines
+
+A call to a function the file defines is not reported, wherever the function is defined (its
+definition may come after the call). `curl() { retry command curl "$@"; }` followed by `curl x`
+runs the function, not the external `curl`. This matches how
+[`sh/no-undeclared-commands`](./rules/README.md) treats in-file functions. Only the command word
+itself is looked up as a function. A real invocation inside the function (`command curl x`), a
+call behind another wrapper (`sudo curl x`), and a call by path (`/usr/bin/curl x`) run the
+external command and are still reported.
+
+### Local-only invocations
+
+Some invocations of a listed command never leave the machine. `localInvocations` names them,
+keyed by the command as the message names it (`curl`, or `git clone` for a command with a
+subcommand), so the factory itself knows no command:
+
+- `argLists` are complete argument lists that are local. They match exactly:
+  `{ curl: { argLists: [['--version'], ['--help']] } }` allows `curl --version` and `curl --help`
+  but still reports `curl --version https://example.com`, which makes the request.
+- `localOperand` makes the invocation local when its first operand, found after the declared
+  `noArgFlags` and `argFlags` (a `--` ends the options), is a static word starting with one of
+  `localPrefixes`. `{ 'git clone': { localOperand: { localPrefixes: ['./', '../', '/', 'file://'] } } }`
+  allows `git clone ./x` and `git clone --depth 1 /srv/x.git`. Only the operand decides: words
+  after it (`git clone ./x "$dest"`), and the value of a declared option (`--depth "$n"`), may be
+  dynamic. An operand that is dynamic, or that follows an option the entry does not declare, is
+  not known to be local and is reported. The whole argument list up to a literal `--` is read, not
+  only up to the operand, because options may follow operands (`git clone ./x --recurse-submodules`):
+  an option the entry does not declare anywhere before `--` makes the invocation not local, and
+  words after `--` are operands. Leave an option out of the entry when it can make the
+  command reach elsewhere (`--recurse-submodules`).
+
+Anything that is not provably local is reported.
+
+### Commands run by path
+
+A command word that contains a slash is matched by its basename, so running a command by path
+cannot bypass the policy. `/usr/bin/curl x` and `./bin/curl x` are `curl`, and the message names
+`curl`. The same holds for wrappers: `/usr/local/bin/retry curl x` is `curl` run through `retry`,
+with `retry`'s declared options, and `/usr/bin/sudo curl x` is `curl` run through `sudo`. Only the
+whole basename is compared: `/usr/bin/curly` is not `curl`.
+
+### Subcommands
+
+`subcommands` restricts a listed command to some subcommands. The subcommand is the word the
+command runs after its own options, located the way a wrapped command is located: options in
+`noArgFlags` and `argFlags` are skipped, and an option in `stopsChainFlags` means no subcommand
+runs. The message names the command with its subcommand: `` `git fetch` must be run through
+`retry`. ``