Separated concerns in @codemod-utils/ast-template-tag (#189)

* breaking: Separated preprocess() into findTemplateTags() and toEcma()

* chore: Updated tests

* breaking: Generalized replaceTemplate()

* chore: Updated tests

* chore: Updated documentation

* chore: Added changeset

Author: ijlee2

.changeset/sharp-dodos-fall.md

@@ -0,0 +1,5 @@
+---
+"@codemod-utils/ast-template-tag": minor
+---
+
+Separated preprocess() into findTemplateTags() and toEcma()

.changeset/wide-spoons-warn.md

@@ -0,0 +1,5 @@
+---
+"@codemod-utils/ast-template-tag": minor
+---
+
+Generalized replaceTemplate()

packages/ast/template-tag/README.md

@@ -33,67 +33,81 @@ const newFile = updateTemplates(oldFile, transform);
 
 ## API
 
-### preprocess
+### findTemplateTags
 
-Processes a file with `<template>` tags into things that work with existing methods or libraries.
-
-⚠️ Likely, you won't need this method but [`updateJavaScript`](#updatejavascript) instead.
+Finds `<template>` tags in a file.
 
 <details>
 
 <summary>Example</summary>
 
-Analyze the JavaScript part of the file.
+Count the number of lines of code (LOC) in `<template>` tags.
 
 ```ts
-const { javascript } = preprocess(file);
+function getLOC(code: string): number {
+  const matches = file.match(/\r?\n/g);
 
-// Some method that checks `*.{js,ts}` files
-analyze(javascript);
+  return (matches ?? []).length;
+}
+
+const templateTags = findTemplateTags(file);
+
+let loc = 0;
+
+templateTags.forEach(({ contents }) => {
+  loc += getLOC(contents.trim());
+});
 ```
 
 </details>
 
+
+### replaceTemplateTag
+
+Replaces a particular `<template>` tag.
+
+⚠️ Likely, you won't need this method but [`updateTemplates`](#updatetemplates) instead.
+
 <details>
 
 <summary>Example</summary>
 
-Count the number of lines inside `<template>` tags.
+Update all template tags in a file.
 
 ```ts
-const { templateTags } = preprocess(file);
+const templateTags = findTemplateTags(file);
 
-let numOfLines = 0;
+templateTags.reverse().forEach(({ contents, range }) => {
+  // Some method that can update `*.hbs` files
+  const template = transform(contents);
 
-templateTags.forEach(({ contents }) => {
-  numOfLines += contents.trim().split('\n').length;
+  file = replaceTemplateTag(file, {
+    code: `<template>${template}</template>`,
+    range,
+  });
 });
 ```
 
 </details>
 
 
-### replaceTemplate
+### toEcma
 
-Replaces the template of a particular `<template>` tag.
+Converts a file with `<template>` tags to standard JavaScript.
 
-⚠️ Likely, you won't need this method but [`updateTemplates`](#updatetemplates) instead.
+⚠️ Likely, you won't need this method but [`updateJavaScript`](#updatejavascript) instead.
 
 <details>
 
 <summary>Example</summary>
 
-Update the template in each tag.
+Analyze the JavaScript part of the file.
 
 ```ts
-const { templateTags } = preprocess(file);
+const ecma = toEcma(file);
 
-templateTags.reverse().forEach(({ contents, range }) => {
-  // Some method that can update `*.hbs` files
-  const template = transform(contents);
-
-  file = replaceTemplate(file, { range, template });
-});
+// Some method that checks `*.{js,ts}` files
+analyze(ecma);
 ```
 
 </details>

packages/ast/template-tag/src/find-template-tags.ts

@@ -0,0 +1,40 @@
+import { type Parsed as TemplateTag, Preprocessor } from 'content-tag';
+
+const preprocessor = new Preprocessor();
+
+/**
+ * Finds `<template>` tags in a file.
+ *
+ * @param file
+ *
+ * A `*.{gjs,gts}` file.
+ *
+ * @return
+ *
+ * A sorted array that tracks tag contents and locations.
+ *
+ * @example
+ *
+ * Count the number of lines of code (LOC) in `<template>` tags.
+ *
+ * ```ts
+ * function getLOC(code: string): number {
+ *   const matches = file.match(/\r?\n/g);
+ *
+ *   return (matches ?? []).length;
+ * }
+ *
+ * const templateTags = findTemplateTags(file);
+ *
+ * let loc = 0;
+ *
+ * templateTags.forEach(({ contents }) => {
+ *   loc += getLOC(contents.trim());
+ * });
+ * ```
+ */
+export function findTemplateTags(file: string): TemplateTag[] {
+  const templateTags = preprocessor.parse(file);
+
+  return templateTags;
+}

packages/ast/template-tag/src/index.ts

@@ -1,4 +1,5 @@
-export * from './preprocess.js';
-export * from './replace-template.js';
+export * from './find-template-tags.js';
+export * from './replace-template-tag.js';
+export * from './to-ecma.js';
 export * from './update-javascript.js';
 export * from './update-templates.js';

packages/ast/template-tag/src/preprocess.ts

@@ -24,15 +24,15 @@ function sliceByteRange(
 }
 
 /**
- * Replaces the template of a particular `<template>` tag.
+ * Replaces a particular `<template>` tag.
  *
  * @param file
  *
  * A `*.{gjs,gts}` file.
  *
  * @param data
  *
- * An object with `range` (tag location) and `template` (what to
+ * An object with `range` (tag location) and `code` (what to
  * replace with).
  *
  * @return
@@ -41,33 +41,34 @@ function sliceByteRange(
  *
  * @example
  *
- * Update the template in each tag.
+ * Update all template tags in a file.
  *
  * ```ts
- * const { templateTags } = preprocess(file);
+ * const templateTags = findTemplateTags(file);
  *
  * templateTags.reverse().forEach(({ contents, range }) => {
  *   // Some method that can update `*.hbs` files
  *   const template = transform(contents);
  *
- *   file = replaceTemplate(file, { range, template });
+ *   file = replaceTemplateTag(file, {
+ *     code: `<template>${template}</template>`,
+ *     range,
+ *   });
  * });
  * ```
  */
-export function replaceTemplate(
+export function replaceTemplateTag(
   file: string,
   data: {
+    code: string;
     range: Range;
-    template: string;
   },
 ): string {
-  const { range, template } = data;
+  const { code, range } = data;
 
   return [
     sliceByteRange(file, 0, range.startByte),
-    '<template>',
-    template,
-    '</template>',
+    code,
     sliceByteRange(file, range.endByte, undefined),
   ].join('');
 }

…ast/template-tag/src/replace-template.ts …template-tag/src/replace-template-tag.tspackages/ast/template-tag/src/replace-template.ts renamed to packages/ast/template-tag/src/replace-template-tag.ts packages/ast/template-tag/src/replace-template.ts renamed to packages/ast/template-tag/src/replace-template-tag.ts

@@ -0,0 +1,31 @@
+import { Preprocessor } from 'content-tag';
+
+const preprocessor = new Preprocessor();
+
+/**
+ * Converts a file with `<template>` tags to standard JavaScript.
+ *
+ * @param file
+ *
+ * A `*.{gjs,gts}` file.
+ *
+ * @return
+ *
+ * File in standard JavaScript.
+ *
+ * @example
+ *
+ * Analyze the JavaScript part of the file.
+ *
+ * ```ts
+ * const ecma = toEcma(file);
+ *
+ * // Some method that checks `*.{js,ts}` files
+ * analyze(ecma);
+ * ```
+ */
+export function toEcma(file: string): string {
+  const { code } = preprocessor.process(file);
+
+  return code;
+}

packages/ast/template-tag/src/to-ecma.ts

@@ -1,5 +1,5 @@
-import { preprocess } from './preprocess.js';
-import { replaceTemplate } from './replace-template.js';
+import { findTemplateTags } from './find-template-tags.js';
+import { replaceTemplateTag } from './replace-template-tag.js';
 
 /**
  * Updates the `<template>` tags in a file. Leaves the JavaScript
@@ -55,12 +55,15 @@ export function updateTemplates(
   file: string,
   update: (code: string) => string,
 ): string {
-  const { templateTags } = preprocess(file);
+  const templateTags = findTemplateTags(file);
 
   templateTags.reverse().forEach(({ contents, range }) => {
     const template = update(contents);
 
-    file = replaceTemplate(file, { range, template });
+    file = replaceTemplateTag(file, {
+      code: `<template>${template}</template>`,
+      range,
+    });
   });
 
   return file;

packages/ast/template-tag/src/update-templates.ts

@@ -0,0 +1,11 @@
+import { assert, test } from '@codemod-utils/tests';
+
+import { findTemplateTags } from '../../src/index.js';
+
+test('find-template-tags > base case', function () {
+  const oldFile = '';
+
+  const templateTags = findTemplateTags(oldFile);
+
+  assert.deepStrictEqual(templateTags, []);
+});