@eslint-sh/eslint-plugin 0.5.0 → 0.6.0

package/docs/examples/no-backticks-rule-tester.mjs

@@ -0,0 +1,106 @@
+/**
+ * The "test your rule" example from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 11). It tests the step 8 rule
+ * (`./no-backticks-rule.mjs`) with ESLint's own `RuleTester`, and a small
+ * inline rule that offers a suggestion rather than an automatic fix.
+ *
+ * `RuleTester` needs two settings to run shell rules: the plugin registered
+ * under `plugins`, and `language: 'sh/sh'`. Leaving either out
+ * makes `RuleTester` throw a configuration error before it checks any case;
+ * the tutorial quotes both messages.
+ *
+ * Run it with `node no-backticks-rule-tester.mjs`. `RuleTester` uses
+ * `describe`/`it` when the test runner defines them, and otherwise throws on
+ * the first failing case, so a quiet exit means every case passed.
+ *
+ * This file and `./no-backticks-rule.mjs` ship in the `@eslint-sh/eslint-plugin`
+ * package only (`docs/examples/`); the umbrella `eslint-sh` package does not
+ * include them. To import from the umbrella instead, change the plugin import
+ * below and the one in `./no-backticks-rule.mjs` to `eslint-sh`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this example backs
+ * @see https://eslint.org/docs/latest/integrate/nodejs-api#ruletester
+ */
+import { RuleTester } from 'eslint';
+import sh, { defineShellRule } from '@eslint-sh/eslint-plugin';
+import noBackticks from './no-backticks-rule.mjs';
+
+const tester = new RuleTester({
+  plugins: { sh },
+  language: 'sh/sh',
+});
+
+tester.run('no-backticks', noBackticks, {
+  valid: [
+    // An empty file, and a command substitution that already uses `$(…)`.
+    { code: '' },
+    { code: 'now=$(date +%s)\n' },
+  ],
+  invalid: [
+    {
+      code: 'now=`date +%s`\n',
+      // `messageId` checks which message fired; `line` and `column` check where.
+      errors: [{ messageId: 'backticks', line: 1, column: 5 }],
+      // `output` is the file after ESLint applies the fix.
+      output: 'now=$(date +%s)\n',
+    },
+    {
+      // Multibyte text before and inside the substitutions.
+      code: 'echo "héllo `id -u` 🎉" `date`\n',
+      errors: [{ messageId: 'backticks' }, { messageId: 'backticks' }],
+      output: 'echo "héllo $(id -u) 🎉" $(date)\n',
+    },
+  ],
+});
+
+/**
+ * A rule that only suggests: it reports `which` and offers `command -v`, which
+ * the reader chooses to apply. A rule with suggestions declares
+ * `hasSuggestions: true`.
+ */
+const noWhich = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    hasSuggestions: true,
+    docs: { description: 'prefer `command -v` over `which`' },
+    schema: [],
+    messages: {
+      noWhich: '`which` is not portable.',
+      useCommandV: 'Use `command -v` instead.',
+    },
+  },
+  create(context) {
+    return {
+      CallExpr(node) {
+        const [name] = node.args ?? [];
+        if (name === undefined || context.sourceCode.getText(name) !== 'which') {
+          return;
+        }
+        context.report({
+          node: name,
+          messageId: 'noWhich',
+          suggest: [
+            { messageId: 'useCommandV', fix: (fixer) => fixer.replaceText(name, 'command -v') },
+          ],
+        });
+      },
+    };
+  },
+});
+
+tester.run('no-which', noWhich, {
+  valid: [{ code: 'command -v ls\n' }],
+  invalid: [
+    {
+      code: 'which ls\n',
+      // `output: null` asserts that the rule has no automatic fix.
+      output: null,
+      errors: [
+        {
+          messageId: 'noWhich',
+          suggestions: [{ messageId: 'useCommandV', output: 'command -v ls\n' }],
+        },
+      ],
+    },
+  ],
+});

package/docs/examples/no-backticks-rule.mjs

