@grafana/create-plugin 6.2.0-canary.2233.19097561440.0 → 6.2.0-canary.2233.19368311379.0

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

@@ -1,12 +1,15 @@
+import { existsSync } from 'node:fs';
 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}`, () => {
+      // ensure migration script exists
+      const sourceFilePath = migration.scriptPath.replace('.js', '.ts');
+      expect(existsSync(sourceFilePath)).toBe(true);
     });
   });
 });

package/src/codemods/migrations/migrations.ts

@@ -1,39 +1,43 @@
 import { LEGACY_UPDATE_CUTOFF_VERSION } from '../../constants.js';
+import { Codemod } from '../types.js';
+import { resolveScriptPath } from '../utils.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: resolveScriptPath(import.meta.url, './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: resolveScriptPath(import.meta.url, './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: resolveScriptPath(import.meta.url, './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: resolveScriptPath(import.meta.url, './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: resolveScriptPath(import.meta.url, './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);

package/src/codemods/utils.ts

@@ -1,9 +1,4 @@
-/**
- * Shared utilities for codemods (migrations and additions).
- * These functions work with the Context class to modify plugin codebases.
- */
-
-import { dirname, join } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
@@ -11,20 +6,10 @@ import chalk from 'chalk';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerSilentInstallCmd, getPackageManagerWithFallback } from '../utils/utils.packageManager.js';
 import { execSync } from 'node:child_process';
-import { clean, coerce, gt } from 'semver';
-
-/**
- * Generic metadata type for printChanges
- */
-type ChangeMetadata = {
-  description: string;
-};
+import { clean, coerce, gt, gte } from 'semver';
+import { fileURLToPath } from 'node:url';
 
-/**
- * Prints changes made to the context in a formatted way.
- * Works with both migrations and additions.
- */
-export function printChanges(context: Context, key: string, meta: ChangeMetadata) {
+export function printChanges(context: Context, key: string, description: string) {
   const changes = context.listChanges();
   const lines = [];
 
@@ -39,7 +24,7 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 
   output.addHorizontalLine('gray');
-  output.logSingleLine(`${key} (${meta.description})`);
+  output.logSingleLine(`${key} (${description})`);
 
   if (lines.length === 0) {
     output.logSingleLine('No changes were made');
@@ -48,9 +33,6 @@ export function printChanges(context: Context, key: string, meta: ChangeMetadata
   }
 }
 
-/**
- * Writes all changes from the context to the filesystem.
- */
 export function flushChanges(context: Context) {
   const basePath = context.basePath;
   const changes = context.listChanges();
@@ -122,9 +104,6 @@ export async function formatFiles(context: Context) {
 // (This runs for each codemod used in an update)
 let packageJsonInstallCache: string;
 
-/**
- * Installs NPM dependencies if package.json has changed.
- */
 export function installNPMDependencies(context: Context) {
   const hasPackageJsonChanges = Object.entries(context.listChanges()).some(
     ([filePath, { changeType }]) => filePath === 'package.json' && changeType === 'update'
@@ -152,9 +131,6 @@ export function installNPMDependencies(context: Context) {
   }
 }
 
-/**
- * Reads and parses a JSON file from the context.
- */
 export function readJsonFile<T extends object = any>(context: Context, path: string): T {
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
@@ -166,9 +142,6 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   }
 }
 
-/**
- * Adds or updates dependencies in package.json, preventing downgrades.
- */
 export function addDependenciesToPackageJson(
   context: Context,
   dependencies: Record<string, string>,
@@ -233,9 +206,6 @@ export function addDependenciesToPackageJson(
   context.updateFile(packageJsonPath, JSON.stringify(updatedPackageJson, null, 2));
 }
 
-/**
- * Removes dependencies from package.json.
- */
 export function removeDependenciesFromPackageJson(
   context: Context,
   dependencies: string[],
@@ -276,8 +246,13 @@ const DIST_TAGS = {
 
 /**
  * Compares two version strings to determine if the incoming version is greater
+ *
+ * @param incomingVersion - The incoming version to compare.
+ * @param existingVersion - The existing version to compare.
+ * @param orEqualTo - Whether to check for greater than or equal to (>=) instead of just greater than (>).
+ *
  */
-export function isVersionGreater(incomingVersion: string, existingVersion: string): boolean {
+export function isVersionGreater(incomingVersion: string, existingVersion: string, orEqualTo = false) {
   const incomingIsDistTag = incomingVersion in DIST_TAGS;
   const existingIsDistTag = existingVersion in DIST_TAGS;
 
@@ -301,6 +276,10 @@ export function isVersionGreater(incomingVersion: string, existingVersion: strin
     return true;
   }
 
+  if (orEqualTo) {
+    return gte(incomingSemver, existingSemver);
+  }
+
   return gt(incomingSemver, existingSemver);
 }
 
@@ -319,3 +298,16 @@ function sortObjectByKeys<T extends Record<string, any>>(obj: T): T {
     .sort()
     .reduce((acc, key) => ({ ...acc, [key]: obj[key] }), {} as T);
 }
+
+/**
+ * Resolves a script path relative to the caller's file location.
+ *
+ * @param callerUrl - The import.meta.url from the calling file
+ * @param relativePath - The relative path to resolve (e.g., './scripts/example.js')
+ * @returns The absolute resolved path
+ */
+export function resolveScriptPath(callerUrl: string, relativePath: string): string {
+  const __filename = fileURLToPath(callerUrl);
+  const __dirname = dirname(__filename);
+  return resolve(__dirname, relativePath);
+}