@eslint-sh/eslint-plugin 0.5.0 → 0.7.0

package/docs/declaration-conventions.md

@@ -0,0 +1,478 @@
+# Declaration conventions
+
+A script that calls `jq` and `curl` depends on both being installed. Many projects want each
+script to _declare_ the external commands it uses, so that a reviewer, an installer, or a lint
+rule can compare what a script says it needs with what it actually runs.
+
+How a script declares its dependencies is a project decision: a header comment, a variable, a
+sourced manifest. This plugin does not pick one for you. It defines an extension point, the
+`DeclarationConvention` interface, and ships one reference implementation, `commentPragma`. Rules
+that check declarations ask the bound convention which commands a script declares and, when they
+offer an autofix, ask the same convention to edit the declaration, because only the convention
+knows its own syntax.
+
+**With no convention bound, rules that consume one report nothing.** Binding a convention is how
+you opt in.
+
+## The interface
+
+```ts
+import type { RuleTextEdit, RuleTextEditor } from '@eslint/core';
+import type { ShellSourceCode } from '@eslint-sh/eslint-plugin';
+
+/** The file being linted, as ESLint's rule context names it. */
+interface LintedFile {
+  readonly filename: string; // virtual for a processor's code block (README.md/0_0.sh)
+  readonly physicalFilename: string; // the path on disk ESLint associates with the code
+  readonly cwd: string; // a relative FileDeclaredCommand.path is relative to this
+}
+
+/** Written in the script. */
+interface ScriptDeclaredCommand {
+  readonly kind: 'script';
+  readonly name: string;
+  /** [start, end) offsets into sourceCode.text, covering just this declaration. */
+  readonly range: readonly [number, number];
+}
+
+/** Written in another file, such as a sidecar next to the script. */
+interface FileDeclaredCommand {
+  readonly kind: 'file';
+  readonly name: string;
+  readonly path: string; // where to look: relative to cwd, or absolute
+  readonly line?: number; // 1-based, when known
+}
+
+/** From a source described in words: a list in eslint.config.js, a registry snapshot. */
+interface DescribedDeclaredCommand {
+  readonly kind: 'described';
+  readonly name: string;
+  readonly description: string; // "the tool registry snapshot of 2026-11-01"
+}
+
+type DeclaredCommand = ScriptDeclaredCommand | FileDeclaredCommand | DescribedDeclaredCommand;
+
+interface DeclarationConvention {
+  /** Every command the linted file declares, in source order. */
+  declaredCommands(sourceCode: ShellSourceCode, file: LintedFile): DeclaredCommand[];
+  /** Optional: the fix that deletes one stale in-script declaration, or null. */
+  removeDeclaration?(
+    sourceCode: ShellSourceCode,
+    declared: ScriptDeclaredCommand,
+    fixer: RuleTextEditor,
+  ): RuleTextEdit | RuleTextEdit[] | null;
+  /** Optional: one sentence telling a person how to declare `command`, or null. */
+  declarationHint?(command: string, sourceCode: ShellSourceCode, file: LintedFile): string | null;
+}
+```
+
+- `declaredCommands` is required. A name declared twice appears twice, each with its own source.
+  Its second argument says which file is being linted; a convention that only reads the script's
+  text can leave it out.
+- **Where a declaration lives** is one of three kinds, told apart by `kind`, which every
+  declaration must carry:
+  - **In the script** (`kind: 'script'`): `range` uses the same coordinates as every node's
+    `range`, UTF-16 offsets into `sourceCode.text`, and must lie within the text. A rule reports
+    the declaration there, so cover exactly the text that declares this one name. Use
+    `sourceCode.getLocFromIndex(offset)` to turn an offset into a line and column.
+  - **In another file** (`kind: 'file'`): `path` says where a person or a tool should look for the
+    declaration. It is relative to `file.cwd` unless it is absolute, and it must be a non-empty
+    single line. Add `line` (1-based) when you know it. Rules name the path in their reports as
+    given; they never read it.
+  - **From a source described in words** (`kind: 'described'`): a declaration with no range in
+    the script and no file to point at, whose source can only be described, such as a list written
+    in `eslint.config.js`, a constant in the convention, or a snapshot of a tool registry.
+    `description` holds those words: it names the source for a person who wants to change the
+    declaration, as a phrase that reads after "declared in", such as
+    `` the `web` image list in eslint.config.js `` or `the tool registry snapshot of 2026-11-01`.
+    It must be a non-empty single line.
+- `removeDeclaration` is optional. It receives one in-script entry that `declaredCommands` returned
+  for the same `sourceCode`, plus the rule's `fixer`, and returns the edit that deletes that
+  declaration. Return `null` when it can't be removed safely. A convention without this hook still
+  gets its stale declarations reported; the reports just carry no autofix. It is never called for
+  a declaration kept anywhere else: a fix can only edit the script being linted.
+- `declarationHint` is optional. `sh/no-undeclared-commands` appends what it returns to its
+  report, so write one short sentence with text a person can copy, such as
+  ``Add `# uses: curl` on a line below the shebang.`` Following it literally must clear the
+  report. Return `null` for a name your syntax can't express. Without the hook, or on `null`,
+  the report ends with the generic `Declare it with the project's declaration convention.`
+  Anything else must be a non-empty single-line string, or linting stops with an error.
+- A declaration with a missing or unknown `kind`, without its kind's fields, or with a `range`
+  outside the text stops linting with an error that starts
+  `Invalid settings.sh.declarationConvention:` and shows the declaration.
+
+To switch on `kind` exhaustively, end with a `never` default. A future kind then fails to compile
+instead of slipping through:
+
+```ts
+function whereToLook(declared: DeclaredCommand): string {
+  switch (declared.kind) {
+    case 'script':
+      return `offset ${String(declared.range[0])}`;
+    case 'file':
+      return declared.path;
+    case 'described':
+      return declared.description;
+    default: {
+      const unreachable: never = declared;
+      return unreachable;
+    }
+  }
+}
+```
+
+These types and `LintedFile` are exported from `@eslint-sh/eslint-plugin`.
+
+## The reference convention: `commentPragma`
+
+`commentPragma` reads `# uses:` comments from a script's header:
+
+```sh
+#!/usr/bin/env bash
+# Publishes the build manifest.
+# uses: jq curl
+# uses: git
+set -euo pipefail
+```
+
+This script declares `jq`, `curl`, and `git`.
+
+- **Header only.** The header is the run of blank and comment-only lines at the top of the file,
+  shebang included. It ends at the first line with anything else on it. A `# uses:` comment after
+  the first command, or inside a heredoc body, is not a declaration.
+- **Pragma lines.** A header comment whose text starts with `uses:` (lowercase) is a pragma.
+  Whitespace is allowed before the `#` and between `#` and `uses:`.
+- **Names.** The rest of the line is a whitespace-separated list of names. Several pragma lines
+  accumulate. Each declaration is `kind: 'script'`, and its `range` covers exactly that name.
+- **Trailing remarks.** The list ends at the first word that starts with `#`. Everything from
+  there to the end of the line is a remark, not a name: `# uses: jq curl # for the release API`
+  declares only `jq` and `curl`. A `#` later in a word does not end the list (`c#sharp` is a
+  name).
+- **Edit hook.** `removeDeclaration` deletes one name and the whitespace that separated it:
+  removing `curl` from `# uses: jq curl` leaves `# uses: jq`, and from
+  `# uses: jq curl # for the release API` leaves `# uses: jq # for the release API`. When the name
+  was the line's last, the whole line goes, remark included, with its `\n` or `\r\n` line
+  ending.
+- **Hint.** `declarationHint` gives `sh/no-undeclared-commands` its fix-it sentence:
+  ``Add `# uses: curl` on a line below the shebang.``, or ``… as the first line of the file.``
+  when there is no shebang (a line above the shebang would break it). A name with whitespace, or
+  one starting with `#`, can't be written in a pragma and gets no hint.
+
+Bind it in your flat config:
+
+```js
+import sh, { commentPragma } from '@eslint-sh/eslint-plugin';
+
+export default [
+  {
+    files: ['**/*.sh', '**/*.bash'],
+    plugins: { sh },
+    language: 'sh/sh',
+    settings: { sh: { declarationConvention: commentPragma } },
+  },
+];
+```
+
+## Binding a convention
+
+Bind a convention with the shared setting `settings.sh.declarationConvention`. Every rule that
+consumes a convention reads it from there.
+
+- **Use `settings`, not a rule's options.** ESLint copies each rule's options with
+  `structuredClone`, which can't copy functions, so ESLint rejects a convention passed as a rule
+  option with a "could not be cloned" configuration error.
+- **Define the convention as a plain object** whose methods are its own properties, as both
+  `commentPragma` and the example below do.
+- **Bind it in one config entry.** When two config entries that match the same file both set
+  `settings.sh.declarationConvention`, ESLint merges the two objects property by property. That
+  drops methods inherited from a class prototype and can mix methods from two different
+  conventions.
+- **A value that isn't a convention is a configuration error.** If the setting holds anything
+  without a `declaredCommands` method, linting stops with an error that names the setting and
+  says what it got instead, starting `Invalid settings.sh.declarationConvention: expected a
+  declaration convention`. A `removeDeclaration` or `declarationHint` that is present but not a
+  function is rejected the same way.
+
+## Writing your own convention
+
+Suppose your project declares each dependency on its own `# @dep <name>` line. This complete
+convention reads those lines and can delete one. It is the shipped file
+[`examples/dep-line-convention.mjs`](./examples/dep-line-convention.mjs), and
+this package's test suite runs it in CI through a real ESLint `Linter`, so this
+page can't drift from working code.
+
+```mjs
+/**
+ * A custom declaration convention: each dependency is declared on its own
+ * `# @dep <name>` line. From `../declaration-conventions.md`, and run in CI.
+ */
+const depLines = {
+  declaredCommands(sourceCode) {
+    const declared = [];
+    for (const match of sourceCode.text.matchAll(/^# @dep (\S+)[ \t]*$/gmu)) {
+      const start = match.index + '# @dep '.length;
+      declared.push({ kind: 'script', name: match[1], range: [start, start + match[1].length] });
+    }
+    return declared;
+  },
+  removeDeclaration(sourceCode, declared, fixer) {
+    const { text } = sourceCode;
+    const lineStart = text.lastIndexOf('\n', declared.range[0]) + 1;
+    const newline = text.indexOf('\n', declared.range[1]);
+    return fixer.removeRange([lineStart, newline === -1 ? text.length : newline + 1]);
+  },
+};
+
+export default depLines;
+```
+
+- `declaredCommands` computes each range from the match's offset into `sourceCode.text`, so the
+  range covers only the name, not the `# @dep ` prefix.
+- `removeDeclaration` deletes the declaration's whole line, including its line ending. The
+  declaration's own `range` tells it which line.
+- This example scans the whole file, so a `# @dep` line inside a heredoc body would count too.
+  `commentPragma` avoids that by reading only the header. Scope your own convention the same way
+  if your scripts carry such text.
+
+Bind it like any other convention:
+
+```js
+import sh from '@eslint-sh/eslint-plugin';
+import depLines from './dep-line-convention.mjs';
+
+export default [
+  {
+    files: ['**/*.sh', '**/*.bash'],
+    plugins: { sh },
+    language: 'sh/sh',
+    settings: { sh: { declarationConvention: depLines } },
+  },
+];
+```
+
+## Declarations outside the script
+
+Some projects keep a script's dependencies next to it rather than in it: `deploy.sh` beside a
+`deploy.commands` file, one name per line. A convention can say so. It uses the `file` argument
+to find the sidecar of the script being linted, and returns `kind: 'file'` declarations that name
+the sidecar and the line. This is the shipped file
+[`examples/sidecar-convention.mjs`](./examples/sidecar-convention.mjs), and
+this package's test suite runs it in CI on real files.
+
+```mjs
+/**
+ * A declaration convention whose declarations live beside each script:
+ * `deploy.sh` declares its commands in `deploy.commands`, one name per line.
+ * It reads the sidecar while linting. From `../declaration-conventions.md`,
+ * and run in CI.
+ */
+import { readFileSync } from 'node:fs';
+import { basename, dirname, extname, join, relative } from 'node:path';
+
+/** `deploy.sh` → `deploy.commands`, next to the script on disk. */
+export function sidecarPathFor(script) {
+  return join(dirname(script), `${basename(script, extname(script))}.commands`);
+}
+
+/** One file declaration per non-blank, non-`#` line of `text`. */
+export function parseSidecar(text, shownPath) {
+  return text.split(/\r?\n/u).flatMap((line, index) => {
+    const name = line.trim();
+    if (name === '' || name.startsWith('#')) return [];
+    return [{ kind: 'file', name, path: shownPath, line: index + 1 }];
+  });
+}
+
+/** Reads the linted script's own sidecar each time it is asked. */
+const sidecarCommands = {
+  declaredCommands(sourceCode, file) {
+    const path = sidecarPathFor(file.physicalFilename);
+    let text;
+    try {
+      text = readFileSync(path, 'utf8');
+    } catch {
+      return []; // No sidecar: the script declares nothing.
+    }
+    return parseSidecar(text, relative(file.cwd, path));
+  },
+};
+
+export default sidecarCommands;
+```
+
+- It resolves the sidecar from `file.physicalFilename`, the path on disk ESLint associates with
+  the code. For a shell block that a processor extracts from Markdown, that is the Markdown file,
+  and `file.filename` is a virtual name like `README.md/0_0.sh`. With
+  `eslint --stdin --stdin-filename scripts/new.sh`, it is the name given on the command line: the
+  code came from standard input, and `scripts/new.sh` may not exist. That is why a missing
+  sidecar is a normal case here, not an error.
+- The path it returns is relative to `file.cwd`, so it says where to look from where ESLint runs.
+- With `git` on line 3 of `scripts/deploy.commands` and never run, `sh/no-unused-declarations`
+  reports: `'git' is declared in scripts/deploy.commands:3 but this script never uses it. Remove
+  it there so the script's stated dependencies match what it runs.` ESLint can only report inside
+  the file it lints, so the report sits at line 1, column 1, with no end, and has no fix. The
+  message says where to look.
+- `sh/no-undeclared-commands` counts every kind of declaration the same way. A script with no
+  sidecar declares nothing, so each command it runs is reported as undeclared.
+
+### Silencing a report about a declaration outside the script
+
+A report about a declaration in another file or a described source sits at line 1, column 1. In a
+script that starts with a shebang, no comment can reach that position. `#!/bin/sh` must be the
+whole first line, so `#!/bin/sh # eslint-disable-line …` is not a directive. A directive on line
+2, whether `# eslint-disable-next-line …` or `# eslint-disable …`, covers only line 3 or line 2
+onward, and ESLint reports it as unused. (In a script with no shebang, a `# eslint-disable …` or
+`# eslint-disable-line …` comment on line 1 does work.) The ways out:
+
+- **Fix the declaration.** Remove the stale name from the file or source the message names. That
+  is what the report asks for, and the report goes away.
+- **A `files` override.** Turn the rule off for the scripts concerned in your config:
+
+  ```js
+  { files: ['scripts/legacy/*.sh'], rules: { 'sh/no-unused-declarations': 'off' } }
+  ```
+
+- **Bulk suppressions.** `eslint --suppress-rule sh/no-unused-declarations` records how many
+  reports each file has in `eslint-suppressions.json`. Later runs hide them while a file has no
+  more than that many, and show them all once it has more.
+
+This package's test suite covers all three.
+
+### Sidecars and `eslint --cache`
+
+One convention object serves every file its config entry matches. Keep its answer a function of
+`sourceCode`, `file` and the data it holds, never of which file it saw before, and two files will
+never see each other's declarations.
+
+**ESLint's cache does not know your convention reads files.** `eslint --cache` reuses a file's
+last result while the file and the hash of its config are unchanged. The convention above reads
+the sidecar while linting, so after you edit only a sidecar, `eslint --cache` reports the old
+result. After editing a sidecar, delete the cache file your runs use: the one `--cache-location`
+names, or `.eslintcache` in the working directory by default. A single run without `--cache` gives
+a correct result and deletes `.eslintcache`, but it leaves a file at another `--cache-location`
+in place, so the next `eslint --cache --cache-location …` run is stale again.
+
+To make sidecar edits invalidate the cache, read the sidecars when the config loads and keep their
+text as plain data on the convention. ESLint's cache hashes the config, `settings` included, as
+JSON: a convention's own data properties are part of that hash, and its functions and closures are
+not. Editing any sidecar then re-lints every file in that config entry. This is the shipped file
+[`examples/sidecar-snapshot-convention.mjs`](./examples/sidecar-snapshot-convention.mjs):
+
+```mjs
+/**
+ * The sidecar convention, reading every sidecar under `root` once, when the
+ * ESLint config loads, and keeping their text as plain data, which ESLint's
+ * `--cache` sees. From `../declaration-conventions.md`, and run in CI.
+ */
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { parseSidecar, sidecarPathFor } from './sidecar-convention.mjs';
+
+/** A convention over the `*.commands` files under `root`, as they are now. */
+export function sidecarSnapshot(root) {
+  const sidecars = {};
+  for (const entry of readdirSync(root, { recursive: true })) {
+    if (entry.endsWith('.commands')) {
+      sidecars[entry] = readFileSync(join(root, entry), 'utf8');
+    }
+  }
+  return {
+    sidecars, // data, not a closure: part of the config ESLint's cache hashes
+    declaredCommands(sourceCode, file) {
+      const path = sidecarPathFor(file.physicalFilename);
+      const text = sidecars[relative(root, path)];
+      return text === undefined ? [] : parseSidecar(text, relative(file.cwd, path));
+    },
+  };
+}
+```
+
+Bind it with `declarationConvention: sidecarSnapshot(import.meta.dirname)` in `eslint.config.js`.
+The trade-off: the snapshot is taken when the config loads, so a long-running integration, such as
+an editor's ESLint server, keeps using it until it reloads the config. Both behaviors, the stale
+cache and the snapshot that invalidates it, are tested in this package's test suite.
+
+## Reading the convention in your own rule
+
+`sh/no-undeclared-commands` and `sh/no-unused-declarations` are the built-in rules that read the
+bound convention. A rule of your own reads it through the same two functions from
+`@eslint-sh/eslint-plugin`, so it gets the same behavior without re-implementing it:
+
+- **`resolveDeclarationConvention(context)`**, from `create()`, returns the convention from the
+  rule's own `declarationConvention` option, else from `settings.sh.declarationConvention`, else
+  `null`. With `null`, return no listeners: there is nothing to check. A bound value that isn't a
+  convention throws the configuration error the built-in rules throw, naming the setting:
+  `Invalid settings.sh.declarationConvention: expected a declaration convention`, and so on.
+- **`readDeclaredCommands(convention, context)`**, from a listener, returns the declarations for
+  the file `context` is linting. It hands the convention the `LintedFile`, so a sidecar
+  convention works in your rule too, and it checks every declaration exactly as the built-in
+  rules do. A missing or unknown `kind`, a missing field, or a `range` outside the text throws
+  `Invalid settings.sh.declarationConvention: …`. Don't call `convention.declaredCommands` directly: you would get unchecked
+  values.
+- Only in-script declarations have a `range`. Check `kind` before reading it: a declaration with
+  `kind` `'file'` or `'described'` lives somewhere your rule can't point at.
+
+This rule reports a declaration that is out of alphabetical order, under whichever convention the
+project binds. It is the shipped file
+[`examples/sorted-declarations-rule.mjs`](./examples/sorted-declarations-rule.mjs), and
+this package's test suite runs it in CI with both `commentPragma` and the
+`# @dep` convention above.
+
+```mjs
+/**
+ * A rule of your own that reads the bound declaration convention: it reports
+ * a declaration that is out of alphabetical order. From
+ * `../declaration-conventions.md`, and run in CI.
+ */
+import {
+  defineShellRule,
+  readDeclaredCommands,
+  resolveDeclarationConvention,
+} from '@eslint-sh/eslint-plugin';
+
+const sortedDeclarations = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    schema: [],
+    messages: { unsorted: 'Declare `{{name}}` before `{{previous}}`.' },
+  },
+  create(context) {
+    // The bound convention, checked exactly as the built-in rules check it;
+    // `null` when none is bound, and then the rule has nothing to check.
+    const convention = resolveDeclarationConvention(context);
+    if (convention === null) {
+      return {};
+    }
+    return {
+      File() {
+        const { sourceCode } = context;
+        // The file's declarations, checked as the built-in rules check them.
+        // Only those written in the script have a range to report at.
+        const declared = readDeclaredCommands(convention, context).filter(
+          (each) => each.kind === 'script',
+        );
+        for (let i = 1; i < declared.length; i++) {
+          const previous = declared[i - 1].name;
+          const { name, range } = declared[i];
+          if (name < previous) {
+            context.report({
+              loc: {
+                start: sourceCode.getLocFromIndex(range[0]),
+                end: sourceCode.getLocFromIndex(range[1]),
+              },
+              messageId: 'unsorted',
+              data: { name, previous },
+            });
+          }
+        }
+      },
+    };
+  },
+});
+
+export default sortedDeclarations;
+```
+
+With `commentPragma` bound, `# uses: jq curl` reports `curl`: `` Declare `curl` before `jq`. ``
+`defineShellRule` and writing rules in general are covered in the [custom-rule
+tutorial](./custom-rule-tutorial.md).

package/docs/examples/audit-wrapper-pack.mjs

@@ -0,0 +1,15 @@
+/**
+ * A rule pack that requires infrastructure CLIs to be run through its
+ * `audit-run` wrapper. From `../wrapper-rules.md`, and run in CI.
+ */
+import { createWrapperRule } from '@eslint-sh/eslint-plugin';
+
+const requireAudit = createWrapperRule({
+  commands: ['kubectl', 'terraform'],
+  wrapper: { names: ['audit-run'], argFlags: ['--ticket'] },
+  subcommands: {
+    terraform: { names: ['apply', 'destroy'], noArgFlags: ['-no-color'] },
+  },
+});
+
+export default { rules: { 'require-audit': requireAudit } };

package/docs/examples/dep-line-convention.mjs

@@ -0,0 +1,22 @@
+/**
+ * A custom declaration convention: each dependency is declared on its own
+ * `# @dep <name>` line. From `../declaration-conventions.md`, and run in CI.
+ */
+const depLines = {
+  declaredCommands(sourceCode) {
+    const declared = [];
+    for (const match of sourceCode.text.matchAll(/^# @dep (\S+)[ \t]*$/gmu)) {
+      const start = match.index + '# @dep '.length;
+      declared.push({ kind: 'script', name: match[1], range: [start, start + match[1].length] });
+    }
+    return declared;
+  },
+  removeDeclaration(sourceCode, declared, fixer) {
+    const { text } = sourceCode;
+    const lineStart = text.lastIndexOf('\n', declared.range[0]) + 1;
+    const newline = text.indexOf('\n', declared.range[1]);
+    return fixer.removeRange([lineStart, newline === -1 ? text.length : newline + 1]);
+  },
+};
+
+export default depLines;

package/docs/examples/eslint.config.mjs

@@ -1,7 +1,7 @@
 // eslint.config.mjs
 //
 // The custom-rule tutorial's exact flat-config wiring
-// (`../custom-rule-tutorial.md`, step 3). `test/custom-rule-tutorial.test.ts`
+// (`../custom-rule-tutorial.md`, step 3). This package's test suite
 // imports this file's default export directly and runs it through a real
 // `eslint` `Linter.verify()` — not a reconstruction of this shape — so the
 // documented wiring is genuinely tested.
@@ -10,7 +10,8 @@ import noRmRf from './no-rm-rf-rule.mjs';
 
 export default [
   {
-    files: ['**/*.sh', '**/*.bash'],
+    // Extensionless scripts need `bin/?*`: ESLint never lints a file matched only by `bin/*` or `bin/**`.
+    files: ['**/*.sh', '**/*.bash', 'bin/?*'],
     plugins: {
       sh,
       'my-rules': { rules: { 'no-rm-rf': noRmRf } },

package/docs/examples/no-and-or-as-if-rule.mjs

@@ -0,0 +1,61 @@
+/**
+ * The "report on an operator" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 6). Plain, directly-runnable
+ * JavaScript; this package's test suite imports this exact file and
+ * asserts the tutorial's code fence matches it byte-for-byte.
+ *
+ * It reports `A && B || C`, which reads like if-then-else but is not: `C`
+ * also runs when `A` succeeds and `B` fails. The report sits on the `&&`
+ * itself. The lint view has no operator positions, so the rule reads the
+ * original sh-ast record with `getSyntax` and converts its byte position
+ * `OpPos` to ESLint coordinates with `getIndexFromSyntaxPos` and
+ * `getLocFromSyntaxPos`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noAndOrAsIf = defineShellRule({
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow `A && B || C` used as if-then-else',
+    },
+    schema: [],
+    messages: {
+      andOr: '`A && B || C` is not if-then-else: C also runs when B fails. Use `if A; then B; else C; fi`.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+
+    /** The two-character operator a `BinaryCmd` record's `OpPos` points at. */
+    const operatorOf = (binaryCmd) => {
+      const start = sourceCode.getIndexFromSyntaxPos(binaryCmd.OpPos);
+      return sourceCode.text.slice(start, start + 2);
+    };
+
+    return {
+      BinaryCmd(node) {
+        // `a && b || c` parses as `(a && b) || c`: the `||` command's left
+        // statement holds the `&&` command.
+        const or = sourceCode.getSyntax(node);
+        const and = or.X?.Cmd;
+        if (operatorOf(or) !== '||' || and?.Type !== 'BinaryCmd' || operatorOf(and) !== '&&') {
+          return;
+        }
+
+        const start = sourceCode.getIndexFromSyntaxPos(and.OpPos);
+        context.report({
+          loc: {
+            start: sourceCode.getLocFromSyntaxPos(and.OpPos),
+            end: sourceCode.getLocFromIndex(start + 2),
+          },
+          messageId: 'andOr',
+        });
+      },
+    };
+  },
+});
+
+export default noAndOrAsIf;