@@ -0,0 +1,60 @@
+/**
+ * The "printed fix" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 8). 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 backtick command substitution (`` `date` ``) and fixes it to
+ * `$(date)`. Instead of rewriting text by hand, which would have to re-escape
+ * nested backticks and backslashes, the fix edits a copy of the substitution's
+ * sh-ast record from `getEditableSyntax` and lets sh-ast's printer write the
+ * new text with `getPrintedReplacement`. The original syntax every other rule
+ * reads stays unchanged.
+ *
+ * @import { PrintOptions } from '@eslint-sh/eslint-plugin/syntax'
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+/**
+ * Prints nested lines with two spaces per level instead of the printer's
+ * default tabs.
+ * @type {PrintOptions}
+ */
+const printOptions = { Indent: 2 };
+
+const noBackticks = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description: 'prefer `$(…)` over backtick command substitution',
+    },
+    schema: [],
+    messages: {
+      backticks: 'Use `$(…)` instead of backticks for command substitution.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+    return {
+      CmdSubst(node) {
+        if (!node.backquotes) {
+          return;
+        }
+        // An independent copy: editing it changes neither the lint view nor
+        // the syntax other rules read.
+        const copy = sourceCode.getEditableSyntax(node);
+        copy.Backquotes = false;
+        const { range, text } = sourceCode.getPrintedReplacement(node, copy, printOptions);
+        context.report({
+          node,
+          messageId: 'backticks',
+          fix: (fixer) => fixer.replaceTextRange(range, text),
+        });
+      },
+    };
+  },
+});
+
+export default noBackticks;

package/docs/examples/no-curl-in-functions-rule.mjs

@@ -0,0 +1,53 @@
+/**
+ * The "every command in the file" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 5). 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 `curl` run anywhere inside a shell function, including through a
+ * wrapper (`sudo curl …`) or inside a command substitution in that function.
+ * Instead of tracking "am I inside a function?" while visiting nodes, it reads
+ * every command once from `context.sourceCode.getCommandSites()`, whose
+ * `context` frames (outermost first) already say how each command is reached.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noCurlInFunctions = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'disallow `curl` inside shell functions',
+    },
+    schema: [],
+    messages: {
+      curlInFunction: 'Function `{{name}}` runs `curl`; fetch data before calling it.',
+    },
+  },
+  create(context) {
+    return {
+      File() {
+        for (const site of context.sourceCode.getCommandSites()) {
+          const { effective } = site.resolveInvokedCommand();
+          if (!effective.static || effective.text !== 'curl') {
+            continue;
+          }
+
+          // Frames run outermost first, so the last `function` frame is the
+          // function that directly contains this command.
+          const fn = site.context.findLast((frame) => frame.kind === 'function');
+          if (fn) {
+            context.report({
+              node: site.node,
+              messageId: 'curlInFunction',
+              data: { name: fn.name },
+            });
+          }
+        }
+      },
+    };
+  },
+});
+
+export default noCurlInFunctions;

package/docs/examples/no-function-keyword-rule.mjs

@@ -0,0 +1,59 @@
+/**
+ * The "position-based text edit" custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 9). 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 the bash-only `function name {` form and fixes it to the
+ * portable `name() {`. The fix replaces only the text from the `function`
+ * keyword through the name, so the body keeps its exact layout, comments and
+ * all; printing the whole edited function would re-indent the body instead.
+ * The two ends of that text come from the sh-ast record's own positions,
+ * converted to string offsets with `getIndexFromSyntaxPos` (sh-ast positions
+ * count UTF-8 bytes).
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noFunctionKeyword = defineShellRule({
+  meta: {
+    type: 'suggestion',
+    fixable: 'code',
+    docs: {
+      description: 'prefer `name() { … }` over the `function` keyword',
+    },
+    schema: [],
+    messages: {
+      useParens: 'Declare `{{name}}` as `{{name}}() { … }`, without the `function` keyword.',
+    },
+  },
+  create(context) {
+    const { sourceCode } = context;
+    return {
+      FuncDecl(node) {
+        const decl = sourceCode.getSyntax(node);
+        // Only `function name {`: not `function name() {`, `name() {`, or
+        // zsh's several-name form.
+        if (!decl.RsrvWord || decl.Parens || decl.Name === null || decl.Names !== null) {
+          return;
+        }
+        // A name that is not valid UTF-8 arrives as bytes, not a string.
+        const name = decl.Name.Value;
+        if (typeof name !== 'string') {
+          return;
+        }
+        const start = sourceCode.getIndexFromSyntaxPos(decl.Position);
+        const end = sourceCode.getIndexFromSyntaxPos(decl.Name.ValueEnd);
+        context.report({
+          node,
+          messageId: 'useParens',
+          data: { name },
+          fix: (fixer) => fixer.replaceTextRange([start, end], `${name}()`),
+        });
+      },
+    };
+  },
+});
+
+export default noFunctionKeyword;

package/docs/examples/no-listed-commands-rule.ts

@@ -0,0 +1,63 @@
+/**
+ * The TypeScript custom rule from the custom-rule tutorial
+ * (`../custom-rule-tutorial.md`, step 10). This package's test suite
+ * asserts the tutorial's code fence matches this file byte-for-byte,
+ * type-checks it against the package's published declarations, and runs it
+ * through a real `eslint` `Linter`.
+ *
+ * It reports any command named in its `commands` option, including through a
+ * wrapper such as `sudo`. Every type comes from `@eslint-sh/eslint-plugin`:
+ * the options and message ids passed to `defineShellRule` flow into
+ * `context.options` and `context.report`, and `ShellRuleContext` types the
+ * helper that reports outside `create()`.
+ *
+ * @see ../custom-rule-tutorial.md — the tutorial this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+import type { ShellCommandSite, ShellRuleContext } from '@eslint-sh/eslint-plugin';
+
+/** The rule's one options object; `commands` defaults to `[]`. */
+type Options = [{ commands?: string[] }?];
+
+/** Reports `site` when the command it runs, after wrappers, is in `listed`. */
+function reportIfListed(
+  context: ShellRuleContext<Options, 'listed'>,
+  site: ShellCommandSite,
+  listed: ReadonlySet<string>,
+): void {
+  const { effective } = site.resolveInvokedCommand();
+  if (effective.static && listed.has(effective.text)) {
+    context.report({ node: site.node, messageId: 'listed', data: { name: effective.text } });
+  }
+}
+
+const noListedCommands = defineShellRule<Options, 'listed'>({
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'disallow the commands named in the `commands` option',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: { commands: { type: 'array', items: { type: 'string' } } },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      listed: '`{{name}}` is not allowed in this project.',
+    },
+  },
+  create(context) {
+    const listed = new Set(context.options[0]?.commands ?? []);
+    return {
+      File() {
+        for (const site of context.sourceCode.getCommandSites()) {
+          reportIfListed(context, site, listed);
+        }
+      },
+    };
+  },
+});
+
+export default noListedCommands;

