From 64eac7276d4f1442ea9b2631e011359c68895fc4 Mon Sep 17 00:00:00 2001
From: ijlee2 <ijlee2@users.noreply.github.com>
Date: Mon, 30 Oct 2023 15:18:16 +0100
Subject: [PATCH] Documented how to update template-tag components

---
 README.md                                     |   1 +
 .../00-introduction.md                        |  24 ++
 .../01-a-simple-example.md                    | 131 +++++++
 .../02-create-utilities.md                    | 368 ++++++++++++++++++
 .../template-tag-components/03-conclusion.md  |   5 +
 5 files changed, 529 insertions(+)
 create mode 100644 tutorials/template-tag-components/00-introduction.md
 create mode 100644 tutorials/template-tag-components/01-a-simple-example.md
 create mode 100644 tutorials/template-tag-components/02-create-utilities.md
 create mode 100644 tutorials/template-tag-components/03-conclusion.md

diff --git a/README.md b/README.md
index 833e92a5..c0d210d3 100644
--- a/README.md
+++ b/README.md
@@ -30,6 +30,7 @@ npx @codemod-utils/cli --name <your-codemod-name>
 
 - [Main tutorial](./tutorials/ember-codemod-rename-test-modules/00-introduction.md)
 - [Tutorial for blueprints](./tutorials/blueprint-for-v2-addon/00-introduction.md)
+- [Tutorial for `<template>`-tag components](./tutorials/template-tag-components/00-introduction.md)
 
 
 ## Codemods written with @codemod-utils
