ember-estree 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-estree",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "ESTree generator for gjs and gts file used by ember",
   "keywords": [
     "AST",
@@ -30,9 +30,9 @@
     }
   },
   "dependencies": {
+    "@glimmer/env": "^0.1.7",
     "@glimmer/syntax": "^0.95.0",
     "content-tag": "^4.1.0",
-    "ember-template-recast": "^6.1.5",
     "oxc-parser": "^0.119.0",
     "zimmerframe": "^1.1.4"
   },

package/src/index.d.ts

@@ -1,23 +1,8 @@
-/**
- * Options accepted by `parse` and `toTree`.
- */
-export interface ParseOptions {
-  /** Path to the file being parsed, used to determine the language (js/ts). */
-  filePath?: string;
-}
-
-/**
- * A 1-based line / 0-based column position, matching ESTree and Glimmer
- * conventions.
- */
 export interface Position {
   line: number;
   column: number;
 }
 
-/**
- * Minimal shape shared by every AST node (ESTree, TypeScript, and Glimmer).
- */
 export interface ASTNode {
   type: string;
   start?: number;
@@ -25,71 +10,55 @@ export interface ASTNode {
   [key: string]: unknown;
 }
 
-/**
- * The `File`-like wrapper returned by `toTree` and `parse`.
- *
- * Mirrors the shape produced internally:
- * ```
- * { type: "File", program: Program, comments: Comment[], start, end }
- * ```
- */
 export interface FileNode extends ASTNode {
   type: "File";
   program: ASTNode;
   comments: ASTNode[];
 }
 
-/**
- * Converts between character offsets and line/column positions within a
- * source string.
- */
+export interface TemplateResult {
+  ast: ASTNode;
+  comments: ASTNode[];
+}
+
+export interface VisitorPath {
+  node: ASTNode;
+  parent: ASTNode | null;
+  parentPath: VisitorPath | null;
+}
+
+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).
+   * Must return at least `{ ast }`.
+   */
+  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.
+   */
+  visitors?: {
+    [glimmerNodeType: string]: (node: ASTNode, path: VisitorPath) => void;
+    GlimmerBlockParams?: (node: ASTNode, path: VisitorPath) => void;
+  };
+}
+
 export class DocumentLines {
   constructor(source: string);
-
-  /** Converts a `{ line, column }` position to a character offset. */
   positionToOffset(pos: Position): number;
-
-  /** Converts a character offset to a `{ line, column }` position. */
   offsetToPosition(offset: number): Position;
 }
 
-/**
- * Parse Ember .gjs/.gts source code and return a File-like ESTree-compatible
- * AST with embedded Glimmer template nodes.
- *
- * @param source  The raw source code of the file.
- * @param options Optional parse options.
- * @returns A `File`-shaped object with a `.program` property.
- */
-export function toTree(source: string, options?: ParseOptions): FileNode;
-
-/**
- * Parse Ember .gjs/.gts source code into an ESTree-compatible AST with
- * embedded Glimmer template nodes.
- *
- * @param source  The source code to parse.
- * @param options Optional parse options.
- * @returns The ESTree-compatible AST.
- */
-export function parse(source: string, options?: ParseOptions): FileNode;
-
-/**
- * Recursively print an AST node back to source code.
- *
- * Handles ESTree, TypeScript, and Glimmer template node types.
- * JSX nodes are not supported — Ember uses Glimmer templates instead.
- *
- * @param node The AST node to print.
- * @returns The printed source string.
- */
+export function toTree(source: string, options?: ParseOptions): FileNode | TemplateResult;
+export function parse(source: string, options?: ParseOptions): FileNode | TemplateResult;
 export function print(node: ASTNode): string;
 
-/**
- * Build and return the Glimmer visitor keys map with a `"Glimmer"` prefix on
- * every key (e.g. `"GlimmerElementNode"`).
- *
- * The result is cached after the first call.
- *
- * @returns A map of Glimmer node type names to arrays of child-property names.
- */
-export function buildGlimmerVisitorKeys(): Record<string, string[]>;
+export const glimmerVisitorKeys: Record<string, string[]>;

