@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/dist/eslint-plugin.d.ts

@@ -1,31 +1,384 @@
+import { Argv0Resolution } from 'sh-ast/analyze';
+import { CommandContext } from 'sh-ast/analyze';
+import type { ConfigObject } from '@eslint/core';
 import type { Directive } from '@eslint/core';
+import type { Expansion } from 'sh-ast';
 import type { File as File_2 } from '@eslint/core';
 import type { FileProblem } from '@eslint/core';
 import type { Language } from '@eslint/core';
+import type { Node } from 'sh-ast';
 import type { OkParseResult } from '@eslint/core';
 import type { ParseResult } from '@eslint/core';
+import type { PrintOptions } from 'sh-ast';
+import type { Replace } from 'sh-ast';
+import { ResolveArgv0Options } from 'sh-ast/analyze';
 import type { ResolveWordOptions } from 'sh-ast/analyze';
+import type { RuleContext } from '@eslint/core';
+import { RuleDefinition } from '@eslint/core';
+import { RuleDefinitionTypeOptions } from '@eslint/core';
 import type { RulesConfig } from '@eslint/core';
+import type { RulesMeta } from '@eslint/core';
+import type { RuleTextEdit } from '@eslint/core';
+import type { RuleTextEditor } from '@eslint/core';
+import type { SettingsConfig } from '@eslint/core';
+import type { Slice } from 'sh-ast';
 import type { SourceLocation } from '@eslint/core';
+import type { SyntaxPos } from 'sh-ast';
 import { TextSourceCodeBase } from '@eslint/plugin-kit';
 import type { TraversalStep } from '@eslint/core';
