ember-estree 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-estree",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "ESTree generator for gjs and gts file used by ember",
   "keywords": [
     "AST",
@@ -33,18 +33,19 @@
     "@glimmer/env": "^0.1.7",
     "@glimmer/syntax": "^0.95.0",
     "content-tag": "^4.1.0",
-    "oxc-parser": "^0.119.0",
-    "zimmerframe": "^1.1.4"
+    "oxc-parser": "^0.119.0"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "^22.0.2",
+    "@typescript-eslint/parser": "^8.59.0",
     "mitata": "^1.0.34",
     "oxfmt": "^0.40.0",
     "oxlint": "^1.55.0",
     "publint": "^0.3.18",
     "release-plan": "^0.18.0",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "zimmerframe": "^1.1.4"
   },
   "scripts": {
     "bench": "node --expose-gc tests/parser.bench.mjs",

package/src/parse.js

@@ -9,11 +9,45 @@
  * 6. Done
  */
 
-import { parseSync } from "oxc-parser";
+import { parseSync, visitorKeys as oxcVisitorKeys } from "oxc-parser";
 import { Preprocessor } from "content-tag";
-import { walk } from "zimmerframe";
 
-import { processTemplate, DocumentLines, glimmerVisitorKeys } from "./transforms.js";
+import { processTemplate, DocumentLines, glimmerVisitorKeys, setParent } from "./transforms.js";
+
+// Base visitor-keys map for the outer-AST walk: oxc-parser's own keys (covers
+// standard ESTree + TS), plus the `File` wrapper we add on the default path,
+// plus Glimmer's keys. Used to iterate only declared child slots instead of
+// every enumerable property on every node.
+//
+// When `options.parser` returns `visitorKeys`, callers merge on top — but if
+// their parser's AST is oxc-compatible, this base is already sufficient.
+const DEFAULT_VISITOR_KEYS = {
+  ...oxcVisitorKeys,
+  File: ["program"],
+  ...glimmerVisitorKeys,
+};
+
+// Swap `oldNode` for `newNode` in whichever slot of `parent` currently holds it.
+// Used to splice a GlimmerTemplate directly into the outer AST without
+// allocating new ancestor objects — keeps WeakMap-keyed data (scope manager,
+// esTreeNodeToTSNodeMap) attached to the existing nodes.
+function replaceInParent(parent, oldNode, newNode) {
+  for (const key of Object.keys(parent)) {
+    const v = parent[key];
+    if (v === oldNode) {
+      parent[key] = newNode;
+      return true;
+    }
+    if (Array.isArray(v)) {
+      const idx = v.indexOf(oldNode);
+      if (idx !== -1) {
+        v[idx] = newNode;
+        return true;
+      }
+    }
+  }
+  return false;
+}
 
 const preprocessor = new Preprocessor();
 
@@ -33,7 +67,9 @@ const PLACEHOLDER_TYPES = new Set([
  * @param {string}  [options.filePath] - File path for language detection
  * @param {boolean} [options.tokens] - Generate a flat token stream on the AST (needed by ESLint; skipped by default)
  * @param {boolean} [options.templateOnly] - Parse as raw Glimmer template content (for .hbs)
- * @param {function} [options.parser] - Custom JS/TS parser: (placeholderJS) => { ast, scopeManager?, visitorKeys?, services?, ... }
+ * @param {function} [options.parser] - Custom JS/TS parser: (placeholderJS) => { ast, scopeManager?, visitorKeys?, services?, ... }.
+ *   Recommended to return `visitorKeys` describing the parser's AST; when omitted, oxc-parser's
+ *   keys are used (fine for oxc-compatible ASTs, incomplete for parsers that emit bespoke node types).
  * @param {object|function} [options.visitors] - Either a map of `{ [Type]: (node, path) => void }`
  *   handlers, or a factory `(outerAst) => handlers` invoked once after parsing (before any
  *   template splicing) to give callers a view of the raw JS/TS tree. Handlers fire on every
@@ -112,8 +148,11 @@ export function toTree(source, options = {}) {
     ? new Map(parseResults.map((r) => [r.range.startUtf16Codepoint, r]))
     : null;
 
-  // Process a matched placeholder node: create Glimmer AST and tokens
-  function processPlaceholder(parseResult) {
+  // Process a matched placeholder node: create Glimmer AST and tokens.
+  // `placeholderNode` is the original JS/TS node being swapped out; we stash
+  // it on templateInfos so consumers can forward its parser-services mapping
+  // (e.g. esTreeNodeToTSNodeMap) onto the GlimmerTemplate that replaces it.
+  function processPlaceholder(parseResult, placeholderNode) {
     let templateContent = parseResult.contents;
     let contentRange = [
       parseResult.contentRange.startUtf16Codepoint,
@@ -159,7 +198,7 @@ export function toTree(source, options = {}) {
       ];
     }
 
-    templateInfos.push({ utf16Range: fullRange, ast });
+    templateInfos.push({ utf16Range: fullRange, ast, placeholder: placeholderNode });
     return ast;
   }
 
@@ -181,47 +220,66 @@ export function toTree(source, options = {}) {
     return parseResult;
   }
 
-  result.ast = walk(result.ast, null, {
-    _(node, { next, visit, state }) {
-      if (hasTemplates && PLACEHOLDER_TYPES.has(node.type)) {
-        const parseResult = matchPlaceholder(node);
-        if (parseResult) {
-          const ast = processPlaceholder(parseResult);
-          // Zimmerframe treats a visitor that returns a node as having
-          // taken responsibility for the subtree — it splices the result
-          // in but does NOT descend into it. So when any handlers are
-          // configured we re-enter the walk manually via `visit()` to
-          // dispatch them across the Glimmer nodes. With no handlers the
-          // walk would be pure overhead, so just return the subtree.
-          //
-          // Pass `state` (the placeholder's inherited parent context) so the
-          // Glimmer root's parentPath reflects its true JS parent. The
-          // placeholder (TemplateLiteral / StaticBlock) is an internal
-          // artifact — the GlimmerTemplate logically lives where the
-          // placeholder was, so its parent is e.g. VariableDeclarator or
-          // ClassBody, not the placeholder itself.
-          return hasVisitors ? visit(ast, state) : ast;
-        }
+  // Walk the outer AST keyed on visitorKeys — iterating only declared child
+  // slots instead of every enumerable property on every node. Custom parsers
+  // may supply their own keys; those override the defaults for types they
+  // recognise, and Glimmer keys stay on top for the spliced subtrees.
+  const allVisitorKeys =
+    useCustomParser && result.visitorKeys
+      ? { ...DEFAULT_VISITOR_KEYS, ...result.visitorKeys, ...glimmerVisitorKeys }
+      : DEFAULT_VISITOR_KEYS;
+
+  function walkWithKeys(node, parentPath) {
+    if (!node || !node.type) return;
+
+    if (hasTemplates && PLACEHOLDER_TYPES.has(node.type)) {
+      const parseResult = matchPlaceholder(node);
+      if (parseResult) {
+        // Splice in place: write the GlimmerTemplate directly into the parent's
+        // slot instead of allocating new ancestor objects. This preserves node
+        // identity for every ancestor, which matters for WeakMap-keyed data
+        // held by custom parsers (scope manager, esTreeNodeToTSNodeMap).
+        const ast = processPlaceholder(parseResult, node);
+        const parent = parentPath?.node ?? null;
+        if (parent) replaceInParent(parent, node, ast);
+        setParent(ast, parent);
+        // Recurse into the Glimmer subtree so visitors fire on its nodes too.
+        // The Glimmer root's parentPath reflects its true JS parent — the
+        // placeholder (TemplateLiteral / StaticBlock) is an internal artifact.
+        if (hasVisitors) walkWithKeys(ast, parentPath);
+        return;
       }
+    }
 
-      const path = {
-        node,
-        parent: state?.parentPath?.node ?? null,
-        parentPath: state?.parentPath ?? null,
-      };
-
-      if (hasVisitors && !seen.has(node)) {
-        seen.add(node);
-        const handler = visitors[node.type];
-        if (handler) handler(node, path);
-        if ("blockParams" in node && visitors.GlimmerBlockParams) {
-          visitors.GlimmerBlockParams(node, path);
+    const path = { node, parent: parentPath?.node ?? null, parentPath };
+
+    if (hasVisitors && !seen.has(node)) {
+      seen.add(node);
+      const handler = visitors[node.type];
+      if (handler) handler(node, path);
+      if ("blockParams" in node && visitors.GlimmerBlockParams) {
+        visitors.GlimmerBlockParams(node, path);
+      }
+    }
+
+    const keys = allVisitorKeys[node.type];
+    if (!keys) return;
+    for (const key of keys) {
+      const child = node[key];
+      if (!child) continue;
+      if (Array.isArray(child)) {
+        for (const item of child) {
+          if (item && typeof item === "object" && item.type) {
+            walkWithKeys(item, path);
+          }
         }
+      } else if (typeof child === "object" && child.type) {
+        walkWithKeys(child, path);
       }
+    }
+  }
 
-      next({ parentPath: path });
-    },
-  });
+  walkWithKeys(result.ast, null);
 
   // Splice template tokens into the AST token stream.
   //
@@ -240,8 +298,11 @@ export function toTree(source, options = {}) {
   // original source byte-for-byte across JS and Glimmer regions.
   //
   // Tokens are sorted by range, so use binary search for O(log n) lookup.
+  // Only splice if the caller asked for tokens — otherwise `ti.ast.tokens`
+  // wasn't populated by processPlaceholder, and a custom parser may still
+  // have returned its own token stream we shouldn't touch.
   const astRoot = result.ast.program || result.ast;
-  if (astRoot.tokens) {
+  if (generateTokens && astRoot.tokens) {
     for (const ti of templateInfos) {
       const [tStart, tEnd] = ti.utf16Range;
       const tokens = astRoot.tokens;

package/src/transforms.js

@@ -64,7 +64,7 @@ export const glimmerVisitorKeys = (() => {
 //   Block: blockParams
 const _desc = { value: undefined, configurable: true, enumerable: true, writable: true };
 const _parentDesc = { value: null, configurable: true, enumerable: false, writable: true };
-function setParent(node, parent) {
+export function setParent(node, parent) {
   _parentDesc.value = parent;
   Object.defineProperty(node, "parent", _parentDesc);
 }