package/src/index.js

@@ -1,3 +1,3 @@
 export { toTree, parse } from "./parse.js";
 export { print } from "./print.js";
-export { buildGlimmerVisitorKeys, DocumentLines } from "./transforms.js";
+export { glimmerVisitorKeys, DocumentLines } from "./transforms.js";

package/src/parse.js

@@ -1,176 +1,340 @@
 /**
  * The Strategy:
  *
- * 1. parse out the <template>...</template> regions
- *    - we haven't shipped "content-tag" through TC39, so for now, gjs and gts are invalid JavaScript
- *
- * 2. create a new string/contents of the file with a placeholder for the template regisions
- *    - this will be used later to splice in the Template AST Nodes
- *    - the placeholder should be the same dimensions as the template region
- *
- * 3. parse the string/contents as js/ts to generate an ESTree
- *
- * 4. parse each template region to generate an AST from that
- *
- * 5. convert the AST from `@glimmer/syntax` to ESTree
- *    - NOTE: it may already be ESTree
- *
- * 6. splice in the template ESTrees into the JS/TS ESTree
- *
- * 7. Done
- */
-
-/**
- * Docs for dependencies:
- * - https://github.com/embroider-build/content-tag/
+ * 1. parse out the <template>...</template> regions (content-tag)
+ * 2. create placeholder JS for the template regions (backtick/static-block, same char length)
+ * 3. parse as js/ts — default: oxc-parser, or a custom parser via options
+ * 4. splice in processed Glimmer ASTs, invoking visitors during traversal
+ * 5. Merge Glimmer visitor keys into the result
+ * 6. Done
  */
 
 import { parseSync } from "oxc-parser";
-import templateRecast from "ember-template-recast";
 import { Preprocessor } from "content-tag";
 import { walk } from "zimmerframe";
 
-import { processGlimmerTemplate } from "./transforms.js";
+import { processTemplate, DocumentLines, glimmerVisitorKeys } from "./transforms.js";
 
 const preprocessor = new Preprocessor();
 
