@grafana/create-plugin 6.2.0-canary.2233.19133609453.0 → 6.2.0-canary.2233.19424871609.0

package/src/codemods/migrations/manager.ts

@@ -1,11 +1,7 @@
-import defaultMigrations, { MigrationMeta } from './migrations.js';
-import { flushChanges, formatFiles, installNPMDependencies } from '../utils.js';
+import defaultMigrations, { Migration } from './migrations.js';
+import { runCodemod } from '../runner.js';
 import { gte, satisfies } from 'semver';
-import { migrationsDebug, printChanges } from './utils.js';
-
 import { CURRENT_APP_VERSION } from '../../utils/utils.version.js';
-import { Context } from '../context.js';
-import type { MigrationModule } from '../types.js';
 import { gitCommitNoVerify } from '../../utils/utils.git.js';
 import { output } from '../../utils/utils.console.js';
 import { setRootConfig } from '../../utils/utils.config.js';
@@ -13,59 +9,36 @@ import { setRootConfig } from '../../utils/utils.config.js';
 export function getMigrationsToRun(
   fromVersion: string,
   toVersion: string,
-  migrations: Record<string, MigrationMeta> = defaultMigrations.migrations
-): Record<string, MigrationMeta> {
+  migrations: Migration[] = defaultMigrations
+): Migration[] {
   const semverRange = `${fromVersion} - ${toVersion}`;
 
-  const migrationsToRun = Object.entries(migrations)
+  return migrations
+    .filter((meta) => satisfies(meta.version, semverRange))
     .sort((a, b) => {
-      return gte(a[1].version, b[1].version) ? 1 : -1;
-    })
-    .reduce<Record<string, MigrationMeta>>((acc, [key, meta]) => {
-      if (satisfies(meta.version, semverRange)) {
-        acc[key] = meta;
-      }
-      return acc;
-    }, {});
-
-  return migrationsToRun;
+      return gte(a.version, b.version) ? 1 : -1;
+    });
 }
 
 type RunMigrationsOptions = {
   commitEachMigration?: boolean;
+  codemodOptions?: Record<string, any>;
 };
 