diff --git a/tutorials/template-tag-components/00-introduction.md b/tutorials/template-tag-components/00-introduction.md
new file mode 100644
index 00000000..c9d19767
--- /dev/null
+++ b/tutorials/template-tag-components/00-introduction.md
@@ -0,0 +1,24 @@
+# Introduction
+
+> [!IMPORTANT]
+> Please complete the [main tutorial](../ember-codemod-rename-test-modules/00-introduction.md) first.
+
+> [!NOTE]
+> This tutorial shows how to use [`content-tag`](https://github.com/embroider-build/content-tag#readme) and [`@codemod-utils/ast-template`](../../packages/ast/template#readme) (i.e. `ember-template-recast`) to read and update `*.{gjs,gts}` files.
+>
+> `content-tag`, in comparison to `ember-template-recast`, is not stable. Since its API may change, `@codemod-utils` doesn't provide a utility package yet.
+
+[`<template>`-tag components](https://github.com/ember-template-imports/ember-template-imports) allow Ember developers to write JavaScript or TypeScript in the same file as the template. The new format has the file extension `.gjs` or `.gts`.
+
+This creates interesting problems for codemods, since they need to parse and transform a new file type. By definition, `ember-template-recast` (meant for `*.hbs` files) and `recast` (for `*.{js,ts}`) aren't enough.
+
+`content-tag` helps Node programs understand `*.{gjs,gts}` files. It does so by returning the locations of all `<template>`-tags in a file and the template code (the "contents") for each tag. At the time of writing, it doesn't provide a way to update the file.
+
+Luckily, we can use `@codemod-utils/ast-template` to update template code.
+
+
+## Table of contents
+
+1. [A simple example](./01-a-simple-example.md)
+1. [Create utilities](./02-create-utilities.md)
+1. [Conclusion](./03-conclusion.md)
diff --git a/tutorials/template-tag-components/01-a-simple-example.md b/tutorials/template-tag-components/01-a-simple-example.md
new file mode 100644
index 00000000..47478a68
--- /dev/null
+++ b/tutorials/template-tag-components/01-a-simple-example.md
@@ -0,0 +1,131 @@
+# A simple example
+
+To illustrate how to read and update `*.{gts,gts}` files, we'll recreate a feature in [`ember-test-selectors`](https://github.com/mainmatter/ember-test-selectors/blob/v6.0.0/strip-data-test-properties-plugin6.js): Remove all data attributes in the template, if the attribute name starts with `data-test`. Our target project is assumed to be an Ember app.
+
+
+## Use the CLI
+
+Change the directory to a place where you like to keep projects. Then, run these commands:
+
+```sh
+# Create project
+npx @codemod-utils/cli --name remove-test-selectors --addon ast-template
+
+# Install dependencies
+cd remove-test-selectors
+pnpm install
+
+# Install content-tag as a dependency
+pnpm install content-tag
+```
+
+> [!NOTE]
+> Just like in [the main tutorial](../ember-codemod-rename-test-modules/04-step-1-update-acceptance-tests-part-1.md#remove-the-sample-step), remove the sample step, `add-end-of-line`.
+
+
+## Scaffold step
+
+Create a step called `remove-test-selectors`. It is to read `*.{gjs,gts}` files and write back the file content (a no-op).
+
+<details>
+
+<summary><code>src/steps/remove-test-selectors.ts</code></summary>
+
+For brevity, how `src/index.ts` calls `removeTestSelectors()` is not shown.
+
+```ts
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { createFiles, findFiles } from '@codemod-utils/files';
+
+import { Options } from '../types/index.js';
+
+export function removeTestSelectors(options: Options): void {
+  const { projectRoot } = options;
+
+  const filePaths = findFiles('app/components/**/*.{gjs,gts}', {
+    projectRoot,
+  });
+
+  const fileMap = new Map(
+    filePaths.map((filePath) => {
+      const file = readFileSync(join(projectRoot, filePath), 'utf8');
+
+      return [filePath, file];
+    }),
+  );
+
+  createFiles(fileMap, options);
+}
+```
+
+</details>
+
+To test the step, we create a component with multiple `<template>`-tags:
+
+<details>
+
+<summary><code>tests/fixtures/sample-project/input/app/components/my-component.gjs</code></summary>
+
+The indentations are inconsistent on purpose. We want to know if our codemod will preserve formatting.
+
+```js
+import { on } from '@ember/modifier';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import styles from './my-component.css';
+
+const Control =
+<template>
+  <div class={{styles.control}}>
+    <button
+      data-test-button="Increment"
+      type="button"
+      {{on "click" @onClick}}
+    >
+      Increment by 1
+    </button>
+  </div>
+</template>
+
+const Display =
+  <template>
+    <div class={{styles.display}}>
+      Count:
+      <p class={{styles.count}} data-test-count ...attributes>
+        {{@count}}
+      </p>
+    </div>
+  </template>
+
+export default class MyComponent extends Component {
+  @tracked count = 0;
+
+  increment = () => {
+    this.count++;
+  }
+
+    <template>
+      <div class={{styles.container}}>
+        <Control
+          @onClick={{this.increment}}
+          />
+        <Display @count={{this.count}} data-test-my-count />
+      </div>
+    </template>
+}
+```
+
+</details>
+
+
+<div align="center">
+  <div>
+    Next: <a href="./02-create-utilities.md">Create utilities</a>
+  </div>
+  <div>
+    Previous: <a href="./00-introduction.md">Introduction</a>
+  </div>
+</div>
diff --git a/tutorials/template-tag-components/02-create-utilities.md b/tutorials/template-tag-components/02-create-utilities.md
new file mode 100644
index 00000000..0ec8b678
--- /dev/null
+++ b/tutorials/template-tag-components/02-create-utilities.md
@@ -0,0 +1,368 @@
+# Create utilities
+
+In [the previous chapter](./01-a-simple-example.md), we read `*.{gjs,gts}` files. We will take small steps to update these files.
+
+
+## Parse file
+
+We avoid directly consuming `content-tag` in our steps, but create **wrappers** instead. Wrapping code helps us minimize the impact of a breaking change in `content-tag`.
+
+Until `@codemod-utils` provides an official package, we can create utilities in `src/utils`.
+
+<details>
+
+<summary><code>src/utils/ast/template-tag.ts</code></summary>
+
+```ts
+import { Preprocessor } from 'content-tag';
+
+type Range = {
+  end: number;
+  start: number;
+};
+
+type ContentTag = {
+  contentRange: Range;
+  contents: string;
+  endRange: Range;
+  range: Range; // range = startRange + contentRange + endRange
+  startRange: Range;
+  tagName: string;
+  type: string;
+};
+
+export function parse(file: string) {
+  const preprocessor = new Preprocessor();
+
+  return preprocessor.parse(file) as unknown as ContentTag[];
+}
+
+export function replaceContents(
+  file: string,
+  options: {
+    contents: string;
+    range: Range;
+  },
+): string {
+  const { contents, range } = options;
+
+  return [
+    file.substring(0, range.start),
+    '<template>',
+    contents,
+    '</template>',
+    file.substring(range.end),
+  ].join('');
+}
+```
+
+</details>
+
+<details>
+
+<summary><code>src/steps/remove-test-selectors.ts</code></summary>
+
+```diff
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { createFiles, findFiles } from '@codemod-utils/files';
+
+import { Options } from '../types/index.js';
++ import { parse } from '../utils/ast/template-tag.js';
+
+export function removeTestSelectors(options: Options): void {
+  const { projectRoot } = options;
+
+  const filePaths = findFiles('app/components/**/*.{gjs,gts}', {
+    projectRoot,
+  });
+
+  const fileMap = new Map(
+    filePaths.map((filePath) => {
+      const file = readFileSync(join(projectRoot, filePath), 'utf8');
++       const contentTags = parse(file);
++
++       contentTags.forEach((contentTag) => {
++         console.log(contentTag);
++       });
+
+      return [filePath, file];
+    }),
+  );
+
+  createFiles(fileMap, options);
+}
+```
+
+</details>
+
+We can run tests to understand what `parse()` returns.
+
+<details>
+
+<summary>Expected output</summary>
+
+The fixture file has 3 `<template>`-tags, so the array `contentTags` has 3 elements. The object keys that matter to us are `contents` and `range`.
+
+```sh
+❯ pnpm test
+
+{
+  type: 'expression',
+  tagName: 'template',
+  contents: '\n' +
+    '  <div class={{styles.control}}>\n' +
+    '    <button\n' +
+    '      data-test-button="Increment"\n' +
+    '      type="button"\n' +
+    '      {{on "click" @onClick}}\n' +
+    '    >\n' +
+    '      Increment by 1\n' +
+    '    </button>\n' +
+    '  </div>\n',
+  range: { start: 186, end: 388 },
+  startRange: { start: 186, end: 196 },
+  contentRange: { start: 196, end: 377 },
+  endRange: { start: 377, end: 388 }
+}
+{
+  type: 'expression',
+  tagName: 'template',
+  contents: '\n' +
+    '    <div class={{styles.display}}>\n' +
+    '      Count:\n' +
+    '      <p class={{styles.count}} data-test-count ...attributes>\n' +
+    '        {{@count}}\n' +
+    '      </p>\n' +
+    '    </div>\n' +
+    '  ',
+  range: { start: 408, end: 584 },
+  startRange: { start: 408, end: 418 },
+  contentRange: { start: 418, end: 573 },
+  endRange: { start: 573, end: 584 }
+}
+{
+  type: 'class-member',
+  tagName: 'template',
+  contents: '\n' +
+    '      <div class={{styles.container}}>\n' +
+    '        <Control\n' +
+    '          @onClick={{this.increment}}\n' +
+    '          />\n' +
+    '        <Display @count={{this.count}} data-test-my-count />\n' +
+    '      </div>\n' +
+    '    ',
+  range: { start: 711, end: 918 },
+  startRange: { start: 711, end: 721 },
+  contentRange: { start: 721, end: 907 },
+  endRange: { start: 907, end: 918 }
+}
+```
+
+</details>
+
+> [!NOTE]
+> From `range.start`, we see that `contentTags` is a sorted array. The `<template>`-tag, which appears first in the file, appears first in the array.
+
+
+## Create contents
+
+Next, we use `@codemod-utils/ast-template` to remove all test selectors.
+
+<details>
+
+<summary><code>src/steps/remove-test-selectors.ts</code></summary>
+
+```diff
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
++ import { AST } from '@codemod-utils/ast-template';
+import { createFiles, findFiles } from '@codemod-utils/files';
+
+import { Options } from '../types/index.js';
+import { parse } from '../utils/ast.js';
+
++ function removeDataTestAttributes(file: string): string {
++   const traverse = AST.traverse();
++ 
++   const ast = traverse(file, {
++     AttrNode(node) {
++       if (!node.name.startsWith('data-test')) {
++         return;
++       }
++ 
++       return null;
++     },
++   });
++ 
++   return AST.print(ast);
++ }
++
+export function removeTestSelectors(options: Options): void {
+  const { projectRoot } = options;
+
+  const filePaths = findFiles('app/components/**/*.{gjs,gts}', {
+    projectRoot,
+  });
+
+  const fileMap = new Map(
+    filePaths.map((filePath) => {
+      const file = readFileSync(join(projectRoot, filePath), 'utf8');
+      const contentTags = parse(file);
+
+      contentTags.forEach((contentTag) => {
+-         console.log(contentTag);
++         const contents = removeDataTestAttributes(contentTag.contents);
++
++         console.log(contents);
+      });
+
+      return [filePath, file];
+    }),
+  );
+
+  createFiles(fileMap, options);
+}
+```
+
+</details>
+
+
+## Replace contents
+
+Last but not least, we use `replaceContents()` to replace the contents of each `<template>`-tag. Because a file may have multiple tags, we update the tags in the reverse order.
+
+<details>
+
+<summary><code>src/steps/remove-test-selectors.ts</code></summary>
+
+```diff
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { AST } from '@codemod-utils/ast-template';
+import { createFiles, findFiles } from '@codemod-utils/files';
+
+import { Options } from '../types/index.js';
+- import { parse } from '../utils/ast.js';
++ import { parse, replaceContents } from '../utils/ast.js';
+
+function removeDataTestAttributes(file: string): string {
+  const traverse = AST.traverse();
+
+  const ast = traverse(file, {
+    AttrNode(node) {
+      if (!node.name.startsWith('data-test')) {
+        return;
+      }
+
+      return null;
+    },
+  });
+
+  return AST.print(ast);
+}
+
+export function removeTestSelectors(options: Options): void {
+  const { projectRoot } = options;
+
+  const filePaths = findFiles('app/components/**/*.{gjs,gts}', {
+    projectRoot,
+  });
+
+  const fileMap = new Map(
+    filePaths.map((filePath) => {
+-       const file = readFileSync(join(projectRoot, filePath), 'utf8');
++       let file = readFileSync(join(projectRoot, filePath), 'utf8');
+      const contentTags = parse(file);
+
+-       contentTags.forEach((contentTag) => {
++       contentTags.reverse().forEach((contentTag) => {
+        const contents = removeDataTestAttributes(contentTag.contents);
+
+-         console.log(contents);
++         file = replaceContents(file, {
++           contents,
++           range: contentTag.range,
++         });
+      });
+
+      return [filePath, file];
+    }),
+  );
+
+  createFiles(fileMap, options);
+}
+```
+
+</details>
+
+Run `./codemod-test-fixtures.sh`. You should see that (1) only the test selectors are removed and (2) formatting is preserved.
+
+<details>
+
+<summary><code>tests/fixtures/sample-project/output/app/components/my-component.gjs</code></summary>
+
+```diff
+import { on } from '@ember/modifier';
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+
+import styles from './my-component.css';
+
+const Control =
+<template>
+  <div class={{styles.control}}>
+    <button
+-       data-test-button="Increment"
+      type="button"
+      {{on "click" @onClick}}
+    >
+      Increment by 1
+    </button>
+  </div>
+</template>
+
+const Display =
+  <template>
+    <div class={{styles.display}}>
+      Count:
+-       <p class={{styles.count}} data-test-count ...attributes>
++       <p class={{styles.count}} ...attributes>
+        {{@count}}
+      </p>
+    </div>
+  </template>
+
+export default class MyComponent extends Component {
+  @tracked count = 0;
+
+  increment = () => {
+    this.count++;
+  }
+
+    <template>
+      <div class={{styles.container}}>
+        <Control
+          @onClick={{this.increment}}
+          />
+-         <Display @count={{this.count}} data-test-my-count />
++         <Display @count={{this.count}} />
+      </div>
+    </template>
+}
+```
+
+</details>
+
+
+<div align="center">
+  <div>
+    Next: <a href="./03-conclusion.md">Conclusion</a>
+  </div>
+  <div>
+    Previous: <a href="./01-a-simple-example.md">A simple example</a>
+  </div>
+</div>
diff --git a/tutorials/template-tag-components/03-conclusion.md b/tutorials/template-tag-components/03-conclusion.md
new file mode 100644
index 00000000..061dfb28
--- /dev/null
+++ b/tutorials/template-tag-components/03-conclusion.md
@@ -0,0 +1,5 @@
+# Conclusion
+
+When utilities form the foundation of a codemod, we can experiment with new libraries and write code that stands the test of time.
+
+To illustrate this idea, we combined `content-tag` with `@codemod-utils/ast-template` so that we can update `*.{gjs,gts}` files—a feature that neither `content-tag` nor `@codemod-utils` provides just yet.