Documented how to use linters and incrementally migrate code

README.md

@@ -20,11 +20,28 @@ cd <path/to/your/project>
 npx ember-codemod-pod-to-octane <arguments>
 ```
 
+> [!NOTE]
+>
+> By default, Octane assumes the **flat component structure**. So does this codemod to help different Ember projects converge to one layout. If you want the **nested component structure** (also supported by Octane), you can run [`ember-flat-to-nested`](https://github.com/bertdeblock/ember-flat-to-nested) afterwards.
+
 Step 2. Remove `podModulePrefix` from `config/environment.js` and `usePods` from `.ember-cli`.
 
 Step 3. Update references originating from, as well as pointing to, the moved files. These can include `import` statement, `composes` property from `ember-css-modules`, etc.
 
-<sup>1. By default, Octane assumes the **flat component structure**. So does this codemod to help different Ember projects converge to one layout. If you want the **nested component structure** (also supported by Octane), you can run [`ember-flat-to-nested`](https://github.com/bertdeblock/ember-flat-to-nested) afterwards.</sup>
+> [!TIP]
+>
+> Linters can help you find the files that need to be updated.
+>
+> ```sh
+> # With eslint-plugin-import
+> [lint:js] /my-v1-addon/addon/index.ts
+> [lint:js]   1:49  error  Unable to resolve path to module './components/navigation-menu/component'  import/no-unresolved
+> 
+> # With typescript
+> [lint:types] addon/index.ts:1:49 - error TS2307: Cannot find module './components/navigation-menu/component' or its corresponding type declarations.
+> [lint:types] 
+> [lint:types] 1 export { default as NavigationMenu } from './components/navigation-menu/component';
+> ```
 
 
 ### Arguments
@@ -122,6 +139,25 @@ pnpm build
 ./dist/bin/ember-codemod-pod-to-octane.js --root <path/to/your/project>
 ```
 
+> [!TIP]
+>
+> You might clone the repo to migrate the project one component or one route at a time. For example, to migrate only the `<NavigationMenu>` component (and its subcomponents, if they exist), update the related file(s) in the `src` folder like this:
+>
+> ```diff
+> export function mapComponentClasses(options: Options): FilePathMapEntries {
+>   const { podPath, projectRoot } = options;
+> 
+>   const podDir = join('app', podPath, 'components');
+> 
+> -   const filePaths = findFiles(`${podDir}/**/component.{d.ts,js,ts}`, {
+> +   const filePaths = findFiles(`${podDir}/navigation-menu/**/component.{d.ts,js,ts}`, {
+> 
+>   // ...
+> }
+> ```
+>
+> That is, look for `findFiles(`, then insert the component or route name between `podDir` and `**`.
+
 
 ## Compatibility
 

src/migration/app/steps/create-file-path-maps/app/map-component-classes.ts

