eslint-sh 0.5.0 → 0.7.0

package/README.md

@@ -1,17 +1,33 @@
 # eslint-sh
 
-Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a
-typed shell AST.
+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 canonical quickstart for the `eslint-sh` / `@eslint-sh/eslint-plugin` project — start
 here regardless of which of the two packages you install.
 
-**Roadmap:** built-in lint rules and shared configs are planned but not implemented yet.
+Built-in rules ship in four presets: `configs.recommended`, `configs['agent-authored']`
+and the deployment-target packs `configs['bash-3.2']` and `configs['posix-portable']` (see
+[Presets](#presets)). Browse the
+[rules index](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/rules/README.md)
+for each rule's purpose, preset membership, and autofix availability.
+
+**Run both eslint-sh and shellcheck.** shellcheck catches shell correctness problems such as
+quoting and word-splitting mistakes. eslint-sh enforces your project's policy: strict mode,
+command declarations, network wrappers, and other conventions. It complements shellcheck; it
+does not aim to reproduce shellcheck's diagnostic catalog. See
+[running eslint-sh beside shellcheck](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/shellcheck.md)
+for who owns what, and the
+[design rationale](https://github.com/mike-north/eslint-sh/blob/main/design/README.md#eslint-sh-and-shellcheck).
 
 ## Installation
 
-Requires `eslint@^10` as a peer dependency (already listed as a peer in `eslint-sh`'s
-`package.json`, so a compatible `eslint` install satisfies it automatically):
+Requires Node.js 22.13 or later on the 22 line, or Node.js 24 or later (`engines.node` is
+`^22.13.0 || >=24`, the range ESLint 10 itself supports, without the end-of-life Node 20 line).
+
+Also requires `eslint@^10.2.0` (ESLint 10.2 or any later 10.x release) as a peer dependency (already
+listed as a peer in `eslint-sh`'s `package.json`, so a compatible `eslint` install satisfies it
+automatically):
 
 ```sh
 npm install --save-dev eslint-sh
@@ -19,8 +35,10 @@ npm install --save-dev eslint-sh
 
 ## Usage
 
-This release reports shell syntax (parse) errors only — no lint rules ship yet, so a "0 problems"
-result means the script parsed without a syntax error, not that it is problem-free.
+Start with `sh.configs.recommended`. It supplies the shell language and plugin registration,
+reports syntax errors, and enables the convention-free rules: require a shebang and strict
+mode, disallow `eval` and dynamic sourcing, and warn about literal secrets in flags. You supply
+the paths to your shell scripts.
 
 ```js
 // eslint.config.mjs
@@ -29,29 +47,262 @@ import sh from 'eslint-sh'; // equivalent to: import sh from '@eslint-sh/eslint-
 
 export default defineConfig([
   {
-    files: ['**/*.sh', '**/*.bash'],
-    plugins: { sh },
-    language: 'sh/sh',
-    languageOptions: { dialect: 'bash', shellVersion: '3.2' },
+    // Extensionless scripts need `bin/?*`: ESLint never lints a file matched only by `bin/*` or `bin/**`.
+    files: ['**/*.sh', '**/*.bash', 'bin/?*'],
+    extends: [sh.configs.recommended],
   },
 ]);
 ```
 
+For example, save this as `bin/deploy` (or `scripts/example.sh`):
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+if [[ "$#" -gt 0 ]]; then echo "$1"; fi
+```
+
+Run `npx eslint .` to lint your scripts, or `npx eslint . --fix` to apply available autofixes.
+This script passes the recommended rules. A script without a shebang or strict mode reports
+errors, and `--fix` can insert both. A clean result means the enabled rules found no problems;
+keep running shellcheck alongside eslint-sh for general shell correctness checks.
+
+Shell scripts are often extensionless (`bin/deploy`), so list the directories that hold them
+with a pattern like `bin/?*`. A pattern that ends in `*` or `/**` (`bin/*`, `bin/**`) never makes a
+file lintable on its own, and ESLint skips the file without a warning. See
+[My extensionless scripts aren't being linted](#troubleshooting) below.
+
 `languageOptions` is entirely optional — omitting it is equivalent to
 `languageOptions: { dialect: 'bash' }`, since `dialect` defaults to `"bash"` (see the
 `languageOptions` reference table below). This README's own [custom-rule tutorial](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/custom-rule-tutorial.md)
 config omits `languageOptions` for exactly that reason — it targets bash, the default, so
-there's nothing to override; add it explicitly (as above) when you need a non-default
-`dialect`, a `shellVersion` hint, or a custom `directivePrefix`.
+there's nothing to override. Add `languageOptions: { dialect: 'posix' }` to your config entry
+when targeting POSIX shell, or set a `shellVersion` hint or custom `directivePrefix` as needed.
+
+### 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` is ESM-only, so `require('eslint-sh')` 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').default;
+// Named exports need no `.default`.
+const { commentPragma } = require('eslint-sh');
+
+module.exports = defineConfig([
+  {
+    files: ['**/*.sh'],
+    extends: [sh.configs.recommended],
+    settings: { sh: { declarationConvention: commentPragma } },
+    rules: { 'sh/no-undeclared-commands': 'error' },
+  },
+]);
+```
+
+## Presets
+
+Each preset is a single config object that supplies `plugins: { sh }` and `language: 'sh/sh'` and
+has no `files` key. Extend it from an entry that lists your shell scripts:
+
+```js
+import { defineConfig } from 'eslint/config';
+import sh from 'eslint-sh';
+
+export default defineConfig([{ files: ['**/*.sh', 'bin/?*'], extends: [sh.configs.recommended] }]);
+```
+
+- **`sh.configs.recommended`** enables the rules that assume no project conventions:
+  `sh/require-strict-mode`, `sh/require-shebang`, `sh/no-eval`, `sh/no-unchecked-cd` and
+  `sh/shebang-matches-dialect` at `error`, and
+  `sh/no-secret-flags` and `sh/quote-expansions` at `warn`.
+- **`sh.configs['agent-authored']`** is for scripts that are machine-written and human-reviewed.
+  It enables every `recommended` rule plus the contract rules, all at `error`:
+  `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` and `sh/max-script-complexity`
+  (which caps function count, nesting depth and statement count).
+  `sh/no-secret-flags` and `sh/quote-expansions` are `error` here too.
+- **`sh.configs['bash-3.2']`** is for scripts that must run on the Bash 3.2 macOS ships as
+  `/bin/bash`. It sets `languageOptions: { dialect: 'bash', shellVersion: '3.2' }` and enables every
+  version-gated `compat/*` rule at `error`.
+- **`sh.configs['posix-portable']`** reports Bash-only constructs that fail on dash, including
+  `[[`, `let` and `source`, but not `local`, `echo -e` or the others it leaves to shellcheck, so a
+  clean run does not prove a script runs under every POSIX `sh`. It sets
+  `languageOptions: { dialect: 'posix' }` and enables the `compat/*` rules and
+  `sh/shebang-matches-dialect` at `error`, and `sh/require-strict-mode` with `set -eu`.
+  Compose them after `recommended`:
+  `extends: [sh.configs.recommended, sh.configs['posix-portable']]`. See
+  [version compatibility](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/compat.md).
+
+Three `agent-authored` rules report nothing until you configure them. `sh/no-undeclared-commands`
+and `sh/no-unused-declarations` need a declaration convention bound in
+`settings.sh.declarationConvention`, and `sh/require-network-wrapper` needs the wrapper your
+network commands must run through, set once in `settings.sh.networkWrapper`. The declaration rules
+read that setting too, so they count `curl` in `with-retry curl …` as used:
+
+```js
+import { defineConfig } from 'eslint/config';
+import sh, { commentPragma } from 'eslint-sh';
+
+export default defineConfig([
+  {
+    files: ['**/*.sh', 'bin/?*'],
+    extends: [sh.configs['agent-authored']],
+    settings: { sh: { declarationConvention: commentPragma, networkWrapper: 'with-retry' } },
+  },
+]);
+```
 
 ## `languageOptions` reference
 
 | Option            | Allowed values                                                          | Default    | Effect                                                                                                                                                                                                                                                                                                                                                                     |
 | ----------------- | ----------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dialect`         | `"bash"`, `"posix"`, `"mksh"`, `"bats"`, `"zsh"`                        | `"bash"`   | Selects which shell grammar the parser accepts. Enforcement is partial: some non-dialect constructs are rejected (e.g. bash array literals under `posix`), but others (e.g. `[[ ... ]]`, `let`) are accepted as ordinary commands — see the [per-dialect enforcement table](https://github.com/mike-north/sh-ast/blob/main/packages/sh-ast/README.md#dialect-enforcement). |
-| `shellVersion`    | A numeric `MAJOR` or `MAJOR.MINOR` string, e.g. `"5"` or `"3.2"`        | unset      | Reserved for the rule layer (e.g. a future bash-3.2 compatibility check); has no effect on parsing today since no rules ship yet.                                                                                                                                                                                                                                          |
+| `shellVersion`    | A numeric `MAJOR` or `MAJOR.MINOR` string, e.g. `"5"` or `"3.2"`        | unset      | The Bash version your scripts must run on. It has no effect on parsing; the `compat/*` rules read it to report features that version lacks. Unset means the newest version. See [version compatibility](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/compat.md).                                                                          |
 | `directivePrefix` | Lowercase, hyphen-separated words, e.g. `"eslint"` or `"shellcheck-sh"` | `"eslint"` | The prefix directive/inline-config comments must start with — e.g. the default recognizes `# eslint-disable-next-line ...`.                                                                                                                                                                                                                                                |
 
+## Continuous integration
+
+Lint with the same command you run locally, `eslint .`, against the config from
+[Usage](#usage). The config's `files` list decides which scripts are linted, including
+extensionless ones such as `bin/deploy`. Listing paths on the command line does not replace it:
+ESLint only lints a file the config's `files` patterns match. Here is a complete GitHub Actions
+job:
+
+```yaml
+name: Lint shell scripts
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  lint-shell:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - name: eslint-sh
+        run: npx eslint . --max-warnings 0
+      - name: shellcheck
+        run: |
+          git ls-files -z '*.sh' '*.bash' 'bin/*' |
+            xargs -0 sh -c '[ "$#" -eq 0 ] || exec shellcheck -- "$@"' sh
+```
+
+It assumes `eslint` and `eslint-sh` are in your `devDependencies` with a committed
+`package-lock.json`; use your package manager's frozen install (`pnpm install --frozen-lockfile`)
+otherwise. `permissions: contents: read` keeps the job's `GITHUB_TOKEN` read-only:
+linting needs nothing more. The `uses:` lines name each action's major version for readability;
+to guard against a moved tag, pin each one to a full commit SHA with the version as a trailing
+comment (`actions/checkout@<40-character SHA> # v4.4.0`), as
+[this repository's workflows](https://github.com/mike-north/eslint-sh/tree/main/.github/workflows)
+do, and let Dependabot's `github-actions` updates bump them. `ubuntu-latest` runners ship with shellcheck. The step is separate because shellcheck
+is a different tool with its own exit code; see
+[running eslint-sh beside shellcheck](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/shellcheck.md).
+
+The shellcheck step checks every tracked `*.sh` and `*.bash` file plus everything tracked under
+`bin/`, so it also works in a project that has no `bin/` or `scripts/` folder (it then checks
+nothing and exits 0). Adapt the pathspecs to where your scripts live. shellcheck needs a shebang
+or a `# shellcheck shell=bash` directive to know a file's dialect: an extensionless file without
+either fails with SC2148, so keep non-shell files out of `bin/`.
+
+Exit codes of `eslint`:
+
+| Exit code | Meaning                                                                                                                        |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `0`       | No errors. Warnings alone (`sh/quote-expansions` and `sh/no-secret-flags` under `recommended`) do not fail the job.            |
+| `1`       | At least one error, or more warnings than `--max-warnings` allows (`ESLint found too many warnings (maximum: 0).`).            |
+| `2`       | ESLint could not run: for example a CLI pattern that matches no files, or an invalid config. Treat it as a failed job as well. |
+
+`--max-warnings 0` in the job above makes warnings fail it. Drop the flag if you want warnings
+reported but not blocking.
+
+**Pre-commit hook.** To lint only the shell files in a commit, including extensionless ones,
+select the staged paths with git and pass them to ESLint. Save this as `.git/hooks/pre-commit`
+(or run it from your hook manager) and make it executable:
+
+```sh
+#!/bin/sh
+git diff --cached --name-only -z --diff-filter=ACM -- '*.sh' '*.bash' 'bin/*' |
+  xargs -0 sh -c '[ "$#" -eq 0 ] || exec npx eslint --max-warnings 0 --no-warn-ignored -- "$@"' sh
+```
+
+The pathspec `'bin/*'` selects extensionless scripts that a `*.sh` pattern would miss; match it
+to the `files` patterns in your config. `--no-warn-ignored` keeps a staged file that your config
+does not cover from failing the hook as an "ignored file" warning. File names are passed
+NUL-separated, so names with spaces work, and the hook does nothing when no shell file is staged.
+
+**Linting code you don't control.** The job above runs the checkout's own config and install,
+which is right for your own repository. When CI lints contributions from people who don't own the
+policy, a script can switch rules off with `# eslint-disable` comments, and the checkout's
+`eslint.config.mjs` is code the contributor wrote. See
+[linting code you don't control](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/untrusted-code.md)
+for a config that ignores those comments and a command that runs ESLint from outside the checkout.
+
+## Editor setup
+
+Editors that run ESLint through its language server, such as the VS Code ESLint extension, run
+the `eslint` installed in your project. They read the same `eslint.config.mjs` as the command
+line, so the plugin and the `files` patterns from [Usage](#usage) apply with no editor-specific
+configuration of eslint-sh. Install `eslint` and `eslint-sh` in the project, not globally.
+
+**VS Code.** What the
+[ESLint extension's documentation](https://github.com/microsoft/vscode-eslint#readme) says, which
+has not been tried against eslint-sh in an editor (see "What was and was not verified" below):
+
+- The extension only activates for the language ids in its `eslint.probe` list by default
+  (JavaScript, TypeScript, HTML, Markdown, JSON and similar, but not `shellscript`). Enforce
+  validation of shell files by listing the language id in `eslint.validate`.
+- Fix on save is the `source.fixAll.eslint` code action.
+
+```json
+{
+  "eslint.validate": ["shellscript"],
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  }
+}
+```
+
+Put it in `.vscode/settings.json` to share it with your team. Two things are expected but not
+confirmed, so check them (items 3 and 4 below) rather than assuming: that fix on save applies
+eslint-sh's autofixes, such as inserting a missing shebang and strict mode, and that the
+`shellscript` language id is what VS Code assigns to your scripts, including extensionless ones.
+The extension's documentation says ESLint v9 and later use flat config files, which is what
+`eslint.config.mjs` is, so `eslint.useFlatConfig` should not be needed; that is also unconfirmed.
+
+**What was and was not verified.**
+
+- Verified: the command-line behavior this section relies on (the `files` patterns, extensionless
+  scripts, and the exit codes above), by running it from packed tarballs of both packages in a
+  separate project, and by a test in this repository that runs the documented commands.
+- Not verified: everything about VS Code. No editor session was driven, and the ESLint extension
+  was not installed. The settings above come from the extension's documentation only, and the
+  extension version tested is therefore none.
+
+Before relying on this setup, check by hand in VS Code with the ESLint extension:
+
+1. Open a `.sh` file and a shebang-less `bin/` script in a project with `eslint-sh` installed.
+   Do diagnostics from eslint-sh rules (for example `sh/require-shebang`) appear in the Problems
+   panel with and without `eslint.validate`? If they appear without it, the setting is not needed.
+2. Does the extension's output channel ("ESLint") report any error loading the plugin or config?
+3. Remove the shebang from a `.sh` file and save. Is it inserted along with strict mode, once
+   `source.fixAll.eslint` is enabled?
+4. Does an extensionless script with a shebang, such as `bin/deploy`, get diagnostics? What does
+   VS Code show as its language in the status bar, with and without the shebang? If it is not
+   `shellscript` (shown as "Shell Script"), the extension will not validate it under
+   `eslint.validate: ["shellscript"]`.
+
 ## Troubleshooting
 
 Every worked example below (config, script, and error output) is extracted straight out of this
@@ -107,6 +358,36 @@ from what the plugin actually does.
   The fix for both is the same one-line addition: set `language: 'sh/sh'` alongside
   `plugins: { sh }` in the config object.
 
+- **My extensionless scripts aren't being linted.** ESLint treats a `files` pattern that ends in
+  `*` or `/**` as one that only adds settings to files another pattern already matched. Such a
+  pattern never makes a file lintable on its own. So with this config:
+
+  ```js
+  export default [{ files: ['**/*.sh', 'bin/*'], plugins: { sh }, language: 'sh/sh' }];
+  ```
+
+  `eslint .` lints `bin/build.sh` but skips the extensionless `bin/deploy`. It prints no warning
+  and still exits 0. Use a pattern that matches the file by itself:
+
+  ```js
+  export default [{ files: ['**/*.sh', 'bin/?*'], plugins: { sh }, language: 'sh/sh' }];
+  ```
+
+  Each of these patterns lints `bin/deploy`:
+  - `bin/?*`: every file directly in `bin/`.
+  - `bin/!(*.*)`: only the files in `bin/` whose names have no dot, so `bin/helper.js` stays out.
+  - `bin/**/?*`: every file in `bin/` and its subdirectories.
+  - `bin/deploy`: just that one file.
+
+  To check whether ESLint will lint a file, print the config it resolves for that file:
+
+  ```sh
+  npx eslint --print-config bin/deploy
+  ```
+
+  It prints `undefined` when no `files` pattern makes the file lintable. When one does, it prints
+  the resolved config, which includes `"language": "sh/sh"`.
+
 - **A script I believe is valid reports a parse error.** The parser is dialect-sensitive: a
   construct that's valid in one shell grammar may be rejected in another. Given this config:
 
@@ -136,17 +417,51 @@ from what the plugin actually does.
   Set `languageOptions.dialect` to match the shell the script is actually written for. Note that
   dialect enforcement is partial by design: some bash-isms — notably `[[ ... ]]` and `let` — are
   not parse errors under `dialect: 'posix'`; they silently parse as ordinary commands instead, so
-  a clean `posix` run does not by itself prove a script is POSIX-compliant. See the
+  a clean `posix` run does not by itself prove a script is POSIX-compliant. The `posix-portable`
+  preset reports `[[`, `let` and `source`, and
+  [names what it does not report](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/compat.md#what-posix-portable-does-not-report). See the
   [per-dialect construct enforcement audit](https://github.com/mike-north/sh-ast/blob/main/packages/sh-ast/README.md#dialect-enforcement)
   in `sh-ast` for the full accept/reject matrix and rationale.
 
-- **Setting `shellVersion` doesn't change anything.** That's expected today — see the
-  `languageOptions` reference table above: `shellVersion` is reserved for a future rule layer and
-  has no effect on parsing while no lint rules ship.
-- **`# eslint-disable-next-line ...` comments don't seem to do anything.** No lint rules ship yet
-  in this release, so there's nothing for a disable comment to suppress until you register a
-  custom rule (see the `@eslint-sh/eslint-plugin` README's "Writing your own rules" section). If
-  you've registered a custom rule and the directive still isn't recognized, check
+- **Every JavaScript file reports a shell parsing error.** `sh.configs.recommended` has no
+  `files` key by design: it lints exactly the paths of the config entry it is used in. Used on its
+  own, it has no paths, so it applies to every file ESLint lints, including your JavaScript.
+  eslint-sh recognizes common non-shell file types (JavaScript, TypeScript, JSON, Markdown, CSS,
+  HTML, Vue, Svelte, YAML) and reports one message per file instead of a misleading shell syntax
+  error. Given this config:
+
+  ```js
+  export default defineConfig([sh.configs.recommended]);
+  ```
+
+  linting `index.js`:
+
+  ```js
+  if (a) {
+    b();
+  }
+  ```
+
+  produces:
+
+  ```text
+  Parsing error: This JavaScript file (.js) is being linted as shell: a config entry selects language 'sh/sh' (for example sh.configs.recommended) without a files list. Wrap the preset in an entry with files, e.g. { files: ['**/*.sh'], extends: [sh.configs.recommended] }
+  ```
+
+  The fix is to wrap the preset in an entry whose `files` lists your shell scripts:
+
+  ```js
+  export default defineConfig([{ files: ['**/*.sh'], extends: [sh.configs.recommended] }]);
+  ```
+
+- **Setting `shellVersion` doesn't change anything.** `shellVersion` has no effect on parsing,
+  and only the version-gated `compat/*` rules read it (`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`). The `bash-3.2` and `posix-portable` presets enable them; to pick rules yourself,
+  enable the ones you want, for example `'sh/compat/no-mapfile': 'error'`. See
+  [version compatibility](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/compat.md).
+- **`# eslint-disable-next-line ...` comments don't seem to do anything.** First check that the
+  rule is enabled, through a preset or your `rules` config. For example,
+  `# eslint-disable-next-line sh/no-eval -- reviewed dynamic evaluation` suppresses an enabled
+  `sh/no-eval` finding on the following line. If the directive still isn't recognized, check
   `languageOptions.directivePrefix` — it must match the prefix your comment uses (the default
   `"eslint"` only recognizes `# eslint-disable-next-line ...`, not a custom prefix).
 - **A disable directive's rule id doesn't match anything I've registered.** An unknown rule id in
@@ -161,16 +476,46 @@ from what the plugin actually does.
   language ids in its message (current ESLint 10.x behavior). This plugin registers exactly one
   language: `sh` (selected as `language: 'sh/sh'`).
 
+## Writing custom rules
+
+`eslint-sh` re-exports everything a custom rule imports, so a project that installs only
+`eslint-sh` needs no other package, even under pnpm's strict `node_modules` layout:
+
+```js
+// The plugin's named exports: the rule helper defineShellRule, view-aware helpers such as
+// resolveWord, and the view and rule types.
+import { defineShellRule, resolveWord } from 'eslint-sh';
+// sh-ast's root entry point: parse, walk, and print faithful records.
+import { parseSync, printSync, walk } from 'eslint-sh/syntax';
+// sh-ast/analyze: command enumeration and wrapper resolution over faithful records.
+import { DEFAULT_TRANSPARENT_WRAPPERS, enumerateCommands } from 'eslint-sh/syntax/analyze';
+```
+
+`eslint-sh` re-exports `@eslint-sh/eslint-plugin`'s named exports, and `eslint-sh/syntax` and
+`eslint-sh/syntax/analyze` are `@eslint-sh/eslint-plugin/syntax` and
+`@eslint-sh/eslint-plugin/syntax/analyze`. Those re-export `sh-ast` and `sh-ast/analyze` from the
+plugin's own `sh-ast` dependency, the same module instance its language parses with. Don't import
+`sh-ast` directly.
+
+**Versioning.** `eslint-sh/syntax` and `eslint-sh/syntax/analyze` track the 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 package, and the changelog entry
+names the new `sh-ast` version.
+
+See the `@eslint-sh/eslint-plugin` package's README for the full API and the
+[custom-rule tutorial](https://github.com/mike-north/eslint-sh/blob/main/packages/eslint-plugin/docs/custom-rule-tutorial.md).
+
 ## Status
 
 Thin umbrella re-exporting `@eslint-sh/eslint-plugin`'s plugin object unchanged as this
 package's default export — `import sh from "eslint-sh"` and `import sh from "@eslint-sh/eslint-plugin"`
-refer to the same object. `@eslint-sh/eslint-plugin` currently ships `ShellLanguage`/
-`ShellSourceCode` only; rules and shared configs are not implemented yet. Disable directives /
-inline config are implemented and live. No lint rules ship yet, so the rule id in the
-troubleshooting section above is illustrative: after you register a custom rule as
-`sh/your-rule`, `# eslint-disable-next-line sh/your-rule -- justification` suppresses it on the
-following line.
+refer to the same object. Its named exports and its `syntax` / `syntax/analyze` subpaths are the
+plugin's, re-exported unchanged (see [Writing custom rules](#writing-custom-rules)). `@eslint-sh/eslint-plugin` currently ships `ShellLanguage`/
+`ShellSourceCode`, the built-in rules documented under its `docs/rules/`, and the `recommended`
+and `agent-authored` [presets](#presets). Disable directives / inline config are implemented and
+live. Disable comments suppress enabled built-in rules and custom rules alike; for example,
+`# eslint-disable-next-line sh/no-eval -- justification` suppresses that rule on the following
+line.
 
 For the plugin's public API reference (types, exports, selector cookbook, and a custom-rule
 authoring tutorial), see the `@eslint-sh/eslint-plugin` package's README.

package/dist/eslint-sh-syntax-analyze.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The faithful shell analysis surface (`eslint-sh/syntax/analyze`):
+ * `@eslint-sh/eslint-plugin/syntax/analyze`, re-exported unchanged. It is the complete public
+ * surface of `sh-ast/analyze`, taken from the same `sh-ast` instance the plugin's language parses
+ * with. Its `resolveWord` takes a faithful `Node`, unlike the view-aware `resolveWord` exported
+ * from `eslint-sh` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+
+
+export * from "@eslint-sh/eslint-plugin/syntax/analyze";
+
+export { }

package/dist/eslint-sh-syntax.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The faithful shell syntax surface (`eslint-sh/syntax`): `@eslint-sh/eslint-plugin/syntax`,
+ * re-exported unchanged. It is the complete public surface of `sh-ast`'s root entry point, taken
+ * from the same `sh-ast` instance the plugin's language parses with, so a project that installs
+ * only `eslint-sh` can edit or analyze faithful syntax without installing `sh-ast` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+
+
+export * from "@eslint-sh/eslint-plugin/syntax";
+
+export { }

package/dist/eslint-sh.d.ts

@@ -2,4 +2,7 @@ import sh from '@eslint-sh/eslint-plugin';
 
 export default sh;
 
+
+export * from "@eslint-sh/eslint-plugin";
+
 export { }

package/dist/index.d.ts

@@ -9,4 +9,4 @@ import sh from '@eslint-sh/eslint-plugin';
  * @public
  */
 export default sh;
-//# sourceMappingURL=index.d.ts.map
+export * from '@eslint-sh/eslint-plugin';

package/dist/index.js

@@ -9,4 +9,7 @@ import sh from '@eslint-sh/eslint-plugin';
  * @public
  */
 export default sh;
-//# sourceMappingURL=index.js.map
+// Every named export of the plugin root (`resolveWord`, `ShellSourceCode`, the view types, …)
+// is re-exported unchanged, so a project that installs only `eslint-sh` can write custom rules
+// without depending on `@eslint-sh/eslint-plugin` being hoisted where it can import it.
+export * from '@eslint-sh/eslint-plugin';

package/dist/syntax/analyze.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The faithful shell analysis surface (`eslint-sh/syntax/analyze`):
+ * `@eslint-sh/eslint-plugin/syntax/analyze`, re-exported unchanged. It is the complete public
+ * surface of `sh-ast/analyze`, taken from the same `sh-ast` instance the plugin's language parses
+ * with. Its `resolveWord` takes a faithful `Node`, unlike the view-aware `resolveWord` exported
+ * from `eslint-sh` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+export * from '@eslint-sh/eslint-plugin/syntax/analyze';

package/dist/syntax/analyze.js

@@ -0,0 +1,15 @@
+/* eslint-disable @api-extractor-tools/package-documentation -- this file is the barrel of the
+   `./syntax/analyze` entry point (package.json `exports`); the rule only recognizes the root barrel. */
+/**
+ * The faithful shell analysis surface (`eslint-sh/syntax/analyze`):
+ * `@eslint-sh/eslint-plugin/syntax/analyze`, re-exported unchanged. It is the complete public
+ * surface of `sh-ast/analyze`, taken from the same `sh-ast` instance the plugin's language parses
+ * with. Its `resolveWord` takes a faithful `Node`, unlike the view-aware `resolveWord` exported
+ * from `eslint-sh` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+export * from '@eslint-sh/eslint-plugin/syntax/analyze';

package/dist/syntax/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The faithful shell syntax surface (`eslint-sh/syntax`): `@eslint-sh/eslint-plugin/syntax`,
+ * re-exported unchanged. It is the complete public surface of `sh-ast`'s root entry point, taken
+ * from the same `sh-ast` instance the plugin's language parses with, so a project that installs
+ * only `eslint-sh` can edit or analyze faithful syntax without installing `sh-ast` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+export * from '@eslint-sh/eslint-plugin/syntax';

package/dist/syntax/index.js

@@ -0,0 +1,14 @@
+/* eslint-disable @api-extractor-tools/package-documentation -- this file is the barrel of the
+   `./syntax` entry point (package.json `exports`); the rule only recognizes the root barrel. */
+/**
+ * The faithful shell syntax surface (`eslint-sh/syntax`): `@eslint-sh/eslint-plugin/syntax`,
+ * re-exported unchanged. It is the complete public surface of `sh-ast`'s root entry point, taken
+ * from the same `sh-ast` instance the plugin's language parses with, so a project that installs
+ * only `eslint-sh` can edit or analyze faithful syntax without installing `sh-ast` itself.
+ *
+ * It tracks the plugin's pinned `sh-ast` minor, so an `sh-ast` 0.x minor bump is a minor release
+ * of this package.
+ *
+ * @packageDocumentation
+ */
+export * from '@eslint-sh/eslint-plugin/syntax';

package/package.json

@@ -1,25 +1,37 @@
 {
   "name": "eslint-sh",
-  "description": "Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a typed shell AST",
-  "version": "0.5.0",
+  "description": "Shell script linting for ESLint, with built-in policy rules, shared presets, and custom rules over a typed shell AST",
+  "version": "0.7.0",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
-    "@eslint-sh/eslint-plugin": "0.5.0"
+    "@eslint-sh/eslint-plugin": "0.7.0"
   },
   "devDependencies": {
     "eslint": "^10.7.0"
   },
   "peerDependencies": {
-    "eslint": "^10.0.0"
+    "eslint": "^10.2.0"
+  },
+  "engines": {
+    "node": "^22.13.0 || >=24"
   },
   "exports": {
     ".": {
       "types": "./dist/eslint-sh.d.ts",
       "default": "./dist/index.js"
+    },
+    "./syntax": {
+      "types": "./dist/eslint-sh-syntax.d.ts",
+      "default": "./dist/syntax/index.js"
+    },
+    "./syntax/analyze": {
+      "types": "./dist/eslint-sh-syntax-analyze.d.ts",
+      "default": "./dist/syntax/analyze.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "!dist/**/*.map"
   ],
   "license": "MIT",
   "main": "./dist/index.js",
@@ -28,8 +40,7 @@
       "check:api-report": {
         "outputs": [
           "{projectRoot}/api-report",
-          "{projectRoot}/temp",
-          "{projectRoot}/dist/eslint-sh.d.ts"
+          "{projectRoot}/temp"
         ]
       },
       "uplevel-api-reports": {
@@ -43,7 +54,11 @@
         ],
         "outputs": [
           "{workspaceRoot}/api-report-combined/eslint-sh.api.md",
-          "{workspaceRoot}/api-docs-temp/eslint-sh.api.json"
+          "{workspaceRoot}/api-docs-temp/eslint-sh.api.json",
+          "{workspaceRoot}/api-report-combined/eslint-sh-syntax.api.md",
+          "{workspaceRoot}/api-docs-temp/eslint-sh-syntax.api.json",
+          "{workspaceRoot}/api-report-combined/eslint-sh-syntax-analyze.api.md",
+          "{workspaceRoot}/api-docs-temp/eslint-sh-syntax-analyze.api.json"
         ]
       }
     }
@@ -59,15 +74,15 @@
     "directory": "packages/eslint-sh"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node ../../scripts/rollup-declarations.mjs api-extractor.json syntax/api-extractor.json syntax/analyze/api-extractor.json",
     "check": "concurrently -n lint,types,api-report \"pnpm run check:lint-ts\" \"pnpm run check:typecheck\" \"pnpm run check:api-report\"",
-    "check:api-report": "api-extractor run",
+    "check:api-report": "api-extractor run && api-extractor run --config syntax/api-extractor.json && api-extractor run --config syntax/analyze/api-extractor.json",
     "check:lint-ts": "eslint .",
     "check:typecheck": "tsc --noEmit",
     "clean": "rimraf --glob dist \"temp/*\" \"*.tsbuildinfo\"",
-    "fix:api-report": "api-extractor run --local",
+    "fix:api-report": "api-extractor run --local && api-extractor run --local --config syntax/api-extractor.json && api-extractor run --local --config syntax/analyze/api-extractor.json",
     "fix:lint-ts": "eslint . --fix",
     "test": "vitest run",
-    "uplevel-api-reports": "mkdir -p ../../api-report-combined ../../api-docs-temp && cp api-report/eslint-sh.api.md ../../api-report-combined/ && cp temp/eslint-sh.api.json ../../api-docs-temp/"
+    "uplevel-api-reports": "mkdir -p ../../api-report-combined ../../api-docs-temp && cp api-report/eslint-sh.api.md api-report/eslint-sh-syntax.api.md api-report/eslint-sh-syntax-analyze.api.md ../../api-report-combined/ && cp temp/eslint-sh.api.json temp/eslint-sh-syntax.api.json temp/eslint-sh-syntax-analyze.api.json ../../api-docs-temp/"
   }
 }

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAe,EAAE,CAAC"}

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAE1C;;;;;;;;GAQG;AACH,eAAe,EAAE,CAAC"}