eslint-sh 0.2.0 → 0.4.0

package/README.md

@@ -10,6 +10,9 @@ here regardless of which of the two packages you install.
 
 ## 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):
+
 ```sh
 npm install --save-dev eslint-sh
 ```
@@ -34,23 +37,109 @@ export default defineConfig([
 ]);
 ```
 
+`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`.
+
 ## `languageOptions` reference
 
-| Option            | Allowed values                                                          | Default    | Effect                                                                                                                            |
-| ----------------- | ----------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `dialect`         | `"bash"`, `"posix"`, `"mksh"`, `"bats"`, `"zsh"`                        | `"bash"`   | Selects which shell grammar the parser accepts; parsing a construct outside the chosen dialect produces a parse error.            |
-| `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. |
-| `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 ...`.       |
+| 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.                                                                                                                                                                                                                                          |
+| `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 ...`.                                                                                                                                                                                                                                                |
 
 ## Troubleshooting
 
-- **ESLint doesn't seem to look at my `.sh`/`.bash` files at all.** Confirm the config object's
-  `files` glob actually matches them, and that `language: 'sh/sh'` is set alongside
-  `plugins: { sh }` — without both, ESLint won't route the file through this plugin's language.
+Every worked example below (config, script, and error output) is extracted straight out of this
+file and run through a real `eslint` `Linter` in CI — see
+`packages/eslint-plugin/test/troubleshooting-examples.test.ts` — so these examples can't drift
+from what the plugin actually does.
+
+- **Getting `Parsing error: Unexpected token` or `Unexpected key "dialect"` on shell files.**
+  Both errors mean the config object is missing `language: 'sh/sh'` — without it, ESLint doesn't
+  route the file through this plugin's language at all, even if `plugins: { sh }` and
+  `files` are set correctly. There are two ways this shows up, depending on whether
+  `languageOptions` is also present:
+  - **No `languageOptions` set:** ESLint falls back to its default JS parser on the shell file,
+    which fails on shell syntax with no mention of eslint-sh at all. Given this config:
+
+    ```js
+    export default [{ files: ['**/*.sh'], plugins: { sh } }];
+    ```
+
+    linting this script:
+
+    ```sh
+    if [[ "$1" == "foo" ]]; then echo matched; fi
+    ```
+
+    produces:
+
+    ```text
+    Parsing error: Unexpected token [
+    ```
+
+  - **`languageOptions` is set (e.g. `{ dialect: 'bash' }`) but `language` is not:** ESLint
+    validates `languageOptions` against its own built-in JS language schema (since no shell
+    `language` was selected to own that key), which doesn't recognize `dialect`. Given this
+    config:
+
+    ```js
+    export default [{ files: ['**/*.sh'], plugins: { sh }, languageOptions: { dialect: 'bash' } }];
+    ```
+
+    linting the same script:
+
+    ```sh
+    if [[ "$1" == "foo" ]]; then echo matched; fi
+    ```
+
+    throws:
+
+    ```text
+    TypeError: Key "languageOptions": Unexpected key "dialect" found.
+    ```
+
+  The fix for both is the same one-line addition: set `language: 'sh/sh'` alongside
+  `plugins: { sh }` in the config object.
+
 - **A script I believe is valid reports a parse error.** The parser is dialect-sensitive: a
-  construct that's valid in one shell grammar (e.g. `[[ ... ]]` in bash) is a parse error in
-  another (e.g. `posix`). Set `languageOptions.dialect` to match the shell the script is actually
-  written for.
+  construct that's valid in one shell grammar may be rejected in another. Given this config:
+
+  ```js
+  export default [
+    {
+      files: ['**/*.sh'],
+      plugins: { sh },
+      language: 'sh/sh',
+      languageOptions: { dialect: 'posix' },
+    },
+  ];
+  ```
+
+  linting this script (a bash array literal):
+
+  ```sh
+  arr=(1 2 3)
+  ```
+
+  produces:
+
+  ```text
+  Parsing error: arrays are a bash/mksh/zsh feature; tried parsing as posix
+  ```
+
+  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
+  [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.
@@ -60,6 +149,17 @@ export default defineConfig([
   you've registered a custom rule and 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
+  a disable comment (e.g. `# eslint-disable-next-line sh/typo-d-rule`) is a lint-time error, not a
+  silent no-op: ESLint reports `Definition for rule '<rule-id>' was not found.` at the directive's
+  location. Double-check the rule id against the name you registered it under (the `plugins`
+  namespace plus the rule key, e.g. `sh/your-rule`).
+- **`TypeError: Key "language": Could not find "..." in plugin "sh".`** A typo in the
+  `language` value (e.g. `language: 'sh/shell'` instead of the registered `language: 'sh/sh'`).
+  This error is thrown by ESLint core itself (`Config`'s constructor), before any of this
+  plugin's own code runs, and does not currently enumerate the plugin's actually-registered
+  language ids in its message (current ESLint 10.x behavior). This plugin registers exactly one
+  language: `sh` (selected as `language: 'sh/sh'`).
 
 ## Status
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import sh from '@eslint-sh/eslint-plugin';
 /**
- * `eslint-sh` — the unscoped umbrella package (design/PACKAGES.md's Naming
- * decision). Re-exports `@eslint-sh/eslint-plugin`'s plugin object
+ * `eslint-sh` — the unscoped umbrella package. Re-exports
+ * `@eslint-sh/eslint-plugin`'s plugin object
  * unchanged as this package's default export, so `import sh from
  * "eslint-sh"` and `import sh from "@eslint-sh/eslint-plugin"` are
  * equivalent.

package/dist/index.js

@@ -1,7 +1,7 @@
 import sh from '@eslint-sh/eslint-plugin';
 /**
- * `eslint-sh` — the unscoped umbrella package (design/PACKAGES.md's Naming
- * decision). Re-exports `@eslint-sh/eslint-plugin`'s plugin object
+ * `eslint-sh` — the unscoped umbrella package. Re-exports
+ * `@eslint-sh/eslint-plugin`'s plugin object
  * unchanged as this package's default export, so `import sh from
  * "eslint-sh"` and `import sh from "@eslint-sh/eslint-plugin"` are
  * equivalent.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "eslint-sh",
   "description": "Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a typed shell AST",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
-    "@eslint-sh/eslint-plugin": "0.2.0"
+    "@eslint-sh/eslint-plugin": "0.4.0"
   },
   "devDependencies": {
     "eslint": "^10.7.0"
@@ -53,6 +53,11 @@
   },
   "type": "module",
   "types": "./dist/eslint-sh.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mike-north/eslint-sh.git",
+    "directory": "packages/eslint-sh"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check": "concurrently -n lint,types,api-report \"pnpm run check:lint-ts\" \"pnpm run check:typecheck\" \"pnpm run check:api-report\"",