@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/README.md

@@ -1,12 +1,13 @@
 # @eslint-sh/eslint-plugin
 
-The underlying ESLint plugin behind the `eslint-sh` umbrella package: shell script parsing and
-syntax-error reporting for ESLint, with custom-rule authoring over a typed shell AST. Provides the
+Shell script linting for ESLint: enforce project conventions and contracts with built-in rules,
+shared presets, and custom rules over a typed shell AST. This is the underlying plugin behind
+the `eslint-sh` umbrella package. It provides the
 `ShellLanguage` / `ShellSourceCode` core that lets ESLint parse and traverse `.sh`/`.bash` files,
 backed by `sh-ast`.
 
-For installation, the config example, the `languageOptions` reference table, the capability
-caveat, and troubleshooting, see the [`eslint-sh` package's README](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md) —
+For installation, the config example, the `languageOptions` reference table, the shellcheck
+positioning, and troubleshooting, see the [`eslint-sh` package's README](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-sh/README.md) —
 that's the canonical quickstart for this project, and applies whether you install `eslint-sh` or
 this package directly.
 
@@ -14,18 +15,66 @@ this package directly.
 
 `ShellLanguage`/`ShellSourceCode` core, plus the six launch esquery selector classes — see the
 [selector cookbook](./docs/selectors.md) (shipped with this package) for ready-made selector
-recipes. Rules and shared `configs` are not implemented yet — `plugin.rules` is intentionally
-empty here. Disable directives / inline config are implemented and live: all four
+recipes. Four shared configs ship, each supplying `plugins: { sh }` and `language: 'sh/sh'`:
+`configs.recommended` enables the convention-free rules (`sh/require-strict-mode`,
+`sh/require-shebang`, `sh/no-eval`, `sh/no-unchecked-cd`, `sh/shebang-matches-dialect` at `error`; `sh/no-secret-flags`, `sh/quote-expansions` at `warn`), and
+`configs['agent-authored']` adds the contract rules (`sh/no-dynamic-invocation`,
+`sh/no-secret-env-reads`, `sh/no-undeclared-commands`, `sh/no-unused-declarations`,
+`sh/require-network-wrapper`, `sh/require-tty-guard`, `sh/prefer-local`, `sh/no-masked-exit-status`) and
+`sh/max-script-complexity`, with every rule at `error`. Its convention and wrapper rules report nothing until you bind a declaration
+convention or a wrapper. The [rules index](./docs/rules/README.md) lists all forty built-in rules,
+their presets, and
+autofix availability. The version-gated rules `sh/compat/no-append-all-redirect`, `sh/compat/no-associative-arrays`, `sh/compat/no-brace-sequence-padding-step`, `sh/compat/no-case-attributes`, `sh/compat/no-case-fallthrough`, `sh/compat/no-case-modification`, `sh/compat/no-coproc`, `sh/compat/no-declare-g`, `sh/compat/no-epoch-variables`, `sh/compat/no-fd-variable`, `sh/compat/no-globstar`, `sh/compat/no-lastpipe-semantics`, `sh/compat/no-mapfile`, `sh/compat/no-nameref`, `sh/compat/no-negative-array-index`, `sh/compat/no-nounset-empty-array`, `sh/compat/no-parameter-transformation`, `sh/compat/no-pipe-all`, `sh/compat/no-printf-time-format`, `sh/compat/no-test-v`, `sh/compat/no-unicode-escape` and `sh/compat/no-wait-n`, report features your target shell version
+lacks; `configs['bash-3.2']` (`shellVersion: '3.2'`) and `configs['posix-portable']` (`dialect: 'posix'`, with
+`sh/require-strict-mode` as `set -eu`) enable them for those targets. `configs['posix-portable']` also reports `[[`, `let` and `source`, which fail on dash (`sh/compat/no-double-bracket`, `sh/compat/no-let`, `sh/compat/no-source`), but not `local`, `echo -e` or the other constructs it leaves to shellcheck, so a clean run does not prove a script runs under every POSIX `sh`; see [version compatibility](./docs/compat.md). Run shellcheck alongside eslint-sh: shellcheck catches shell correctness
+problems; eslint-sh enforces project policy. [Running eslint-sh beside shellcheck](./docs/shellcheck.md)
+covers who owns what and the rules that overlap it deliberately (see also the
+[design rationale](https://github.com/mike-north/eslint-sh/blob/main/design/README.md#eslint-sh-and-shellcheck)).
+
+Disable directives / inline config are implemented and live: all four
 `# eslint-disable*` comment forms, unused-directive detection, and `linterOptions.noInlineConfig`
-interplay work through ESLint's native machinery. No lint rules ship with this package yet, so the
-rule id below is illustrative — but once you register a custom rule of your own, the directives
-suppress it: for a rule you've configured as `sh/your-rule`,
+interplay work through ESLint's native machinery. The rule id below is illustrative; the
+directives suppress built-in rules and your own custom rules alike: for a rule you've configured as `sh/your-rule`,
 `# eslint-disable-next-line sh/your-rule -- justification` suppresses it on the following line.
+A script can therefore switch any rule off for itself. When the scripts you lint come from someone
+who doesn't own the policy, see [linting code you don't control](./docs/untrusted-code.md): a
+config that ignores those comments, and how to run ESLint from outside the checkout under review,
+so that it can't supply the config, ESLint, the plugin, or anything else ESLint looks for in the
+directory it runs in.
+
+## CommonJS config
+
+In a package without `"type": "module"` (the ESLint default), `eslint.config.js` is CommonJS, as
+is `eslint.config.cjs` in any package. `@eslint-sh/eslint-plugin` is ESM-only, so
+`require('@eslint-sh/eslint-plugin')` returns the module namespace and the plugin object is its
+`.default`. Named exports such as `commentPragma` are ordinary properties of the `require` result.
+Without `.default`, `sh.configs` is `undefined` and ESLint fails with
+`Cannot read properties of undefined (reading 'recommended')`.
+
+```js
+// eslint.config.js (CommonJS package) or eslint.config.cjs
+const { defineConfig } = require('eslint/config');
+const sh = require('@eslint-sh/eslint-plugin').default;
+// Named exports need no `.default`.
+const { commentPragma } = require('@eslint-sh/eslint-plugin');
+
+module.exports = defineConfig([
+  {
+    files: ['**/*.sh'],
+    extends: [sh.configs.recommended],
+    settings: { sh: { declarationConvention: commentPragma } },
+    rules: { 'sh/no-undeclared-commands': 'error' },
+  },
+]);
+```
 
 ## Public API
 
 - `plugin` (default export) — `{ meta: { name, version, namespace: "sh" }, languages: { sh:
-ShellLanguage }, rules: {} }`. `meta.version` always matches this package's `package.json`.
+ShellLanguage }, rules, configs: { recommended, 'agent-authored', 'bash-3.2', 'posix-portable' } }`. `meta.version` always
+  matches this package's `package.json`. Each config is a single config object with no `files`
+  key (`bash-3.2` and `posix-portable` also set `languageOptions`); extend it under your own `files`:
+  `defineConfig({ files: ['**/*.sh'], extends: [sh.configs.recommended] })`.
 - `ShellLanguage` — the `@eslint/core` `Language` implementation: `fileType: "text"`,
   `lineStart`/`columnStart: 1`, `nodeTypeKey: "type"`, the consumer's schema-derived `visitorKeys`,
   `validateLanguageOptions`/`normalizeLanguageOptions` for the
@@ -36,7 +85,13 @@ ShellLanguage }, rules: {} }`. `meta.version` always matches this package's `pac
 - `ShellSourceCode` — extends `@eslint/plugin-kit`'s `TextSourceCodeBase`; implements `traverse()`
   (driven by the consumer's `visitorKeys`, yielding two-phase `VisitNodeStep`s), `getParent()`, and
   the disable-directive surface (`getDisableDirectives()`, `getInlineConfigNodes()`,
-  `applyInlineConfig()`).
+  `applyInlineConfig()`). Rule authors get helpers that delegate to `sh-ast/analyze`, so every rule
+  gets the same answer: `resolveWordText(word, options?)` (a word's literal text, or `null` if
+  `resolveWord` does not report it static), `getCommandName(callExpr)` (the static command word,
+  without following wrappers), and `resolveInvokedCommand(callExpr, { transparentWrappers? })` (the
+  full `Argv0Resolution` once wrappers such as `env`, `sudo`, and `exec` are followed, including the
+  wrapper `chain` and the `effective` command or the reason it is unknowable). The `dialect` and
+  `shellVersion` accessors return the file's normalized language options.
 - `ShellLanguageOptions` / `NormalizedShellLanguageOptions` / `ShellLanguageOptionsJSON` — the
   `languageOptions` types (`dialect`, `shellVersion`, `directivePrefix`). `directivePrefix` is the
   prefix directive/inline-config comments must start with — e.g. the default `"eslint"` recognizes
@@ -45,20 +100,176 @@ ShellLanguage }, rules: {} }`. `meta.version` always matches this package's `pac
 - `ShellNode` / `ShellFile` / `ShellComment` / `ShellPosition` — the plugin's lint view: lowercase
   fields, UTF-16 ranges, and one-based UTF-16 locations, independent of the raw parser syntax.
   Locations come from one parse-time position snapshot and remain bound to that original source;
