chore: Documented how to support Windows

Author: ijlee2

README.md

@@ -31,6 +31,7 @@ npx @codemod-utils/cli <your-codemod-name>
 
 - [Main tutorial](./tutorials/main-tutorial/00-introduction.md)
 - [Create blueprints](./tutorials/create-blueprints/00-introduction.md)
+- [Support Windows](./tutorials/support-windows/00-introduction.md)
 - [Update CSS files](./tutorials/update-css-files/00-introduction.md)
 - [Update `<template>` tags](./tutorials/update-template-tags/00-introduction.md)
 

packages/tests/README.md

@@ -94,7 +94,7 @@ In the example above (an "acceptance" test), `inputProject` and `outputProject`
 <summary>Example</summary>
 
 ```ts
-const oldFile = createFile([
+const oldFile = normalizeFile([
   `import Component from '@glimmer/component';`,
   ``,
   `export default class Hello extends Component {}`,
@@ -105,7 +105,7 @@ const newFile = transform(oldFile);
 
 assert.strictEqual(
   newFile,
-  createFile([
+  normalizeFile([
     `import Component from '@glimmer/component';`,
     ``,
     `import styles from './hello.module.css';`,

tutorials/create-blueprints/03-define-options.md

@@ -282,7 +282,7 @@ See if you can complete the starter code shown above. The requirements are:
 <summary>Solution: <code>src/steps/create-options.ts</code></summary>
 
 ```diff
-+ import { join } from 'node:path';
++ import { join, sep } from 'node:path';
 + 
 import type { CodemodOptions, Options } from '../types/index.js';
 