-import type { WordResolution } from 'sh-ast/analyze';
+import { WordResolution } from 'sh-ast/analyze';
+import { WrapperSpec } from 'sh-ast/analyze';
+
+export { Argv0Resolution }
+
+export { CommandContext }
+
+/**
+ * The reference {@link DeclarationConvention}: a script declares the external
+ * commands it uses in `# uses:` comments in its header.
+ *
+ * ```sh
+ * #!/usr/bin/env bash
+ * # uses: jq curl
+ * # uses: git
+ * set -euo pipefail
+ * ```
+ *
+ * declares `jq`, `curl`, and `git`. The header is the run of blank and
+ * comment-only lines at the top of the file; a `# uses:` comment after the
+ * first command is not a declaration. Several pragma lines accumulate, names
+ * are whitespace-separated, and each declaration is `kind: 'script'` with a
+ * `range` that covers exactly that name. A word starting with `#` ends the list and begins a trailing
+ * remark: `# uses: jq # for json` declares only `jq`.
+ *
+ * Its `removeDeclaration` hook deletes one name and the whitespace that
+ * separated it, or the whole pragma line (with its `\n` or `\r\n`) when that
+ * name was the line's last.
+ *
+ * Its `declarationHint` hook tells a person exactly what to add: the line
+ * `# uses: curl`, on a line below the shebang, or as the first line of the
+ * file when there is no shebang. A name a pragma cannot express (one with
+ * whitespace, or starting with `#`) gets no hint.
+ *
+ * Bind it with `settings: { sh: { declarationConvention: commentPragma } }`.
+ *
+ * @public
+ */
+export declare const commentPragma: Readonly<Required<DeclarationConvention>>;
+
+/**
+ * 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'>;
+
+/**
+ * How a project declares the external commands its shell scripts depend on.
+ *
+ * Implement this to teach the plugin a project's own declaration syntax, then
+ * bind it with `settings: { sh: { declarationConvention: myConvention } }`.
+ * Until a convention is bound, rules that consume one report nothing.
+ *
+ * Bind it through `settings`, not through a rule's options: ESLint copies
+ * rule options with `structuredClone`, which cannot copy functions. Define it
+ * as a plain object whose methods are its own properties, and bind it in one
+ * config entry: when two matching config entries both set it, ESLint merges
+ * the two objects property by property, which drops methods inherited from a
+ * class prototype and can mix methods from two different conventions.
+ *
+ * One convention object serves every file its config entry matches, so its
+ * answer must depend only on its arguments and on data it holds, never on
+ * which file it saw before. ESLint's `--cache` sees a convention's own
+ * enumerable data properties (they are part of the config it hashes) but not
+ * files the convention reads while linting.
+ *
+ * {@link commentPragma} is the reference implementation.
+ *
+ * @public
+ */
+export declare interface DeclarationConvention {
+    /**
+     * Returns every command the linted file declares, in source order. A name
+     * declared twice appears twice, each with its own source. `file` names the
+     * file being linted, for a convention whose declarations live beside it;
+     * a convention that reads only `sourceCode` can leave it out.
+     */
+    declaredCommands(sourceCode: ShellSourceCode, file: LintedFile): DeclaredCommand[];
+    /**
+     * Optional edit hook: returns the fix that deletes the single stale
+     * declaration `declared` (an in-script entry previously returned by
+     * {@link DeclarationConvention.declaredCommands} for the same
+     * `sourceCode`), built with the rule's `fixer`. Returns `null` when that
+     * declaration cannot be removed safely.
+     *
+     * It is only ever called with a {@link ScriptDeclaredCommand}: a fix edits
+     * only the linted script, and no edit to the script removes a declaration
+     * kept anywhere else.
+     *
+     * A convention without this hook still reports stale declarations; those
+     * reports simply carry no autofix.
+     */
+    removeDeclaration?(sourceCode: ShellSourceCode, declared: ScriptDeclaredCommand, fixer: RuleTextEditor): RuleTextEdit | RuleTextEdit[] | null;
+    /**
+     * Optional hint hook: returns one short sentence that tells a person how to
+     * declare `command`, with text they can copy. {@link commentPragma}'s hint says to
+     * add `# uses: curl` on a line below the shebang.
+     * `sh/no-undeclared-commands` appends it to its report. Following the
+     * sentence literally must make that report go away.
+     *
+     * Return `null` when this convention cannot declare `command` as written
+     * (for example, a name its syntax cannot express). The report then falls
+     * back to a generic sentence, as it does for a convention without this
+     * hook. Anything other than `null` must be a non-empty single-line string.
+     */
+    declarationHint?(command: string, sourceCode: ShellSourceCode, file: LintedFile): string | null;
+}
+
+/**
+ * The slice of an ESLint rule context that binding resolution reads: the rule
+ * id (for error messages), its configured options, and the shared settings.
+ * Any rule `context` satisfies it, so a rule passes its own `context`.
+ *
+ * @public
+ */
+export declare interface DeclarationConventionBindingContext {
+    /** The rule id as configured (`pack/my-rule`), named in an option-binding error. */
+    readonly id: string;
+    /** The rule's configured options; the first may carry `declarationConvention`. */
+    readonly options: readonly unknown[];
+    /** The shared settings; `settings.sh.declarationConvention` is the usual binding. */
+    readonly settings: SettingsConfig;
+}
+
+/**
+ * What {@link readDeclaredCommands} reads from a rule's context: the linted
+ * file and its source code. Any shell rule's `context` satisfies it.
+ *
+ * @public
+ */
+export declare interface DeclarationReadContext extends LintedFile {
+    /** The source code of the file being linted. */
+    readonly sourceCode: ShellSourceCode;
+}
+
+/**
+ * One command a script declares it depends on, as reported by a
+ * {@link DeclarationConvention}. Where the declaration lives is part of what
+ * it is, so it is one of three kinds, told apart by the required `kind`:
+ * written in the script ({@link ScriptDeclaredCommand}), in another file
+ * ({@link FileDeclaredCommand}), or in a source that can only be described in
+ * words ({@link DescribedDeclaredCommand}). Only the script kind has a `range`, so
+ * narrow on `kind` before reading it.
+ *
+ * @public
+ */
+export declare type DeclaredCommand = ScriptDeclaredCommand | FileDeclaredCommand | DescribedDeclaredCommand;
+
+/**
+ * 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>;
+
+/**
+ * A declaration whose source can only be described in words: there is no
+ * range in the script and no path to point at, only a phrase that tells a
+ * person where it comes from, such as a list written in the ESLint config, a
+ * convention's own constant, or a snapshot of a tool registry. A report about
+ * it names the source by `description` and carries no fix.
+ *
+ * @public
+ */
+export declare interface DescribedDeclaredCommand {
+    /** Says the declaration's source is described in words, by `description`. */
+    readonly kind: 'described';
+    /** The declared command name, exactly as it would be invoked. */
+    readonly name: string;
+    /**
+     * Names the source for a person who wants to change the declaration, as a
+     * phrase that reads after "declared in": "the web image list in
+     * eslint.config.js", "the tool registry snapshot of 2026-11-01". It must be a
+     * non-empty single line.
+     */
+    readonly description: string;
+}
+
+/**
+ * A declaration written in a file other than the linted script: a per-script
+ * sidecar, or a manifest several scripts share. A report about it names the
+ * file, and carries no fix, since a fix can only edit the linted script.
+ *
+ * @public
+ */
+export declare interface FileDeclaredCommand {
+    /** Says the declaration is in another file. */
+    readonly kind: 'file';
+    /** The declared command name, exactly as it would be invoked. */
+    readonly name: string;
+    /**
+     * Where a person or a tool should look for the declaration: a path
+     * relative to {@link LintedFile.cwd}, or an absolute path. It must be a
+     * non-empty single line. Rules name it in their reports as given; they never
+     * read it.
+     */
+    readonly path: string;
+    /** The 1-based line of `path` that declares the command, when the convention knows it. */
+    readonly line?: number;
+}
+
+/**
+ * The file ESLint is linting, as its rule context names it. A
+ * {@link DeclarationConvention} receives it so it can find declarations kept
+ * outside the script, such as a per-script sidecar file next to it.
+ *
+ * A rule's own `context` is a `LintedFile`, so a rule that calls
+ * `declaredCommands` passes `context`.
+ *
+ * @public
+ */
+export declare interface LintedFile {
+    /**
+     * The name ESLint lints the code under (`context.filename`). For a code
+     * block a processor extracts from another file it is virtual
+     * (`README.md/0_0.sh`).
+     */
+    readonly filename: string;
+    /**
+     * The path on disk ESLint associates with the code
+     * (`context.physicalFilename`): the file it read, or the file a
+     * processor's code block came from. With `--stdin --stdin-filename`, it is
+     * the name given on the command line; the code came from standard input,
+     * and that file may not exist. Resolve sidecar paths from this one, and
+     * treat a missing sidecar as a normal case.
+     */
+    readonly physicalFilename: string;
+    /**
+     * ESLint's working directory (`context.cwd`). A relative
+     * {@link FileDeclaredCommand.path} is relative to it.
+     */
+    readonly cwd: string;
+}
+
+/**
+ * The result of {@link ShellLanguage.normalizeLanguageOptions}: `dialect` and
+ * `directivePrefix` are always resolved to concrete values (defaulted when
+ * the caller didn't specify them), and `toJSON()` provides the "custom
+ * serialization" ESLint's languages guide recommends
+ * (https://eslint.org/docs/latest/extend/languages, "normalizeLanguageOptions")
+ * so that config caching keyed off `JSON.stringify(languageOptions)` is
+ * stable irrespective of the input object's own key order — `JSON.stringify`
+ * calls `toJSON()` automatically when present.
+ *
+ * @public
+ */
+export declare interface NormalizedShellLanguageOptions extends Record<string, unknown> {
+    readonly dialect: ShellDialect;
+    readonly directivePrefix: string;
+    readonly shellVersion?: string;
+    toJSON(): ShellLanguageOptionsJSON;
+}
 
 /**
- * The `@eslint-sh/eslint-plugin` plugin object: `languages.sh` provides
+ * The `@eslint-sh/eslint-plugin` plugin object, this package's default
+ * export (`import sh from '@eslint-sh/eslint-plugin'`). `languages.sh` provides
  * `ShellLanguage` / `ShellSourceCode`, selected in a flat config via
  * `language: "sh/sh"` (`namespace: "sh"`). `meta.version` is read from this
  * package's own `package.json` at runtime — never hardcoded (see
  * `version.ts`).
  *
- * The empty `rules` registry lets consumers supply their own rules while
- * sharing parsing, selectors, source coordinates, and directive semantics.
+ * `rules` holds the plugin's built-in rules, each built with
+ * `defineShellRule` (so each declares `meta.languages: ["sh/sh"]`) and
+ * linking its docs page from `meta.docs.url`. Consumers can also supply their
+ * own rules, built with the same `defineShellRule`, while sharing parsing,
+ * selectors, source coordinates, and directive semantics.
+ *
+ * `configs.recommended` is the `sh/recommended` preset: a single config
+ * object carrying `plugins: { sh }` and `language: "sh/sh"` but no `files`,
+ * so it inherits the globs of the entry that extends it:
+ * `{ files: [...], extends: [sh.configs.recommended] }`. It enables the
+ * convention-free policy rules. The rules index at
+ * https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/rules/README.md
+ * describes preset membership and available autofixes.
+ * `configs['agent-authored']` is the strict `sh/agent-authored` preset for
+ * machine-written, human-reviewed scripts:
+ * every `recommended` rule plus the contract rules, all at `error`.
+ * `configs['bash-3.2']` and `configs['posix-portable']` are deployment-target
+ * packs: the first sets `languageOptions.shellVersion: "3.2"` and enables
+ * every version-gated `compat/*` rule; the second sets
+ * `languageOptions.dialect: "posix"`, enables the `compat/*` rules and the
+ * shebang/dialect check, and requires `set -eu`; it reports named constructs
+ * that fail on dash, not every non-POSIX construct, and leaves `local`,
+ * `echo -e` and the rest of shellcheck's SC3xxx catalog to shellcheck. Every
+ * shipped config is a
+ * single object with no `files`; the two packs also carry `languageOptions`,
+ * because the target they name is their meaning.
  *
  * Re-exported, unchanged, as the default export of the `eslint-sh` umbrella
  * package: importing this package or the umbrella package both yield the
  * same plugin object.
+ *
+ * @public
  */
