@eslint-sh/eslint-plugin 0.6.0 → 0.8.0

package/docs/untrusted-code.md

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

package/docs/wrapper-rules.md

@@ -9,6 +9,10 @@ Which commands need a wrapper, and which wrapper, is your project's policy. This
 wrapper name. You bind both, either in a rule pack with `createWrapperRule` or in your config
 with [`sh/require-network-wrapper`](./rules/require-network-wrapper.md)'s `wrapper` option.
 
+Project wrapper facts are shared through
+`settings: { sh: { transparentWrappers: ['with-retry'] } }`. This rule follows
+those wrappers and the shared network wrapper; see [shared transparent wrappers](./transparent-wrappers.md).
+
 ## `createWrapperRule`
 
 ```ts
@@ -204,3 +208,8 @@ command runs after its own options, located the way a wrapped command is located
 `noArgFlags` and `argFlags` are skipped, and an option in `stopsChainFlags` means no subcommand
 runs. The message names the command with its subcommand: `` `git fetch` must be run through
 `retry`. ``
+
+A `WrapperSpec` may set `shellBuiltin: true` for a wrapper that runs inside the current shell.
+Such entries match exact names: an executable such as `/tmp/command` is not the `command`
+builtin and its argument words remain opaque. Omitted or false retains utility-wrapper path
+matching. The same boolean field is accepted in the network-wrapper option and setting.

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@eslint-sh/eslint-plugin",
   "description": "Shell script linting for ESLint, with built-in policy rules, shared presets, and custom rules over a typed shell AST",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
     "@eslint/core": "^1.2.1",
     "@eslint/plugin-kit": "^0.7.2",
-    "sh-ast": "^0.7.0"
+    "sh-ast": "^0.9.0"
   },
   "devDependencies": {
     "eslint": "^10.7.0"

package/dist/language/end-of-input-marker.d.ts

@@ -1,29 +0,0 @@
-/**
- * Detects a source whose U+0080 made the parser silently drop text.
- *
- * mvdan/sh's reader uses U+0080 (`utf8.RuneSelf`) as its internal end-of-input marker. In some
- * positions the parser reads it as an ordinary character and returns the whole tree; in others
- * it stops there and returns a tree for only the text before it, with no error. A linter that
- * accepted the second kind would skip every rule on the lost text, so those sources must be
- * refused while the first kind keeps linting.
- *
- * The two are told apart by asking the parser what it does with the same source when U+0080 is
- * an ordinary character: the parse is complete exactly when the printed tree is the same as the
- * printed tree of the source with every U+0080 swapped for `X`. Text the parser dropped is
- * missing from the first print and present in the second. Nothing is inferred from tree
- * extents, so a trailing comment or heredoc body cannot make a truncated file look complete.
- */
-import { type ParseOptions } from 'sh-ast';
-/**
- * The UTF-16 index of the first U+0080 whose presence makes the parser drop text, or
- * `undefined` when `text` holds none or the parser handles every one of them completely.
- *
- * A source the parser rejects with an error is also `undefined`: that is a fatal parse error the
- * caller reports through its normal path, not a silent loss. Every other doubt is a refusal:
- * a source that parses but prints differently from its swapped counterpart is refused, and so is
- * one whose swapped counterpart no longer parses, so an undecidable position is never accepted.
- *
- * @param text - The source about to be parsed.
- * @param options - The parse options the caller will use, so the dialect matches.
- */
-export declare function firstDroppedTextIndex(text: string, options: ParseOptions): number | undefined;

package/dist/language/end-of-input-marker.js

@@ -1,88 +0,0 @@
-/**
- * Detects a source whose U+0080 made the parser silently drop text.
- *
- * mvdan/sh's reader uses U+0080 (`utf8.RuneSelf`) as its internal end-of-input marker. In some
- * positions the parser reads it as an ordinary character and returns the whole tree; in others
- * it stops there and returns a tree for only the text before it, with no error. A linter that
- * accepted the second kind would skip every rule on the lost text, so those sources must be
- * refused while the first kind keeps linting.
- *
- * The two are told apart by asking the parser what it does with the same source when U+0080 is
- * an ordinary character: the parse is complete exactly when the printed tree is the same as the
- * printed tree of the source with every U+0080 swapped for `X`. Text the parser dropped is
- * missing from the first print and present in the second. Nothing is inferred from tree
- * extents, so a trailing comment or heredoc body cannot make a truncated file look complete.
- */
-import { parseSync, printSync } from 'sh-ast';
-const END_OF_INPUT_MARKER = '\u0080';
-/** An ordinary one-UTF-16-unit word character, so offsets are the same in both parses. */
-const ORDINARY_CHARACTER = 'X';
-/** What the parser makes of a source: the printed tree, or `ERROR` when it does not parse. */
-const ERROR = Symbol('parse error');
-/**
- * Prints `text` the way the parser sees it. Every U+0080 in the result is swapped for the
- * ordinary character so the print of the original can be compared with the print of the
- * swapped source.
- */
-function printed(text, options) {
-    try {
-        const output = printSync(parseSync(text, options));
-        const decoded = typeof output === 'string' ? output : new TextDecoder().decode(output);
-        return decoded.replaceAll(END_OF_INPUT_MARKER, ORDINARY_CHARACTER);
-    }
-    catch {
-        return ERROR;
-    }
-}
-/**
- * The UTF-16 index of the first U+0080 whose presence makes the parser drop text, or
- * `undefined` when `text` holds none or the parser handles every one of them completely.
- *
- * A source the parser rejects with an error is also `undefined`: that is a fatal parse error the
- * caller reports through its normal path, not a silent loss. Every other doubt is a refusal:
- * a source that parses but prints differently from its swapped counterpart is refused, and so is
- * one whose swapped counterpart no longer parses, so an undecidable position is never accepted.
- *
- * @param text - The source about to be parsed.
- * @param options - The parse options the caller will use, so the dialect matches.
- */
-export function firstDroppedTextIndex(text, options) {
-    const indices = [];
-    for (let at = text.indexOf(END_OF_INPUT_MARKER); at !== -1; at = text.indexOf(END_OF_INPUT_MARKER, at + 1)) {
-        indices.push(at);
-    }
-    if (indices.length === 0)
-        return undefined;
-    const ordinary = text.replaceAll(END_OF_INPUT_MARKER, ORDINARY_CHARACTER);
-    const expected = printed(ordinary, options);
-    const actual = printed(text, options);
-    if (actual === ERROR)
-        return undefined;
-    if (expected !== ERROR && actual === expected)
-        return undefined;
-    /** Whether keeping only the first `count` U+0080 characters (the rest swapped) still differs. */
-    const dropsText = (count) => {
-        let candidate = '';
-        let from = 0;
-        for (const index of indices.slice(0, count)) {
-            candidate += ordinary.slice(from, index) + END_OF_INPUT_MARKER;
-            from = index + 1;
-        }
-        candidate += ordinary.slice(from);
-        const result = printed(candidate, options);
-        return result === ERROR || expected === ERROR || result !== expected;
-    };
-    // The full source differs, so the smallest differing prefix of U+0080 characters exists; the
-    // search assumes that keeping more of them never repairs the parse, and only ever lands on a
-    // count that was itself observed to differ.
-    let low = 1;
-    let high = indices.length;
-    while (low < high) {
-        const middle = (low + high) >> 1;
-        if (dropsText(middle))
-            high = middle;
-        else
-            low = middle + 1;
-    }
-    return indices[high - 1];
-}