@@ -296,12 +296,12 @@ export function createOptions(codemodOptions: CodemodOptions): Options {
 
   return {
 +     addon: {
-+       location: join('packages', addonLocation),
++       location: join('packages', addonLocation).replaceAll(sep, '/'),
 +       name: addonName,
 +     },
     projectRoot,
 +     testApp: {
-+       location: join('tests', addonLocation),
++       location: join('tests', addonLocation).replaceAll(sep, '/'),
 +       name: `test-app-for-${dasherize(addonName)}`,
 +     },
   };

tutorials/main-tutorial/05-step-1-update-acceptance-tests-part-2.md

@@ -594,11 +594,14 @@ Currently, `data.moduleName` is hard-coded. We can derive the test module name f
 
 <summary>Solution: <code>src/steps/rename-acceptance-tests.ts</code></summary>
 
+It's important to note that Windows uses `\` as the file separator, while the entity name uses `/` (independently of the operating system). We can use `relative()` and `sep` to normalize values.
+
 The implementation for `renameModule()` remains unchanged and has been hidden for simplicity.
 
 ```diff
 import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+- import { join } from 'node:path';
++ import { join, relative, sep } from 'node:path';
 
 import { AST } from '@codemod-utils/ast-javascript';
 - import { findFiles } from '@codemod-utils/files';
@@ -614,10 +617,10 @@ type Data = {
 + function getModuleName(filePath: string): string {
 +   let { dir, name } = parseFilePath(filePath);
 + 
-+   dir = dir.replace(/^tests\/acceptance(\/)?/, '');
++   dir = relative('tests/acceptance', dir);
 +   name = name.replace(/-test$/, '');
 + 
-+   const entityName = join(dir, name);
++   const entityName = join(dir, name).replaceAll(sep, '/');
 + 
 +   // a.k.a. friendlyTestDescription
 +   return ['Acceptance', entityName].join(' | ');

tutorials/main-tutorial/06-step-2-update-integration-tests.md

@@ -120,10 +120,10 @@ type Data = {
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
-  dir = dir.replace(/^tests\/acceptance(\/)?/, '');
+  dir = relative('tests/acceptance', dir);
   name = name.replace(/-test$/, '');
 
-  const entityName = join(dir, name);
+  const entityName = join(dir, name).replaceAll(sep, '/');
 
   // a.k.a. friendlyTestDescription
   return ['Acceptance', entityName].join(' | ');
@@ -179,7 +179,7 @@ I highlighted only how `getModuleName()` and `renameModule()` differ between `re
 
 ```diff
 import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 import { AST } from '@codemod-utils/ast-javascript';
 import { findFiles, parseFilePath } from '@codemod-utils/files';
@@ -194,11 +194,11 @@ type Data = {
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
--   dir = dir.replace(/^tests\/acceptance(\/)?/, '');
-+   dir = dir.replace(/^tests\/integration(\/)?/, '');
+-   dir = relative('tests/acceptance', dir);
++   dir = relative('tests/integration', dir);
   name = name.replace(/-test$/, '');
 
-  const entityName = join(dir, name);
+  const entityName = join(dir, name).replaceAll(sep, '/');
 
   // a.k.a. friendlyTestDescription
 -   return ['Acceptance', entityName].join(' | ');
@@ -339,10 +339,10 @@ We say that an [iterative method](https://en.wikipedia.org/wiki/Iterative_method
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
-  dir = dir.replace(/^tests\/integration(\/)?/, '');
+  dir = relative('tests/integration', dir);
   name = name.replace(/-test$/, '');
 
-  const entityName = join(dir, name);
+  const entityName = join(dir, name).replaceAll(sep, '/');
 
   // a.k.a. friendlyTestDescription
   return ['Integration', entityName].join(' | ');
@@ -355,7 +355,7 @@ Let's correct the overshoot by adding the entity type (here, we represent it as
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
-  dir = dir.replace(/^tests\/integration(\/)?/, '');
+  dir = relative('tests/integration', dir);
   name = name.replace(/-test$/, '');
 
   const entityType = /* ... */;
@@ -387,6 +387,8 @@ const entityName = join(remainingPath, name);
 Let me first show you the solution for `parseEntity()`, then explain the particular approach.
 
 ```ts
+import { sep } from 'node:path';
+
 const folderToEntityType = new Map([
   ['components', 'Component'],
   ['helpers', 'Helper'],
@@ -397,12 +399,12 @@ function parseEntity(dir: string): {
   entityType: string | undefined;
   remainingPath: string;
 } {
-  const [folder, ...remainingPaths] = dir.split('/');
+  const [folder, ...remainingPaths] = dir.split(sep);
   const entityType = folderToEntityType.get(folder!);
 
   return {
     entityType,
-    remainingPath: remainingPaths.join('/'),
+    remainingPath: remainingPaths.join(sep),
   };
 }
 ```
@@ -419,7 +421,7 @@ The implementations for `renameModule()` and `renameIntegrationTests()` remain u
 
 ```diff
 import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 import { AST } from '@codemod-utils/ast-javascript';
 import { findFiles, parseFilePath } from '@codemod-utils/files';
@@ -441,24 +443,24 @@ type Data = {
 +   entityType: string | undefined;
 +   remainingPath: string;
 + } {
-+   const [folder, ...remainingPaths] = dir.split('/');
++   const [folder, ...remainingPaths] = dir.split(sep);
 +   const entityType = folderToEntityType.get(folder!);
 + 
 +   return {
 +     entityType,
-+     remainingPath: remainingPaths.join('/'),
++     remainingPath: remainingPaths.join(sep),
 +   };
 + }
 + 
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
-  dir = dir.replace(/^tests\/integration(\/)?/, '');
+  dir = relative('tests/integration', dir);
   name = name.replace(/-test$/, '');
 
--   const entityName = join(dir, name);
+-   const entityName = join(dir, name).replaceAll(sep, '/');
 +   const { entityType, remainingPath } = parseEntity(dir);
-+   const entityName = join(remainingPath, name);
++   const entityName = join(remainingPath, name).replaceAll(sep, '/');
 
   // a.k.a. friendlyTestDescription
 -   return ['Integration', entityName].join(' | ');

tutorials/main-tutorial/07-step-3-update-unit-tests.md

@@ -23,7 +23,7 @@ Note that, because `'instance-initializers'` and `'utils'` need to be mapped to
 
 ```diff
 import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, relative, sep } from 'node:path';
 
 import { AST } from '@codemod-utils/ast-javascript';
 import { findFiles, parseFilePath } from '@codemod-utils/files';
@@ -57,24 +57,24 @@ function parseEntity(dir: string): {
   entityType: string | undefined;
   remainingPath: string;
 } {
-  const [folder, ...remainingPaths] = dir.split('/');
+  const [folder, ...remainingPaths] = dir.split(sep);
   const entityType = folderToEntityType.get(folder!);
 
   return {
     entityType,
-    remainingPath: remainingPaths.join('/'),
+    remainingPath: remainingPaths.join(sep),
   };
 }
 
 function getModuleName(filePath: string): string {
   let { dir, name } = parseFilePath(filePath);
 
--   dir = dir.replace(/^tests\/integration(\/)?/, '');
-+   dir = dir.replace(/^tests\/unit(\/)?/, '');
+-   dir = relative('tests/integration', dir);
++   dir = relative('tests/unit', dir);
   name = name.replace(/-test$/, '');
 
   const { entityType, remainingPath } = parseEntity(dir);
-  const entityName = join(remainingPath, name);
+  const entityName = join(remainingPath, name).replaceAll(sep, '/');
 
   // a.k.a. friendlyTestDescription
 -   return ['Integration', entityType, entityName].join(' | ');