-export async function runMigrations(migrations: Record<string, MigrationMeta>, options: RunMigrationsOptions = {}) {
-  const basePath = process.cwd();
-  const migrationList = Object.entries(migrations).map(
-    ([key, migrationMeta]) => `${key} (${migrationMeta.description})`
-  );
+export async function runMigrations(migrations: Migration[], options: RunMigrationsOptions = {}) {
+  const migrationList = migrations.map((meta) => `${meta.name} (${meta.description})`);
 
   const migrationListBody = migrationList.length > 0 ? output.bulletList(migrationList) : ['No migrations to run.'];
 
   output.log({ title: 'Running the following migrations:', body: migrationListBody });
 
-  for (const [key, migration] of Object.entries(migrations)) {
-    try {
-      const context = await runMigration(migration, new Context(basePath));
-      const shouldCommit = options.commitEachMigration && context.hasChanges();
-
-      migrationsDebug(`context for "${key} (${migration.migrationScript})":`);
-      migrationsDebug('%O', context.listChanges());
-
-      await formatFiles(context);
-      flushChanges(context);
-      printChanges(context, key, migration);
+  // run migrations sequentially in version order where lowest version runs first
+  for (const migration of migrations) {
+    const context = await runCodemod(migration, options.codemodOptions);
+    const shouldCommit = options.commitEachMigration && context.hasChanges();
 
-      installNPMDependencies(context);
-
-      if (shouldCommit) {
-        await gitCommitNoVerify(`chore: run create-plugin migration - ${key} (${migration.migrationScript})`);
-      }
-    } catch (error) {
-      if (error instanceof Error) {
-        throw new Error(`Error running migration "${key} (${migration.migrationScript})": ${error.message}`);
-      }
+    if (shouldCommit) {
+      await gitCommitNoVerify(`chore: run create-plugin migration - ${migration.name} (${migration.scriptPath})`);
     }
   }
 
@@ -75,9 +48,3 @@ export async function runMigrations(migrations: Record<string, MigrationMeta>, o
     await gitCommitNoVerify(`chore: update .config/.cprc.json to version ${CURRENT_APP_VERSION}.`);
   }
 }
-
-export async function runMigration(migration: MigrationMeta, context: Context): Promise<Context> {
-  const module = (await import(migration.migrationScript)) as MigrationModule;
-
-  return module.default(context);
-}

package/src/codemods/migrations/migrations.test.ts

@@ -1,12 +1,17 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import defaultMigrations from './migrations.js';
 
 describe('migrations json', () => {
   // As migration scripts are imported dynamically when update is run we assert the path is valid
-  Object.entries(defaultMigrations.migrations).forEach(([key, migration]) => {
-    it(`should have a valid migration script path for ${key}`, () => {
-      expect(async () => {
-        await import(migration.migrationScript);
-      }).not.toThrow();
+  // Vitest 4 reimplemented its workers, which caused the previous dynamic import tests to fail.
+  // This test now only asserts that the migration script source file exists.
+  defaultMigrations.forEach((migration) => {
+    it(`should have a valid migration script path for ${migration.name}`, () => {
+      // import.meta.resolve() returns a file:// URL, convert to path
+      const filePath = fileURLToPath(migration.scriptPath);
+      const sourceFilePath = filePath.replace('.js', '.ts');
+      expect(existsSync(sourceFilePath)).toBe(true);
     });
   });
 });

package/src/codemods/migrations/migrations.ts

@@ -1,39 +1,42 @@
 import { LEGACY_UPDATE_CUTOFF_VERSION } from '../../constants.js';
+import { Codemod } from '../types.js';
 
-export type MigrationMeta = {
+export interface Migration extends Codemod {
   version: string;
-  description: string;
-  migrationScript: string;
-};
+}
 
-type Migrations = {
-  migrations: Record<string, MigrationMeta>;
-};
-
-export default {
-  migrations: {
-    '001-update-grafana-compose-extend': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Update ./docker-compose.yaml to extend from ./.config/docker-compose-base.yaml.',
-      migrationScript: './scripts/001-update-grafana-compose-extend.js',
-    },
-    '002-update-is-compatible-workflow': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description:
-        'Update ./.github/workflows/is-compatible.yml to use is-compatible github action instead of calling levitate directly',
-      migrationScript: './scripts/002-update-is-compatible-workflow.js',
-    },
-    '003-update-eslint-deprecation-rule': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Replace deprecated eslint-plugin-deprecation with @typescript-eslint/no-deprecated rule.',
-      migrationScript: './scripts/003-update-eslint-deprecation-rule.js',
-    },
-    '004-eslint9-flat-config': {
-      version: LEGACY_UPDATE_CUTOFF_VERSION,
-      description: 'Migrate eslint config to flat config format and update devDependencies to latest versions.',
-      migrationScript: './scripts/004-eslint9-flat-config.js',
-    },
-    // Do not use LEGACY_UPDATE_CUTOFF_VERSION for new migrations. It is only used above to force migrations to run
-    // for those written before the switch to updates as migrations.
+export default [
+  {
+    name: '001-update-grafana-compose-extend',
+    version: LEGACY_UPDATE_CUTOFF_VERSION,
+    description: 'Update ./docker-compose.yaml to extend from ./.config/docker-compose-base.yaml.',
+    scriptPath: import.meta.resolve('./scripts/001-update-grafana-compose-extend.js'),
+  },
+  {
+    name: '002-update-is-compatible-workflow',
+    version: LEGACY_UPDATE_CUTOFF_VERSION,
+    description:
+      'Update ./.github/workflows/is-compatible.yml to use is-compatible github action instead of calling levitate directly',
+    scriptPath: import.meta.resolve('./scripts/002-update-is-compatible-workflow.js'),
+  },
+  {
+    name: '003-update-eslint-deprecation-rule',
+    version: LEGACY_UPDATE_CUTOFF_VERSION,
+    description: 'Replace deprecated eslint-plugin-deprecation with @typescript-eslint/no-deprecated rule.',
+    scriptPath: import.meta.resolve('./scripts/003-update-eslint-deprecation-rule.js'),
+  },
+  {
+    name: '004-eslint9-flat-config',
+    version: LEGACY_UPDATE_CUTOFF_VERSION,
+    description: 'Migrate eslint config to flat config format and update devDependencies to latest versions.',
+    scriptPath: import.meta.resolve('./scripts/004-eslint9-flat-config.js'),
+  },
+  {
+    name: '005-react-18-3',
+    version: '6.1.9',
+    description: 'Update React and ReactDOM 18.x versions to ^18.3.0 to surface React 19 compatibility issues.',
+    scriptPath: import.meta.resolve('./scripts/005-react-18-3.js'),
   },
-} as Migrations;
+  // Do not use LEGACY_UPDATE_CUTOFF_VERSION for new migrations. It is only used above to force migrations to run
+  // for those written before the switch to updates as migrations.
+] satisfies Migration[];

package/src/codemods/migrations/scripts/004-eslint9-flat-config.ts

@@ -7,7 +7,7 @@ import { dirname, relative, resolve } from 'node:path';
 import * as recast from 'recast';
 import type { Context } from '../../context.js';
 import { addDependenciesToPackageJson } from '../../utils.js';
-import { migrationsDebug } from '../utils.js';
+// migrationsDebug removed - was from deleted migrations/utils.js
 
 type Imports = Map<string, { name?: string; bindings?: string[] }>;
 
@@ -407,7 +407,7 @@ function getIgnorePaths(context: Context): string[] {
         }
       }
     } catch (error) {
-      migrationsDebug('Error parsing package.json: %s', error);
+      console.log('Error parsing package.json: %s', error);
     }
   }
 

package/src/codemods/migrations/scripts/005-react-18-3.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect } from 'vitest';
+import { Context } from '../../context.js';
+import migrate from './005-react-18-3.js';
+
+describe('005-react-18-3', () => {
+  it('should not modify anything if package.json does not exist', async () => {
+    const context = new Context('/virtual');
+    await migrate(context);
+    expect(context.listChanges()).toEqual({});
+  });
+
+  it('should not modify anything if there are no React dependencies', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          lodash: '^4.17.21',
+        },
+      })
+    );
+    const initialChanges = context.listChanges();
+    await migrate(context);
+    expect(context.listChanges()).toEqual(initialChanges);
+  });
+
+  it('should not update React if version is below 18.0.0', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^17.0.2',
+        'react-dom': '^17.0.2',
+      },
+      devDependencies: {
+        '@types/react': '^17.0.0',
+        '@types/react-dom': '^17.0.0',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+    const initialPackageJson = context.getFile('./package.json');
+
+    await migrate(context);
+
+    expect(context.getFile('./package.json')).toBe(initialPackageJson);
+  });
+
+  it('should update React 18.0.0 to ^18.3.0', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '^18.0.0',
+        },
+      })
+    );
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.0');
+    expect(updatedPackageJson.devDependencies?.['@types/react']).toBe('^18.3.0');
+  });
+
+  it('should not update React if version is already 18.3.0 or higher', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^18.3.0',
+        'react-dom': '^18.3.0',
+      },
+      devDependencies: {
+        '@types/react': '^18.3.0',
+        '@types/react-dom': '^18.3.0',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.0');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^18.3.0');
+  });
+
+  it('should not downgrade React 19.0.0 to 18.3.0', async () => {
+    const context = new Context('/virtual');
+    const packageJson = {
+      dependencies: {
+        react: '^19.0.0',
+        'react-dom': '^19.0.0',
+      },
+      devDependencies: {
+        '@types/react': '^19.0.0',
+        '@types/react-dom': '^19.0.0',
+      },
+    };
+    context.addFile('./package.json', JSON.stringify(packageJson, null, 2));
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^19.0.0');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^19.0.0');
+    expect(updatedPackageJson.devDependencies['@types/react']).toBe('^19.0.0');
+    expect(updatedPackageJson.devDependencies['@types/react-dom']).toBe('^19.0.0');
+  });
+
+  it('should handle version ranges correctly', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '~18.1.0',
+          'react-dom': '18.2.0',
+        },
+      })
+    );
+
+    await migrate(context);
+
+    const updatedPackageJson = JSON.parse(context.getFile('./package.json') || '{}');
+    expect(updatedPackageJson.dependencies.react).toBe('^18.3.0');
+    expect(updatedPackageJson.dependencies['react-dom']).toBe('^18.3.0');
+  });
+
+  it('should be idempotent', async () => {
+    const context = new Context('/virtual');
+    context.addFile(
+      './package.json',
+      JSON.stringify({
+        dependencies: {
+          react: '^18.2.0',
+          'react-dom': '^18.2.0',
+        },
+        devDependencies: {
+          '@types/react': '^18.2.0',
+          '@types/react-dom': '^18.2.0',
+        },
+      })
+    );
+    await expect(migrate).toBeIdempotent(context);
+  });
+});