package/docs/examples/no-rm-rf-rule.mjs

@@ -2,10 +2,13 @@
  * The complete "flag `rm -rf`" custom rule from the custom-rule tutorial
  * (`../custom-rule-tutorial.md`). Plain, directly-runnable JavaScript (no
  * compile step) — this file *is* the tutorial's rule-module code fence,
- * copy-paste-verbatim; `test/custom-rule-tutorial.test.ts` imports this
+ * copy-paste-verbatim; this package's test suite imports this
  * exact file (not a reconstruction) and asserts the markdown fence matches
  * it byte-for-byte, so the two can't silently drift.
  *
+ * Built with `defineShellRule`, which declares `meta.languages: ['sh/sh']`
+ * for it, so ESLint refuses to run the rule on a file of any other language.
+ *
  * Built on the `:command` launch class from the selector cookbook
  * (`../selectors.md`) — `:command` matches every `CallExpr`, so `create()`
  * narrows further by inspecting the command word and its flag arguments,
@@ -16,12 +19,16 @@
  *
  * Flag words are resolved with `@eslint-sh/eslint-plugin`'s view-aware
  * `resolveWord` (backed by `sh-ast/analyze`) rather than a
- * hand-rolled scan: a word is only ever treated as the literal text
- * `-rf`/`-fr` when it is *statically* that string (bare or quoted literal
- * concatenations); a word containing a `ParamExp`/`CmdSubst`/`ArithmExp`/
- * `ProcSubst` resolves to `null` ("unknown") rather than being silently
- * erased into a static match or a static non-match — the same static-word
- * contract `design/PACKAGES.md` documents for `resolveWordText`. Importing
+ * hand-rolled scan: a word is only treated as a short-option cluster
+ * when it is *statically* that string (bare or
+ * quoted literal concatenations). Recursive (`r`/`R`) and force (`f`)
+ * flags accumulate across words before `--`; uppercase `F` is not force.
+ * Options are matched anywhere before `--`, GNU-style, even after operands.
+ * This teaching example does not model long options or option precedence.
+ * A word containing a `ParamExp`/`CmdSubst`/`ArithmExp`/
+ * `ProcSubst` resolves to `{ static: false, reason }` (`'expansion'`,
+ * `'tilde'`, `'glob'`, …) rather than being silently erased into a static
+ * match — see `resolveWord`'s API docs. Importing
  * it from the plugin package (rather than `sh-ast/analyze` directly) means
  * a project that installs only `@eslint-sh/eslint-plugin` has everything
  * this rule needs, with no separate `sh-ast` install or npm-hoisting
