@eslint-sh/eslint-plugin 0.1.0

package/docs/selectors.md

@@ -0,0 +1,89 @@
+# Selector cookbook
+
+`@eslint-sh/eslint-plugin` registers `ShellLanguage.matchesSelectorClass`, which lets ESLint's
+[esquery](https://github.com/estools/esquery)-based rule selectors use six shorthand **launch
+classes** against shell ASTs, in addition to matching bare node type names
+(`CallExpr`, `IfClause`, ...). Selector-first rule authoring — writing a rule as a selector string
+rather than a `create()` full of manual type checks — is a headline feature of this plugin; this
+page is a copy-paste cookbook of real selectors, each backed by a passing test (see
+`test/selectors-cookbook.test.ts`) so the examples can't silently rot as the plugin evolves.
+
+Looking for a complete, runnable `create()` that uses one of these selectors — the full
+`{ meta, create(context) }` rule module, `context.report`, and the `eslint.config.mjs`
+`plugins`/`rules`/`language` wiring? See the [custom-rule tutorial](./custom-rule-tutorial.md).
+
+## The six launch classes
+
+| Class          | Matches                                             |
+| -------------- | ---------------------------------------------------- |
+| `:command`     | `CallExpr`                                          |
+| `:loop`        | `ForClause`, `WhileClause`                          |
+| `:conditional` | `IfClause`, `CaseClause`                            |
+| `:expansion`   | `ParamExp`, `CmdSubst`, `ArithmExp`, `ProcSubst`     |
+| `:quoted`      | `SglQuoted`, `DblQuoted`                            |
+| `:function`    | `FuncDecl`                                          |
+
+`:loop` deliberately does **not** include `CStyleLoop` — that node is `ForClause.loop`'s nested
+C-style arithmetic header (`init`/`cond`/`post`), not a loop statement in its own right. A
+`for ((i=0;i<3;i++))` loop's outer node is still `ForClause`, so `:loop` already reaches it.
+
+## Recipes
+
+### Match a specific command by name
+
+```
+CallExpr[args.0.parts.0.value='jq']
+```
+
+`args.0` is the command word (the first argument of a `CallExpr` is the command name itself, not
+a separate field); `.parts.0.value` reaches that word's first literal part. This is the pattern
+behind rules like "forbid calling `curl` directly, use the wrapped helper instead."
+
+### Match every command nested inside a function
+
+```
+:function :command
+```
+
+A descendant combinator: any `CallExpr` that has a `FuncDecl` ancestor. Useful for rules that only
+apply to commands run from within a shell function (e.g. "functions must not shell out to `sudo`").
+
+### Match every command nested inside a conditional
+
+```
+:conditional :command
+```
+
+Same shape as above, but for `IfClause`/`CaseClause` ancestors — matches commands in both the
+condition and the branch bodies of an `if`/`case`.
+
+### Match unquoted expansions
+
+```
+:expansion:not(DblQuoted :expansion)
+```
+
+A compound selector: match any of the four expansion node types, but reject the ones that also
+have a `DblQuoted` ancestor. `echo $foo "$bar"` — this matches `$foo` (unquoted) but not the
+`$bar` inside the double-quoted word, which is exactly the risky, word-splitting/glob-expanding
+case most "quote your variables" lint rules care about.
+
+### Match a function declaration by name
+
+```
+FuncDecl[name.value='deploy']
+```
+
+`FuncDecl.name` is the declared function's identifier (a `Lit` node); this pattern targets a rule
+at one specific, by-convention-named function (e.g. a project's `deploy` entrypoint) rather than
+every function.
+
+### Match any of the six launch classes at once
+
+```
+:command, :loop, :conditional, :expansion, :quoted, :function
+```
+
+esquery's top-level comma is an OR across selectors — useful for a single rule that reports on
+"anything selector-class-worthy" (for example, a rule collecting a script's shape/complexity
+metrics across all six categories in one listener instead of six).

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@eslint-sh/eslint-plugin",
+  "description": "Shell script parsing and syntax-error reporting for ESLint, with custom-rule authoring over a typed shell AST, backed by sh-ast.",
+  "version": "0.1.0",
+  "author": "Mike North <michael.l.north@gmail.com>",
+  "dependencies": {
+    "@eslint/core": "^1.2.1",
+    "@eslint/plugin-kit": "^0.7.2",
+    "sh-ast": "^0.1.0"
+  },
+  "devDependencies": {
+    "eslint": "^10.7.0"
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/eslint-plugin.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "nx": {
+    "targets": {
+      "build": {
+        "outputs": [
+          "{projectRoot}/dist/**/*.js",
+          "{projectRoot}/dist/**/*.js.map",
+          "{projectRoot}/dist/**/*.d.ts",
+          "{projectRoot}/dist/**/*.d.ts.map",
+          "!{projectRoot}/dist/eslint-plugin.d.ts"
+        ]
+      },
+      "check:api-report": {
+        "outputs": [
+          "{projectRoot}/api-report",
+          "{projectRoot}/temp",
+          "{projectRoot}/dist/eslint-plugin.d.ts"
+        ]
+      },
+      "uplevel-api-reports": {
+        "dependsOn": [
+          "check:api-report"
+        ],
+        "cache": true,
+        "inputs": [
+          "{projectRoot}/api-report/**",
+          "{projectRoot}/temp/**"
+        ],
+        "outputs": [
+          "{workspaceRoot}/api-report-combined/eslint-plugin.api.md",
+          "{workspaceRoot}/api-docs-temp/eslint-plugin.api.json"
+        ]
+      }
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "types": "./dist/eslint-plugin.d.ts",
+  "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\"",
+    "check:api-report": "api-extractor run",
+    "check:lint-ts": "eslint .",
+    "check:typecheck": "tsc --noEmit",
+    "clean": "rimraf --glob dist \"temp/*\" \"*.tsbuildinfo\"",
+    "fix:api-report": "api-extractor run --local",
+    "fix:lint-ts": "eslint . --fix",
+    "test": "vitest run",
+    "uplevel-api-reports": "mkdir -p ../../api-report-combined ../../api-docs-temp && cp api-report/eslint-plugin.api.md ../../api-report-combined/ && cp temp/eslint-plugin.api.json ../../api-docs-temp/"
+  }
+}