@eslint-sh/eslint-plugin 0.3.0 → 0.5.0

package/dist/language/syntax-view.js

@@ -0,0 +1,164 @@
+/**
+ * Projects faithful upstream syntax into the source view ESLint's selectors and
+ * fixers consume. Lowercase fields, UTF-16 spans, and synthetic auxiliary views
+ * are consumer conventions; the original syntax remains untouched and associated
+ * by identity. Bounds are observations of the original parse, tied to this exact
+ * source. This is neither upstream Walk nor a replacement syntax model.
+ */
+import { SYNTAX_INTERFACES, SYNTAX_SCHEMA } from 'sh-ast';
+import { SourceCoordinates } from './source-coordinates.js';
+/** Raw syntax is associated without adding parent cycles or consumer fields to its records. */
+const originalSyntax = new WeakMap();
+/** The upstream Node union distinguishes real nodes from auxiliary syntax records. */
+const nodeTypes = new Set(SYNTAX_INTERFACES.Node);
+/** Parser input is a JavaScript string; unexpected invalid-byte fields must never be silently replaced. */
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+/** ESLint child relationships follow the consumer projection, including auxiliary views; not upstream Walk ordering. @internal */
+export const shellVisitorKeys = Object.freeze(Object.fromEntries(Object.entries(SYNTAX_SCHEMA).map(([name, schema]) => [
+    name,
+    Object.freeze(Object.entries(schema.fields)
+        .filter(([, field]) => field.kind === 'struct' || field.kind === 'interface')
+        .map(([fieldName]) => fieldName.toLowerCase())),
+])));
+/** Checks record identity without pretending unknown transport values already have syntax types. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Parser-produced records with an upstream Node discriminator may use the faithful bounds operations. */
+function isSyntaxNode(value) {
+    return isRecord(value) && typeof value.Type === 'string' && nodeTypes.has(value.Type);
+}
+/** Identifies projected children without confusing raw position records or byte strings with nodes. @internal */
+export function isShellNode(value) {
+    return isRecord(value) && typeof value.type === 'string' && Array.isArray(value.range);
+}
+/** Directive processing requires both the comment kind and its decoded text. @internal */
+export function isShellComment(node) {
+    return node.type === 'Comment' && typeof node.text === 'string';
+}
+/** Recognizes the guaranteed root shape after projection without changing its associated identity. */
+function isShellFile(node) {
+    return node.type === 'File' && Array.isArray(node.stmts) && node.stmts.every(isShellNode);
+}
+/** Returns the actual parser node, or undefined for consumer-created/synthetic views. @internal */
+export function syntaxForNode(node) {
+    return originalSyntax.get(node);
+}
+/** Converts valid source-associated Go strings; invalid byte sequences have no faithful text view here. */
+function sourceText(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (value instanceof Uint8Array) {
+        return textDecoder.decode(value);
+    }
+    throw new TypeError('shell text view expected a Go string');
+}
+/**
+ * Builds a source-bound view immediately from one parse's File and Positions.
+ * Snapshot bounds describe that original parse, never subsequent syntax edits.
+ * A missing observation indicates a mismatched/incomplete snapshot and cannot be
+ * repaired by querying live syntax without reintroducing repeated subtree work.
+ * @internal
+ */
+export function adaptSyntaxFile(file, source, positions) {
+    if (!isRecord(positions) || typeof positions.get !== 'function') {
+        throw new TypeError('shell view requires a source position snapshot');
+    }
+    const coordinates = new SourceCoordinates(source);
+    const wholeSource = { start: coordinates.atIndex(0), end: coordinates.atIndex(source.length) };
+    /** Invalid/recovered positions have no exact text boundary; the enclosing view supplies an explicit consumer fallback. */
+    const position = (raw, fallback) => raw.IsValid && !raw.IsRecovered ? coordinates.fromByteOffset(raw.Offset) : fallback;
+    /** Each projected record owns its derived fields, while real syntax nodes retain their original identity. */
+    const project = (raw, fallback) => {
+        if (!isRecord(raw) || typeof raw.Type !== 'string' || !Object.hasOwn(SYNTAX_SCHEMA, raw.Type)) {
+            throw new TypeError('shell view expected a known upstream syntax record');
+        }
+        const schema = SYNTAX_SCHEMA[raw.Type];
+        const realNode = isSyntaxNode(raw);
+        // eslint-disable-next-line @api-extractor-tools/forgotten-export -- This span belongs only to the private projection closure, not the exported signature.
+        let span = fallback;
+        if (realNode) {
+            const observed = positions.get(raw);
+            if (observed === undefined) {
+                throw new TypeError(`shell position snapshot has no observation for ${raw.Type}`);
+            }
+            span = {
+                start: position(observed.Pos, fallback.start),
+                end: position(observed.End, fallback.end),
+            };
+        }
+        const fields = {};
+        const children = [];
+        for (const [name, field] of Object.entries(schema.fields)) {
+            if (field.kind === 'position') {
+                continue;
+            }
+            const value = raw[name];
+            const key = name.toLowerCase();
+            if (field.kind === 'struct' || field.kind === 'interface') {
+                if (field.slice) {
+                    const items = value === null ? [] : value;
+                    if (!Array.isArray(items)) {
+                        throw new TypeError(`shell view expected ${raw.Type}.${name} to be a slice`);
+                    }
+                    const projected = items
+                        .filter((item) => item !== null)
+                        .map((item) => project(item, span));
+                    fields[key] = projected;
+                    children.push(...projected);
+                }
+                else if (value !== null) {
+                    const child = project(value, span);
+                    fields[key] = child;
+                    children.push(child);
+                }
+            }
+            else {
+                fields[key] = field.kind === 'string' ? sourceText(value) : value;
+            }
+        }
+        if (!realNode && children.length > 0) {
+            span = {
+                start: coordinates.atIndex(Math.min(...children.map((node) => node.range[0]))),
+                end: coordinates.atIndex(Math.max(...children.map((node) => node.range[1]))),
+            };
+        }
+        const view = {
+            ...fields,
+            type: raw.Type,
+            range: [span.start.index, span.end.index],
+            loc: {
+                start: { line: span.start.line, column: span.start.column },
+                end: { line: span.end.line, column: span.end.column },
+            },
+        };
+        if (realNode) {
+            originalSyntax.set(view, raw);
+        }
+        return view;
+    };
+    const root = project(file, wholeSource);
+    if (!isShellFile(root)) {
+        throw new TypeError('shell view expected a File with statements');
+    }
+    return root;
+}
+/** Consumer traversal visits each projected child, including auxiliary views, without claiming upstream Walk control semantics. @internal */
+export function walkShell(root, visit) {
+    visit(root);
+    for (const key of shellVisitorKeys[root.type] ?? []) {
+        const value = root[key];
+        if (Array.isArray(value)) {
+            for (const child of value) {
+                if (isShellNode(child)) {
+                    walkShell(child, visit);
+                }
+            }
+        }
+        else if (isShellNode(value)) {
+            walkShell(value, visit);
+        }
+    }
+}
+//# sourceMappingURL=syntax-view.js.map

