eslint-sh 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +90 -11
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -36,21 +36,100 @@ export default defineConfig([
36
36
 
37
37
  ## `languageOptions` reference
38
38
 
39
- | Option | Allowed values | Default | Effect |
40
- | ----------------- | ----------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
41
- | `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. |
42
- | `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. |
43
- | `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 ...`. |
39
+ | Option | Allowed values | Default | Effect |
40
+ | ----------------- | ----------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `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/pull/28). |
42
+ | `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. |
43
+ | `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 ...`. |
44
44
 
45
45
  ## Troubleshooting
46
46
 
47
- - **ESLint doesn't seem to look at my `.sh`/`.bash` files at all.** Confirm the config object's
48
- `files` glob actually matches them, and that `language: 'sh/sh'` is set alongside
49
- `plugins: { sh }` — without both, ESLint won't route the file through this plugin's language.
47
+ Every worked example below (config, script, and error output) is extracted straight out of this
48
+ file and run through a real `eslint` `Linter` in CI — see
49
+ `packages/eslint-plugin/test/troubleshooting-examples.test.ts` — so these examples can't drift
50
+ from what the plugin actually does.
51
+
52
+ - **Getting `Parsing error: Unexpected token` or `Unexpected key "dialect"` on shell files.**
53
+ Both errors mean the config object is missing `language: 'sh/sh'` — without it, ESLint doesn't
54
+ route the file through this plugin's language at all, even if `plugins: { sh }` and
55
+ `files` are set correctly. There are two ways this shows up, depending on whether
56
+ `languageOptions` is also present:
57
+ - **No `languageOptions` set:** ESLint falls back to its default JS parser on the shell file,
58
+ which fails on shell syntax with no mention of eslint-sh at all. Given this config:
59
+
60
+ ```js
61
+ export default [{ files: ['**/*.sh'], plugins: { sh } }];
62
+ ```
63
+
64
+ linting this script:
65
+
66
+ ```sh
67
+ if [[ "$1" == "foo" ]]; then echo matched; fi
68
+ ```
69
+
70
+ produces:
71
+
72
+ ```text
73
+ Parsing error: Unexpected token [
74
+ ```
75
+
76
+ - **`languageOptions` is set (e.g. `{ dialect: 'bash' }`) but `language` is not:** ESLint
77
+ validates `languageOptions` against its own built-in JS language schema (since no shell
78
+ `language` was selected to own that key), which doesn't recognize `dialect`. Given this
79
+ config:
80
+
81
+ ```js
82
+ export default [{ files: ['**/*.sh'], plugins: { sh }, languageOptions: { dialect: 'bash' } }];
83
+ ```
84
+
85
+ linting the same script:
86
+
87
+ ```sh
88
+ if [[ "$1" == "foo" ]]; then echo matched; fi
89
+ ```
90
+
91
+ throws:
92
+
93
+ ```text
94
+ TypeError: Key "languageOptions": Unexpected key "dialect" found.
95
+ ```
96
+
97
+ The fix for both is the same one-line addition: set `language: 'sh/sh'` alongside
98
+ `plugins: { sh }` in the config object.
99
+
50
100
  - **A script I believe is valid reports a parse error.** The parser is dialect-sensitive: a
51
- construct that's valid in one shell grammar (e.g. `[[ ... ]]` in bash) is a parse error in
52
- another (e.g. `posix`). Set `languageOptions.dialect` to match the shell the script is actually
53
- written for.
101
+ construct that's valid in one shell grammar may be rejected in another. Given this config:
102
+
103
+ ```js
104
+ export default [
105
+ {
106
+ files: ['**/*.sh'],
107
+ plugins: { sh },
108
+ language: 'sh/sh',
109
+ languageOptions: { dialect: 'posix' },
110
+ },
111
+ ];
112
+ ```
113
+
114
+ linting this script (a bash array literal):
115
+
116
+ ```sh
117
+ arr=(1 2 3)
118
+ ```
119
+
120
+ produces:
121
+
122
+ ```text
123
+ Parsing error: arrays are a bash/mksh/zsh feature; tried parsing as posix
124
+ ```
125
+
126
+ Set `languageOptions.dialect` to match the shell the script is actually written for. Note that
127
+ dialect enforcement is partial by design: some bash-isms — notably `[[ ... ]]` and `let` — are
128
+ not parse errors under `dialect: 'posix'`; they silently parse as ordinary commands instead, so
129
+ a clean `posix` run does not by itself prove a script is POSIX-compliant. See the
130
+ [per-dialect construct enforcement audit](https://github.com/mike-north/sh-ast/pull/28) in
131
+ `sh-ast` for the full accept/reject matrix and rationale.
132
+
54
133
  - **Setting `shellVersion` doesn't change anything.** That's expected today — see the
55
134
  `languageOptions` reference table above: `shellVersion` is reserved for a future rule layer and
56
135
  has no effect on parsing while no lint rules ship.
package/package.json CHANGED
@@ -1,10 +1,10 @@
1
1
  {
2
2
  "name": "eslint-sh",
3
3
  "description": "Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a typed shell AST",
4
- "version": "0.2.0",
4
+ "version": "0.3.0",
5
5
  "author": "Mike North <michael.l.north@gmail.com>",
6
6
  "dependencies": {
7
- "@eslint-sh/eslint-plugin": "0.2.0"
7
+ "@eslint-sh/eslint-plugin": "0.3.0"
8
8
  },
9
9
  "devDependencies": {
10
10
  "eslint": "^10.7.0"