@@ -30,13 +37,13 @@
  * @see ../custom-rule-tutorial.md — the tutorial this rule backs
  * @see ../selectors.md — the `:command` launch class
  */
-import { resolveWord } from '@eslint-sh/eslint-plugin';
+import { defineShellRule, resolveWord } from '@eslint-sh/eslint-plugin';
 
-const noRmRf = {
+const noRmRf = defineShellRule({
   meta: {
     type: 'problem',
     docs: {
-      description: 'disallow `rm -rf`/`rm -fr` invocations',
+      description: 'disallow recursive-force `rm` invocations',
     },
     schema: [],
     messages: {
@@ -62,11 +69,15 @@ const noRmRf = {
         const endOfOptions = words.indexOf('--');
         const flagCandidates = words.slice(1, endOfOptions === -1 ? undefined : endOfOptions);
 
-        const isRecursiveForce = flagCandidates.some(
-          (word) =>
-            word !== null &&
-            (/^-[a-z]*r[a-z]*f[a-z]*$/i.test(word) || /^-[a-z]*f[a-z]*r[a-z]*$/i.test(word)),
+        // Only static short-option clusters contribute flags; operands,
+        // long options, and unresolved words supply no evidence. Recursive
+        // and force may occur in the same word or in separate words.
+        const shortOptions = flagCandidates.filter(
+          (word) => word !== null && /^-[a-zA-Z]+$/.test(word),
         );
+        const hasRecursive = shortOptions.some((word) => /[rR]/.test(word));
+        const hasForce = shortOptions.some((word) => word.includes('f'));
+        const isRecursiveForce = hasRecursive && hasForce;
 
         if (isRecursiveForce) {
           context.report({ node, loc: node.loc, messageId: 'rmRf' });
@@ -74,6 +85,6 @@ const noRmRf = {
       },
     };
   },
-};
+});
 
 export default noRmRf;

package/docs/examples/no-unquoted-rm-variable-rule.ts

@@ -0,0 +1,54 @@
+/**
+ * The TypeScript example rule from "Reading nodes" (`../reading-nodes.md`).
+ * This package's test suite asserts the page's code fence matches this
+ * file byte-for-byte, type-checks it against the package's published
+ * declarations, and runs it, with its fix, through a real `eslint` `Linter`.
+ *
+ * It reports an `rm` argument that is a lone, unquoted variable (`rm -rf $dir`)
+ * and quotes it. Every field it reads is typed by `ShellNode`: narrowing on
+ * `type` is the only thing between a listener's node and its fields.
+ *
+ * @see ../reading-nodes.md — the page this rule backs
+ */
+import { defineShellRule } from '@eslint-sh/eslint-plugin';
+
+const noUnquotedRmVariable = defineShellRule({
+  meta: {
+    type: 'problem',
+    fixable: 'code',
+    docs: { description: 'require the variable operands of `rm` to be quoted' },
+    schema: [],
+    messages: {
+      unquoted: 'Quote `${{name}}`: unquoted, it is split and globbed before `rm` runs.',
+    },
+  },
+  create(context) {
+    return {
+      CallExpr(node) {
+        // A listener keyed by a node type receives that node type: `args`, `assigns`, … are typed.
+        if (context.sourceCode.getCommandName(node) !== 'rm') return;
+
+        // `args` is always an array of `Word`s (the command word first), never null.
+        for (const word of node.args.slice(1)) {
+          // A `Word` is a list of parts; a lone `$name` is a single `ParamExp` part.
+          const [part] = word.parts;
+          if (word.parts.length !== 1 || part.type !== 'ParamExp') continue;
+
+          context.report({
+            node: word,
+            messageId: 'unquoted',
+            // `param` is optional: a `ParamExp` with no name (rare) has no `param` child.
+            data: { name: part.param?.value ?? '' },
+            // `word.range` is the tuple ESLint's fixer methods take, so it needs no cast.
+            fix: (fixer) => [
+              fixer.insertTextBeforeRange(word.range, '"'),
+              fixer.insertTextAfterRange(word.range, '"'),
+            ],
+          });
+        }
+      },
+    };
+  },
+});
+
+export default noUnquotedRmVariable;

package/docs/examples/sidecar-convention.mjs

@@ -0,0 +1,38 @@
+/**
+ * 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;

package/docs/examples/sidecar-snapshot-convention.mjs

@@ -0,0 +1,26 @@
+/**
+ * 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));
+    },
+  };
+}

package/docs/examples/sorted-declarations-rule.mjs

@@ -0,0 +1,52 @@
+/**
+ * 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;