-declare const _default: {
+declare const plugin: {
     meta: {
         name: string;
         version: string;
@@ -34,57 +387,204 @@ declare const _default: {
     languages: {
         sh: ShellLanguage;
     };
-    rules: {};
+    rules: Record<string, RuleDefinition<RuleDefinitionTypeOptions>>;
+    configs: {
+        recommended: ConfigObject;
+        "agent-authored": ConfigObject;
+        "bash-3.2": ConfigObject;
+        "posix-portable": ConfigObject;
+    };
 };
-export default _default;
+export default plugin;
 
 /**
- * The result of {@link ShellLanguage.normalizeLanguageOptions}: `dialect` and
- * `directivePrefix` are always resolved to concrete values (defaulted when
- * the caller didn't specify them), and `toJSON()` provides the "custom
- * serialization" ESLint's languages guide recommends
- * (https://eslint.org/docs/latest/extend/languages, "normalizeLanguageOptions")
- * so that config caching keyed off `JSON.stringify(languageOptions)` is
- * stable irrespective of the input object's own key order — `JSON.stringify`
- * calls `toJSON()` automatically when present.
+ * Returns the declarations `convention` makes for the file `context` is
+ * linting, after checking each one against its kind. Call it from a rule's
+ * listener with the convention `resolveDeclarationConvention` returned and
+ * the rule's own `context`.
+ *
+ * The convention receives a frozen {@link LintedFile} holding only
+ * `filename`, `physicalFilename` and `cwd`, never the whole context, so it
+ * sees which file it is reading and nothing it could report through.
+ *
+ * Throws an `Error` that names the setting, starting
+ * `Invalid settings.sh.declarationConvention:`, and shows the offending value when
+ * `declaredCommands` does not return an array, or returns a declaration with
+ * a missing or unknown `kind`, without its kind's fields, or with a `range`
+ * outside the linted text.
+ *
+ * @example
+ * ```ts
+ * const convention = resolveDeclarationConvention(context);
+ * if (convention === null) return {};
+ * return {
+ *   File() {
+ *     for (const declared of readDeclaredCommands(convention, context)) {
+ *       if (declared.kind === 'script') {
+ *         // declared.range is an offset pair into context.sourceCode.text
+ *       }
+ *     }
+ *   },
+ * };
+ * ```
  *
  * @public
  */
-export declare interface NormalizedShellLanguageOptions extends Record<string, unknown> {
-    readonly dialect: ShellDialect;
-    readonly directivePrefix: string;
-    readonly shellVersion?: string;
-    toJSON(): ShellLanguageOptionsJSON;
-}
+export declare function readDeclaredCommands(convention: DeclarationConvention, context: DeclarationReadContext): DeclaredCommand[];
+
+export { ResolveArgv0Options }
+
+/**
+ * Resolves the declaration convention bound for the rule running in
+ * `context`: the rule's `declarationConvention` option, else
+ * `settings.sh.declarationConvention`, else `null` (the rule is inert).
+ *
+ * Throws an `Error` naming the offending setting when the configured value is
+ * present but does not implement `declaredCommands` (or has a non-function
+ * `removeDeclaration`). The message names where the value came from and what
+ * it was, for example one beginning
+ * `Invalid settings.sh.declarationConvention: expected a declaration convention`
+ * and ending `but got string "jq".` Call it from `create()`, so the error
+ * surfaces as ESLint's
+ * configuration message for the file being linted.
+ *
+ * A rule that receives `null` should register no listeners: with no
+ * convention bound, a convention consumer has nothing to check.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   defineShellRule,
+ *   readDeclaredCommands,
+ *   resolveDeclarationConvention,
+ * } from '@eslint-sh/eslint-plugin';
+ *
+ * export const maxDeclaredCommands = defineShellRule({
+ *   meta: { schema: [], messages: { tooMany: 'Declare at most 5 commands.' } },
+ *   create(context) {
+ *     const convention = resolveDeclarationConvention(context);
+ *     if (convention === null) return {};
+ *     return {
+ *       File(node) {
+ *         // Validated declarations for the file `context` is linting.
+ *         if (readDeclaredCommands(convention, context).length > 5) {
+ *           context.report({ node, messageId: 'tooMany' });
+ *         }
+ *       },
+ *     };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function resolveDeclarationConvention(context: DeclarationConventionBindingContext): DeclarationConvention | null;
 
 /**
  * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
  * The view supplies locations and selector fields; sh-ast/analyze owns the word
  * interpretation. Fabricated or synthetic view nodes have no source syntax and
  * are rejected instead of being treated as known or unknown shell values.
+ * A static word that ends a line of a CRLF file resolves without the line
+ * terminator's carriage return, as it would on LF input.
  * @public
  */
-export declare function resolveWord(word: ShellNode, options?: ResolveWordOptions): WordResolution;
+export declare function resolveWord(word: ShellNodeOf<'Word'>, options?: ResolveWordOptions): WordResolution;
 
-/** Directive processing uses the comment text without its leading shell hash. @public */
-export declare interface ShellComment extends ShellNode {
-    /** Comment discriminator used by directive collection. */
-    readonly type: 'Comment';
-    /** Decoded comment content after the leading hash, preserving its whitespace. */
-    readonly text: string;
+/**
+ * A declaration written in the linted script's own text: the only kind an
+ * ESLint fix can edit, because a fix edits only the file being linted.
+ *
+ * @public
+ */
+export declare interface ScriptDeclaredCommand {
+    /** Says the declaration is in the script. */
+    readonly kind: 'script';
+    /** The declared command name, exactly as it would be invoked (`jq`, `docker-compose`). */
+    readonly name: string;
+    /**
+     * The `[start, end)` source range of this declaration, as UTF-16 offsets
+     * into `sourceCode.text` (the same coordinates as every node's `range`),
+     * with `0 <= start <= end <= sourceCode.text.length`. Rules report a
+     * declaration at this range, so it should cover the text that declares
+     * this one name and nothing else.
+     */
+    readonly range: readonly [number, number];
 }
 
+/**
+ * One command invocation in a linted shell file, in lint-view terms: an
+ * `sh-ast/analyze` `CommandSite` whose `node` is the `CallExpr` view node
+ * ESLint passes to rule visitors, so a rule can `context.report()` on it.
+ *
+ * The data comes from `sh-ast/analyze`'s `enumerateCommands` and is facts
+ * only: how the command is reached and what its words resolve to, never a
+ * verdict on whether running it is safe. A dynamic (`static: false`) `argv0`
+ * is a normal result.
+ *
+ * Read one through `ShellSourceCode.getCommandSites()`.
+ *
+ * Every rule linting a file sees the same sites, so each one is deeply
+ * frozen: the entry, its `context` array and every frame in it, its `argv`
+ * array, and every `WordResolution` in `argv` (`argv0` included). Writing to
+ * any of them throws in strict-mode code and is ignored otherwise, so one rule
+ * cannot change what another rule reads. The `node` is the shared lint view
+ * node, which, like every node ESLint passes to rules, is not frozen and must
+ * not be modified.
+ *
+ * @public
+ */
+export declare interface ShellCommandSite {
+    /**
+     * The `CallExpr` view node for this command: the same object (`===`)
+     * ESLint passes to a `CallExpr` visitor, with `range` and `loc` in this
+     * file's UTF-16 coordinates.
+     */
+    readonly node: ShellNodeOf<'CallExpr'>;
+    /**
+     * The path from the file root to this command, outermost frame first,
+     * exactly as `sh-ast/analyze` reports it. For example, `date` in
+     * `f() { echo "$(date)"; }` has
+     * `[{ kind: 'function', name: 'f' }, { kind: 'cmdSubst' }]`.
+     */
+    readonly context: readonly CommandContext[];
+    /** The command word (`argv[0]`) resolved with `{ context: 'command-argument' }`. */
+    readonly argv0: WordResolution;
+    /**
+     * Every word of the command, `argv0` included, in argument order, each
+     * resolved with `{ context: 'command-argument' }`. Leading `VAR=val`
+     * assignments are not part of argv.
+     */
+    readonly argv: readonly WordResolution[];
+    /**
+     * Follows this command's argv0 through transparent wrappers (`env`, `sudo`,
+     * `nohup`, `exec`, …) and returns `sh-ast/analyze`'s `resolveArgv0`
+     * result. Same answer as
+     * `ShellSourceCode.resolveInvokedCommand(node, options)`; both read the
+     * same per-file index.
+     *
+     * @param options - Forwarded to `resolveArgv0` unchanged.
+     * `transparentWrappers` replaces `sh-ast/analyze`'s
+     * `DEFAULT_TRANSPARENT_WRAPPERS`; spread the defaults into the array to
+     * extend them instead.
+     * @returns A new result on every call. Its `chain` and `chainIndices`
+     * arrays belong to the caller. `chainIndices` gives each chain entry's
+     * position in this site's `argv`.
+     * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+     * `options.transparentWrappers` contains a malformed entry.
+     */
+    resolveInvokedCommand(options?: ResolveArgv0Options): Argv0Resolution;
+}
+
+/** Directive processing uses the comment text without its leading shell hash. @public */
+export declare type ShellComment = ShellNodeOf<'Comment'>;
+
 /** Owns ESLint configuration labels and validates their consumer-facing meaning before parsing. */
 /** The dialect labels understood by ESLint configuration, mapped to upstream numeric variants when parsing. @public */
 export declare type ShellDialect = 'bash' | 'posix' | 'mksh' | 'bats' | 'zsh';
 
 /** The lint root has a statement collection even when upstream represents it as nil. @public */
-export declare interface ShellFile extends ShellNode {
-    /** Root discriminator retained for selectors. */
-    readonly type: 'File';
-    /** Top-level statements in source order; nil upstream slices become an empty view. */
-    readonly stmts: readonly ShellNode[];
-}
+export declare type ShellFile = ShellNodeOf<'File'>;
 
 /**
  * `ShellLanguage` — the `@eslint/core` `Language` implementation for shell
@@ -144,6 +644,13 @@ export declare class ShellLanguage implements Language {
      * the `{ok: true, ast}` / `{ok: false, errors}` shape `Language.parse` is
      * required to return. Never throws — parse failures are reported as
      * fatal lint messages, per the `Language` contract.
+     *
+     * A file whose extension marks it as a known non-shell source type (for
+     * example `.js` or `.json`) is never shell-parsed: it fails with a single
+     * diagnostic explaining that a `language: 'sh/sh'` config entry without
+     * `files` reached it, and how to scope that entry. A source in which
+     * the parser silently drops text at a U+0080 fails at that character; a
+     * U+0080 the parser reads as an ordinary character does not.
      */
     parse(file: File_2, context: {
         languageOptions: ShellLanguageOptions;
@@ -157,7 +664,9 @@ export declare class ShellLanguage implements Language {
      * `createSourceCode` is called) — `directivePrefix` is therefore always
      * present, but `?? 'eslint'` stays as an explicit, honest fallback for
      * direct construction (e.g. tests that skip the `Language` normalization
-     * step), mirroring `parse()`'s `dialect` default above.
+     * step), mirroring `parse()`'s `dialect` default above. `dialect` and
+     * `shellVersion` are forwarded so rules read the same normalized values
+     * through `sourceCode.dialect` / `sourceCode.shellVersion`.
      */
     createSourceCode(file: File_2, parseResult: OkParseResult<ShellFile>, context: {
         languageOptions: ShellLanguageOptions;
@@ -181,6 +690,13 @@ export declare class ShellLanguage implements Language {
  */
 export declare interface ShellLanguageOptions extends Record<string, unknown> {
     readonly dialect?: ShellDialect;
+    /**
+     * The Bash version (`MAJOR[.MINOR]`, such as `"3.2"`) the scripts must run
+     * on. The parser ignores it. The `compat/*` rules read it: unset means the
+     * newest version, versions compare numerically by major then minor, and
+     * under `dialect: "posix"` Bash-only features are unavailable at any
+     * version.
+     */
     readonly shellVersion?: string;
     /**
      * The prefix directive/inline-config comments must start with — e.g. the
@@ -217,24 +733,107 @@ export declare interface ShellLanguageOptionsJSON {
 }
 
 /**
- * A node in the consumer's lint view. Scalar/child fields use lowercase upstream
- * spellings; syntax fidelity belongs to the associated upstream tree. Auxiliary
- * view nodes may have spans derived from children and are not upstream Nodes.
+ * 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 declare interface ShellNode {
-    /** Original syntax kind retained as the discriminator for lint selectors. */
-    readonly type: string;
-    /** Half-open UTF-16 span used to slice source and place fixes. */
-    readonly range: readonly [number, number];
-    /** Source-derived endpoints for ESLint diagnostics. */
-    readonly loc: {
-        readonly start: ShellPosition;
-        readonly end: ShellPosition;
+export declare type ShellListener<Node extends ShellNode = ShellNode> = {
+    listener(node: Node, parent: ShellNode | undefined): void;
+}['listener'];
+
+/**
+ * A node in the consumer's lint view: the union of every node type, so
+ * narrowing on `type` gives that node's fields with no cast. Scalar/child fields
+ * use lowercase upstream spellings; syntax fidelity belongs to the associated
+ * upstream tree. Auxiliary view nodes may have spans derived from children and
+ * are not upstream Nodes.
+ * @public
+ */
+export declare type ShellNode = ShellNodeMap[ShellNodeType];
+
+/**
+ * The lint-view type of one upstream field value `Value`: a record becomes the
+ * node type of that record (a union of records, a union of node types), a slice
+ * becomes a read-only array of such nodes with its nil elements removed, a Go
+ * string becomes a JavaScript `string`, and booleans and operator values stay
+ * as they are. Upstream nil (`null`) and typed nils never reach a view, so
+ * neither appears in the result.
+ *
+ * It is the type of every field of every {@link ShellNodeMap} entry, exported
+ * so a helper that takes or returns a node's field value can name it.
+ *
+ * @public
+ */
+export declare type ShellNodeField<Value> = Exclude<Value, null | {
+    readonly Type: 'TypedNil';
+}> extends infer Present ? Present extends readonly (infer Element)[] ? readonly ShellNodeField<Element>[] : Present extends {
+    readonly Type: infer Type extends ShellNodeType;
+} ? ShellNodeMap[Type] : Present extends string | Uint8Array ? string : Present : never;
+
+/**
+ * Lint-view node types by their `type` discriminator, one entry per upstream
+ * syntax record. It is computed from `sh-ast`'s generated interfaces, so it
+ * follows the pinned mvdan/sh version.
+ *
+ * A node has `type`, `range` and `loc`, plus a lowercase field for each
+ * non-position upstream field. A field that is a single child that may be nil
+ * upstream is optional, because the view omits the key when the child is
+ * absent; a slice is always present.
+ *
+ * `range` is a half-open UTF-16 span of the source text and `loc` its ESLint
+ * line/column form; both describe the view, not the upstream byte positions. A
+ * node whose line ends in CRLF ends before the `\r` (and a text field such as
+ * `value` loses that one trailing `\r`), so a CRLF file reads like its LF
+ * twin. Auxiliary records (`Expansion`, `Replace`, `Slice`) take their span
+ * from their children.
+ *
+ * @public
+ */
+export declare type ShellNodeMap = {
+    [Record in Exclude<Node, {
+        readonly Type: 'TypedNil';
+    }> | Expansion | Replace | Slice as Record['Type']]: {
+        /** Syntax kind of this node; the discriminator to narrow a ShellNode by. */
+        readonly type: Record['Type'];
+        /**
+         * Half-open UTF-16 span of the node in the source text. Its type is the
+         * mutable tuple ESLint's `fixer` methods take, so `node.range` can be passed
+         * to `fixer.insertTextBeforeRange` and the others without a cast; treat it
+         * as read-only.
+         */
+        range: [number, number];
+        /** ESLint line and column of the span's two ends. */
+        readonly loc: {
+            readonly start: ShellPosition;
+            readonly end: ShellPosition;
+        };
+    } & {
+        readonly [Name in keyof Record & string as Name extends 'Type' ? never : [Record[Name]] extends [SyntaxPos] ? never : null extends Record[Name] ? Exclude<Record[Name], null | {
+            readonly Type: 'TypedNil';
+        }> extends {
+            readonly Type: string;
+        } ? never : Lowercase<Name> : Lowercase<Name>]: ShellNodeField<Record[Name]>;
+    } & {
+        readonly [Name in keyof Record & string as null extends Record[Name] ? Exclude<Record[Name], null | {
+            readonly Type: 'TypedNil';
+        }> extends {
+            readonly Type: string;
+        } ? Lowercase<Name> : never : never]?: ShellNodeField<Record[Name]>;
     };
-    /** Lowercase syntax fields containing consumer children or decoded scalar values. */
-    readonly [field: string]: unknown;
-}
+};
+
+/** The lint-view node whose `type` is `Type`, for example `ShellNodeOf<'Stmt'>`. @public */
+export declare type ShellNodeOf<Type extends ShellNodeType> = ShellNodeMap[Type];
+
+/** Every value a lint-view node's `type` can hold. @public */
+export declare type ShellNodeType = keyof ShellNodeMap;
 
 /** An ESLint location counts UTF-16 units, with both line and column starting at one. @public */
 export declare interface ShellPosition {
@@ -244,6 +843,105 @@ export declare interface ShellPosition {
     readonly column: number;
 }
 
+/**
+ * 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 declare 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'];
+    };
+};
+
+/**
+ * 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 declare 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 declare 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 declare 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;
+}
+
+/**
+ * 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 declare interface ShellRuleVisitor extends ShellTypedListeners {
+    [selector: string]: ShellListener | undefined;
+}
+
 /**
  * `ShellSourceCode` — the `SourceCode` object ESLint uses to work with a
  * parsed shell file. Extends `@eslint/plugin-kit`'s `TextSourceCodeBase`, which
@@ -260,8 +958,8 @@ export declare interface ShellPosition {
  * `applyInlineConfig`) recognizes all four disable-comment forms
  * (`<prefix>-disable`, `<prefix>-enable`, `<prefix>-disable-line`,
  * `<prefix>-disable-next-line`) plus whole-file inline rule config
- * (bare `<prefix> <rule-config>`), sourced from `Comment` nodes gathered via
- * the consumer's `walkShell()` and parsed with
+ * (bare `<prefix> <rule-config>`), sourced from the tree's `Comment` nodes
+ * and parsed with
  * `@eslint/plugin-kit`'s `ConfigCommentParser` — the same building blocks
  * `@eslint/json`'s `JSONSourceCode` uses, generalized so the `<prefix>` is
  * configurable (default `"eslint"`; see `ShellLanguageOptions.directivePrefix`)
@@ -271,6 +969,24 @@ export declare interface ShellPosition {
  * classes) is implemented on `ShellLanguage` — see `shell-language.ts` and
  * `selector-classes.ts`.
  *
+ * Rule-author helpers (`resolveWordText`, `getCommandName`,
+ * `resolveInvokedCommand`, `getCommandSites`) answer "is this word statically
+ * the string `jq`?", "which command does this invocation run?", and "which
+ * commands does this file run, and where?" by delegating to
+ * `sh-ast/analyze`. They never reinterpret words themselves, so every rule
+ * gets the same answer for the same syntax. `dialect` and `shellVersion`
+ * expose the file's normalized language options.
+ *
+ * Syntax access (`getSyntax`, `getViewNode`, `getIndexFromSyntaxPos`,
+ * `getLocFromSyntaxPos`) reaches behind the lint view to the sh-ast records
+ * this file was parsed into: from a view node to its record and back, and
+ * from a record's byte positions (such as `BinaryCmd.OpPos`, which the view
+ * leaves out) to ESLint coordinates in this file's text.
+ *
+ * Printed fixes (`getEditableSyntax`, `getPrintedReplacement`) edit an
+ * independent copy of a view node's record and print it with sh-ast's
+ * printer, returning the source range and text for `fixer.replaceTextRange`.
+ *
  * @public
  */
 export declare class ShellSourceCode extends TextSourceCodeBase<{
@@ -284,7 +1000,324 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
         text: string;
         ast: ShellFile;
         directivePrefix?: string;
+        dialect?: ShellDialect;
+        shellVersion?: string;
     });
+    /**
+     * The shell dialect this file was parsed as: the normalized
+     * `languageOptions.dialect`, which defaults to `"bash"` when the config
+     * leaves it unset. Rules use it to gate dialect-specific checks.
+     */
+    get dialect(): ShellDialect;
+    /**
+     * The configured `languageOptions.shellVersion` (a `MAJOR[.MINOR]` string
+     * such as `"3.2"`), or `undefined` when the config does not set one. The
+     * parser never reads it; it exists for rules that gate on shell version.
+     */
+    get shellVersion(): string | undefined;
+    /**
+     * The one-based location of a UTF-16 `index` in this file's text, where
+     * `index` may be anywhere from 0 to `text.length`. CRLF counts as one line
+     * break.
+     *
+     * Overrides the base class, which measures every index from the root
+     * node's own start and so assumes the root spans the whole text. A shell
+     * file's root starts at its first statement or comment, so the base answer
+     * was shifted by any leading blank lines or indentation.
+     *
+     * @throws TypeError when `index` is not a number.
+     * @throws RangeError when `index` is not an integer from 0 to `text.length`.
+     */
+    getLocFromIndex(index: number): {
+        line: number;
+        column: number;
+    };
+    /**
+     * The UTF-16 index of a one-based `loc` in this file's text: the inverse of
+     * {@link ShellSourceCode.getLocFromIndex}. The column may name any position
+     * on its line up to and including the line break.
+     *
+     * Overrides the base class for the same reason as `getLocFromIndex`.
+     *
+     * @throws TypeError when `loc` is not an object with numeric `line` and `column`.
+     * @throws RangeError when `loc` is not inside the text.
+     */
+    getIndexFromLoc(loc: {
+        line: number;
+        column: number;
+    }): number;
+    /**
+     * Returns the literal text of `word` when `sh-ast/analyze`'s `resolveWord`
+     * reports it static, or `null` otherwise.
+     *
+     * Delegates to `resolveWord` (through this package's `resolveWord` export),
+     * which alone defines what "static" means: a word is static iff
+     * `resolveWord` reports `static: true`. Its non-static reasons are
+     * `expansion`, `tilde`, `glob`, `brace`, `locale`, and `unsupported`.
+     * Call the root `resolveWord` export instead when the reason matters.
+     *
+     * `options` is forwarded to `resolveWord` unchanged. When it is omitted, the
+     * word's grammar position picks the tilde context: a word in a `CallExpr`'s
+     * `args` uses `{ context: 'command-argument' }`, the context
+     * `enumerateCommands` uses for argv, so `resolveWordText(callExpr.args[0])`
+     * equals `getCommandName(callExpr)`. Any other word uses `resolveWord`'s
+     * conservative default, which also treats a `~` after an unquoted `:` as a
+     * tilde expansion, as assignment values do.
+     *
+     * @param word - A parsed `Word` node from this file's lint tree.
+     * @param options - Forwarded to `resolveWord` unchanged when supplied.
+     * @returns The resolved text, or `null` when the word is not static.
+     * @throws TypeError when `word` is not a parsed shell `Word`.
+     */
+    resolveWordText(word: ShellNodeOf<'Word'>, options?: ResolveWordOptions): string | null;
+    /**
+     * Returns the static text of `callExpr`'s command word (`argv[0]`) as
+     * written, or `null` when that word is dynamic or absent. Transparent
+     * wrappers are **not** followed: `sudo rm x` yields `"sudo"`. Use
+     * {@link ShellSourceCode.resolveInvokedCommand} for the command a wrapper
+     * chain actually runs.
+     *
+     * Delegates to `sh-ast/analyze`: the answer is the `argv0` resolution of the
+     * `CommandSite` that `enumerateCommands` reports for this `CallExpr` in this
+     * file. Leading `VAR=val` assignments are not part of argv, so
+     * `FOO=1 jq .` yields `"jq"`. An assignment-only statement (`FOO=1`) has no
+     * argv0 and no `CommandSite`, and yields `null`.
+     *
+     * @param callExpr - A parsed `CallExpr` node from this file's lint tree.
+     * @returns The command word's static text, or `null`.
+     * @throws TypeError when `callExpr` is not a parsed shell `CallExpr`.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard; see
+     * {@link ShellSourceCode.resolveInvokedCommand}.
+     */
+    getCommandName(callExpr: ShellNodeOf<'CallExpr'>): string | null;
+    /**
+     * Follows `callExpr`'s argv0 through transparent wrappers (`env`, `sudo`,
+     * `nohup`, `exec`, …) and returns `sh-ast/analyze`'s full `resolveArgv0`
+     * result, or `null` for a `CallExpr` that has no `CommandSite` (an
+     * assignment-only statement such as `FOO=1`).
+     *
+     * Delegates to `resolveArgv0` with the `CommandSite` that `enumerateCommands`
+     * reports for this `CallExpr` in this file, so it inherits that function's
+     * guarantee that an unknowable word is never guessed through. Read the
+     * effective command's name as
+     * `res.effective.static ? res.effective.text : null`.
+     * `sudo -u x "$prog"` and `exec "$@"` have a non-static `effective` with
+     * reason `expansion`; `env -S '…'` has reason `embedded-command`; `chain`
+     * lists every word resolved along the way, outermost wrapper first, and
+     * `chainIndices` gives each entry's position in the command's `argv` (as
+     * {@link ShellSourceCode.getCommandSites} reports it). When `effective` is
+     * static, the effective command's arguments are
+     * `argv.slice(chainIndices.at(-1)! + 1)`: every entry after the effective
+     * command's own index.
+     *
+     * Enumeration runs once per file, the first time any command helper is
+     * called. If the file's nesting exceeds `enumerateCommands`'s recursion
+     * guard, its `ShAnalyzeMaxDepthError` propagates unchanged and ESLint
+     * reports the rule as crashed for that file. That fails closed: a partial
+     * index would silently omit real commands.
+     *
+     * @param callExpr - A parsed `CallExpr` node from this file's lint tree.
+     * @param options - Forwarded to `resolveArgv0` unchanged.
+     * `transparentWrappers` replaces `sh-ast/analyze`'s
+     * `DEFAULT_TRANSPARENT_WRAPPERS`; spread the defaults into the array to
+     * extend them instead.
+     * @returns The resolution, or `null` when `callExpr` invokes no command.
+     * @throws TypeError when `callExpr` is not a parsed shell `CallExpr`.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard.
+     * @throws `ShAnalyzeInvalidWrapperSpecError` (from `sh-ast/analyze`) when
+     * `options.transparentWrappers` contains a malformed entry.
+     */
+    resolveInvokedCommand(callExpr: ShellNodeOf<'CallExpr'>, options?: ResolveArgv0Options): Argv0Resolution | null;
+    /**
+     * Returns every command invocation in this file, one entry per
+     * `sh-ast/analyze` `CommandSite`, in source order. Use it when a rule needs
+     * the whole file's commands with their structural context, such as every
+     * command inside a function or inside `$(…)`, instead of visiting
+     * `CallExpr` nodes one by one.
+     *
+     * The data comes from `sh-ast/analyze`'s `enumerateCommands`: facts about
+     * how each command is reached and what its words resolve to, never a
+     * verdict. Each entry's `context`, `argv0`, and `argv` are analysis's own
+     * values, unchanged; `context` lists frames outermost first, as in sh-ast.
+     * Each entry's `node` is the `CallExpr` view node (`===` the node ESLint
+     * passes to a `CallExpr` visitor), so it can be passed to
+     * `context.report()`.
+     *
+     * An assignment-only statement (`FOO=1`) runs no command and has no entry,
+     * although a command substitution in its value (`FOO=$(date)`) does.
+     *
+     * Enumeration runs at most once per file, shared with
+     * {@link ShellSourceCode.getCommandName} and
+     * {@link ShellSourceCode.resolveInvokedCommand}, and every call returns the
+     * same array. Because every rule shares it, the array and everything in each
+     * entry except `node` are deeply frozen (see `ShellCommandSite`): no rule can
+     * change what another rule reads. If the file's nesting exceeds `enumerateCommands`'s
+     * recursion guard, its `ShAnalyzeMaxDepthError` propagates unchanged, as it
+     * does for those helpers: a partial list would silently omit real commands.
+     *
+     * @returns This file's command sites, in source order.
+     * @throws `ShAnalyzeMaxDepthError` (from `sh-ast/analyze`) when this file's
+     * nesting exceeds analysis's recursion guard.
+     */
+    getCommandSites(): readonly ShellCommandSite[];
+    /**
+     * Returns the sh-ast record `node` was projected from: this file's original
+     * parse of `node`, with every field the lint view leaves out, including
+     * named token positions such as `BinaryCmd.OpPos`, `Stmt.Semicolon` and
+     * `Redirect.OpPos`. Pass those positions to
+     * {@link ShellSourceCode.getIndexFromSyntaxPos} or
+     * {@link ShellSourceCode.getLocFromSyntaxPos} to report on them, or pass the
+     * record to an `sh-ast/analyze` function.
+     *
+     * The returned record is read-only by contract. It is the language's
+     * original parse, shared by every rule and helper linting this file, and
+     * mutating it is unsupported: helpers such as
+     * {@link ShellSourceCode.resolveWordText} read the same record and would see
+     * the edit. It is not frozen, so a write does not throw. Make edits on an
+     * editable copy from {@link ShellSourceCode.getEditableSyntax} instead.
+     *
+     * @param node - A view node from this file's lint tree.
+     * @returns The original sh-ast record, or `undefined` when `node` has none
+     * in this file: an auxiliary view (a record whose type is not an sh-ast
+     * `Node`, such as the `Slice` of `${x:1:2}`), a view node from another
+     * file's tree, or an
+     * object that did not come from the parser.
+     */
+    getSyntax(node: ShellNode): Node | undefined;
+    /**
+     * Returns the lint view node projected from `syntax`: the inverse of
+     * {@link ShellSourceCode.getSyntax}. The result is the same object (`===`)
+     * ESLint passes to rule visitors, so it can be passed to
+     * `context.report()`. Use it to come back to the view after navigating the
+     * original records, for example from a `Stmt` record's `Cmd`.
+     *
+     * Lookup is by object identity, so only the parser's own records match.
+     * sh-ast's `walk` passes its callback a fresh copy of each comment stored
+     * on a `Stmt`, `CaseItem` or `ArrayElem`, as Go's `syntax.Walk` does, so
+     * those `Comment` copies have no view node. Read the stored comment from
+     * the record's `Comments` array instead.
+     *
+     * @param syntax - An sh-ast `Node` record from this file's original parse.
+     * @returns The view node, or `undefined` for any other record, including a
+     * copy of one of this file's records (such as a `structuredClone`) and a
+     * record from another parse.
+     */
+    getViewNode(syntax: Node): ShellNode | undefined;
+    /**
+     * Returns an independent, editable deep copy of the sh-ast record `node`
+     * was parsed from: the first half of a printed fix. Edit the copy, then pass
+     * it to {@link ShellSourceCode.getPrintedReplacement}.
+     *
+     * The copy is `structuredClone` of the record
+     * {@link ShellSourceCode.getSyntax} returns. sh-ast documents and tests
+     * ordinary `structuredClone` as the supported way to make an independent
+     * editable copy of a syntax subtree (sh-ast 0.7.0 README, "Editing and
+     * printing"), so no second parse is involved. The copy owns its records,
+     * arrays, positions and byte buffers. Editing it leaves this file's original
+     * syntax, its lint view, its cached traversal and the answers of view-aware
+     * helpers such as `resolveWord` and
+     * {@link ShellSourceCode.resolveWordText} unchanged. Each call returns a new
+     * copy.
+     *
+     * The copy's position fields keep their original values, and the copy has
+     * no view node: {@link ShellSourceCode.getViewNode},
+     * {@link ShellSourceCode.getIndexFromSyntaxPos} and the parse's position
+     * snapshot describe the original source, not the edit. Keep `node` to know
+     * which source range the fix replaces.
+     *
+     * @param node - A view node from this file's lint tree.
+     * @returns A deep copy of `node`'s original sh-ast record.
+     * @throws TypeError when `node` has no original record in this file: an
+     * auxiliary view (such as the `Slice` of `${x:1:2}`), a view node of another
+     * file, or an object that did not come from the parser.
+     */
+    getEditableSyntax(node: ShellNode): Node;
+    /**
+     * Prints `edited` with sh-ast's `printSync` and pairs the text with the
+     * source range it replaces, so a printed fix is
+     * `fix: (fixer) => fixer.replaceTextRange(r.range, r.text)`. `edited` is
+     * usually a copy from {@link ShellSourceCode.getEditableSyntax} of `node`
+     * or of one of its ancestors.
+     *
+     * The range is `node.range`, except that a `File` root replaces the whole
+     * text (`[0, text.length]`) whatever `node` is, which allows whole-file
+     * regeneration. `options` is passed to `printSync` unchanged.
+     *
+     * The printer formats; it does not replay the source. Its output starts at
+     * column 0 and indents nested lines with upstream's indentation (tabs by
+     * default, `Indent` spaces when `options.Indent` is set). Replacing a
+     * multi-line root nested inside other code, such as an `if` statement in a
+     * function body, therefore keeps the shell meaning but may change the
+     * formatting of its lines. Use a `Word` or `WordPart` root for a surgical
+     * fix that leaves the surrounding source as written.
+     *
+     * A `Stmt` root is adjusted so its text matches `node.range`. A statement's
+     * own leading and trailing comments lie outside its range, so they are not
+     * printed (the copy passed in is not modified). When `node` is a statement
+     * whose range ends in its `;` or `&` terminator, upstream prints the
+     * statement without a `;`, so a `;` is appended unless the edited statement
+     * prints its own `&`, `|&` or disown operator. Without this, replacing `a`
+     * in `a; b` would produce `a b`.
+     *
+     * @param node - A view node from this file's lint tree: the node the fix
+     * replaces.
+     * @param edited - The record to print: a `File`, `Stmt`, `Word`, `Assign`,
+     * `Command` or `WordPart`.
+     * @param options - Forwarded to `printSync` unchanged.
+     * @returns The range to replace and the printed text to put there.
+     * @throws TypeError when `node` has no original record in this file (see
+     * {@link ShellSourceCode.getEditableSyntax}), when `edited` is not a
+     * printable root (the message names its type), or when the printer's output
+     * is not valid UTF-8. Non-UTF-8 output comes back from `printSync` as a
+     * `Uint8Array` and is never decoded lossily into a fix.
+     * @throws `PrintError` or `PrintPanicError` (from sh-ast) when upstream's
+     * printer fails for `edited` or `options`.
+     */
+    getPrintedReplacement(node: ShellNode, edited: Node, options?: PrintOptions): {
+        range: [number, number];
+        text: string;
+    };
+    /**
+     * Converts a byte position from this file's original parse into the
+     * UTF-16 index ESLint uses for `range` and `text.slice`. sh-ast positions
+     * count UTF-8 bytes, so a raw `Offset` is wrong for any source with
+     * non-ASCII text before it. For example, in `echo 🎉 && echo 中文`,
+     * `getIndexFromSyntaxPos(binaryCmd.OpPos)` is the index where `&&` starts.
+     *
+     * The conversion is only correct for positions of this file's original
+     * parse, as read from {@link ShellSourceCode.getSyntax}'s records. The live
+     * positions of an edited or copied tree describe that edit, not this
+     * source.
+     *
+     * @param pos - A `SyntaxPos` from one of this file's original records.
+     * @returns The UTF-16 index of `pos` in this file's text.
+     * @throws RangeError when `pos` is invalid (`IsValid === false`), recovered
+     * (`IsRecovered === true`), or overflowed (`OffsetOverflow === true`), or
+     * when its offset is not a UTF-8 character boundary of this source. Such a
+     * position is never rounded to a nearby boundary.
+     * @throws TypeError when `pos` is not a `SyntaxPos`, or when this source
+     * code's tree was not built by this language's parser.
+     */
+    getIndexFromSyntaxPos(pos: SyntaxPos): number;
+    /**
+     * Converts a byte position from this file's original parse into a one-based
+     * ESLint location, the shape `context.report({ loc })` takes. The column
+     * counts UTF-16 code units, not bytes, and CRLF counts as one line break.
+     * Same contract as {@link ShellSourceCode.getIndexFromSyntaxPos}.
+     *
+     * @param pos - A `SyntaxPos` from one of this file's original records.
+     * @returns The one-based line and UTF-16 column of `pos`.
+     * @throws RangeError when `pos` is invalid, recovered, or overflowed, or
+     * when its offset is not a UTF-8 character boundary of this source.
+     * @throws TypeError when `pos` is not a `SyntaxPos`, or when this source
+     * code's tree was not built by this language's parser.
+     */
+    getLocFromSyntaxPos(pos: SyntaxPos): {
+        line: number;
+        column: number;
+    };
     /**
      * Returns the parent of `node`, or `undefined` for the root `File` node
      * (or any node visited before `traverse()` has run once). ESLint always
@@ -352,4 +1385,130 @@ export declare class ShellSourceCode extends TextSourceCodeBase<{
     };
 }
 
+/**
+ * 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 declare type ShellTypedListeners = {
+    [Type in ShellNodeType as Type | `${Type}:exit`]?: ShellListener<ShellNodeOf<Type>>;
+};
+
+export { WordResolution }
+
+/**
+ * What a "must be run through a wrapper" rule enforces. Passed to
+ * {@link createWrapperRule}.
+ *
+ * @public
+ */
+export declare 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;
+    };
+}
+
+/**
+ * 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 declare 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;
+}
+
+/**
+ * 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 declare 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[];
+}
+
+/**
+ * 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 declare 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[];
+}
+
+export { WrapperSpec }
+
 export { }