+// Node types that placeholders parse into (backtick/static-block format)
+const PLACEHOLDER_TYPES = new Set([
+  "ExpressionStatement",
+  "StaticBlock",
+  "TemplateLiteral",
+  "ExportDefaultDeclaration",
+]);
+
 /**
+ * Parse Ember source and return an ESTree-compatible AST.
+ *
  * @param {string} source
- * @param {object} options
- * @return {object} A File-like AST with a `.program` property
+ * @param {object} [options]
+ * @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
+ * @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);
+  }
+
   let parseResults = preprocessor.parse(source);
   let js = toPlaceholderJS(source, parseResults);
 
-  let filename = options.filePath || "input.ts";
-  let oxcResult = parseSync(filename, js);
-
-  // Wrap in a File-like node to match the expected structure
-  let outerAST = {
-    type: "File",
-    program: oxcResult.program,
-    comments: oxcResult.comments || [],
-    start: oxcResult.program.start,
-    end: oxcResult.program.end,
-  };
-
-  // content-tag v4 provides UTF-16 codepoint offsets that match
-  // JavaScript string indices and oxc-parser character offsets directly,
-  // so no byte-to-character conversion is needed.
-  outerAST = walk(outerAST, null, {
-    _(node, { next }) {
-      if (isExpressionPlaceholder(node) || isClassMemberPlaceholder(node)) {
-        let parseResult = parseResults.find((r) => {
-          return (
-            node.start === r.range.startUtf16Codepoint && node.end === r.range.endUtf16Codepoint
-          );
-        });
-
-        let content = parseResult.contents;
-        let templateAST = templateRecast.parse(content);
-
-        let contentOffset = parseResult.contentRange.startUtf16Codepoint;
-        let templateRange = [
-          parseResult.range.startUtf16Codepoint,
-          parseResult.range.endUtf16Codepoint,
-        ];
-
-        return processGlimmerTemplate(templateAST, {
-          contentOffset,
-          templateRange,
-          source,
-        });
+  const useCustomParser = !!options.parser;
+  const visitors = options.visitors || null;
+
+  // Parse the placeholder JS — use custom parser or default oxc
+  let result;
+  if (useCustomParser) {
+    result = options.parser(js);
+    if (!result.ast) {
+      result = { ast: result };
+    }
+  } else {
+    let filename = options.filePath || "input.ts";
+    let oxcResult = parseSync(filename, js);
+    result = {
+      ast: {
+        type: "File",
+        program: oxcResult.program,
+        comments: oxcResult.comments || [],
+        start: oxcResult.program.start,
+        end: oxcResult.program.end,
+      },
+    };
+  }
+
+  // If no templates, return early
+  if (!parseResults.length) {
+    if (useCustomParser) {
+      result.visitorKeys = { ...result.visitorKeys, ...glimmerVisitorKeys };
+      return result;
+    }
+    result.ast.visitorKeys = glimmerVisitorKeys;
+    return result.ast;
+  }
+
+  const codeLines = new DocumentLines(source);
+  const allComments = [];
+  const templateInfos = [];
+
+  // Build a map of template ranges for lookup
+  const templateRangeByStart = new Map(parseResults.map((r) => [r.range.startUtf16Codepoint, r]));
+
+  // Process a matched placeholder node: create Glimmer AST and tokens
+  function processPlaceholder(parseResult) {
+    let templateContent = parseResult.contents;
+    let contentRange = [
+      parseResult.contentRange.startUtf16Codepoint,
+      parseResult.contentRange.endUtf16Codepoint,
+    ];
+    let fullRange = [parseResult.range.startUtf16Codepoint, parseResult.range.endUtf16Codepoint];
+
+    const { ast, comments } = processTemplate(
+      templateContent,
+      codeLines,
+      contentRange,
+      templateOpts,
+    );
+
+    // Fix the Template root to cover the full <template>...</template> range
+    ast.range = fullRange;
+    ast.start = fullRange[0];
+    ast.end = fullRange[1];
+    ast.loc = {
+      start: codeLines.offsetToPosition(fullRange[0]),
+      end: codeLines.offsetToPosition(fullRange[1]),
+    };
+
+    // Add tokens for the <template> and </template> tags
+    const openEnd = contentRange[0];
+    const closeStart = contentRange[1];
+    const openTag = source.slice(fullRange[0], openEnd);
+    const closeTag = source.slice(closeStart, fullRange[1]);
+    const makeToken = (value, range) => ({
+      type: "Punctuator",
+      value,
+      range,
+      start: range[0],
+      end: range[1],
+      loc: {
+        start: codeLines.offsetToPosition(range[0]),
+        end: codeLines.offsetToPosition(range[1]),
+      },
+    });
+    ast.tokens = [
+      makeToken(openTag, [fullRange[0], openEnd]),
+      ...(ast.tokens || []),
+      makeToken(closeTag, [closeStart, fullRange[1]]),
+    ];
+
+    allComments.push(...comments);
+    templateInfos.push({ utf16Range: fullRange, ast });
+    return ast;
+  }
+
+  // Check if a node matches a template range
+  function matchPlaceholder(node) {
+    let range = node.range || [node.start, node.end];
+    if (node.type === "ExportDefaultDeclaration" && node.declaration) {
+      const decl = node.declaration;
+      range = decl.range || [decl.start, decl.end];
+    }
+    const parseResult = templateRangeByStart.get(range[0]);
+    if (
+      !parseResult ||
+      (parseResult.range.endUtf16Codepoint !== range[1] &&
+        parseResult.range.endUtf16Codepoint !== range[1] + 1)
+    ) {
+      return null;
+    }
+    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);
       }
-      next();
-    },
-  });
+    }
 
-  let ast = outerAST;
+    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);
+      }
+    }
+  }
 
-  return ast;
-}
+  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 || {};
 
-/**
- * Parse Ember .gjs/.gts source code into an ESTree-compatible AST
- * with embedded Glimmer template nodes.
- *
- * @param {string} source - The source code to parse
- * @param {object} [options] - Parse options
- * @return {object} The ESTree-compatible AST
- */
-export function parse(source, options = {}) {
-  let ast = toTree(source, options);
+    function visitNode(node, parentPath) {
+      if (!node || typeof node !== "object" || !node.type) return;
 
-  return ast;
-}
+      const path = { node, parent: parentPath?.node ?? null, parentPath };
 
-//////////////////////////////////////////////////
-//
-// Helpers
-//
-//////////////////////////////////////////////////
+      if (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;
+        }
+      }
 