package/dist/language/syntax-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syntax-view.js","sourceRoot":"","sources":["../../src/language/syntax-view.ts"],"names":[],"mappings":"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"}

package/dist/language/word-resolution.d.ts

@@ -0,0 +1,11 @@
+import type { ResolveWordOptions, WordResolution } from 'sh-ast/analyze';
+import type { ShellNode } from './syntax-view.js';
+/**
+ * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
+ * The view supplies locations and selector fields; sh-ast/analyze owns the word
+ * interpretation. Fabricated or synthetic view nodes have no source syntax and
+ * are rejected instead of being treated as known or unknown shell values.
+ * @public
+ */
+export declare function resolveWord(word: ShellNode, options?: ResolveWordOptions): WordResolution;
+//# sourceMappingURL=word-resolution.d.ts.map

package/dist/language/word-resolution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-resolution.d.ts","sourceRoot":"","sources":["../../src/language/word-resolution.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAMzF"}

package/dist/language/word-resolution.js

@@ -0,0 +1,18 @@
+/** Bridges custom-rule analysis from ESLint view identity back to faithful syntax. */
+import { resolveWord as resolveSyntaxWord } from 'sh-ast/analyze';
+import { syntaxForNode } from './syntax-view.js';
+/**
+ * Resolves a parsed lint Word using the upstream-shaped syntax associated with it.
+ * The view supplies locations and selector fields; sh-ast/analyze owns the word
+ * interpretation. Fabricated or synthetic view nodes have no source syntax and
+ * are rejected instead of being treated as known or unknown shell values.
+ * @public
+ */
+export function resolveWord(word, options) {
+    const syntax = syntaxForNode(word);
+    if (syntax?.Type !== 'Word') {
+        throw new TypeError('resolveWord expects a parsed shell Word from this language adapter');
+    }
+    return resolveSyntaxWord(syntax, options);
+}
+//# sourceMappingURL=word-resolution.js.map