-  projecting the view does not run live bounds operations on every syntax subtree.
+  projecting the view does not run live bounds operations on every syntax subtree. `ShellNode` is
+  the union of every node type, so narrowing on `node.type` gives that node's fields, typed, with
+  no cast. See [Reading nodes](./docs/reading-nodes.md).
+- `ShellNodeOf` / `ShellNodeType` / `ShellNodeMap` / `ShellNodeField` — the types behind the union.
+  `ShellNodeOf<'Stmt'>` is one node type by name, `ShellNodeType` is every name, and
+  `ShellNodeMap` maps one to the other. They are computed from `sh-ast`'s generated typings, so
+  they follow the pinned mvdan/sh version. `ShellNodeField<T>` is the type of one node field
+  (`ShellNodeField<ShellNodeOf<'Stmt'>['cmd']>`), for a helper that takes or returns field values.
+- `ShellCommandSite` / `CommandContext` / `ResolveArgv0Options` — one command in a file as `getCommandSites()` reports it:
+  its `CallExpr` node (`node`), the `context` path of enclosing constructs from the file root
+  (each frame a `CommandContext`, discriminated by `kind`: `and`, `or`, `pipeline`, `subshell`,
+  `cmdSubst`, …), its `argv0` and `argv` as `WordResolution`s, and `resolveInvokedCommand()`,
+  which follows wrappers. `ResolveArgv0Options` is that method's option bag (and
+  `ShellSourceCode.resolveInvokedCommand`'s): `transparentWrappers` replaces the wrapper table
+  followed.
+- `WordResolution` — what `resolveWord` and a site's `argv` words report: `{ static: true, text }`
+  when the word's value is known without running the script, or `{ static: false, reason }` when
+  it is not (`reason` is `'expansion'`, `'tilde'`, `'glob'`, `'brace'`, `'locale'` or
+  `'unsupported'`; a new reason can appear in a minor release, so keep a `default` branch). Check
+  `static` before reading `text`.
+- `ShellDialect` — the `dialect` language option's values: `'bash'`, `'posix'`, `'mksh'`,
+  `'bats'` and `'zsh'`.
+- `Argv0Resolution` — the type `ShellSourceCode.resolveInvokedCommand` returns, re-exported from
+  `sh-ast/analyze`.
 - `resolveWord` — adapts a parsed lint Word to `sh-ast`'s word-resolution helper, so a project that installs only
   this package can write custom rules that resolve static shell words (e.g. the `no-rm-rf` example
   in the [custom-rule tutorial](./docs/custom-rule-tutorial.md)) without a separate `sh-ast`
   install. Fabricated nodes are rejected because they have no original syntax association.
