eslint-sh 0.1.0 → 0.1.1

package/README.md

@@ -3,24 +3,17 @@
 Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a
 typed shell AST.
 
+This is the canonical quickstart for the `eslint-sh` / `@eslint-sh/eslint-plugin` project — start
+here regardless of which of the two packages you install.
+
 **Roadmap:** built-in lint rules and shared configs are planned but not implemented yet.
 
 ## Installation
 
-This package is not yet published. Once it is, install it as a dev dependency:
-
 ```sh
 npm install --save-dev eslint-sh
 ```
 
-## `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 ...`.       |
-
 ## Usage
 
 This release reports shell syntax (parse) errors only — no lint rules ship yet, so a "0 problems"
@@ -41,13 +34,43 @@ export default defineConfig([
 ]);
 ```
 
+## `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 ...`.       |
+
+## 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.
+- **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.
+- **Setting `shellVersion` doesn't change anything.** That's expected today — see the
+  `languageOptions` reference table above: `shellVersion` is reserved for a future rule layer and
+  has no effect on parsing while no lint rules ship.
+- **`# eslint-disable-next-line ...` comments don't seem to do anything.** No lint rules ship yet
+  in this release, so there's nothing for a disable comment to suppress until you register a
+  custom rule (see the `@eslint-sh/eslint-plugin` README's "Writing your own rules" section). If
+  you've registered a custom rule and the directive still isn't recognized, check
+  `languageOptions.directivePrefix` — it must match the prefix your comment uses (the default
+  `"eslint"` only recognizes `# eslint-disable-next-line ...`, not a custom prefix).
+
 ## Status
 
 Thin umbrella re-exporting `@eslint-sh/eslint-plugin`'s plugin object unchanged as this
 package's default export — `import sh from "eslint-sh"` and `import sh from "@eslint-sh/eslint-plugin"`
 refer to the same object. `@eslint-sh/eslint-plugin` currently ships `ShellLanguage`/
 `ShellSourceCode` only; rules and shared configs are not implemented yet. Disable directives /
-inline config are implemented and live. No lint rules ship yet, so the rule id is illustrative:
-after you register a custom rule as `sh/your-rule`,
-`# eslint-disable-next-line sh/your-rule -- justification` suppresses it on the following line;
-see `@eslint-sh/eslint-plugin`'s README for the full directive surface.
+inline config are implemented and live. No lint rules ship yet, so the rule id in the
+troubleshooting section above is illustrative: after you register a custom rule as
+`sh/your-rule`, `# eslint-disable-next-line sh/your-rule -- justification` suppresses it on the
+following line.
+
+For the plugin's public API reference (types, exports, selector cookbook, and a custom-rule
+authoring tutorial), see the `@eslint-sh/eslint-plugin` package's README.

package/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.1.0",
+  "version": "0.1.1",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
-    "@eslint-sh/eslint-plugin": "0.1.0"
+    "@eslint-sh/eslint-plugin": "0.1.1"
   },
   "devDependencies": {
     "eslint": "^10.7.0"