-function isExpressionPlaceholder(node) {
-  if (node.type !== "CallExpression") return;
+      // 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);
+        }
+      }
+    }
 
-  return node.callee.name === "TEMPLATE_TEMPLATE";
-}
+    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);
+      }
+    }
+  }
 
-function isClassMemberPlaceholder(node) {
-  if (node.type !== "PropertyDefinition") return;
+  // Splice template tokens into the AST token stream.
+  // Tokens are sorted by range, so use binary search for O(log n) lookup.
+  const astRoot = result.ast.program || result.ast;
+  if (astRoot.tokens) {
+    for (const ti of templateInfos) {
+      const [tStart, tEnd] = ti.utf16Range;
+      const tokens = astRoot.tokens;
+      // Binary search for first token with range[0] >= tStart
+      let lo = 0;
+      let hi = tokens.length;
+      while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (tokens[mid].range[0] < tStart) lo = mid + 1;
+        else hi = mid;
+      }
+      const firstIdx = lo;
+      if (firstIdx >= tokens.length || tokens[firstIdx].range[0] >= tEnd) continue;
+      let lastIdx = firstIdx;
+      while (lastIdx < tokens.length && tokens[lastIdx].range[1] <= tEnd) {
+        lastIdx++;
+      }
+      tokens.splice(firstIdx, lastIdx - firstIdx, ...ti.ast.tokens);
+    }
+  }
 
-  return (
-    node.computed && node.key?.type === "CallExpression" && node.key.callee?.name === "_TEMPLATE_"
-  );
+  // Merge comments
+  if (allComments.length) {
+    if (!astRoot.comments) astRoot.comments = [];
+    astRoot.comments.push(...allComments);
+  }
+
+  if (useCustomParser) {
+    result.visitorKeys = { ...result.visitorKeys, ...glimmerVisitorKeys };
+    result.templateInfos = templateInfos;
+    return result;
+  }
+
+  // Default path: return bare AST with visitorKeys attached
+  result.ast.visitorKeys = glimmerVisitorKeys;
+  return result.ast;
 }
 