package/src/codemods/migrations/scripts/005-react-18-3.ts

@@ -0,0 +1,19 @@
+import type { Context } from '../../context.js';
+import { addDependenciesToPackageJson, isVersionGreater } from '../../utils.js';
+
+export default function migrate(context: Context) {
+  if (context.doesFileExist('package.json')) {
+    const packageJson = JSON.parse(context.getFile('package.json') || '{}');
+    if (packageJson.dependencies?.react) {
+      if (isVersionGreater(packageJson.dependencies.react, '18.0.0', true)) {
+        addDependenciesToPackageJson(context, { react: '^18.3.0' }, { '@types/react': '^18.3.0' });
+      }
+    }
+    if (packageJson.dependencies?.['react-dom']) {
+      if (isVersionGreater(packageJson.dependencies['react-dom'], '18.0.0', true)) {
+        addDependenciesToPackageJson(context, { 'react-dom': '^18.3.0' }, { '@types/react-dom': '^18.3.0' });
+      }
+    }
+  }
+  return context;
+}

package/src/codemods/migrations/scripts/example-migration.test.ts

@@ -14,7 +14,7 @@ describe('Migration - append profile to webpack', () => {
       })
     );
 
-    const updatedContext = await migrate(context);
+    const updatedContext = await migrate(context, { profile: true, skipBackup: false, verbose: false });
 
     expect(updatedContext.getFile('./package.json')).toMatch(
       'webpack -c ./.config/webpack/webpack.config.ts --profile --env production'

package/src/codemods/migrations/scripts/example-migration.ts

@@ -1,6 +1,23 @@
 import type { Context } from '../../context.js';
 
-export default function migrate(context: Context): Context {
+/**
+ * Example migration that demonstrates basic context operations
+ * This example shows how to modify package.json, add/delete files, and rename files
+ */
+
+type MigrateOptions = {
+  profile?: boolean;
+  skipBackup?: boolean;
+  verbose?: boolean;
+};
+
+export default function migrate(context: Context, options: MigrateOptions = {}): Context {
+  const { profile = false, skipBackup = false, verbose = false } = options;
+
+  if (verbose) {
+    console.log('Running migration with options:', options);
+  }
+
   const rawPkgJson = context.getFile('./package.json') ?? '{}';
   const packageJson = JSON.parse(rawPkgJson);
 
@@ -9,14 +26,14 @@ export default function migrate(context: Context): Context {
 
     const pattern = /(webpack.+-c\s.+\.ts)\s(.+)/;
 
-    if (pattern.test(buildScript) && !buildScript.includes('--profile')) {
+    if (profile && pattern.test(buildScript) && !buildScript.includes('--profile')) {
       packageJson.scripts.build = buildScript.replace(pattern, `$1 --profile $2`);
     }
 
     context.updateFile('./package.json', JSON.stringify(packageJson, null, 2));
   }
 
-  if (context.doesFileExist('./src/README.md')) {
+  if (!skipBackup && context.doesFileExist('./src/README.md')) {
     context.deleteFile('./src/README.md');
   }
 

package/src/codemods/runner.ts

@@ -0,0 +1,57 @@
+import { Context } from './context.js';
+import { formatFiles, flushChanges, installNPMDependencies, printChanges } from './utils.js';
+import { parseAndValidateOptions } from './schema-parser.js';
+import { output } from '../utils/utils.console.js';
+import { Codemod } from './types.js';
+
+/**
+ * Run a single codemod
+ *
+ * Steps:
+ * 1. Load codemod module from scriptPath
+ * 2. Parse and validate options from schema
+ * 3. Execute codemod transformation
+ * 4. Format files
+ * 5. Flush changes to disk
+ * 6. Print summary
+ * 7. Install dependencies if needed
+ */
+export async function runCodemod(codemod: Codemod, options?: Record<string, any>): Promise<Context> {
+  const codemodModule = await import(codemod.scriptPath);
+  if (!codemodModule.default || typeof codemodModule.default !== 'function') {
+    throw new Error(`Codemod ${codemod.name} must export a default function`);
+  }
+
+  let codemodOptions = {};
+
+  if (options && codemodModule.schema) {
+    codemodOptions = parseAndValidateOptions(options, codemodModule.schema);
+  }
+
+  const basePath = process.cwd();
+  const context = new Context(basePath);
+
+  try {
+    output.log({
+      title: `Running ${codemod.name}`,
+      body: [codemod.description],
+    });
+
+    const updatedContext = await codemodModule.default(context, codemodOptions);
+
+    // standard post-processing pipeline
+    await formatFiles(updatedContext);
+    flushChanges(updatedContext);
+    printChanges(updatedContext, codemod.name, codemod.description);
+    installNPMDependencies(updatedContext);
+
+    return updatedContext;
+  } catch (error) {
+    if (error instanceof Error) {
+      const newError = new Error(`Error running ${codemod.name}: ${error.message}`);
+      newError.cause = error;
+      throw newError;
+    }
+    throw error;
+  }
+}

package/src/codemods/schema-parser.ts

@@ -0,0 +1,27 @@
+import * as v from 'valibot';
+
+/**
+ * Parse and validate options using Valibot schema
+ * Valibot handles parsing, validation, type coercion, and defaults automatically
+ */
+export function parseAndValidateOptions<T extends v.BaseSchema<any, any, any>>(
+  options: Record<string, any>,
+  schema: T
+): v.InferOutput<T> {
+  try {
+    return v.parse(schema, options);
+  } catch (error) {
+    if (v.isValiError(error)) {
+      // format Valibot validation errors
+      const formattedErrors = error.issues
+        .map((issue) => {
+          const path = issue.path?.map((p) => p.key).join('.') || '';
+          return `  --${path}: ${issue.message}`;
+        })
+        .join('\n');
+
+      throw new Error(`Invalid flag(s) provided:\n\n${formattedErrors}`);
+    }
+    throw error;
+  }
+}

package/src/codemods/types.ts

@@ -1,21 +1,16 @@
 import type { Context } from './context.js';
+import type * as v from 'valibot';
 
-export interface CodemodModule {
-  default: (context: Context) => Context | Promise<Context>;
+// used as a generic constraint for codemod schemas. accepts any input, output and error types
+type AnySchema = v.BaseSchema<any, any, any>;
+
+export interface CodemodModule<TSchema extends AnySchema = AnySchema> {
+  default: (context: Context, options: v.InferOutput<TSchema>) => Context | Promise<Context>;
+  schema?: TSchema;
 }
 
-export interface FlagDefinition {
+export interface Codemod {
   name: string;
   description: string;
-  required: boolean;
-}
-
-export interface AdditionModule<TOptions = any> extends CodemodModule {
-  default: (context: Context, options?: TOptions) => Context | Promise<Context>;
-  flags?: FlagDefinition[];
-  parseFlags?: (argv: any) => TOptions;
-}
-
-export interface MigrationModule extends CodemodModule {
-  default: (context: Context) => Context | Promise<Context>;
+  scriptPath: string;
 }

package/src/codemods/{migrations/utils.test.ts → utils.test.ts}

@@ -1,5 +1,5 @@
 import { dirSync } from 'tmp';
-import { Context } from '../context.js';
+import { Context } from './context.js';
 import {
   addDependenciesToPackageJson,
   removeDependenciesFromPackageJson,
@@ -7,12 +7,13 @@ import {
   formatFiles,
   readJsonFile,
   isVersionGreater,
-} from '../utils.js';
-import { printChanges } from './utils.js';
+  printChanges,
+} from './utils.js';
 import { join } from 'node:path';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { readFileSync } from 'node:fs';
-import { output } from '../../utils/utils.console.js';
+import { output } from '../utils/utils.console.js';
+import { vi } from 'vitest';
 
 describe('utils', () => {
   const tmpObj = dirSync({ unsafeCleanup: true });
@@ -80,7 +81,7 @@ describe('utils', () => {
       context.updateFile('baz.ts', 'new content');
       context.deleteFile('bar.ts');
 
-      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+      printChanges(context, 'key', 'test');
 
       expect(outputMock.addHorizontalLine).toHaveBeenCalledWith('gray');
       expect(outputMock.logSingleLine).toHaveBeenCalledWith('key (test)');
@@ -102,7 +103,7 @@ describe('utils', () => {
     it('should print no changes', async () => {
       const context = new Context(tmpDir);
 
-      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+      printChanges(context, 'key', 'test');
 
       expect(outputMock.logSingleLine).toHaveBeenCalledWith('No changes were made');
     });
@@ -271,7 +272,7 @@ describe('utils', () => {
     });
   });
 
-  describe('isIncomingVersionGreater', () => {
+  describe('isVersionGreater', () => {
     describe('dist tag comparison', () => {
       it('should return false when incoming is "latest" and existing is "next"', () => {
         expect(isVersionGreater('latest', 'next')).toBe(false);