chore(codemods): add codemods guide documentation (#10501)

* fix(codemods): centralize defaults, improve error visibility, remove hardcoded path

- Centralize default values (inputDir, outputDir, modelSourceDir, etc.) in
  config.ts and make them required on FinalOptions so downstream code reads
  them directly without scattered fallbacks
- Promote extension creation failure from log.warn to log.error so failures
  are visible at default log levels
- Remove hardcoded /app/core/ intermediate model check — users should
  configure additionalModelSources instead

* docs(codemods): Add using codemods guide

* fix(codemods): use 'modern' warpdrive imports by default

fix: use LegacyTrait interface for traits instead of LegacyResourceSchema

* chore(codemods): add a TODO note for POJO extensions

Author: BobrImperator

guides/migrating/codemods.md

@@ -50,6 +50,13 @@ function createMigrateToSchemaCommand(applyCommand: Command) {
 
   command
     .addOption(new Option('--config <path>', 'Path to configuration file'))
+    .addOption(new Option('--project-name <name>', 'Project name for resolving classic ember module imports'))
+    .addOption(
+      new Option(
+        '--warp-drive-imports <preset>',
+        'WarpDrive import preset: "legacy" for @ember-data/*, "modern" for @warp-drive/*, "mirror" for @warp-drive-mirror/*'
+      ).choices(['legacy', 'modern', 'mirror'])
+    )
     .addOption(new Option('--skip-processed', 'Skip files that have already been processed'))
     .addOption(new Option('--force-typescript', 'Force all output files to TypeScript (.ts)'))
     .addOption(new Option('--model-source-dir <path>', 'Directory containing model files').default('./app/models'))
@@ -136,6 +143,10 @@ async function handleMigrateToSchema(
     ...(options.mixinsOnly !== undefined && { mixinsOnly: Boolean(options.mixinsOnly) }),
     ...(options.skipProcessed !== undefined && { skipProcessed: Boolean(options.skipProcessed) }),
     ...(options.forceTypescript !== undefined && { forceTypeScript: Boolean(options.forceTypescript) }),
+    ...(options.projectName !== undefined && { projectName: String(options.projectName) }),
+    ...(options.warpDriveImports !== undefined && {
+      warpDriveImports: options.warpDriveImports as 'legacy' | 'modern' | 'mirror',
+    }),
     modelSourceDir: String(options.modelSourceDir || './app/models'),
     mixinSourceDir: String(options.mixinSourceDir || './app/mixins'),
     outputDir: String(options.outputDir || './app/schemas'),

packages/codemods/src/cli/apply.ts

@@ -65,11 +65,6 @@ function isIntermediateModel(
           }
         }
       }
-
-      // Also check if it's in app/core
-      if (filePath.includes('/app/core/')) {
-        return true;
-      }
     }
   }
 
