ember-estree 0.4.3 → 0.5.0

package/README.md

@@ -57,6 +57,109 @@ print({
 // => "<template>Hello</template>"
 ```
 
+## Options
+
+Both `toTree` and `parse` accept an options object as their second argument.
+
+All options are optional.
+
+| Option         | Type                                              | Description                                                                                                       |
+| -------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `filePath`     | `string`                                          | Used for language detection.                                                                                      |
+| `templateOnly` | `boolean`                                         | Parse the source as a raw Glimmer template. Use for `.hbs` files.                                                 |
+| `parser`       | `(placeholderJS: string) => { ast, ... }`         | Use a custom JS/TS parser instead of the default oxc-parser. See [Custom parser](#custom-parser).                 |
+| `visitors`     | `VisitorMap` <br /> or `(outerAst) => VisitorMap` | Callbacks fired on every node during traversal — JS/TS and Glimmer — in a single pass. See [Visitors](#visitors). |
+
+Handler signature is `(node, path) => void`, where `path = { node, parent, parentPath }` — a linked list walking back to the root.
+
+### Custom parser
+
+Pass any JS/TS parser that returns an ESTree-compatible AST. ember-estree handles template splicing and Glimmer traversal on top of it.
+
+```js
+import { parseSync } from "oxc-parser";
+import { toTree } from "ember-estree";
+
+const result = toTree(source, {
+  parser: (js) => ({
+    ast: parseSync("input.ts", js).program,
+    visitorKeys: {
+      /* ...parser's visitor keys... */
+    },
+  }),
+});
+```
+
+The parser receives a placeholder-JS string (templates replaced with backtick expressions of equal length) and must return at least `{ ast }`. Additional fields like `scopeManager`, `visitorKeys`, or `services` are preserved on the returned result.
+
+### Visitors
+
+Pass `visitors` to observe or rewrite the tree in a single traversal. Handlers fire on both outer JS/TS nodes and spliced Glimmer subtrees, and a single node is never dispatched twice — safe to relocate nodes mid-walk.
+
+The pseudo-type `GlimmerBlockParams` fires on any node that carries a `blockParams` array.
+
+**Plain-object form** — use when you only need the type → handler map:
+
+```js
+import { toTree } from "ember-estree";
+
+const identifiers = [];
+toTree(source, {
+  visitors: {
+    Identifier: (node) => identifiers.push(node.name),
+    GlimmerPathExpression: (node) => identifiers.push(node.original),
+  },
+});
+```
+
+**Factory form** — use when you need the outer JS/TS AST up front (for example, to attach state to it before the walk):
+
+```js
+import { toTree, print } from "ember-estree";
+
+const ast = toTree(`const world = "🌍"; const X = <template>{{world}}</template>;`, {
+  visitors: () => ({
+    Identifier: (node) => (node.name = node.name.toUpperCase()),
+    GlimmerPathExpression(node) {
+      node.original = node.original.toUpperCase();
+      if (node.head) node.head.name = node.original;
+    },
+  }),
+});
+
+print(ast.program);
+// => 'const WORLD = "🌍";\nconst X = <template>{{WORLD}}</template>;'
+```
+
+**Collecting Glimmer comments into `program.comments`** — useful when adapting the AST for ESLint, which reads comments from the Program node:
+
+```js
+const ast = toTree(source, {
+  visitors: (outerAst) => {
+    outerAst.program.comments = [...(outerAst.comments ?? [])];
+    const push = (node) => outerAst.program.comments.push(node);
+    return {
+      GlimmerCommentStatement: push,
+      GlimmerMustacheCommentStatement: push,
+    };
+  },
+});
+```
+
+**Removing nodes mid-traversal** — siblings are splice-safe:
+
+```js
+toTree(source, {
+  visitors: () => ({
+    GlimmerMustacheCommentStatement(node, path) {
+      const siblings = path.parent?.body ?? path.parent?.children;
+      const idx = siblings?.indexOf(node) ?? -1;
+      if (idx >= 0) siblings.splice(idx, 1);
+    },
+  }),
+});
+```
+
 ## Examples
 
 The [`examples/`](./examples) directory contains ready-to-run integrations:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-estree",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "ESTree generator for gjs and gts file used by ember",
   "keywords": [
     "AST",

package/src/index.d.ts

@@ -30,11 +30,6 @@ export interface VisitorPath {
 export interface ParseOptions {
   filePath?: string;
   templateOnly?: boolean;
-  /**
-   * Include `parent` references on Glimmer AST nodes.
-   * Defaults to `true`. Set to `false` for JSON-serializable output.
-   */
-  includeParentLinks?: boolean;
   /**
    * Custom JS/TS parser. Called with the placeholder JS string
    * (templates replaced with backtick expressions of equal length).
@@ -42,15 +37,24 @@ export interface ParseOptions {
    */
   parser?: (placeholderJS: string) => { ast: ASTNode; [key: string]: unknown };
   /**
-   * Callbacks invoked for Glimmer nodes during the AST splice traversal.
-   * Runs in DFS order, so parent nodes are visited before children.
+   * Callbacks fired on each node during traversal — outer JS/TS nodes AND
+   * spliced Glimmer subtrees — so callers can gather information or mutate
+   * the tree in a single pass.
+   *
+   * Pass either a plain handler map, or a factory `(outerAst) => handlers`
+   * that's called once after parsing (before template splicing) when you
+   * need a view of the raw JS/TS tree up front.
+   *
+   * The pseudo-type `GlimmerBlockParams` fires on any node that carries
+   * a `blockParams` array.
    */
-  visitors?: {
-    [glimmerNodeType: string]: (node: ASTNode, path: VisitorPath) => void;
-    GlimmerBlockParams?: (node: ASTNode, path: VisitorPath) => void;
-  };
+  visitors?: VisitorMap | ((outerAst: ASTNode) => VisitorMap | null | undefined);
 }
 
+export type VisitorMap = {
+  [nodeType: string]: (node: ASTNode, path: VisitorPath) => void;
+};
+
 export class DocumentLines {
   constructor(source: string);
   positionToOffset(pos: Position): number;

package/src/parse.js

@@ -33,21 +33,22 @@ const PLACEHOLDER_TYPES = new Set([
  * @param {string}  [options.filePath] - File path for language detection
  * @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 {object}  [options.visitors] - Callbacks invoked for Glimmer nodes during traversal
+ * @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
+ *   node during traversal — outer JS/TS nodes AND spliced Glimmer subtrees — in a single pass.
+ *   The pseudo-type `GlimmerBlockParams` fires on any node that carries `blockParams`.
  * @return {object}
  */
 export function toTree(source, options = {}) {
-  const templateOpts = options.includeParentLinks === false ? { includeParentLinks: false } : {};
-
   if (options.templateOnly) {
-    return processTemplate(source, new DocumentLines(source), [0, source.length], templateOpts);
+    return processTemplate(source, new DocumentLines(source), [0, source.length]);
   }
 
   let parseResults = preprocessor.parse(source);
   let js = toPlaceholderJS(source, parseResults);
 
   const useCustomParser = !!options.parser;
-  const visitors = options.visitors || null;
 
   // Parse the placeholder JS — use custom parser or default oxc
   let result;
@@ -73,8 +74,24 @@ export function toTree(source, options = {}) {
     };
   }
 
-  // If no templates, return early
-  if (!parseResults.length) {
+  // Resolve user visitors against the outer AST. A plain object is used
+  // as-is; a factory is called once so callers can introspect the raw
+  // JS/TS tree before any template splicing. Default to `{}` so downstream
+  // dispatch can be a bare `visitors[type]` lookup without null-guards.
+  const visitors =
+    typeof options.visitors === "function"
+      ? (options.visitors(result.ast) ?? {})
+      : (options.visitors ?? {});
+  const hasVisitors = Object.keys(visitors).length > 0;
+  // Guard against dispatching a handler twice on the same node.
+  // Visitors that relocate nodes (e.g. moving Glimmer comments into
+  // `program.comments`) would otherwise fire a second time when the walk
+  // reaches the new location.
+  const seen = new WeakSet();
+  const hasTemplates = parseResults.length > 0;
+
+  // Nothing to walk — attach visitor keys and return.
+  if (!hasTemplates && !hasVisitors) {
     if (useCustomParser) {
       result.visitorKeys = { ...result.visitorKeys, ...glimmerVisitorKeys };
       return result;
@@ -83,11 +100,11 @@ export function toTree(source, options = {}) {
     return result.ast;
   }
 
-  const codeLines = new DocumentLines(source);
+  const codeLines = hasTemplates ? new DocumentLines(source) : null;
   const templateInfos = [];
-
-  // Build a map of template ranges for lookup
-  const templateRangeByStart = new Map(parseResults.map((r) => [r.range.startUtf16Codepoint, r]));
+  const templateRangeByStart = hasTemplates
+    ? new Map(parseResults.map((r) => [r.range.startUtf16Codepoint, r]))
+    : null;
 
   // Process a matched placeholder node: create Glimmer AST and tokens
   function processPlaceholder(parseResult) {
@@ -98,7 +115,7 @@ export function toTree(source, options = {}) {
     ];
     let fullRange = [parseResult.range.startUtf16Codepoint, parseResult.range.endUtf16Codepoint];
 
-    const { ast } = processTemplate(templateContent, codeLines, contentRange, templateOpts);
+    const { ast } = processTemplate(templateContent, codeLines, contentRange);
 
     // Fix the Template root to cover the full <template>...</template> range
     ast.range = fullRange;
@@ -153,101 +170,57 @@ export function toTree(source, options = {}) {
     return parseResult;
   }
 
-  // Walk Glimmer subtree, invoking visitors with full path context
-  function walkGlimmerTree(node, parentPath) {
-    if (!node || typeof node !== "object" || !node.type) return;
-    const path = { node, parent: parentPath?.node ?? null, parentPath };
-
-    if (visitors && node.type.startsWith("Glimmer")) {
-      const handler = visitors[node.type];
-      if (handler) handler(node, path);
-      if ("blockParams" in node && visitors.GlimmerBlockParams) {
-        visitors.GlimmerBlockParams(node, path);
-      }
-    }
-
-    const keys = glimmerVisitorKeys[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) {
-          walkGlimmerTree(item, path);
-        }
-      } else if (typeof child === "object" && child.type) {
-        walkGlimmerTree(child, path);
-      }
-    }
-  }
-
-  if (useCustomParser) {
-    // Custom parser path: mutate the parser's AST in-place, invoke visitors.
-    // Use the parser's visitorKeys to traverse efficiently (avoids Object.keys).
-    const parserVisitorKeys = result.visitorKeys || {};
-
-    function visitNode(node, parentPath) {
-      if (!node || typeof node !== "object" || !node.type) return;
-
-      const path = { node, parent: parentPath?.node ?? null, parentPath };
-
-      if (PLACEHOLDER_TYPES.has(node.type)) {
+  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);
-          for (const key of Object.keys(node)) {
-            if (!(key in ast) && key !== "parent") {
-              delete node[key];
-            }
-          }
-          Object.assign(node, ast);
-          if (visitors) walkGlimmerTree(node, parentPath);
-          return;
+          // 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.
+          return hasVisitors ? visit(ast, null) : ast;
         }
       }
 
-      // Use visitorKeys for efficient child traversal
-      const keys = parserVisitorKeys[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) {
-              visitNode(item, path);
-            }
-          }
-        } else if (typeof child === "object" && child.type) {
-          visitNode(child, path);
+      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);
         }
       }
-    }
-
-    visitNode(result.ast, null);
-  } else {
-    // Default oxc path: use zimmerframe walk (returns new tree)
-    result.ast = walk(result.ast, null, {
-      _(node, { next }) {
-        if (PLACEHOLDER_TYPES.has(node.type)) {
-          const parseResult = matchPlaceholder(node);
-          if (parseResult) {
-            return processPlaceholder(parseResult);
-          }
-        }
-        next();
-      },
-    });
 
-    // Walk Glimmer subtrees for visitors (after zimmerframe splicing)
-    if (visitors) {
-      for (const ti of templateInfos) {
-        walkGlimmerTree(ti.ast, null);
-      }
-    }
-  }
+      next({ parentPath: path });
+    },
+  });
 
   // Splice template tokens into the AST token stream.
+  //
+  // `tokens` is the flat lexed stream (keywords, punctuators, identifiers,
+  // literals) that ESLint, formatters, and source-map tooling consume —
+  // `SourceCode.getTokens()` reads it directly.
+  //
+  // We replaced each <template>...</template> region with a backtick
+  // placeholder before handing the source to the JS/TS parser, so the
+  // parser's tokens for those ranges describe the placeholder, not the
+  // real source. Here we swap them out for the real lexemes:
+  //   1. a fabricated `<template>` Punctuator (added in processPlaceholder)
+  //   2. the Glimmer AST's own tokens (from transforms.js)
+  //   3. a fabricated `</template>` Punctuator
+  // so consumers see a position-accurate token stream matching the
+  // original source byte-for-byte across JS and Glimmer regions.
+  //
   // Tokens are sorted by range, so use binary search for O(log n) lookup.
   const astRoot = result.ast.program || result.ast;
   if (astRoot.tokens) {

package/src/transforms.js

@@ -61,6 +61,11 @@ export const glimmerVisitorKeys = (() => {
 //   VarHead: name, original
 //   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) {
+  _parentDesc.value = parent;
+  Object.defineProperty(node, "parent", _parentDesc);
+}
 function defOwn(obj, key) {
   _desc.value = obj[key];
   Object.defineProperty(obj, key, _desc);
@@ -168,12 +173,7 @@ function buildTokenStream(rawTokens, comments, textNodes) {
  * positions, create parts/blockParamNodes, nullify empty hashes, and
  * prefix types. No separate collect-then-transform loop.
  */
-export function processTemplate(
-  templateContent,
-  codeLines,
-  templateRange,
-  { includeParentLinks = true } = {},
-) {
+export function processTemplate(templateContent, codeLines, templateRange) {
   const offset = templateRange[0];
   const docLines = offset === 0 ? codeLines : new DocumentLines(templateContent);
 
@@ -187,7 +187,6 @@ export function processTemplate(
   });
 
   const ast = glimmerPreprocess(templateContent, { mode: "codemod" });
-  const allNodes = [];
   const comments = [];
   const textNodes = [];
   const emptyTextNodes = [];
@@ -197,8 +196,7 @@ export function processTemplate(
   // children using raw visitor keys. Type prefixing happens inline
   // AFTER recursing (so children see the original type during lookup).
   function visit(n, parent) {
-    n.parent = parent;
-    allNodes.push(n);
+    setParent(n, parent);
 
     // Categorize
     if (n.type === "CommentStatement" || n.type === "MustacheCommentStatement") {
@@ -257,18 +255,17 @@ export function processTemplate(
       n.name = n.tag;
       const p = n.path.head;
       const partRange = toFileRange(p.loc);
-      n.parts = [
-        {
-          type: "GlimmerElementNodePart",
-          original: p.original,
-          name: p.original,
-          parent: n,
-          range: partRange,
-          start: partRange[0],
-          end: partRange[1],
-          loc: toFileLoc(partRange),
-        },
-      ];
+      const part = {
+        type: "GlimmerElementNodePart",
+        original: p.original,
+        name: p.original,
+        range: partRange,
+        start: partRange[0],
+        end: partRange[1],
+        loc: toFileLoc(partRange),
+      };
+      setParent(part, n);
+      n.parts = [part];
     }
 
     // Create blockParamNodes
@@ -276,27 +273,31 @@ export function processTemplate(
       if (n.params && n.params.length === n.blockParams.length) {
         n.blockParamNodes = n.params.map((p) => {
           const range = toFileRange(p.loc);
-          return {
+          const bp = {
             type: "GlimmerBlockParam",
             name: p.original || p.name,
             original: p.original,
-            parent: n,
             range,
             start: range[0],
             end: range[1],
             loc: toFileLoc(range),
           };
+          setParent(bp, n);
+          return bp;
         });
       } else {
-        n.blockParamNodes = n.blockParams.map((bpName) => ({
-          type: "GlimmerBlockParam",
-          name: bpName,
-          parent: n,
-          range: [n.range[0], n.range[1]],
-          start: n.range[0],
-          end: n.range[1],
-          loc: toFileLoc(n.range),
-        }));
+        n.blockParamNodes = n.blockParams.map((bpName) => {
+          const bp = {
+            type: "GlimmerBlockParam",
+            name: bpName,
+            range: [n.range[0], n.range[1]],
+            start: n.range[0],
+            end: n.range[1],
+            loc: toFileLoc(n.range),
+          };
+          setParent(bp, n);
+          return bp;
+        });
       }
     }
 
@@ -337,13 +338,5 @@ export function processTemplate(
   ast.tokens = buildTokenStream(tokenize(templateContent, codeLines, offset), comments, textNodes);
   ast.contents = templateContent;
 
-  if (!includeParentLinks) {
-    for (const n of allNodes) {
-      delete n.parent;
-      if (n.parts) for (const p of n.parts) delete p.parent;
-      if (n.blockParamNodes) for (const p of n.blockParamNodes) delete p.parent;
-    }
-  }
-
   return { ast, comments };
 }