ember-estree 0.0.0 → 0.1.1

package/README.md

@@ -1 +1,71 @@
 # ember-estree
+
+ESTree-compatible AST parser for Ember's `.gjs` and `.gts` files.
+
+Parses `<template>` tags into [Glimmer](https://github.com/emberjs/ember.js/) AST nodes that are embedded directly in the ESTree, so tools like linters and codemods can work with both the JavaScript/TypeScript _and_ template portions of a single file.
+
+## Install
+
+```bash
+pnpm add ember-estree
+```
+
+## Usage
+
+### Parsing
+
+`toTree` returns a `File` node whose `.program` is a standard ESTree `Program`, with any `<template>` regions represented as `Glimmer*` AST nodes.
+
+```js
+import { toTree } from "ember-estree";
+
+let ast = toTree(`
+  import Component from "@glimmer/component";
+
+  export default class Demo extends Component {
+    <template>Hello, {{this.name}}!</template>
+  }
+`);
+
+console.log(ast.type); // "File"
+console.log(ast.program.body.length); // 2 — ImportDeclaration + ClassDeclaration
+```
+
+`parse` is a lower-level alternative that returns the `Program` node directly.
+
+```js
+import { parse } from "ember-estree";
+
+let program = parse(`const x = <template>hi</template>;`);
+console.log(program.type); // "Program"
+```
+
+### Printing
+
+`print` converts an AST node (ESTree _or_ Glimmer) back to source code.
+
+```js
+import { print } from "ember-estree";
+
+print({ type: "Identifier", name: "foo" });
+// => "foo"
+
+print({
+  type: "GlimmerTemplate",
+  body: [{ type: "GlimmerTextNode", chars: "Hello" }],
+});
+// => "<template>Hello</template>"
+```
+
+## Examples
+
+The [`examples/`](./examples) directory contains ready-to-run integrations:
+
+| Example                                     | Description                                                          |
+| ------------------------------------------- | -------------------------------------------------------------------- |
+| [`eslint-parser`](./examples/eslint-parser) | Custom ESLint parser that understands `<template>`                   |
+| [`zmod`](./examples/zmod)                   | Codemod toolkit using [zmod](https://github.com/nicolo-ribaudo/zmod) |
+
+## License
+
+MIT

package/package.json

@@ -1,25 +1,51 @@
 {
   "name": "ember-estree",
-  "version": "0.0.0",
+  "version": "0.1.1",
   "description": "ESTree generator for gjs and gts file used by ember",
+  "keywords": [
+    "AST",
+    "codemod",
+    "ember",
+    "estree",
+    "glimmer",
+    "traversal",
+    "walker"
+  ],
+  "license": "MIT",
+  "author": "NullVoxPopuli",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:NullVoxPopuli/ember-estree.git"
+  },
+  "files": [
+    "src"
+  ],
   "type": "module",
-  "main": "index.js",
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
   "dependencies": {
-    "@babel/core": "^7.28.4",
-    "@babel/parser": "^7.28.4",
-    "@babel/plugin-transform-typescript": "^7.28.0",
     "@glimmer/syntax": "^0.95.0",
-    "content-tag": "^4.0.0",
-    "content-tag-utils": "^0.4.1",
-    "decorator-transforms": "^2.3.0"
+    "content-tag-utils": "^0.5.1",
+    "ember-template-recast": "^6.1.5",
+    "oxc-parser": "^0.119.0",
+    "zimmerframe": "^1.1.4"
   },
   "devDependencies": {
+    "@tsconfig/node-lts": "^22.0.2",
+    "oxfmt": "^0.40.0",
+    "oxlint": "^1.55.0",
+    "publint": "^0.3.18",
+    "release-plan": "^0.17.4",
+    "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "format": "oxfmt",
+    "format:check": "oxfmt --check",
+    "lint": "oxlint && pnpm format:check && publint",
+    "lint:fix": "oxlint --fix && oxfmt",
+    "test": "vitest run"
   }
 }

package/src/index.js

@@ -1,15 +1,3 @@
-/**
- * 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
- */
+export { toTree, parse } from "./parse.js";
+export { print } from "./print.js";
+export { buildGlimmerVisitorKeys, DocumentLines } from "./transforms.js";

package/src/parse.js

@@ -0,0 +1,111 @@
+/**
+ * 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/
+ */
+
+import { parseSync } from "oxc-parser";
+import templateRecast from "ember-template-recast";
+import { Transformer } from "content-tag-utils";
+import { walk } from "zimmerframe";
+
+import { processGlimmerTemplate } from "./transforms.js";
+
+/**
+ * @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 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,
+  };
+
+  let parseResults = t.parseResults;
+
+  outerAST = walk(outerAST, null, {
+    _(node, { next }) {
+      if (isExpressionPlaceholder(node)) {
+        let parseResult = parseResults.find((r) => {
+          // WARNING: these are byte ranges
+          return node.start === r.range.start && node.end === r.range.end;
+        });
+
+        let content = t.stringUtils.originalContentOf(parseResult);
+        let templateAST = templateRecast.parse(content);
+
+        let contentOffset = parseResult.contentRange.start;
+        let templateRange = [parseResult.range.start, parseResult.range.end];
+
+        return processGlimmerTemplate(templateAST, {
+          contentOffset,
+          templateRange,
+          source,
+        });
+      }
+      next();
+    },
+  });
+
+  let ast = outerAST;
+
+  return ast;
+}
+
+/**
+ * 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);
+
+  return ast;
+}
+
+//////////////////////////////////////////////////
+//
+// Helpers
+//
+//////////////////////////////////////////////////
+
+function isExpressionPlaceholder(node) {
+  if (node.type !== "CallExpression") return;
+
+  return node.callee.name === "TEMPLATE_TEMPLATE";
+}