@@ -267,7 +262,6 @@ export class Codemod {
   }
 
   async findModels() {
-    // TODO: || './app/models'
     if (!this.finalOptions.modelSourceDir) {
       throw new Error('`options.modelSourceDir` must be specified before looking for files');
     }

packages/codemods/src/schema-migration/codemod.ts

@@ -1,5 +1,10 @@
 export const DEFAULT_RESOURCES_DIR = './app/data/resources';
 export const DEFAULT_TRAITS_DIR = './app/data/traits';
+export const DEFAULT_INPUT_DIR = './app';
+export const DEFAULT_OUTPUT_DIR = './app/schemas';
+export const DEFAULT_MODEL_SOURCE_DIR = './app/models';
+export const DEFAULT_MIXIN_SOURCE_DIR = './app/mixins';
+export const DEFAULT_WARP_DRIVE_IMPORTS = 'modern' as const;
 
 export interface PackageImport {
   imported: string;
@@ -37,25 +42,29 @@ interface TransformPackageImports {
   Type: PackageImport;
   WithLegacy: PackageImport;
   LegacyResourceSchema: PackageImport;
+  LegacyTrait: PackageImport;
 }
 
 export const LegacyPackageImports = {
   Model: { imported: 'default', source: '@ember-data/model' },
   Type: { imported: 'Type', source: '@warp-drive/core-types/symbols' },
   WithLegacy: { imported: 'WithLegacy', source: '@ember-data/model/migration-support' },
   LegacyResourceSchema: { imported: 'LegacyResourceSchema', source: '@warp-drive/core-types/schema/fields' },
+  LegacyTrait: { imported: 'LegacyTrait', source: '@warp-drive/core-types/schema/fields' },
 } satisfies TransformPackageImports;
 export const ModernPackageImports = {
   Model: { imported: 'Model', source: '@warp-drive/legacy/model' },
   Type: { imported: 'Type', source: '@warp-drive/core/types/symbols' },
   WithLegacy: { imported: 'WithLegacy', source: '@warp-drive/legacy/model/migration-support' },
   LegacyResourceSchema: { imported: 'LegacyResourceSchema', source: '@warp-drive/core/types/schema/fields' },
+  LegacyTrait: { imported: 'LegacyTrait', source: '@warp-drive/core/types/schema/fields' },
 } satisfies TransformPackageImports;
 export const MirrorPackageImports = {
   Model: { imported: 'Model', source: '@warp-drive-mirror/legacy/model' },
   Type: { imported: 'Type', source: '@warp-drive-mirror/core/types/symbols' },
   WithLegacy: { imported: 'WithLegacy', source: '@warp-drive-mirror/legacy/model/migration-support' },
   LegacyResourceSchema: { imported: 'LegacyResourceSchema', source: '@warp-drive-mirror/core/types/schema/fields' },
+  LegacyTrait: { imported: 'LegacyTrait', source: '@warp-drive-mirror/core/types/schema/fields' },
 } satisfies TransformPackageImports;
 
 export function getConfiguredImport(
@@ -210,4 +219,10 @@ export interface MigrateOptions extends Partial<TransformOptions> {
   mixinSourceDir?: string;
 }
 
-export type FinalOptions = TransformOptions & MigrateOptions & { kind: 'finalized' };
+export type FinalOptions = TransformOptions &
+  MigrateOptions &
+  Required<Pick<TransformOptions, 'modelSourceDir' | 'mixinSourceDir' | 'warpDriveImports' | 'projectName'>> &
+  Required<Pick<MigrateOptions, 'inputDir'>> & {
+    kind: 'finalized';
+    outputDir: string;
+  };

packages/codemods/src/schema-migration/config.ts

@@ -192,7 +192,7 @@ function resolveMixinPath(
   options: FinalOptions
 ): string | null {
   try {
-    const mixinSourceDir = resolve(options.mixinSourceDir || './app/mixins');
+    const mixinSourceDir = resolve(options.mixinSourceDir);
     const config = getImportSourceConfig('mixin', options);
 
     // Handle relative paths - must be within mixin source directory

packages/codemods/src/schema-migration/processors/mixin-analyzer.ts

@@ -5,7 +5,15 @@ import { type InstanciatedLogger, logger } from '../../../utils/logger.js';
 import type { SkippedFile, TransformerResult } from '../codemod.js';
 import { Codemod } from '../codemod.js';
 import type { FinalOptions, MigrateOptions, TransformOptions } from '../config.js';
-import { DEFAULT_RESOURCES_DIR, DEFAULT_TRAITS_DIR } from '../config.js';
+import {
+  DEFAULT_INPUT_DIR,
+  DEFAULT_MIXIN_SOURCE_DIR,
+  DEFAULT_MODEL_SOURCE_DIR,
+  DEFAULT_OUTPUT_DIR,
+  DEFAULT_RESOURCES_DIR,
+  DEFAULT_TRAITS_DIR,
+  DEFAULT_WARP_DRIVE_IMPORTS,
+} from '../config.js';
 import { toArtifacts as mixinToArtifacts } from '../processors/mixin.js';
 import { processIntermediateModelsToTraits, toArtifacts as modelToArtifacts } from '../processors/model.js';
 import type { SchemaArtifact, SchemaArtifactRegistry } from '../utils/artifact.js';
@@ -121,9 +129,9 @@ function getRelativePathFromAdditionalSources(
 /**
  * Get the relative path for a mixin file, handling both local and external mixins
  */
-function getRelativePathForMixin(filePath: string, options: TransformOptions): string {
+function getRelativePathForMixin(filePath: string, options: FinalOptions): string {
   // First, try to get relative path from the main mixin source directory
-  const mixinSourceDir = resolve(options.mixinSourceDir || './app/mixins');
+  const mixinSourceDir = resolve(options.mixinSourceDir);
   if (filePath.startsWith(mixinSourceDir)) {
     return filePath.replace(mixinSourceDir, '').replace(/^\//, '');
   }
@@ -154,9 +162,9 @@ function getRelativePathForMixin(filePath: string, options: TransformOptions): s
 /**
  * Calculate relative path for model-based artifacts (schema, resource-type)
  */
-function getRelativePathForModel(filePath: string, options: TransformOptions): string {
+function getRelativePathForModel(filePath: string, options: FinalOptions): string {
   // Try standard model source directory first
-  let relativePath = filePath.replace(resolve(options.modelSourceDir || './app/models'), '');
+  let relativePath = filePath.replace(resolve(options.modelSourceDir), '');
 
   // If not in standard directory, check additionalModelSources
   if (relativePath === filePath) {
@@ -210,7 +218,7 @@ function buildOutputFileName(
 /**
  * Get the output directory for an artifact type
  */
-function getOutputDirectory(artifactType: string, options: TransformOptions): string {
+function getOutputDirectory(artifactType: string, options: FinalOptions): string {
   const config = ARTIFACT_CONFIG[artifactType as ArtifactType] ?? DEFAULT_FALLBACK_CONFIG;
   return options[config.directoryKey] ?? config.defaultDir;
 }
@@ -221,7 +229,7 @@ function getOutputDirectory(artifactType: string, options: TransformOptions): st
 function getArtifactOutputPath(
   artifact: Artifact,
   filePath: string,
-  options: TransformOptions
+  options: FinalOptions
 ): { outputDir: string; outputPath: string } {
   const config = ARTIFACT_CONFIG[artifact.type as ArtifactType] ?? DEFAULT_FALLBACK_CONFIG;
   const outputDir = getOutputDirectory(artifact.type, options);
@@ -367,21 +375,21 @@ function processFiles({ registry, finalOptions, log }: ProcessFilesOptions): Pro
 export async function runMigration(options: MigrateOptions): Promise<void> {
   const finalOptions: FinalOptions = {
     kind: 'finalized',
-    inputDir: options.inputDir || './app',
-    outputDir: options.outputDir || './app/schemas',
+    inputDir: options.inputDir || DEFAULT_INPUT_DIR,
+    outputDir: options.outputDir || DEFAULT_OUTPUT_DIR,
     dryRun: options.dryRun || false,
     verbose: options.verbose || false,
-    warpDriveImports: options.warpDriveImports || 'legacy',
-    modelSourceDir: options.modelSourceDir || './app/models',
-    mixinSourceDir: options.mixinSourceDir || './app/mixins',
+    warpDriveImports: options.warpDriveImports || DEFAULT_WARP_DRIVE_IMPORTS,
+    modelSourceDir: options.modelSourceDir || DEFAULT_MODEL_SOURCE_DIR,
+    mixinSourceDir: options.mixinSourceDir || DEFAULT_MIXIN_SOURCE_DIR,
     projectName: options.projectName || '',
     ...options,
   };
 
   const log = logger.for('migrate-to-schema');
   log.info(`🚀 Starting schema migration...`);
-  log.info(`📁 Input directory: ${resolve(finalOptions.inputDir || './app')}`);
-  log.info(`📁 Output directory: ${resolve(finalOptions.outputDir || './app/schemas')}`);
+  log.info(`📁 Input directory: ${resolve(finalOptions.inputDir)}`);
+  log.info(`📁 Output directory: ${resolve(finalOptions.outputDir)}`);
 
   const codemod = new Codemod(log, finalOptions);
 

packages/codemods/src/schema-migration/tasks/migrate.ts

@@ -7,6 +7,8 @@ export interface ConfigOptions {
   debug?: boolean;
   forceTypeScript?: boolean;
   mirror?: boolean;
+  projectName?: string;
+  warpDriveImports?: 'legacy' | 'modern' | 'mirror';
   emberDataImportSource?: string;
   intermediateModelPaths?: string[] | string;
   modelImportSource?: string;

packages/codemods/src/schema-migration/utils/config.ts

@@ -303,15 +303,16 @@ export function generateExtensionCode(
 
   const objectCode = `export const ${config.identifiers.extension} = {\n${properties}\n};`;
   const registrationBlock = generateRegistrationBlock(config.name, config.identifiers.extension!);
+  const migrationNote = `// TODO: migrate this extension to a class so that TypeScript declaration merging works.\n// Object extensions do not support interface merging.\n`;
 
   if (config.extensionIsTyped && typeToExtend) {
     const importStatement = interfaceImportPath
       ? `import type { ${typeToExtend} } from '${interfaceImportPath}';\n\n`
       : '';
-    return `${importStatement}export interface ${config.identifiers.extension} extends ${typeToExtend} {}\n\n${objectCode}\n\n${registrationBlock}`;
+    return `${importStatement}export interface ${config.identifiers.extension} extends ${typeToExtend} {}\n\n${migrationNote}${objectCode}\n\n${registrationBlock}`;
   }
 
-  return `${objectCode}\n\n${registrationBlock}`;
+  return `${migrationNote}${objectCode}\n\n${registrationBlock}`;
 }
 
 /**
@@ -622,7 +623,7 @@ export function createExtensionFromOriginalFile(
       suggestedFileName: extFileName,
     };
   } catch (error) {
-    log.warn(`Error creating extension from original file: ${String(error)}`);
+    log.error(`❌ Error creating extension for '${filePath}': ${String(error)}`);
     return null;
   }
 }

packages/codemods/src/schema-migration/utils/extension-generation.ts

@@ -692,7 +692,8 @@ function generateSchemaDeclaration(config: ArtifactConfig, schemaObject: Record<
   jsonString = jsonString.replace(new RegExp(`'${SCHEMA_OPTION_REF_PREFIX}([^']+)'`, 'g'), '$1');
 
   if (config.schemaIsTyped) {
-    return `const ${config.identifiers.schema} = ${jsonString} satisfies LegacyResourceSchema;`;
+    const satisfiesType = config.type === 'trait' ? 'LegacyTrait' : 'LegacyResourceSchema';
+    return `const ${config.identifiers.schema} = ${jsonString} satisfies ${satisfiesType};`;
   } else {
     return `const ${config.identifiers.schema} = ${jsonString};`;
   }
@@ -865,7 +866,8 @@ export function generateMergedSchemaCode(opts: MergedSchemaOptions): GeneratedSc
   };
 
   if (!opts.options?.disableTypescriptSchemas) {
-    const importLocation = getConfiguredImport(opts.options, 'LegacyResourceSchema');
+    const schemaTypeKey = config.type === 'trait' ? 'LegacyTrait' : 'LegacyResourceSchema';
+    const importLocation = getConfiguredImport(opts.options, schemaTypeKey);
     parts.schemaImports = `import type { ${importLocation.imported} } from '${importLocation.source}';\n`;
   }