+export const parse = toTree;
+
+// ── Placeholder JS ────────────────────────────────────────────────────
+
 /**
- * Replaces <template>...</template> regions in source with
- * placeholder expressions of the same character length that
- * are valid JavaScript, so oxc-parser can parse them.
- *
- * Expression templates become:  TEMPLATE_TEMPLATE(`...`)
- * Class member templates become: [_TEMPLATE_(`...`)] = 0;
+ * Replaces <template>...</template> regions with placeholder expressions
+ * of the same character length that are valid JS/TS.
  *
- * Both placeholder forms use exactly 21 characters for the
- * opening + closing wrappers, matching the original
- * <template> (10) + </template> (11) = 21 character overhead.
+ * Expression templates become:  `content          ` (backtick, space-padded)
+ * Class member templates become: static{`content  `} (static block, space-padded)
  *
- * @param {string} source
- * @param {Array<object>} parseResults
- * @returns {string}
+ * This format is compatible with all JS/TS parsers including
+ * oxc-parser, @typescript-eslint/parser, and @babel/eslint-parser.
  */
 function toPlaceholderJS(source, parseResults) {
-  let result = source;
-  let offset = 0;
-
-  for (let pr of parseResults) {
-    let start = pr.range.startUtf16Codepoint;
-    let end = pr.range.endUtf16Codepoint;
-
-    let openingTag, closingTag;
-    switch (pr.type) {
-      case "expression":
-        openingTag = "TEMPLATE_TEMPLATE(`";
-        closingTag = "`)";
-        break;
-      case "class-member":
-        openingTag = "[_TEMPLATE_(`";
-        closingTag = "`)] = 0;";
-        break;
-    }
+  // Build result in forward order using parts array (avoids intermediate string allocations)
+  const parts = [];
+  let cursor = 0;
 
-    let content = source.slice(
-      pr.contentRange.startUtf16Codepoint,
-      pr.contentRange.endUtf16Codepoint,
-    );
+  for (const pr of parseResults) {
+    const start = pr.range.startUtf16Codepoint;
+    const end = pr.range.endUtf16Codepoint;
+    const tplLength = end - start;
+
+    parts.push(source.slice(cursor, start));
 
-    let replacement = openingTag + content + closingTag;
+    const content = source
+      .slice(pr.contentRange.startUtf16Codepoint, pr.contentRange.endUtf16Codepoint)
+      .replace(/`/g, "\\`")
+      .replace(/\$/g, "\\$");
+
+    if (pr.type === "class-member") {
+      const spaces = tplLength - content.length - 10; // "static{`" + "`}" = 10
+      parts.push(`static{\`${content}${" ".repeat(Math.max(0, spaces))}\`}`);
+    } else {
+      const spaces = tplLength - content.length - 2; // "`" + "`" = 2
+      parts.push(`\`${content}${" ".repeat(Math.max(0, spaces))}\``);
+    }
 
-    result = result.slice(0, start + offset) + replacement + result.slice(end + offset);
-    offset += replacement.length - (end - start);
+    cursor = end;
   }
 
-  return result;
+  parts.push(source.slice(cursor));
+  return parts.join("");
 }

package/src/transforms.js

@@ -1,18 +1,11 @@
 /**
  * Glimmer AST → ESTree transform utilities.
- *
- * Ported from ember-eslint-parser's transforms.js, adapted for
- * ember-estree's ESM architecture. Handles:
- *
- *  - Type prefixing (all Glimmer types get a "Glimmer" prefix)
- *  - Range / loc fixing (converts template-local positions to file-level)
- *  - ElementNode `parts` and `name` fields
- *  - blockParams → virtual node creation
- *  - Empty hash nullification
- *  - Empty text node removal
  */
 
-import { traverse, visitorKeys as glimmerVisitorKeys } from "@glimmer/syntax";
+import {
+  visitorKeys as rawGlimmerVisitorKeys,
+  preprocess as glimmerPreprocess,
+} from "@glimmer/syntax";
 
 /**
  * Converts between character offsets and line/column positions.
@@ -45,38 +38,65 @@ export class DocumentLines {
 }
 
 /**
- * Traverse a Glimmer AST, set parent references, and categorize nodes.
+ * Glimmer visitor keys map with "Glimmer" prefix.
+ * Computed once at module load.
  */
-function collectNodes(ast) {
-  const allNodes = [];
-  const comments = [];
-  const textNodes = [];
-  const emptyTextNodes = [];
+export const glimmerVisitorKeys = (() => {
+  const keys = {};
+  for (const [k, v] of Object.entries(rawGlimmerVisitorKeys)) {
+    keys[`Glimmer${k}`] = v;
+  }
+  keys.GlimmerElementNode = [...keys.GlimmerElementNode, "blockParamNodes", "parts"];
+  keys.GlimmerProgram = ["body", "blockParamNodes"];
+  keys.GlimmerTemplate = ["body"];
+  return keys;
+})();
 
-  traverse(ast, {
-    All(node, path) {
-      node.parent = path.parentNode;
-      allNodes.push(node);
-      if (node.type === "CommentStatement" || node.type === "MustacheCommentStatement") {
-        comments.push(node);
-      }
-      if (node.type === "TextNode") {
-        node.value = node.chars;
-        if (node.value.trim().length !== 0 || (node.parent && node.parent.type === "AttrNode")) {
-          textNodes.push(node);
-        } else {
-          emptyTextNodes.push(node);
+// ── Internal helpers ──────────────────────────────────────────────────
+
+/**
+ * Recursively collect all nodes in a Glimmer AST using visitor keys.
+ * Sets parent references during traversal.
+ */
+function collectNodes(node, parent, allNodes, comments, textNodes, emptyTextNodes) {
+  node.parent = parent;
+  allNodes.push(node);
+  if (node.type === "CommentStatement" || node.type === "MustacheCommentStatement") {
+    comments.push(node);
+  }
+  if (node.type === "TextNode") {
+    node.value = node.chars;
+    if (node.value.trim().length !== 0 || (parent && parent.type === "AttrNode")) {
+      textNodes.push(node);
+    } else {
+      emptyTextNodes.push(node);
+    }
+  }
+  const keys = rawGlimmerVisitorKeys[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) {
+          collectNodes(item, node, allNodes, comments, textNodes, emptyTextNodes);
         }
       }
-    },
-  });
+    } else if (typeof child === "object" && child.type) {
+      collectNodes(child, node, allNodes, comments, textNodes, emptyTextNodes);
+    }
+  }
+}
 
-  return { allNodes, comments, textNodes, emptyTextNodes };
+// Reusable descriptor — shadows prototype getters with own properties.
+// @glimmer/syntax nodes have getter chains that cause esrecurse infinite recursion.
+const _desc = { value: undefined, configurable: true, enumerable: true, writable: true };
+function defOwn(obj, key, val) {
+  _desc.value = val;
+  Object.defineProperty(obj, key, _desc);
 }
 
-/**
- * Remove nodes from their parent's children/body/parts arrays.
- */
 function removeFromParent(nodes) {
   for (const node of nodes) {
     const children =
@@ -88,117 +108,182 @@ function removeFromParent(nodes) {
   }
 }
 
-/**
- * Build the Glimmer visitor keys map with "Glimmer" prefix.
- * Uses the visitor keys exported by @glimmer/syntax.
- */
-let _cachedGlimmerVisitorKeys = null;
-export function buildGlimmerVisitorKeys() {
-  if (_cachedGlimmerVisitorKeys) return _cachedGlimmerVisitorKeys;
-  const keys = {};
-  for (const [k, v] of Object.entries(glimmerVisitorKeys)) {
-    keys[`Glimmer${k}`] = [...v];
+function isAlphaNumeric(code) {
+  return !(!(code > 47 && code < 58) && !(code > 64 && code < 91) && !(code > 96 && code < 123));
+}
+
+function isWhiteSpaceCode(code) {
+  return code === 32 || code === 9 || code === 13 || code === 10 || code === 11;
+}
+
+function tokenize(template, doc, startOffset) {
+  const tokens = [];
+  let wordStart = -1;
+  function pushToken(value, type, range) {
+    tokens.push({
+      type,
+      value,
+      range,
+      start: range[0],
+      end: range[1],
+      loc: {
+        start: { ...doc.offsetToPosition(range[0]), index: range[0] },
+        end: { ...doc.offsetToPosition(range[1]), index: range[1] },
+      },
+    });
+  }
+  for (let i = 0; i < template.length; i++) {
+    const code = template.charCodeAt(i);
+    if (isAlphaNumeric(code)) {
+      if (wordStart < 0) wordStart = i;
+    } else {
+      if (wordStart >= 0) {
+        pushToken(template.slice(wordStart, i), "word", [startOffset + wordStart, startOffset + i]);
+        wordStart = -1;
+      }
+      if (!isWhiteSpaceCode(code)) {
+        pushToken(template[i], "Punctuator", [startOffset + i, startOffset + i + 1]);
+      }
+    }
   }
-  if (!keys.GlimmerElementNode.includes("blockParamNodes")) {
-    keys.GlimmerElementNode.push("blockParamNodes", "parts");
+  if (wordStart >= 0) {
+    pushToken(template.slice(wordStart), "word", [
+      startOffset + wordStart,
+      startOffset + template.length,
+    ]);
   }
-  keys.GlimmerProgram = ["body", "blockParamNodes"];
-  keys.GlimmerTemplate = ["body"];
-  _cachedGlimmerVisitorKeys = keys;
-  return keys;
+  return tokens;
+}
+
+function buildTokenStream(rawTokens, comments, textNodes) {
+  const commentIntervals = comments.map((c) => c.range).sort((a, b) => a[0] - b[0]);
+  const textNodeIntervals = textNodes.map((t) => t.range).sort((a, b) => a[0] - b[0]);
+
+  function isCovered(tokenRange, intervals) {
+    let lo = 0;
+    let hi = intervals.length - 1;
+    while (lo <= hi) {
+      const mid = (lo + hi) >> 1;
+      const iv = intervals[mid];
+      if (iv[0] <= tokenRange[0] && iv[1] >= tokenRange[1]) return true;
+      if (iv[0] > tokenRange[0]) hi = mid - 1;
+      else lo = mid + 1;
+    }
+    return false;
+  }
+
+  const filteredTokens = rawTokens.filter(
+    (t) => !isCovered(t.range, commentIntervals) && !isCovered(t.range, textNodeIntervals),
+  );
+
+  const sortedTextNodes = [...textNodes].sort((a, b) => a.range[0] - b.range[0]);
+  const result = [];
+  let ti = 0;
+  for (const token of filteredTokens) {
+    while (ti < sortedTextNodes.length && sortedTextNodes[ti].range[0] < token.range[0]) {
+      result.push(sortedTextNodes[ti++]);
+    }
+    result.push(token);
+  }
+  while (ti < sortedTextNodes.length) {
+    result.push(sortedTextNodes[ti++]);
+  }
+  return result;
 }
 
 /**
- * Process a Glimmer AST into an ESTree-compatible form.
- *
- * @param {object} templateAST - The Glimmer AST (from ember-template-recast / @glimmer/syntax)
- * @param {object} opts
- * @param {number} opts.contentOffset - Byte offset where the template content begins in the full source
- * @param {[number, number]} opts.templateRange - [start, end] byte range of the full <template>...</template> block
- * @param {string} opts.source - The full source code
- * @returns {object} The transformed AST
+ * Parse and transform a Glimmer template into an ESTree-compatible AST.
+ * Internal — consumed by toTree.
  */
-export function processGlimmerTemplate(templateAST, { contentOffset, templateRange, source }) {
-  // The Glimmer AST locs are relative to the inner template content only
-  const closingTagLen = "</template>".length;
-  const contentEnd = templateRange[1] - closingTagLen;
-  const contentStr = source.substring(contentOffset, contentEnd);
-  const contentDoc = new DocumentLines(contentStr);
-  const sourceDoc = new DocumentLines(source);
-
-  const toFileRange = (loc) => {
-    const locObj = loc.toJSON ? loc.toJSON() : loc;
-    return [
-      contentOffset + contentDoc.positionToOffset(locObj.start),
-      contentOffset + contentDoc.positionToOffset(locObj.end),
-    ];
-  };
+export function processTemplate(
+  templateContent,
+  codeLines,
+  templateRange,
+  { includeParentLinks = true } = {},
+) {
+  const offset = templateRange[0];
+  const docLines = new DocumentLines(templateContent);
 
+  const toFileRange = (loc) => [
+    offset + docLines.positionToOffset(loc.start),
+    offset + docLines.positionToOffset(loc.end),
+  ];
   const toFileLoc = (range) => ({
-    start: sourceDoc.offsetToPosition(range[0]),
-    end: sourceDoc.offsetToPosition(range[1]),
+    start: codeLines.offsetToPosition(range[0]),
+    end: codeLines.offsetToPosition(range[1]),
   });
 
-  const { allNodes, comments, emptyTextNodes } = collectNodes(templateAST);
+  const ast = glimmerPreprocess(templateContent, { mode: "codemod" });
+  const allNodes = [];
+  const comments = [];
+  const textNodes = [];
+  const emptyTextNodes = [];
+  collectNodes(ast, null, allNodes, comments, textNodes, emptyTextNodes);
 
   for (const n of allNodes) {
-    const loc = n.loc.toJSON ? n.loc.toJSON() : n.loc;
-
-    // Fix PathExpression head
     if (n.type === "PathExpression") {
-      const head = n.head;
-      if (head && head.loc) {
-        const headLoc = head.loc.toJSON ? head.loc.toJSON() : head.loc;
-        if (headLoc && headLoc.start) {
-          head.range = toFileRange(headLoc);
-          head.start = head.range[0];
-          head.end = head.range[1];
-          head.loc = toFileLoc(head.range);
-        }
-      }
+      n.head.range = toFileRange(n.head.loc);
+      n.head.start = n.head.range[0];
+      n.head.end = n.head.range[1];
+      n.head.loc = toFileLoc(n.head.range);
     }
 
-    // Set range — Template root gets the full <template>...</template> range
-    n.range = n.type === "Template" ? [...templateRange] : toFileRange(loc);
+    n.range = n.type === "Template" ? [...templateRange] : toFileRange(n.loc);
     n.start = n.range[0];
     n.end = n.range[1];
     n.loc = toFileLoc(n.range);
 
-    // Add parts and name to ElementNode
     if (n.type === "ElementNode") {
+      defOwn(n, "tag", n.tag);
       n.name = n.tag;
-      // Compute the tag name range: starts 1 char after element start (<), length = tag.length
-      const tagStart = n.range[0] + 1; // skip "<"
-      const tagEnd = tagStart + n.tag.length;
-      const tagRange = [tagStart, tagEnd];
+      const p = n.path.head;
+      defOwn(p, "name", p.name);
+      defOwn(p, "original", p.original);
+      const partRange = toFileRange(p.loc);
       n.parts = [
         {
-          original: n.tag,
-          name: n.tag,
           type: "GlimmerElementNodePart",
-          range: tagRange,
-          start: tagRange[0],
-          end: tagRange[1],
-          loc: toFileLoc(tagRange),
+          original: p.original,
+          name: p.original,
+          parent: n,
+          range: partRange,
+          start: partRange[0],
+          end: partRange[1],
+          loc: toFileLoc(partRange),
         },
       ];
     }
 
-    // Handle blockParams — create virtual nodes from the blockParams string array
     if ("blockParams" in n && Array.isArray(n.blockParams)) {
-      n.blockParamNodes = n.blockParams.map((name) => {
-        return {
+      if (n.params && n.params.length === n.blockParams.length) {
+        n.blockParamNodes = n.params.map((p) => {
+          defOwn(p, "name", p.name);
+          defOwn(p, "original", p.original);
+          const range = toFileRange(p.loc);
+          return {
+            type: "GlimmerBlockParam",
+            name: p.original || p.name,
+            original: p.original,
+            parent: n,
+            range,
+            start: range[0],
+            end: range[1],
+            loc: toFileLoc(range),
+          };
+        });
+      } else {
+        n.blockParamNodes = n.blockParams.map((name) => ({
           type: "GlimmerBlockParam",
           name,
-          range: [...n.range],
+          parent: n,
+          range: [n.range[0], n.range[1]],
           start: n.range[0],
           end: n.range[1],
           loc: toFileLoc(n.range),
-        };
-      });
+        }));
+      }
     }
 
-    // Nullify empty hashes
     if (
       (n.type === "MustacheStatement" ||
         n.type === "BlockStatement" ||
@@ -210,21 +295,31 @@ export function processGlimmerTemplate(templateAST, { contentOffset, templateRan
       n.hash = null;
     }
 
-    // Prefix type with "Glimmer"
     n.type = `Glimmer${n.type}`;
+
+    // Snapshot PathExpression.head getters (name/original)
+    if (n.type === "GlimmerPathExpression" && n.head) {
+      defOwn(n.head, "name", n.head.name);
+      defOwn(n.head, "original", n.head.original);
+    }
   }
 
-  // Clean up AST structure
   removeFromParent(emptyTextNodes);
   removeFromParent(comments);
   for (const comment of comments) {
     comment.type = "Block";
   }
 
-  // Clear parent references (they cause circular JSON issues)
-  for (const n of allNodes) {
-    n.parent = null;
+  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 templateAST;
+  return { ast, comments };
 }