ember-eslint-parser 0.5.13 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # ember-eslint-parser
 
-This is the eslint parser for ember's gjs and gts files (using `<template>`).
+This is the eslint parser for ember's gjs and gts files (using `<template>`), and also for Handlebars (`.hbs`) template files.
 
 It is meant to be used with [eslint-plugin-ember](https://github.com/ember-cli/eslint-plugin-ember), which provides nice defaults for all the different file types in ember projects.
 
@@ -31,6 +31,26 @@ It's recommended to only use _overrides_ when defining your eslint config, so us
 if we detect a typescript parser, it will also be used for all files, otherwise babel parser will be used.
 If we cannot find a typescript parser when linting gts we throw an error. 
 
+## HBS (Handlebars) support
+
+For `.hbs` template files, use the `ember-eslint-parser/hbs` parser. In ESLint's flat config format (ESLint 9+):
+
+```js
+// eslint.config.mjs
+import hbsParser from 'ember-eslint-parser/hbs';
+
+export default [
+  {
+    files: ['**/*.hbs'],
+    languageOptions: {
+      parser: hbsParser,
+    },
+  },
+];
+```
+
+> **Note:** In `.hbs` files, all locals not defined in the template are assumed to be defined at runtime. This avoids false-positive `no-undef` errors for template identifiers. This is a known limitation of the classic HBS format — use `.gjs`/`.gts` for full static analysis.
+
 ## Support
 
 eslint-plugin-ember is the primary consumer of this parser library, so SemVer _may_ not be respected for other consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-eslint-parser",
-  "version": "0.5.13",
+  "version": "0.6.0",
   "description": "",
   "keywords": [],
   "repository": {
@@ -11,6 +11,7 @@
   "author": "",
   "exports": {
     ".": "./src/parser/gjs-gts-parser.js",
+    "./hbs": "./src/parser/hbs-parser.js",
     "./noop": "./src/preprocessor/noop.js"
   },
   "main": "src/parser/gjs-gts-parser.js",
@@ -44,7 +45,7 @@
     "fs-extra": "^11.2.0",
     "prettier": "^3.2.5",
     "publint": "^0.2.6",
-    "release-plan": "^0.16.0",
+    "release-plan": "^0.17.4",
     "typescript": "^5.3.3",
     "vite": "^5.0.12",
     "vitest": "^1.2.2"

package/src/parser/hbs-parser.js

@@ -0,0 +1,89 @@
+const eslintScope = require('eslint-scope');
+const DocumentLines = require('../utils/document');
+const { processGlimmerTemplate, buildGlimmerVisitorKeys } = require('./transforms');
+
+/**
+ * implements https://eslint.org/docs/latest/extend/custom-parsers
+ * for Handlebars (.hbs) template files.
+ *
+ * The entire file is treated as a Glimmer template.
+ * All locals not defined in the template are assumed to be defined
+ * (no no-undef errors for template identifiers).
+ */
+
+/**
+ * @type {import('eslint').ParserModule}
+ */
+module.exports = {
+  meta: {
+    name: 'ember-eslint-parser/hbs',
+    version: '*',
+  },
+
+  parseForESLint(code, options) {
+    const filePath = (options && options.filePath) || '<hbs>';
+    const codeLines = new DocumentLines(code);
+
+    let result;
+    try {
+      result = processGlimmerTemplate({
+        templateContent: code,
+        codeLines,
+        templateRange: [0, code.length],
+      });
+    } catch (e) {
+      // Transform glimmer parse error to ESLint-compatible error
+      const loc = e.location || (e.hash && e.hash.loc);
+      if (loc && loc.start) {
+        const err = Object.assign(new SyntaxError(e.message), {
+          lineNumber: loc.start.line,
+          column: loc.start.column,
+          index: codeLines.positionToOffset(loc.start),
+          fileName: filePath,
+        });
+        throw err;
+      }
+      throw e;
+    }
+
+    const { ast: templateNode, comments } = result;
+
+    // Wrap in a synthetic Program node (required by ESLint)
+    const program = {
+      type: 'Program',
+      body: [templateNode],
+      tokens: templateNode.tokens,
+      comments,
+      range: [0, code.length],
+      start: 0,
+      end: code.length,
+      loc: {
+        start: { line: 1, column: 0 },
+        end: codeLines.offsetToPosition(code.length),
+      },
+    };
+
+    // Build visitor keys: Program + all Glimmer node types
+    const visitorKeys = { Program: ['body'], ...buildGlimmerVisitorKeys() };
+
+    // Create an empty scope manager.
+    // For HBS, all locals are assumed to be defined at runtime,
+    // so we don't track variable references (no no-undef errors).
+    const scopeManager = eslintScope.analyze(
+      {
+        type: 'Program',
+        body: [],
+        range: [0, code.length],
+        loc: program.loc,
+      },
+      { range: true }
+    );
+
+    return {
+      ast: program,
+      scopeManager,
+      visitorKeys,
+      services: {},
+    };
+  },
+};

package/src/parser/transforms.js

@@ -1,7 +1,7 @@
 const ContentTag = require('content-tag');
 const glimmer = require('@glimmer/syntax');
+const { visitorKeys: glimmerVisitorKeys } = glimmer;
 const DocumentLines = require('../utils/document');
-const { visitorKeys: glimmerVisitorKeys } = require('@glimmer/syntax');
 const { Reference, Scope, Variable, Definition } = require('eslint-scope');
 const htmlTags = require('html-tags');
 const svgTags = require('svg-tags');
@@ -112,6 +112,24 @@ function registerNodeInScope(node, scope, variable) {
   scope.references.push(ref);
 }
 
+/**
+ * Builds the complete Glimmer visitor keys map with "Glimmer" prefix and
+ * additional keys needed for traversal (blockParamNodes, parts, etc).
+ * @return {object}
+ */
+function buildGlimmerVisitorKeys() {
+  const keys = {};
+  for (const [k, v] of Object.entries(glimmerVisitorKeys)) {
+    keys[`Glimmer${k}`] = [...v];
+  }
+  if (!keys.GlimmerElementNode.includes('blockParamNodes')) {
+    keys.GlimmerElementNode.push('blockParamNodes', 'parts');
+  }
+  keys.GlimmerProgram = ['body', 'blockParamNodes'];
+  keys.GlimmerTemplate = ['body'];
+  return keys;
+}
+
 /**
  * traverses all nodes using the {visitorKeys} calling the callback function, visitor
  * @param visitorKeys
@@ -119,7 +137,7 @@ function registerNodeInScope(node, scope, variable) {
  * @param visitor
  */
 function traverse(visitorKeys, node, visitor) {
-  const allVisitorKeys = visitorKeys;
+  const allVisitorKeys = { ...visitorKeys, ...buildGlimmerVisitorKeys() };
   const queue = [];
 
   queue.push({
@@ -137,17 +155,7 @@ function traverse(visitorKeys, node, visitor) {
 
     if (!currentPath.node) continue;
 
-    const visitorKeys = [...(allVisitorKeys[currentPath.node.type] || [])];
-    if (currentPath.node.type === 'GlimmerElementNode') {
-      if (!visitorKeys.includes('blockParamNodes')) {
-        visitorKeys.push('blockParamNodes', 'parts');
-      }
-    }
-    if (currentPath.node.type === 'GlimmerProgram') {
-      if (!visitorKeys.includes('blockParamNodes')) {
-        visitorKeys.push('blockParamNodes');
-      }
-    }
+    const visitorKeys = allVisitorKeys[currentPath.node.type];
     if (!visitorKeys) {
       continue;
     }
@@ -242,6 +250,187 @@ function tokenize(template, doc, startOffset) {
   return tokens;
 }
 
+/**
+ * Traverses a Glimmer AST, sets parent references, and categorizes nodes.
+ * @param {object} ast
+ * @return {{ allNodes: object[], comments: object[], textNodes: object[], emptyTextNodes: object[] }}
+ */
+function collectNodes(ast) {
+  const allNodes = [];
+  const comments = [];
+  const textNodes = [];
+  const emptyTextNodes = [];
+
+  glimmer.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);
+        }
+      }
+    },
+  });
+
+  return { allNodes, comments, textNodes, emptyTextNodes };
+}
+
+/**
+ * Removes nodes from their parent's children/body/parts arrays.
+ * @param {object[]} nodes
+ */
+function removeFromParent(nodes) {
+  for (const node of nodes) {
+    const children =
+      (node.parent && (node.parent.children || node.parent.body || node.parent.parts)) || [];
+    const idx = children.indexOf(node);
+    if (idx >= 0) {
+      children.splice(idx, 1);
+    }
+  }
+}
+
+/**
+ * Builds the final token stream by filtering out tokens covered by comments
+ * or text nodes, then merging text nodes back in sorted order.
+ * @param {object[]} rawTokens
+ * @param {object[]} comments
+ * @param {object[]} textNodes
+ * @return {object[]}
+ */
+function buildTokenStream(rawTokens, comments, textNodes) {
+  let tokens = rawTokens.filter(
+    (t) => !comments.some((c) => c.range[0] <= t.range[0] && c.range[1] >= t.range[1])
+  );
+  tokens = tokens.filter(
+    (t) => !textNodes.some((c) => c.range[0] <= t.range[0] && c.range[1] >= t.range[1])
+  );
+
+  const sortedTextNodes = [...textNodes];
+  let currentTextNode = sortedTextNodes.pop();
+  for (let i = tokens.length - 1; i >= 0; i--) {
+    const t = tokens[i];
+    while (currentTextNode && t.range[0] < currentTextNode.range[0]) {
+      tokens.splice(i + 1, 0, currentTextNode);
+      currentTextNode = sortedTextNodes.pop();
+    }
+  }
+  if (currentTextNode) {
+    tokens.unshift(currentTextNode);
+  }
+
+  return tokens;
+}
+
+/**
+ * Parses a Glimmer template and produces a processed AST ready for ESLint.
+ * Shared between hbs-parser (standalone .hbs files) and gjs/gts parser (embedded templates).
+ *
+ * @param {object} options
+ * @param {string} options.templateContent - The template string to parse with glimmer
+ * @param {DocumentLines} options.codeLines - DocumentLines for the full source file
+ * @param {[number, number]} options.templateRange - Range [start, end] for the Template root node
+ * @param {string} [options.tokenSource] - String to tokenize (defaults to templateContent)
+ * @return {{ ast: object, comments: object[] }}
+ */
+function processGlimmerTemplate({ templateContent, codeLines, templateRange, tokenSource }) {
+  const offset = templateRange[0];
+  const docLines = new DocumentLines(templateContent);
+
+  /** Convert a Glimmer loc to a file-level [start, end] range */
+  const toFileRange = (loc) => [
+    offset + docLines.positionToOffset(loc.start),
+    offset + docLines.positionToOffset(loc.end),
+  ];
+  /** Convert a file-level range to a file-level loc */
+  const toFileLoc = (range) => ({
+    start: codeLines.offsetToPosition(range[0]),
+    end: codeLines.offsetToPosition(range[1]),
+  });
+
+  const ast = glimmer.preprocess(templateContent, { mode: 'codemod' });
+  const { allNodes, comments, textNodes, emptyTextNodes } = collectNodes(ast);
+
+  // Fix ranges, locs, and prefix types with "Glimmer"
+  for (const n of allNodes) {
+    if (n.type === 'PathExpression') {
+      n.head.range = toFileRange(n.head.loc);
+      n.head.loc = toFileLoc(n.head.range);
+    }
+
+    n.range = n.type === 'Template' ? [...templateRange] : toFileRange(n.loc);
+    n.start = n.range[0];
+    n.end = n.range[1];
+    n.loc = toFileLoc(n.range);
+
+    if (n.type === 'ElementNode') {
+      n.name = n.tag;
+      n.parts = [n.path.head].map((p) => {
+        const range = toFileRange(p.loc);
+        return {
+          ...p,
+          name: p.original,
+          parent: n,
+          type: 'GlimmerElementNodePart',
+          range,
+          loc: toFileLoc(range),
+        };
+      });
+    }
+
+    if ('blockParams' in n) {
+      n.params = (n.params || []).map((p) => {
+        const range = toFileRange(p.loc);
+        return {
+          ...p,
+          type: 'BlockParam',
+          name: p.original,
+          parent: n,
+          range,
+          loc: toFileLoc(range),
+        };
+      });
+    }
+
+    n.type = `Glimmer${n.type}`;
+  }
+
+  // Clean up AST structure
+  removeFromParent(emptyTextNodes);
+  removeFromParent(comments);
+  for (const comment of comments) {
+    comment.type = 'Block';
+  }
+
+  // Nullify empty hashes
+  for (const n of allNodes) {
+    if (
+      ['GlimmerMustacheStatement', 'GlimmerBlockStatement', 'GlimmerSubExpression'].includes(n.type)
+    ) {
+      if (n.hash && n.hash.pairs && n.hash.pairs.length === 0) {
+        n.hash = null;
+      }
+    }
+  }
+
+  // Build final token stream
+  ast.tokens = buildTokenStream(
+    tokenize(tokenSource || templateContent, codeLines, offset),
+    comments,
+    textNodes
+  );
+  ast.contents = templateContent;
+
+  return { ast, comments };
+}
+
 /**
  * Preprocesses the template info, parsing the template content to Glimmer AST,
  * fixing the offsets and locations of all nodes
@@ -257,164 +446,34 @@ module.exports.preprocessGlimmerTemplates = function preprocessGlimmerTemplates(
     templateRange: [r.range.start, r.range.end],
     utf16Range: [byteToCharIndex(code, r.range.start), byteToCharIndex(code, r.range.end)],
   }));
-  const templateVisitorKeys = {};
   const codeLines = new DocumentLines(code);
-  const comments = [];
+  const allComments = [];
+  const templateVisitorKeys = {};
+
   for (const tpl of templateInfos) {
-    const currentComments = [];
-    const textNodes = [];
-    const emptyTextNodes = [];
     const range = tpl.utf16Range;
-    const offset = range[0];
     const template = code.slice(...range);
-    const docLines = new DocumentLines(template);
-    const ast = glimmer.preprocess(template, { mode: 'codemod' });
-    ast.tokens = tokenize(sliceByteRange(code, ...tpl.templateRange), codeLines, tpl.utf16Range[0]);
-    const allNodes = [];
-    glimmer.traverse(ast, {
-      All(node, path) {
-        const n = node;
-        n.parent = path.parentNode;
-        allNodes.push(node);
-        if (node.type === 'CommentStatement' || node.type === 'MustacheCommentStatement') {
-          comments.push(node);
-          currentComments.push(node);
-        }
-        if (node.type === 'TextNode') {
-          n.value = node.chars;
-          // empty text nodes are not allowed, it's empty if its only whitespace or line terminators
-          // it's okay for AttrNodes
-          if (n.value.trim().length !== 0 || n.parent.type === 'AttrNode') {
-            textNodes.push(node);
-          } else {
-            emptyTextNodes.push(node);
-          }
-        }
-      },
-    });
-    ast.content = template;
-    const allNodeTypes = new Set();
-    for (const n of allNodes) {
-      if (n.type === 'PathExpression') {
-        n.head.range = [
-          offset + docLines.positionToOffset(n.head.loc.start),
-          offset + docLines.positionToOffset(n.head.loc.end),
-        ];
-        n.head.loc = {
-          start: codeLines.offsetToPosition(n.head.range[0]),
-          end: codeLines.offsetToPosition(n.head.range[1]),
-        };
-      }
-      n.range =
-        n.type === 'Template'
-          ? [...tpl.utf16Range]
-          : [
-              offset + docLines.positionToOffset(n.loc.start),
-              offset + docLines.positionToOffset(n.loc.end),
-            ];
-      n.start = n.range[0];
-      n.end = n.range[1];
-      n.loc = {
-        start: codeLines.offsetToPosition(n.range[0]),
-        end: codeLines.offsetToPosition(n.range[1]),
-      };
-      if (n.type === 'Template') {
-        n.loc.start = codeLines.offsetToPosition(tpl.utf16Range[0]);
-        n.loc.end = codeLines.offsetToPosition(tpl.utf16Range[1]);
-      }
-
-      if (n.type === 'ElementNode') {
-        n.name = n.tag;
-        n.parts = [n.path.head].map((p) => {
-          const range = [
-            offset + docLines.positionToOffset(p.loc.start),
-            offset + docLines.positionToOffset(p.loc.end),
-          ];
-          const loc = {
-            start: codeLines.offsetToPosition(range[0]),
-            end: codeLines.offsetToPosition(range[1]),
-          };
-          return {
-            ...p,
-            name: p.original,
-            parent: n,
-            type: 'GlimmerElementNodePart',
-            range,
-            loc,
-          };
-        });
-      }
 
-      if ('blockParams' in n) {
-        n.params = (n.params || []).map((p) => {
-          const range = [
-            offset + docLines.positionToOffset(p.loc.start),
-            offset + docLines.positionToOffset(p.loc.end),
-          ];
-          const loc = {
-            start: codeLines.offsetToPosition(range[0]),
-            end: codeLines.offsetToPosition(range[1]),
-          };
-          return {
-            ...p,
-            type: 'BlockParam',
-            name: p.original,
-            parent: n,
-            range,
-            loc,
-          };
-        });
-      }
-      n.type = `Glimmer${n.type}`;
-      allNodeTypes.add(n.type);
-    }
-
-    // ast should not contains empty text nodes
-    for (const node of emptyTextNodes) {
-      const children = node.parent.children || node.parent.body || node.parent.parts;
-      const idx = children.indexOf(node);
-      children.splice(idx, 1);
-    }
+    const { ast, comments } = processGlimmerTemplate({
+      templateContent: template,
+      codeLines,
+      templateRange: [...tpl.utf16Range],
+      tokenSource: sliceByteRange(code, ...tpl.templateRange),
+    });
 
-    // ast should not contain comment nodes
-    for (const comment of currentComments) {
-      const parentBody = comment.parent.body || comment.parent.children;
-      const idx = parentBody.indexOf(comment);
-      if (idx >= 0) {
-        parentBody.splice(idx, 1);
-      }
-      // comment type can be a block comment or a line comment
-      // mark comments as always block comment, this works for eslint in all cases
-      comment.type = 'Block';
-    }
-    // tokens should not contain tokens of comments
-    ast.tokens = ast.tokens.filter(
-      (t) => !comments.some((c) => c.range[0] <= t.range[0] && c.range[1] >= t.range[1])
-    );
-    // tokens should not contain tokens of text nodes, but represent the whole node
-    // remove existing tokens
-    ast.tokens = ast.tokens.filter(
-      (t) => !textNodes.some((c) => c.range[0] <= t.range[0] && c.range[1] >= t.range[1])
-    );
-    // merge in text nodes
-    let currentTextNode = textNodes.pop();
-    for (let i = ast.tokens.length - 1; i >= 0; i--) {
-      const t = ast.tokens[i];
-      while (currentTextNode && t.range[0] < currentTextNode.range[0]) {
-        ast.tokens.splice(i + 1, 0, currentTextNode);
-        currentTextNode = textNodes.pop();
-      }
-    }
-    ast.contents = template;
+    ast.content = template;
+    allComments.push(...comments);
     tpl.ast = ast;
   }
+
   for (const [k, v] of Object.entries(glimmerVisitorKeys)) {
     templateVisitorKeys[`Glimmer${k}`] = [...v];
   }
+
   return {
     templateVisitorKeys,
     templateInfos,
-    comments,
+    comments: allComments,
   };
 };
 
@@ -557,21 +616,6 @@ module.exports.convertAst = function convertAst(result, preprocessedResult, visi
     return null;
   });
 
-  traverse(visitorKeys, result.ast, (path) => {
-    const node = path.node;
-    if (!node) return null;
-
-    if (
-      ['GlimmerMustacheStatement', 'GlimmerBlockStatement', 'GlimmerSubExpression'].includes(
-        node.type
-      )
-    ) {
-      if (node.hash && node.hash.pairs.length === 0) {
-        node.hash = null;
-      }
-    }
-  });
-
   if (counter !== templateInfos.length) {
     throw new Error('failed to process all templates');
   }
@@ -690,3 +734,5 @@ module.exports.transformForLint = function transformForLint(code, fileName) {
 
 module.exports.traverse = traverse;
 module.exports.tokenize = tokenize;
+module.exports.processGlimmerTemplate = processGlimmerTemplate;
+module.exports.buildGlimmerVisitorKeys = buildGlimmerVisitorKeys;