@@ -11,16 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapComponentClasses(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(
-    join('app', podPath, 'components/**/component.{d.ts,js,ts}'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir = join('app', podPath, 'components');
+
+  const filePaths = findFiles(`${podDir}/**/component.{d.ts,js,ts}`, {
+    projectRoot,
+  });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath, 'components'),
+      podDir,
       replace: (key: string) => {
         return `app/components/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-component-stylesheets.ts

@@ -11,16 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapComponentStylesheets(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(
-    join('app', podPath, 'components/**/styles.{css,scss}'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir = join('app', podPath, 'components');
+
+  const filePaths = findFiles(`${podDir}/**/styles.{css,scss}`, {
+    projectRoot,
+  });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath, 'components'),
+      podDir,
       replace: (key: string) => {
         return `app/components/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-component-templates.ts

@@ -11,16 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapComponentTemplates(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(
-    join('app', podPath, 'components/**/template.hbs'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir = join('app', podPath, 'components');
+
+  const filePaths = findFiles(`${podDir}/**/template.hbs`, {
+    projectRoot,
+  });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath, 'components'),
+      podDir,
       replace: (key: string) => {
         return `app/components/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-adapters.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteAdapters(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/adapter.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/adapter.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/adapters/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-controllers.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteControllers(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/controller.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/controller.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/controllers/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-models.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteModels(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/model.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/model.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/models/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-routes.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteRoutes(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/route.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/route.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/routes/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-serializers.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteSerializers(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/serializer.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/serializer.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/serializers/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-stylesheets.ts

@@ -11,14 +11,16 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteStylesheets(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/styles.{css,scss}'), {
-    ignoreList: [join('app', podPath, 'components', '**')],
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/styles.{css,scss}`, {
+    ignoreList: [join('app', podPath, 'components/**')],
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/styles/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-route-templates.ts

@@ -11,14 +11,16 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapRouteTemplates(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/template.hbs'), {
-    ignoreList: [join('app', podPath, 'components', '**')],
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/template.hbs`, {
+    ignoreList: [join('app', podPath, 'components/**')],
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/templates/${key}`;
       },

src/migration/app/steps/create-file-path-maps/app/map-services.ts

@@ -11,13 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapServices(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(join('app', podPath, '**/service.{js,ts}'), {
+  const podDir = join('app', podPath);
+
+  const filePaths = findFiles(`${podDir}/**/service.{js,ts}`, {
     projectRoot,
   });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('app', podPath),
+      podDir,
       replace: (key: string) => {
         return `app/services/${key}`;
       },

src/migration/app/steps/create-file-path-maps/tests/map-components.ts

@@ -11,16 +11,15 @@ import { renamePodPath } from '../../../../../utils/files/index.js';
 export function mapComponents(options: Options): FilePathMapEntries {
   const { podPath, projectRoot } = options;
 
-  const filePaths = findFiles(
-    join('tests/integration', podPath, 'components/**/component-test.{js,ts}'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir = join('tests/integration', podPath, 'components');
+
+  const filePaths = findFiles(`${podDir}/**/component-test.{js,ts}`, {
+    projectRoot,
+  });
 
   return filePaths.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('tests/integration', podPath, 'components'),
+      podDir,
       replace: (key: string) => {
         return `tests/integration/components/${key}-test`;
       },

src/migration/app/steps/create-file-path-maps/tests/map-route-controllers.ts

@@ -14,17 +14,16 @@ export function mapRouteControllers(options: Options): FilePathMapEntries {
   /*
     Case 1: Didn't pass the --pod flag, but configured { usePods: true } in .ember-cli
   */
-  const filePaths1 = findFiles(
-    join('tests/unit', podPath, '**/controller-test.{js,ts}'),
-    {
-      ignoreList: [join('tests/unit', podPath, 'controllers', '**')],
-      projectRoot,
-    },
-  );
+  const podDir1 = join('tests/unit', podPath);
+
+  const filePaths1 = findFiles(`${podDir1}/**/controller-test.{js,ts}`, {
+    ignoreList: [join('tests/unit', podPath, 'controllers/**')],
+    projectRoot,
+  });
 
   const filePathMap1 = filePaths1.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('tests/unit', podPath),
+      podDir: podDir1,
       replace: (key: string) => {
         return `tests/unit/controllers/${key}-test`;
       },
@@ -36,16 +35,15 @@ export function mapRouteControllers(options: Options): FilePathMapEntries {
   /*
     Case 2: Passed the --pod flag to Ember CLI
   */
-  const filePaths2 = findFiles(
-    join('tests/unit', podPath, 'controllers/**/controller-test.{js,ts}'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir2 = join('tests/unit', podPath, 'controllers');
+
+  const filePaths2 = findFiles(`${podDir2}/**/controller-test.{js,ts}`, {
+    projectRoot,
+  });
 
   const filePathMap2 = filePaths2.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('tests/unit', podPath, 'controllers'),
+      podDir: podDir2,
       replace: (key: string) => {
         return `tests/unit/controllers/${key}-test`;
       },

src/migration/app/steps/create-file-path-maps/tests/map-route-routes.ts

@@ -14,17 +14,16 @@ export function mapRouteRoutes(options: Options): FilePathMapEntries {
   /*
     Case 1: Didn't pass the --pod flag, but configured { usePods: true } in .ember-cli
   */
-  const filePaths1 = findFiles(
-    join('tests/unit', podPath, '**/route-test.{js,ts}'),
-    {
-      ignoreList: [join('tests/unit', podPath, 'routes', '**')],
-      projectRoot,
-    },
-  );
+  const podDir1 = join('tests/unit', podPath);
+
+  const filePaths1 = findFiles(`${podDir1}/**/route-test.{js,ts}`, {
+    ignoreList: [join('tests/unit', podPath, 'routes/**')],
+    projectRoot,
+  });
 
   const filePathMap1 = filePaths1.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('tests/unit', podPath),
+      podDir: podDir1,
       replace: (key: string) => {
         return `tests/unit/routes/${key}-test`;
       },
@@ -36,16 +35,15 @@ export function mapRouteRoutes(options: Options): FilePathMapEntries {
   /*
     Case 2: Passed the --pod flag to Ember CLI
   */
-  const filePaths2 = findFiles(
-    join('tests/unit', podPath, 'routes/**/route-test.{js,ts}'),
-    {
-      projectRoot,
-    },
-  );
+  const podDir2 = join('tests/unit', podPath, 'routes');
+
+  const filePaths2 = findFiles(`${podDir2}/**/route-test.{js,ts}`, {
+    projectRoot,
+  });
 
   const filePathMap2 = filePaths2.map((oldFilePath) => {
     const newFilePath = renamePodPath(oldFilePath, {
-      entityDir: join('tests/unit', podPath, 'routes'),
+      podDir: podDir2,
       replace: (key: string) => {
         return `tests/unit/routes/${key}-test`;
       },