package/dist/language/word-resolution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"word-resolution.js","sourceRoot":"","sources":["../../src/language/word-resolution.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,OAAO,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAElE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGjD;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,IAAe,EAAE,OAA4B;IACvE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,MAAM,IAAI,SAAS,CAAC,oEAAoE,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC5C,CAAC"}

package/docs/custom-rule-tutorial.md

@@ -46,8 +46,8 @@ flag?) the same way a hand-written rule narrows any other selector-first ESLint
  * here the selector does the node-type narrowing, `create()` only does the
  * domain-specific check).
  *
- * Flag words are resolved with `@eslint-sh/eslint-plugin`'s re-exported
- * `resolveWord` (originally from `sh-ast/analyze`) rather than a
+ * 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`/
@@ -117,8 +117,8 @@ A few things worth calling out:
   classes](./selectors.md#the-six-launch-classes) — not a bare node-type name. ESLint's
   `esquery`-based rule-listener matching (via `ShellLanguage.matchesSelectorClass`) treats it
   exactly like any other selector key such as `CallExpr` or `CallExpr[args.0.parts.0.value='jq']`.
-- `resolveWord(arg, { context: 'command-argument' })` — re-exported from `@eslint-sh/eslint-plugin`
-  (originally `sh-ast/analyze`) — is the correct way to ask "is this word statically the string X":
+- `resolveWord(arg, { context: 'command-argument' })` — exported from `@eslint-sh/eslint-plugin`
+  (using the raw Word associated with the lint view) — is the correct way to ask "is this word statically the string X":
   it returns `{ static: true, text }` for a bare or
   quoted literal (`rm`, `'r'm`, `"-rf"` all resolve), and `{ static: false, reason }` the moment any
   part of the word depends on a `ParamExp`/`CmdSubst`/`ArithmExp`/`ProcSubst` — never inventing a

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

@@ -14,8 +14,8 @@
  * here the selector does the node-type narrowing, `create()` only does the
  * domain-specific check).
  *
- * Flag words are resolved with `@eslint-sh/eslint-plugin`'s re-exported
- * `resolveWord` (originally from `sh-ast/analyze`) rather than a
+ * 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`/

package/docs/selectors.md

@@ -27,6 +27,15 @@ Looking for a complete, runnable `create()` that uses one of these selectors —
 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.
 
+## Node-type names vs. TypeScript interface names
+
+Selectors and `node.type` use the **bare** node-type name shown in the table above and
+throughout this cookbook (`CallExpr`, `IfClause`, `FuncDecl`, ...). The plugin's `ShellNode`
+view preserves these discriminator values while supplying lowercase child fields, UTF-16
+ranges, and locations. The underlying `sh-ast` syntax uses its own `Type` discriminator and
+upstream field spellings; rule listeners receive the plugin view. Import view types from
+`@eslint-sh/eslint-plugin` (or `eslint-sh`) when typing a custom rule.
+
 ## Recipes
 
 ### Match a specific command by name

package/package.json

@@ -1,12 +1,12 @@
 {
   "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.3.0",
+  "version": "0.5.0",
   "author": "Mike North <michael.l.north@gmail.com>",
   "dependencies": {
     "@eslint/core": "^1.2.1",
     "@eslint/plugin-kit": "^0.7.2",
-    "sh-ast": "^0.3.0"
+    "sh-ast": "^0.5.0"
   },
   "devDependencies": {
     "eslint": "^10.7.0"
@@ -65,6 +65,11 @@
   },
   "type": "module",
   "types": "./dist/eslint-plugin.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mike-north/eslint-sh.git",
+    "directory": "packages/eslint-plugin"
+  },
   "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\"",
@@ -75,6 +80,7 @@
     "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/"
+    "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/",
+    "test:candidate": "node --experimental-strip-types test/candidate/run.mjs"
   }
 }