+- `DeclarationConvention` / `DeclaredCommand` / `commentPragma` — the extension point for how a
+  project declares the external commands its scripts use, bound with
+  `settings: { sh: { declarationConvention } }`. `commentPragma` is the reference convention,
+  reading `# uses: jq curl` header comments. See [declaration
+  conventions](./docs/declaration-conventions.md).
+- `ScriptDeclaredCommand` / `FileDeclaredCommand` / `DescribedDeclaredCommand` / `LintedFile` — the
+  three kinds of `DeclaredCommand`, by where a declaration lives (in the script, in another file
+  such as a sidecar, or in a source described in words, such as a config list or a registry
+  snapshot), and the
+  linted file a convention is told about so it can find a per-script sidecar. See [declarations
+  outside the script](./docs/declaration-conventions.md#declarations-outside-the-script).
+- `readDeclaredCommands` / `DeclarationReadContext` — reads the bound convention's declarations
+  for the file a rule is linting, checked exactly as the built-in rules check them. See [reading
+  the convention in your own
+  rule](./docs/declaration-conventions.md#reading-the-convention-in-your-own-rule).
+- `defineShellRule` / `ShellRule` / `ShellRuleSpec` / `ShellRuleMeta` / `ShellRuleContext` /
+  `ShellRuleVisitor` / `ShellListener` / `ShellTypedListeners` — the rule-authoring helper and its types. `defineShellRule({ meta, create })`
+  returns an ordinary ESLint rule with `meta.languages: ['sh/sh']` set, so ESLint refuses to run it
+  on another language; `context.sourceCode` is typed `ShellSourceCode`, a listener keyed by a node
+  type (`CallExpr`, `Word:exit`) receives that node type, and any other selector's listener receives
+  `ShellNode`. Writing `meta.languages` yourself is a type error. The built-in rules are made with
+  it too. `ShellListener<Node>` is the type of one listener, so a helper that builds listeners for
+  several rules can name its return type; `ShellTypedListeners` is the node-type-keyed half of
+  `ShellRuleVisitor`. See [Writing your own rules](#writing-your-own-rules).
+- `resolveDeclarationConvention` / `DeclarationConventionBindingContext` — resolves the declaration
+  convention bound for a rule (its `declarationConvention` option, else
+  `settings.sh.declarationConvention`, else `null`) with the validation and error messages the
+  built-in consumers use, so a rule of your own can read the convention. See [declaration
+  conventions](./docs/declaration-conventions.md#reading-the-convention-in-your-own-rule).
+- `createWrapperRule` / `WrapperRuleConfig` / `WrapperRuleSubcommands` / `WrapperSpec` — the
+  factory for "command X must be run through wrapper Y" rules a rule pack
+  binds to its own commands and wrapper. `sh/require-network-wrapper` is the built-in rule made
+  with it. See [wrapper rules](./docs/wrapper-rules.md).
+- `WrapperRuleLocalInvocation` / `WrapperRuleLocalOperand` — the `localInvocations` entry of a
+  `createWrapperRule` config: invocations of a listed command that only act locally and are not
+  reported, such as `curl --version` or `git clone ./x`. See
+  [wrapper rules](./docs/wrapper-rules.md#local-only-invocations).
+
+## Faithful syntax: `@eslint-sh/eslint-plugin/syntax`
+
+The root exports work on the plugin's lint view (`ShellNode`). A rule that edits or analyzes the
+parser's own records needs `sh-ast` itself: `walk`, `parseSync`, `printSync` and `PrintOptions`,
+the record types (`Node`, `Word`, `CallExpr`, `SyntaxPos`, `GoString`, …), and the analysis
+helpers. Import them from this package's subpaths, not from `sh-ast`:
+
+```js
+// View-aware helpers: take lint-view nodes.
+import { resolveWord } from '@eslint-sh/eslint-plugin';
+// sh-ast's root entry point: parse, walk, and print faithful records.
+import { parseSync, printSync, walk } from '@eslint-sh/eslint-plugin/syntax';
+// sh-ast/analyze: command enumeration and wrapper resolution over faithful records.
+import {
+  DEFAULT_TRANSPARENT_WRAPPERS,
+  enumerateCommands,
+} from '@eslint-sh/eslint-plugin/syntax/analyze';
+```
+
+- `@eslint-sh/eslint-plugin/syntax` re-exports the complete public surface of `sh-ast`, and
+  `@eslint-sh/eslint-plugin/syntax/analyze` re-exports `sh-ast/analyze`. Both come from the
+  `sh-ast` this plugin depends on, the same module instance its language parses with, so you
+  don't install `sh-ast` yourself and records always match the parser that made them. Nothing is
+  wrapped or renamed; each name keeps `sh-ast`'s own contract and docs.
+- The two `resolveWord`s differ. The root's takes a lint-view `ShellNode`; the one in
+  `…/syntax/analyze` takes a faithful `Node`. That is why the subpaths are kept apart from the
+  root.
+- **Versioning.** `…/syntax` and `…/syntax/analyze` track this plugin's pinned `sh-ast` minor
+  (currently `sh-ast@^0.7.0`). Under 0.x, a different `sh-ast` minor is a breaking change, so
+  an `sh-ast` 0.x minor bump is a minor bump of this plugin, and the changelog entry names the
+  new `sh-ast` version.
 
 Syntax failures surface as fatal lint messages at mvdan/sh's reported byte offset, converted to
-the source's UTF-16 location. Failures without a valid syntax position use a 1:1 fallback.
+the source's UTF-16 location. Failures without a valid syntax position use a 1:1 fallback. A
+failure of the parser runtime itself (an abort, or a failure of the bridge to it) is not a
+syntax error, and the file may be perfectly valid. It is reported at 1:1 as
+`Parsing error: eslint-sh parser runtime failure (not a syntax error in this file): <detail>`.
+ESLint adds the `Parsing error: ` prefix to every message a language returns from `parse`, and a
+language cannot remove it, so look for the marker text `eslint-sh parser runtime failure` to tell
+this apart from a real syntax error, which has no marker and sits at the offending position. Linting
+the file again, or in a fresh process, usually gets past a runtime failure.
+
+### Known parser gaps
+
+The parser is the upstream `sh-ast`, and it rejects three valid Bash forms. Each is reported as a
+syntax error. Until the parser accepts them, write the workaround in the right-hand column.
+
+| Valid Bash form          | Workaround                 |
+| ------------------------ | -------------------------- |
+| `x=$((a \|\| b) \| c)`   | `x=$( (a \|\| b) \| c )`   |
+| `x=(${y}[0])`            | `word=${y}[0]; x=($word)`  |
+| `declare -A m=([a.b]=1)` | `declare -A m=(["a.b"]=1)` |
+
+- `x=$((a || b) | c)`: the parser reads `$((` as the start of arithmetic. A space after `$(` makes
+  it a command substitution containing a subshell.
+- `x=(${y}[0])`: inside an array literal, any element word that ends in an unquoted `[…]` is read
+  as an indexed element (`[0]=value`) and must be followed by `=`. It is not limited to a word
+  that starts with an expansion: `x=(a[0])`, `x=(a${y}[0])` and `x=("${y}"[0])` are rejected too
+  (a `[0]` that is meant as a glob character class). Building the word in its own statement keeps
+  the same splitting and globbing.
+- An associative-array subscript containing a `.` that is not quoted: the parser reads the
+  subscript as arithmetic and rejects the dot ("floating point arithmetic is a zsh feature"). The
+  gap is wider than the `declare` form above. It also rejects `m[a.b]=1` and `${m[a.b]}`, which
+  parse once quoted: `m["a.b"]=1` and `${m["a.b"]}`.
 
 ## Writing your own rules
 
-Want to write a custom rule against the shell AST? See the [custom-rule
-tutorial](./docs/custom-rule-tutorial.md) for a complete, CI-tested walkthrough: a selector from
-the cookbook, a full `{ meta, create(context) }` rule module with `context.report`, and the
-flat-config wiring to run it. `docs/` ships with this package (see `package.json#files`), so the
+Build a rule with `defineShellRule`. It takes the `{ meta, create(context) }` object you would
+write for any ESLint rule and returns an ESLint rule you register in a plugin's `rules`:
+
+```js
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+export default defineShellRule({
+  meta: {
+    type: 'problem',
+    schema: [],
+    messages: { noEval: 'Avoid `eval`; it runs a string as code.' },
+  },
+  create(context) {
+    return {
+      CallExpr(node) {
+        if (context.sourceCode.getCommandName(node) === 'eval') {
+          context.report({ node, messageId: 'noEval' });
+        }
+      },
+    };
+  },
+});
+```
+
+`defineShellRule` sets `meta.languages: ['sh/sh']`, the declaration that makes ESLint refuse to
+run the rule on a file of another language (usually because a config entry is missing
+`language: 'sh/sh'`) instead of letting it silently match nothing. In TypeScript,
+`context.sourceCode` is `ShellSourceCode`, a listener keyed by a node type receives that node type
+(`CallExpr(node)` reads `node.args` with no check), and `context.report`
+accepts only the message ids in `meta.messages`, with no `@eslint/core` import of your own.
+
+[Reading nodes](./docs/reading-nodes.md) is the field reference for the nodes your listeners
+receive: narrow a `ShellNode` on `type` and read its fields, typed, with one worked rule.
+
+The [custom-rule tutorial](./docs/custom-rule-tutorial.md) is a complete, CI-tested walkthrough: a
+selector from the cookbook, a full rule with `context.report`, the flat-config wiring to run it,
+fixes (and when a printed fix reflows code, so a position-based text edit is the better choice),
+and a TypeScript rule. `docs/` ships with this package (see `package.json#files`), so the
 tutorial and its example files (`docs/examples/`) are available in every installed copy — not just
 on GitHub.

package/dist/command-harvest/builtins/bash.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The commands bash runs as builtins: data for the command harvest, never
+ * rule logic.
+ *
+ * Source: the Bash Reference Manual for **Bash 5.3**, chapter 4 "Shell
+ * Builtin Commands" (§4.1 Bourne Shell Builtins, §4.2 Bash Builtin Commands,
+ * §4.3 Modifying Shell Behavior: `set`, `shopt`), plus the builtins that
+ * chapter defers to other chapters: §6.8.1 Directory Stack Builtins
+ * (`dirs`, `popd`, `pushd`), §7.2 Job Control Builtins (`bg`, `fg`, `jobs`,
+ * `kill`, `wait`, `disown`, `suspend`), §8.7 Programmable Completion
+ * Builtins (`compgen`, `complete`, `compopt`) and §9.2 Bash History Builtins
+ * (`fc`, `history`). `true` and `false` are builtins in every bash release
+ * (`help true`) although the manual describes them only as utilities.
+ * Cross-checked against `compgen -b` from bash 5.3.9, which prints exactly
+ * this list.
+ *
+ * Reserved words (`if`, `time`, `[[`, `function`, …) are not here: the
+ * parser never produces them as command words.
+ *
+ * The list is the latest bash's, and is not narrowed by `shellVersion`:
+ * `mapfile`, `readarray` and `compopt` (added in bash 4.0) are builtins here
+ * even for a file configured as bash 3.2. Whether a script may use them on
+ * an old bash is a version-compatibility question, not a dependency one.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Shell-Builtin-Commands
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Directory-Stack-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Job-Control-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Programmable-Completion-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Bash-History-Builtins
+ */
+/**
+ * Every bash 5.3 builtin command name, in `compgen -b` order.
+ *
+ * @internal
+ */
+export declare const BASH_BUILTINS: readonly string[];

package/dist/command-harvest/builtins/bash.js

@@ -0,0 +1,98 @@
+/**
+ * The commands bash runs as builtins: data for the command harvest, never
+ * rule logic.
+ *
+ * Source: the Bash Reference Manual for **Bash 5.3**, chapter 4 "Shell
+ * Builtin Commands" (§4.1 Bourne Shell Builtins, §4.2 Bash Builtin Commands,
+ * §4.3 Modifying Shell Behavior: `set`, `shopt`), plus the builtins that
+ * chapter defers to other chapters: §6.8.1 Directory Stack Builtins
+ * (`dirs`, `popd`, `pushd`), §7.2 Job Control Builtins (`bg`, `fg`, `jobs`,
+ * `kill`, `wait`, `disown`, `suspend`), §8.7 Programmable Completion
+ * Builtins (`compgen`, `complete`, `compopt`) and §9.2 Bash History Builtins
+ * (`fc`, `history`). `true` and `false` are builtins in every bash release
+ * (`help true`) although the manual describes them only as utilities.
+ * Cross-checked against `compgen -b` from bash 5.3.9, which prints exactly
+ * this list.
+ *
+ * Reserved words (`if`, `time`, `[[`, `function`, …) are not here: the
+ * parser never produces them as command words.
+ *
+ * The list is the latest bash's, and is not narrowed by `shellVersion`:
+ * `mapfile`, `readarray` and `compopt` (added in bash 4.0) are builtins here
+ * even for a file configured as bash 3.2. Whether a script may use them on
+ * an old bash is a version-compatibility question, not a dependency one.
+ *
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Shell-Builtin-Commands
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Directory-Stack-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Job-Control-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Programmable-Completion-Builtins
+ * @see https://www.gnu.org/software/bash/manual/bash.html#Bash-History-Builtins
+ */
+/**
+ * Every bash 5.3 builtin command name, in `compgen -b` order.
+ *
+ * @internal
+ */
+export const BASH_BUILTINS = Object.freeze([
+    '.',
+    ':',
+    '[',
+    'alias',
+    'bg',
+    'bind',
+    'break',
+    'builtin',
+    'caller',
+    'cd',
+    'command',
+    'compgen',
+    'complete',
+    'compopt',
+    'continue',
+    'declare',
+    'dirs',
+    'disown',
+    'echo',
+    'enable',
+    'eval',
+    'exec',
+    'exit',
+    'export',
+    'false',
+    'fc',
+    'fg',
+    'getopts',
+    'hash',
+    'help',
+    'history',
+    'jobs',
+    'kill',
+    'let',
+    'local',
+    'logout',
+    'mapfile',
+    'popd',
+    'printf',
+    'pushd',
+    'pwd',
+    'read',
+    'readarray',
+    'readonly',
+    'return',
+    'set',
+    'shift',
+    'shopt',
+    'source',
+    'suspend',
+    'test',
+    'times',
+    'trap',
+    'true',
+    'type',
+    'typeset',
+    'ulimit',
+    'umask',
+    'unalias',
+    'unset',
+    'wait',
+]);

package/dist/command-harvest/builtins/bats.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The helpers bats-core defines for every test file: data for the command
+ * harvest under the `bats` dialect, never rule logic.
+ *
+ * A `.bats` file runs inside bats, which defines these as shell functions
+ * before any test runs. They are not external commands, so a test file never
+ * declares them. They are not defined in the file either, so the harvest's
+ * in-file function check cannot see them. Hence this list.
+ *
+ * Source: the bats-core manual, "Writing tests": `run` ("Test other
+ * commands"), `bats_pipe` ("Run commands with pipes"), `load` and
+ * `bats_load_safe` ("Share common code"), `bats_load_library` ("Load system
+ * wide libraries"), `skip` ("Easily skip tests"),
+ * `bats_require_minimum_version`, and `bats_test_function` ("Dynamic test
+ * registration").
+ *
+ * Absent by design: the hooks a test file defines itself (`setup`,
+ * `teardown`, `setup_file`, `teardown_file`, `bats::on_failure`), which the
+ * in-file function check already covers, and helpers from separately
+ * installed libraries such as bats-assert (`assert_success`), which are not
+ * part of bats-core.
+ *
+ * @see https://bats-core.readthedocs.io/en/stable/writing-tests.html
+ */
+import type { WrapperSpec } from 'sh-ast/analyze';
+/**
+ * Every helper function bats-core provides to test files.
+ *
+ * @internal
+ */
+export declare const BATS_HELPERS: readonly string[];
+/**
+ * bats' `run`, as a transparent wrapper: it runs the command after its own
+ * options and captures the result, so `run curl x` uses `curl`.
+ *
+ * Its options, all before the command (bats-core manual, "`run`: Test other
+ * commands"): `-N` (expect exit status N, 0–255), `!` (expect a nonzero
+ * status), `--keep-empty-lines`, `--separate-stderr`, and `--` to end option
+ * parsing. `!` is not dash-prefixed, but `noArgFlags` matches it as an exact
+ * word all the same.
+ *
+ * @see https://bats-core.readthedocs.io/en/stable/writing-tests.html#run-test-other-commands
+ * @internal
+ */
+export declare const BATS_RUN_WRAPPER: WrapperSpec;

package/dist/command-harvest/builtins/bats.js

@@ -0,0 +1,33 @@
+/**
+ * Every helper function bats-core provides to test files.
+ *
+ * @internal
+ */
+export const BATS_HELPERS = Object.freeze([
+    'run',
+    'bats_pipe',
+    'load',
+    'bats_load_safe',
+    'bats_load_library',
+    'skip',
+    'bats_require_minimum_version',
+    'bats_test_function',
+]);
+/**
+ * bats' `run`, as a transparent wrapper: it runs the command after its own
+ * options and captures the result, so `run curl x` uses `curl`.
+ *
+ * Its options, all before the command (bats-core manual, "`run`: Test other
+ * commands"): `-N` (expect exit status N, 0–255), `!` (expect a nonzero
+ * status), `--keep-empty-lines`, `--separate-stderr`, and `--` to end option
+ * parsing. `!` is not dash-prefixed, but `noArgFlags` matches it as an exact
+ * word all the same.
+ *
+ * @see https://bats-core.readthedocs.io/en/stable/writing-tests.html#run-test-other-commands
+ * @internal
+ */
+export const BATS_RUN_WRAPPER = Object.freeze({
+    names: Object.freeze(['run']),
+    noArgFlags: Object.freeze(['!', '--keep-empty-lines', '--separate-stderr']),
+    noArgFlagPattern: /^-\d+$/u,
+});

package/dist/command-harvest/builtins/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Which command names the shell itself provides for a given dialect.
+ *
+ * A builtin runs inside the shell, so a script never depends on it being
+ * installed, and the command harvest drops it. Under `bats`, the helper
+ * functions bats-core defines for every test file (`run`, `load`, `skip`, …)
+ * are provided the same way and are dropped too. The lists themselves are
+ * data, each citing its source, in `./bash.ts`, `./posix.ts` and `./bats.ts`;
+ * this module only maps each supported dialect to a combination of them.
+ */
+import type { ShellDialect } from '../../language/shell-language-options.js';
+/**
+ * Returns the set of command names that `dialect` provides without an
+ * external command: its builtins, plus bats-core's helpers for `bats`.
+ *
+ * @internal
+ */
+export declare function builtinsForDialect(dialect: ShellDialect): ReadonlySet<string>;

package/dist/command-harvest/builtins/index.js

@@ -0,0 +1,39 @@
+import { BASH_BUILTINS } from './bash.js';
+import { BATS_HELPERS } from './bats.js';
+import { POSIX_CONVENTIONAL_BUILTINS, POSIX_REGULAR_BUILTINS, POSIX_SPECIAL_BUILTINS, } from './posix.js';
+/** Every bash builtin. */
+const BASH = new Set(BASH_BUILTINS);
+/** Every bash builtin, plus the helpers bats-core defines for test files. */
+const BATS = new Set([...BASH_BUILTINS, ...BATS_HELPERS]);
+/** Every POSIX builtin: special, regular, and conventionally built in. */
+const POSIX = new Set([
+    ...POSIX_SPECIAL_BUILTINS,
+    ...POSIX_REGULAR_BUILTINS,
+    ...POSIX_CONVENTIONAL_BUILTINS,
+]);
+/**
+ * The builtin set for each dialect.
+ *
+ * - `bats` files are bash scripts run by bats, so they use the bash list
+ *   plus bats-core's helpers.
+ * - `mksh` and `zsh` have no list of their own yet. Both implement every
+ *   POSIX builtin, so the POSIX list is a safe floor: it never counts a real
+ *   external command as a builtin. Their own extra builtins (`print`,
+ *   `whence`, `setopt`, …) are reported as commands until they get lists.
+ */
+const BUILTINS_BY_DIALECT = {
+    bash: BASH,
+    bats: BATS,
+    posix: POSIX,
+    mksh: POSIX,
+    zsh: POSIX,
+};
+/**
+ * Returns the set of command names that `dialect` provides without an
+ * external command: its builtins, plus bats-core's helpers for `bats`.
+ *
+ * @internal
+ */
+export function builtinsForDialect(dialect) {
+    return BUILTINS_BY_DIALECT[dialect];
+}

package/dist/command-harvest/builtins/posix.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The commands a POSIX `sh` runs as builtins: data for the command harvest,
+ * never rule logic.
+ *
+ * Three groups, each from its own source (POSIX.1-2017, XCU Issue 7, whose
+ * section numbers are used here):
+ *
+ * - **Special built-ins**, XCU §2.14 "Special Built-In Utilities": `break`,
+ *   `:`, `continue`, `.`, `eval`, `exec`, `exit`, `export`, `readonly`,
+ *   `return`, `set`, `shift`, `times`, `trap`, `unset`.
+ * - **Regular built-ins**, XCU §2.9.1.1 "Command Search and Execution",
+ *   step 1.d: the utilities a shell must invoke before searching `PATH`
+ *   (`alias`, `bg`, `cd`, `command`, `false`, `fc`, `fg`, `getopts`, `hash`,
+ *   `jobs`, `kill`, `newgrp`, `pwd`, `read`, `true`, `umask`, `unalias`,
+ *   `wait`), plus `type` and `ulimit`, which the same step lists under the
+ *   XSI option. POSIX.1-2024 (Issue 8) calls most of these "intrinsic
+ *   utilities" (XCU §1.7).
+ * - **Built in by every POSIX shell in practice**: `echo`, `printf`, `test`
+ *   and `[`. POSIX specifies them as ordinary utilities that a shell may
+ *   build in (XCU §1.6), and dash, ash, ksh, mksh and bash all do (see the
+ *   "Builtins" section of dash(1)). Counting them as external would make
+ *   nearly every script declare `echo`.
+ *
+ * Bash-only builtins such as `local`, `source` and `mapfile` are
+ * deliberately absent: in a `posix` file they are commands that a POSIX
+ * shell need not provide.
+ *
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_14 — XCU §2.14 Special Built-In Utilities
+ * @see https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_09_01_01 — XCU §2.9.1.1 Command Search and Execution
+ * @see https://pubs.opengroup.org/onlinepubs/9799919799/utilities/V3_chap01.html — POSIX.1-2024 XCU §1.7 Intrinsic Utilities
+ * @see https://man7.org/linux/man-pages/man1/dash.1.html — dash(1), "Builtins"
+ */
+/**
+ * POSIX special built-in utilities (XCU §2.14).
+ *
+ * @internal
+ */
+export declare const POSIX_SPECIAL_BUILTINS: readonly string[];
+/**
+ * POSIX regular built-in utilities (XCU §2.9.1.1 step 1.d, including the
+ * XSI `type` and `ulimit`).
+ *
+ * @internal
+ */
+export declare const POSIX_REGULAR_BUILTINS: readonly string[];
+/**
+ * Utilities POSIX lets a shell build in, and every POSIX shell does.
+ *
+ * @internal
+ */
+export declare const POSIX_CONVENTIONAL_BUILTINS: readonly string[];