ember-estree 0.1.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-estree",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "ESTree generator for gjs and gts file used by ember",
   "keywords": [
     "AST",
@@ -22,12 +22,16 @@
   ],
   "type": "module",
   "main": "src/index.js",
+  "types": "src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "dependencies": {
     "@glimmer/syntax": "^0.95.0",
-    "content-tag-utils": "^0.5.1",
+    "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

@@ -0,0 +1,104 @@
+/**
+ * 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;
+  end?: number;
+  [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 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 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[]>;
+
+/**
+ * Recursively remove all `parent` references from an AST.
+ * Useful when you need to serialize the tree to JSON,
+ * since parent back-references create circular structures.
+ *
+ * Mutates the tree in place and returns it.
+ */
+export function removeParentReferences(ast: ASTNode): ASTNode;

package/src/index.js

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

package/src/parse.js

@@ -27,19 +27,21 @@
 
 import { parseSync } from "oxc-parser";
 import templateRecast from "ember-template-recast";
-import { Transformer } from "content-tag-utils";
+import { Preprocessor } from "content-tag";
 import { walk } from "zimmerframe";
 
 import { processGlimmerTemplate } from "./transforms.js";
 
+const preprocessor = new Preprocessor();
+
 /**
  * @param {string} source
  * @param {object} options
  * @return {object} A File-like AST with a `.program` property
  */
 export function toTree(source, options = {}) {
-  let t = new Transformer(source);
-  let js = t.toString({ placeholders: true });
+  let parseResults = preprocessor.parse(source);
+  let js = toPlaceholderJS(source, parseResults);
 
   let filename = options.filePath || "input.ts";
   let oxcResult = parseSync(filename, js);
@@ -53,21 +55,26 @@ export function toTree(source, options = {}) {
     end: oxcResult.program.end,
   };
 
-  let parseResults = t.parseResults;
-
+  // 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) => {
-          // WARNING: these are byte ranges
-          return node.start === r.range.start && node.end === r.range.end;
+          return (
+            node.start === r.range.startUtf16Codepoint && node.end === r.range.endUtf16Codepoint
+          );
         });
 
-        let content = t.stringUtils.originalContentOf(parseResult);
+        let content = parseResult.contents;
         let templateAST = templateRecast.parse(content);
 
-        let contentOffset = parseResult.contentRange.start;
-        let templateRange = [parseResult.range.start, parseResult.range.end];
+        let contentOffset = parseResult.contentRange.startUtf16Codepoint;
+        let templateRange = [
+          parseResult.range.startUtf16Codepoint,
+          parseResult.range.endUtf16Codepoint,
+        ];
 
         return processGlimmerTemplate(templateAST, {
           contentOffset,
@@ -117,3 +124,53 @@ function isClassMemberPlaceholder(node) {
     node.computed && node.key?.type === "CallExpression" && node.key.callee?.name === "_TEMPLATE_"
   );
 }
+
+/**
+ * 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;
+ *
+ * Both placeholder forms use exactly 21 characters for the
+ * opening + closing wrappers, matching the original
+ * <template> (10) + </template> (11) = 21 character overhead.
+ *
+ * @param {string} source
+ * @param {Array<object>} parseResults
+ * @returns {string}
+ */
+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;
+    }
+
+    let content = source.slice(
+      pr.contentRange.startUtf16Codepoint,
+      pr.contentRange.endUtf16Codepoint,
+    );
+
+    let replacement = openingTag + content + closingTag;
+
+    result = result.slice(0, start + offset) + replacement + result.slice(end + offset);
+    offset += replacement.length - (end - start);
+  }
+
+  return result;
+}

package/src/transforms.js

@@ -221,10 +221,5 @@ export function processGlimmerTemplate(templateAST, { contentOffset, templateRan
     comment.type = "Block";
   }
 
-  // Clear parent references (they cause circular JSON issues)
-  for (const n of allNodes) {
-    n.parent = null;
-  }
-
   return templateAST;
 }

package/src/utils.js

@@ -0,0 +1,22 @@
+/**
+ * Optional utility functions for working with ESTree ASTs
+ * produced by ember-estree.
+ */
+
+import { walk } from "zimmerframe";
+
+/**
+ * Recursively remove all `parent` references from an AST.
+ * Useful when you need to serialize the tree to JSON (e.g. for zmod),
+ * since parent back-references create circular structures.
+ *
+ * Mutates the tree in place and returns it.
+ */
+export function removeParentReferences(ast) {
+  return walk(ast, null, {
+    _(node, { next }) {
+      delete node.parent;
+      next();
+    },
+  });
+}