@grafana/create-plugin 7.17.0 → 7.19.0

package/src/codemods/additions/scripts/rspack.ts

@@ -0,0 +1,453 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { lt, major, minVersion, validRange } from 'semver';
+import type { Context } from '../../context.js';
+import { replaceExperimentalRspackFlag } from '../../utils.rspack.js';
+import { renderHandlebarsTemplate } from '../../../utils/utils.handlebars.js';
+import { getTemplateData } from '../../../utils/utils.templates.js';
+import {
+  additionsDebug,
+  addDependenciesToPackageJson,
+  readJsonFile,
+  removeDependenciesFromPackageJson,
+  renderTemplate,
+} from '../../utils.js';
+
+const RSPACK_TEMPLATE_DATA_OVERRIDES = {
+  useRspack: true,
+  frontendBundler: 'rspack',
+};
+
+const RSPACK_CONFIG_FILES = [
+  '.config/rspack/rspack.config.ts',
+  '.config/rspack/BuildModeRspackPlugin.ts',
+  '.config/rspack/LiveReloadRspackPlugin.ts',
+  '.config/rspack/LicenseRspackPlugin.ts',
+  '.config/rspack/DiagnosticsRspackPlugin.ts',
+  '.config/rspack/PluginCssRspackPlugin.ts',
+];
+
+// files the rspack template used to ship under another name. removed so they do not linger
+const RETIRED_RSPACK_FILES = ['.config/rspack/liveReloadPlugin.ts'];
+
+// markdown in .config that describes the bundler, for agents and for developers
+const DOC_FILES = ['.config/AGENTS/instructions.md', '.config/README.md'];
+
+const BUNDLER_FILES = [
+  '.config/bundler/constants.ts',
+  '.config/bundler/copyFiles.ts',
+  '.config/bundler/externals.ts',
+  '.config/bundler/utils.ts',
+];
+
+const WEBPACK_CONFIG_PATH = '.config/webpack/webpack.config.ts';
+const RSPACK_CONFIG_PATH = '.config/rspack/rspack.config.ts';
+
+// every file create-plugin has scaffolded into .config/webpack over time. anything else in there
+// was added by the plugin author, so it is kept and reported instead of deleted
+const WEBPACK_TEMPLATE_FILES = [
+  '.config/webpack/BuildModeWebpackPlugin.ts',
+  '.config/webpack/PluginSchemaWebpackPlugin.ts',
+  '.config/webpack/constants.ts',
+  '.config/webpack/generateCode.ts',
+  '.config/webpack/publicPath.ts',
+  '.config/webpack/tsconfig.webpack.json',
+  '.config/webpack/utils.ts',
+  '.config/webpack/watchPluginJson.ts',
+  '.config/webpack/webpack.config.ts',
+  '.config/webpack/webpack.parts.ts',
+];
+
+export default function rspack(context: Context): Context {
+  const hasWebpackSetup = context.doesFileExist(WEBPACK_CONFIG_PATH);
+  const hasRspackSetup = context.doesFileExist(RSPACK_CONFIG_PATH);
+
+  if (!hasWebpackSetup && !hasRspackSetup) {
+    context.setMessage({
+      level: 'warning',
+      title: 'No create-plugin bundler configuration found, so nothing was changed.',
+      body: [`The rspack addition expects ${WEBPACK_CONFIG_PATH} or ${RSPACK_CONFIG_PATH} to exist.`],
+    });
+    return context;
+  }
+
+  const followUps: string[] = [];
+
+  deleteRetiredRspackFiles(context);
+  renderTemplateFiles(context, RSPACK_CONFIG_FILES);
+  renderTemplateFiles(context, BUNDLER_FILES);
+  renderTemplateFiles(context, DOC_FILES, false);
+  replaceExperimentalRspackFlag(context, { enable: true });
+
+  followUps.push(...addRootRspackConfigStub(context));
+  followUps.push(...updatePackageJson(context));
+  followUps.push(...raiseGrafanaDependency(context));
+  followUps.push(...deleteWebpackTemplateFiles(context));
+  reportFollowUps(context, followUps);
+
+  return context;
+}
+
+function deleteRetiredRspackFiles(context: Context): void {
+  for (const filePath of RETIRED_RSPACK_FILES) {
+    if (context.doesFileExist(filePath)) {
+      context.deleteFile(filePath);
+    }
+  }
+}
+
+function reportFollowUps(context: Context, followUps: string[]): void {
+  if (followUps.length === 0) {
+    return;
+  }
+
+  context.setMessage({
+    level: 'warning',
+    title: 'The rspack addition left some things for you to review.',
+    body: followUps,
+  });
+}
+
+const resolveTemplatePath = (relativePath: string) =>
+  fileURLToPath(new URL(`../../../../templates/common/${relativePath}`, import.meta.url));
+
+// updateFile is a no-op for identical content, so re-rendering on every run keeps the addition idempotent
+function renderTemplateFiles(context: Context, filePaths: string[], includeWarning = true): void {
+  const templateData = { ...getTemplateData(), ...RSPACK_TEMPLATE_DATA_OVERRIDES };
+  for (const filePath of filePaths) {
+    const rendered = renderTemplate(resolveTemplatePath(filePath), includeWarning, templateData);
+    if (context.doesFileExist(filePath)) {
+      context.updateFile(filePath, rendered);
+    } else {
+      context.addFile(filePath, rendered);
+    }
+  }
+}
+
+const ROOT_CONFIG_EXTENSIONS = ['ts', 'js', 'cjs', 'mjs', 'cts', 'mts'];
+
+// a root webpack config means the plugin extends the build. the stub makes the build fail loudly
+// until that config is ported, so a plugin cannot ship without the build features it relies on
+function addRootRspackConfigStub(context: Context): string[] {
+  const rootWebpackConfig = ROOT_CONFIG_EXTENSIONS.map((extension) => `webpack.config.${extension}`).find((filePath) =>
+    context.doesFileExist(filePath)
+  );
+  if (!rootWebpackConfig) {
+    return [];
+  }
+
+  const existingRootRspackConfig = ROOT_CONFIG_EXTENSIONS.map((extension) => `rspack.config.${extension}`).find(
+    (filePath) => context.doesFileExist(filePath)
+  );
+  if (existingRootRspackConfig) {
+    return [
+      `${existingRootRspackConfig} already exists, so it was left as is. Check that it includes everything from ${rootWebpackConfig}.`,
+    ];
+  }
+
+  additionsDebug(`Custom ${rootWebpackConfig} detected. Adding a rspack.config.ts stub that fails until it is ported.`);
+  context.addFile('rspack.config.ts', getRootRspackConfigStub(rootWebpackConfig));
+
+  return [
+    `rspack.config.ts was added and fails the build until the customisations in ${rootWebpackConfig} are ported to it.`,
+  ];
+}
+
+interface PackageJson {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  scripts?: Record<string, string>;
+  engines?: Record<string, string>;
+  [key: string]: unknown;
+}
+
+function updatePackageJson(context: Context): string[] {
+  if (!context.doesFileExist('package.json')) {
+    additionsDebug('No package.json found. Skipping dependency and script updates.');
+    return [];
+  }
+
+  const followUps: string[] = [];
+  const templateVersions = getTemplateDevDependencyVersions();
+  const userBuildFileSources = readUserBuildFileSources(context);
+  const stillUsedDevDependencies = WEBPACK_ONLY_DEV_DEPENDENCIES.filter((name) =>
+    userBuildFileSources.some((source) => referencesPackage(source, name))
+  );
+  const unusedDevDependencies = WEBPACK_ONLY_DEV_DEPENDENCIES.filter(
+    (name) => !stillUsedDevDependencies.includes(name)
+  );
+
+  addDependenciesToPackageJson(
+    context,
+    {},
+    {
+      ...pickVersions(getMissingPackages(context, BASE_CONFIG_DEV_DEPENDENCIES), templateVersions),
+      ...pickVersions(RSPACK_DEV_DEPENDENCIES, templateVersions),
+    }
+  );
+  removeDependenciesFromPackageJson(context, [], unusedDevDependencies);
+
+  if (stillUsedDevDependencies.length > 0) {
+    followUps.push(
+      'These webpack packages were kept because your root build config still uses them. Remove them once the config is ported to rspack:',
+      ...stillUsedDevDependencies.map((name) => `  ${name}`)
+    );
+  }
+
+  const packageJson = readJsonFile<PackageJson>(context, 'package.json');
+  const { scripts, unparsedScripts } = rewriteWebpackScripts(packageJson.scripts ?? {});
+
+  if (packageJson.scripts) {
+    context.updateFile('package.json', JSON.stringify({ ...packageJson, scripts }, null, 2));
+  }
+
+  raiseNodeEngine(context);
+  dropLockedRspackOnePackages(context);
+
+  if (unparsedScripts.length > 0) {
+    followUps.push(
+      'These scripts still call webpack in a way the addition could not rewrite. Change them to call rspack with ./rspack.config.ts or ./.config/rspack/rspack.config.ts:',
+      ...unparsedScripts.map(([name, command]) => `  ${name}: ${command}`)
+    );
+  }
+
+  return followUps;
+}
+
+// rspack 2 needs Node 22.12. 22.23 also has type stripping on by default, so the rspack CLI can
+// always load TypeScript configs natively. matches the engines range create-plugin scaffolds
+const MIN_NODE_VERSION = '22.23.0';
+
+function raiseNodeEngine(context: Context): void {
+  const packageJson = readJsonFile<PackageJson>(context, 'package.json');
+  const nodeRange = packageJson.engines?.node;
+  if (!nodeRange || !validRange(nodeRange)) {
+    return;
+  }
+
+  const lowestAllowedVersion = minVersion(nodeRange);
+  if (!lowestAllowedVersion || !lt(lowestAllowedVersion, MIN_NODE_VERSION)) {
+    return;
+  }
+
+  const engines = { ...packageJson.engines, node: '>=22.23' };
+  context.updateFile('package.json', JSON.stringify({ ...packageJson, engines }, null, 2));
+}
+
+// the base config externalizes react/jsx-runtime, which Grafana provides from 12.2.5
+const MIN_GRAFANA_VERSION = '12.2.5';
+
+function raiseGrafanaDependency(context: Context): string[] {
+  const pluginJsonPath = 'src/plugin.json';
+  if (!context.doesFileExist(pluginJsonPath)) {
+    return [];
+  }
+
+  const pluginJson = readJsonFile<{ dependencies?: Record<string, unknown> }>(context, pluginJsonPath);
+  const grafanaRange = pluginJson.dependencies?.grafanaDependency;
+  if (typeof grafanaRange !== 'string' || !validRange(grafanaRange)) {
+    return [];
+  }
+
+  const lowestAllowedVersion = minVersion(grafanaRange);
+  if (!lowestAllowedVersion || !lt(lowestAllowedVersion, MIN_GRAFANA_VERSION)) {
+    return [];
+  }
+
+  const grafanaDependency = `>=${MIN_GRAFANA_VERSION}`;
+  const dependencies = { ...pluginJson.dependencies, grafanaDependency };
+  context.updateFile(pluginJsonPath, JSON.stringify({ ...pluginJson, dependencies }, null, 2));
+  return [
+    `Raised grafanaDependency in src/plugin.json from ${grafanaRange} to ${grafanaDependency}. Earlier versions of Grafana do not provide react/jsx-runtime, which the rspack config loads from Grafana.`,
+  ];
+}
+
+// npm refuses to move @rspack/cli and @rspack/core from 1 to 2 in one install while the lockfile
+// still pins the old versions (ERESOLVE). dropping the locked @rspack packages lets npm resolve
+// them again from package.json. pnpm and yarn upgrade them without help
+const LOCKED_RSPACK_PACKAGE_PATTERN = /(^|\/)node_modules\/@rspack\//;
+
+function dropLockedRspackOnePackages(context: Context): void {
+  if (!context.doesFileExist('package-lock.json')) {
+    return;
+  }
+
+  const lockfile = readJsonFile<{ packages?: Record<string, { version?: string }> }>(context, 'package-lock.json');
+  const lockedCoreVersion = lockfile.packages?.['node_modules/@rspack/core']?.version;
+  if (!lockfile.packages || !lockedCoreVersion || major(lockedCoreVersion) >= 2) {
+    return;
+  }
+
+  const packages = Object.fromEntries(
+    Object.entries(lockfile.packages).filter(([path]) => !LOCKED_RSPACK_PACKAGE_PATTERN.test(path))
+  );
+  context.updateFile('package-lock.json', JSON.stringify({ ...lockfile, packages }, null, 2) + '\n');
+}
+
+// a webpack or webpack-cli command at the start of a script, after a shell separator, after env
+// assignments or after npx. the lookbehind keeps the separator and prefixes out of the match
+const WEBPACK_COMMAND_PATTERN = /(?<=(?:^|&&|\|\||;|\|)\s*(?:\w+=\S*\s+)*(?:npx\s+)?)webpack(?:-cli)?(?=\s|$)/g;
+const ROOT_WEBPACK_CONFIG_ARG_PATTERN =
+  /((?:^|\s)(?:-c|--config)(?:\s+|=))(?:\.\/)?webpack\.config\.[cm]?[jt]s(?=\s|$)/g;
+const TEMPLATE_WEBPACK_CONFIG_ARG_PATTERN =
+  /((?:^|\s)(?:-c|--config)(?:\s+|=))(?:\.\/)?\.config\/webpack\/webpack\.config\.ts(?=\s|$)/g;
+// anything that still runs webpack after the rewrite, e.g. node_modules/webpack-cli/bin/cli.js
+const REMAINING_WEBPACK_PATTERN = /(?:^|[\s/])webpack(?:-cli)?(?:[\s/]|$)|\.config\/webpack\//;
+
+function rewriteWebpackScripts(scripts: Record<string, string>) {
+  const unparsedScripts: Array<[string, string]> = [];
+  const rewrittenScripts = Object.fromEntries(
+    Object.entries(scripts).map(([name, command]) => {
+      const rewritten = command
+        .replace(WEBPACK_COMMAND_PATTERN, 'rspack')
+        .replace(ROOT_WEBPACK_CONFIG_ARG_PATTERN, '$1./rspack.config.ts')
+        .replace(TEMPLATE_WEBPACK_CONFIG_ARG_PATTERN, '$1./.config/rspack/rspack.config.ts');
+
+      if (REMAINING_WEBPACK_PATTERN.test(rewritten)) {
+        unparsedScripts.push([name, command]);
+        return [name, command];
+      }
+
+      return [name, rewritten];
+    })
+  );
+
+  return { scripts: rewrittenScripts, unparsedScripts };
+}
+
+// root level webpack.* and rspack.* files, e.g. webpack.config.ts and helpers like webpack.config.utils.ts
+const USER_BUILD_FILE_PATTERN = /^(webpack|rspack)\.[\w.-]*\.[cm]?[jt]s$/;
+
+function readUserBuildFileSources(context: Context): string[] {
+  return context
+    .readDir('.')
+    .filter((filePath) => USER_BUILD_FILE_PATTERN.test(filePath))
+    .map((filePath) => context.getFile(filePath) ?? '');
+}
+
+// matches the package as a module specifier or loader string: 'name', "name", `name` or 'name/subpath'
+function referencesPackage(source: string, packageName: string): boolean {
+  const escapedName = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`['"\`]${escapedName}(/[^'"\`]*)?['"\`]`).test(source);
+}
+
+// packages the rspack base config and its helpers need that webpack plugins do not
+export const RSPACK_DEV_DEPENDENCIES = [
+  '@rspack/cli',
+  '@rspack/core',
+  '@types/ws',
+  'diagnostics-webpack-plugin',
+  'rspack-merge',
+  'rspack-plugin-virtual-module',
+  'ts-checker-rspack-plugin',
+  // diagnostics-webpack-plugin peers on webpack ^5.106
+  'webpack',
+  'ws',
+];
+
+// packages only the webpack base config uses. removed unless a root build file still imports them
+export const WEBPACK_ONLY_DEV_DEPENDENCIES = [
+  'copy-webpack-plugin',
+  'css-loader',
+  'eslint-webpack-plugin',
+  'fork-ts-checker-webpack-plugin',
+  'imports-loader',
+  'style-loader',
+  'swc-loader',
+  'terser-webpack-plugin',
+  'webpack-cli',
+  'webpack-livereload-plugin',
+  'webpack-subresource-integrity',
+  'webpack-virtual-modules',
+];
+
+// packages the rendered .config/rspack and .config/bundler files load at build time that every
+// scaffold gets, so older plugins may have removed some of them. added only when missing.
+// @swc/helpers is needed because builtin:swc-loader runs with externalHelpers, which webpack did not
+export const BASE_CONFIG_DEV_DEPENDENCIES = ['@swc/helpers', 'replace-in-file-webpack-plugin', 'sass', 'sass-loader'];
+
+// the lists above say which packages the addition manages. their versions come from the package.json
+// template, so they always match the .config files rendered from that same template. the template is
+// rendered with fixed data, since only devDependencies are read and they do not depend on the plugin
+const PACKAGE_JSON_TEMPLATE_DATA = {
+  ...RSPACK_TEMPLATE_DATA_OVERRIDES,
+  pluginName: 'plugin',
+  orgName: 'org',
+  pluginType: 'panel',
+  packageManagerName: 'npm',
+  packageManagerVersion: '10.0.0',
+  scenesVersion: '*',
+  isAppType: false,
+  isNPM: true,
+};
+
+export function getTemplateDevDependencyVersions(): Record<string, string> {
+  const template = readFileSync(resolveTemplatePath('_package.json'), 'utf-8');
+  const rendered: { devDependencies?: Record<string, string> } = JSON.parse(
+    renderHandlebarsTemplate(template, PACKAGE_JSON_TEMPLATE_DATA)
+  );
+  return rendered.devDependencies ?? {};
+}
+
+function pickVersions(names: string[], templateVersions: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    names.map((name) => {
+      const version = templateVersions[name];
+      if (!version) {
+        throw new Error(`The package.json template has no version for ${name}, which the rspack addition installs.`);
+      }
+      return [name, version];
+    })
+  );
+}
+
+// a plugin that already has one of these keeps its version
+function getMissingPackages(context: Context, names: string[]): string[] {
+  const packageJson = readJsonFile<PackageJson>(context, 'package.json');
+  const installed = { ...packageJson.dependencies, ...packageJson.devDependencies };
+  return names.filter((name) => !(name in installed));
+}
+
+function deleteWebpackTemplateFiles(context: Context): string[] {
+  for (const filePath of WEBPACK_TEMPLATE_FILES) {
+    if (context.doesFileExist(filePath)) {
+      context.deleteFile(filePath);
+    }
+  }
+
+  const leftoverFiles = context.readDir('.config/webpack');
+  if (leftoverFiles.length === 0) {
+    return [];
+  }
+
+  return [
+    'These files in .config/webpack were not created by create-plugin, so they were kept. Move anything you still need out of .config and port it to rspack:',
+    ...leftoverFiles.map((filePath) => `  ${filePath}`),
+  ];
+}
+
+function getRootRspackConfigStub(rootWebpackConfig: string): string {
+  return `import type { Configuration } from '@rspack/core';
+import { merge } from 'rspack-merge';
+
+import grafanaConfig, { type Env } from './.config/rspack/rspack.config.ts';
+
+// TODO(rspack): port the customisations in ./${rootWebpackConfig} to this file, then delete it.
+// Run \`npx @grafana/create-plugin@latest add rspack --agent\` to have an AI agent do the port,
+// or follow https://grafana.com/developers/plugin-tools/how-to-guides/extend-configurations
+// This file is loaded as native ESM, so CommonJS globals are not available. Use import.meta.dirname,
+// createRequire(import.meta.url) and .ts extensions on relative imports.
+throw new Error(
+  '[rspack] ${rootWebpackConfig} has not been ported to rspack.config.ts yet. ' +
+    'Run \`npx @grafana/create-plugin@latest add rspack --agent\` or port it by hand, then remove this error.'
+);
+
+const config = async (env: Env): Promise<Configuration> => {
+  const baseConfig = await grafanaConfig(env);
+
+  return merge(baseConfig, {});
+};
+
+export default config;
+`;
+}

package/src/codemods/agentic/prompts.test.ts

@@ -89,8 +89,17 @@ describe('buildSystemPrompt', () => {
     expect(systemPrompt).toContain('Write it with your file-writing tool, not a shell command.');
   });
 
-  it('should tell the agent to fix failing checks rather than suppress them', () => {
-    expect(systemPrompt).toContain('fix the cause. Never make it pass by suppressing it');
+  it('should tell the agent to fix failing checks rather than hide them', () => {
+    expect(systemPrompt).toContain('fix the cause. Never hide a failure');
+  });
+
+  it('should defer to the addition instructions for setting aside what cannot be applied', () => {
+    // additions keep the build passing by commenting out unportable code under a TODO marker,
+    // so the contract must not forbid that or tell the agent to leave the check failing instead
+    expect(systemPrompt).toContain(
+      'If the addition instructions say how to set aside something that cannot be applied, such as commenting it out under a `TODO(<addition-name>):` marker, follow them.'
+    );
+    expect(systemPrompt).not.toMatch(/or changed scripts\./);
   });
 
   it('should render the package manager commands', () => {

package/src/codemods/agentic/prompts.ts

@@ -76,7 +76,7 @@ Before changing any file, print a short plan of what you intend to do so the use
 
 <scope_rules>
 Make only the changes the addition instructions require. Do not run package installs, builds, or tests unless the instructions ask for them. Run the repository formatter on files you touched if one is configured. Do not reformat files you did not change.
-When a check fails (typecheck, lint, build or tests), fix the cause. Never make it pass by suppressing it: no disable comments, skipped or deleted tests, loosened compiler or lint settings, or changed scripts. If you cannot fix the cause, leave it failing and say so in your summary.
+When a check fails (typecheck, lint, build or tests), fix the cause. Never hide a failure: no disable comments, skipped or deleted tests, loosened compiler or lint settings, or scripts changed to skip the check. If the addition instructions say how to set aside something that cannot be applied, such as commenting it out under a \`TODO(<addition-name>):\` marker, follow them. Otherwise leave the check failing and say so in your summary.
 </scope_rules>
 
 <handoff_contract>

package/src/codemods/migrations/migrations.ts

@@ -133,6 +133,13 @@ export default [
     description: 'Replace the glob package with the Node.js built-in fs.glob in bundler utils.',
     scriptPath: import.meta.resolve('./scripts/019-remove-glob-dependency.js'),
   },
+  {
+    name: '020-rename-rspack-feature-flag',
+    version: '7.18.0',
+    description:
+      'Rename the useExperimentalRspack feature flag to useRspack in .config/.cprc.json, and remove it from the plugin .cprc.json.',
+    scriptPath: import.meta.resolve('./scripts/020-rename-rspack-feature-flag.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.
   //

package/src/codemods/migrations/scripts/020-rename-rspack-feature-flag.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from 'vitest';
+import migrate from './020-rename-rspack-feature-flag.js';
+import { Context } from '../../context.js';
+
+const ROOT_CPRC_PATH = '.config/.cprc.json';
+const USER_CPRC_PATH = '.cprc.json';
+
+function setupContext(files: { root?: object; user?: object }) {
+  const context = new Context('/virtual');
+  if (files.root) {
+    context.addFile(ROOT_CPRC_PATH, JSON.stringify(files.root, null, 2));
+  }
+  if (files.user) {
+    context.addFile(USER_CPRC_PATH, JSON.stringify(files.user, null, 2));
+  }
+  return context;
+}
+
+function readFeatures(context: Context, path: string) {
+  return JSON.parse(context.getFile(path) || '{}').features;
+}
+
+describe('020-rename-rspack-feature-flag', () => {
+  it('should rename the flag in .config/.cprc.json', () => {
+    const result = migrate(setupContext({ root: { version: '7.9.0', features: { useExperimentalRspack: true } } }));
+
+    expect(readFeatures(result, ROOT_CPRC_PATH)).toEqual({ useRspack: true });
+  });
+
+  it('should move the flag from the plugin .cprc.json to .config/.cprc.json', () => {
+    const result = migrate(
+      setupContext({
+        root: { version: '7.9.0', features: {} },
+        user: { features: { bundleGrafanaUI: false, useExperimentalRspack: true } },
+      })
+    );
+
+    expect(readFeatures(result, ROOT_CPRC_PATH)).toEqual({ useRspack: true });
+    expect(readFeatures(result, USER_CPRC_PATH)).toEqual({ bundleGrafanaUI: false });
+  });
+
+  it('should remove a disabled flag without turning rspack on', () => {
+    const result = migrate(
+      setupContext({
+        root: { version: '7.9.0', features: {} },
+        user: { features: { bundleGrafanaUI: false, useExperimentalRspack: false } },
+      })
+    );
+
+    expect(readFeatures(result, ROOT_CPRC_PATH)).toEqual({});
+    expect(readFeatures(result, USER_CPRC_PATH)).toEqual({ bundleGrafanaUI: false });
+  });
+
+  it('should keep the version and other feature flags', () => {
+    const result = migrate(
+      setupContext({ root: { version: '7.9.0', features: { bundleGrafanaUI: true, useExperimentalRspack: true } } })
+    );
+
+    expect(JSON.parse(result.getFile(ROOT_CPRC_PATH) || '{}')).toEqual({
+      version: '7.9.0',
+      features: { bundleGrafanaUI: true, useRspack: true },
+    });
+  });
+
+  it('should not rewrite config files that never had the flag', () => {
+    const context = setupContext({
+      root: { version: '7.9.0', features: {} },
+      user: { features: { bundleGrafanaUI: false } },
+    });
+    // formatting a rewrite would change, so an untouched file keeps it
+    context.updateFile(ROOT_CPRC_PATH, '{"version":"7.9.0","features":{}}');
+    context.updateFile(USER_CPRC_PATH, '{"features":{"bundleGrafanaUI":false}}');
+
+    const result = migrate(context);
+
+    expect(result.getFile(ROOT_CPRC_PATH)).toBe('{"version":"7.9.0","features":{}}');
+    expect(result.getFile(USER_CPRC_PATH)).toBe('{"features":{"bundleGrafanaUI":false}}');
+  });
+
+  it('should not fail when neither config file exists', () => {
+    const result = migrate(new Context('/virtual'));
+
+    expect(result.hasChanges()).toBe(false);
+  });
+
+  it('should be idempotent', async () => {
+    await expect(migrate).toBeIdempotent(
+      setupContext({
+        root: { version: '7.9.0', features: { useExperimentalRspack: true } },
+        user: { features: { bundleGrafanaUI: false, useExperimentalRspack: false } },
+      })
+    );
+  });
+});

package/src/codemods/migrations/scripts/020-rename-rspack-feature-flag.ts

@@ -0,0 +1,8 @@
+import type { Context } from '../../context.js';
+import { replaceExperimentalRspackFlag } from '../../utils.rspack.js';
+
+// only renames the flag. plugins on the experimental rspack setup move to rspack 2 by running `add rspack`
+export default function migrate(context: Context): Context {
+  replaceExperimentalRspackFlag(context, { enable: false });
+  return context;
+}

package/src/codemods/utils.rspack.ts

@@ -0,0 +1,58 @@
+import type { Context } from './context.js';
+import { readJsonFile } from './utils.js';
+
+const ROOT_CPRC_PATH = '.config/.cprc.json';
+const USER_CPRC_PATH = '.cprc.json';
+const EXPERIMENTAL_RSPACK_FLAG = 'useExperimentalRspack';
+
+interface CprcConfig {
+  features?: Record<string, unknown>;
+}
+
+/**
+ * Replaces the `useExperimentalRspack` feature flag with `useRspack` in `.config/.cprc.json`, and removes the old flag
+ * from both config files. Every generated plugin's own `.cprc.json` carried the old flag as `false`, and that file
+ * overrides `.config/.cprc.json`. `useRspack` is set when the old flag was on in either file, or when `enable` is true.
+ * Files that need no change are left untouched.
+ */
+export function replaceExperimentalRspackFlag(context: Context, { enable }: { enable: boolean }): void {
+  const wasRspack = [ROOT_CPRC_PATH, USER_CPRC_PATH].some(
+    (path) => readCprc(context, path)?.features?.[EXPERIMENTAL_RSPACK_FLAG] === true
+  );
+
+  updateFeatures(context, USER_CPRC_PATH, (features) => withoutExperimentalFlag(features));
+  updateFeatures(context, ROOT_CPRC_PATH, (features) => {
+    const cleaned = withoutExperimentalFlag(features);
+    return enable || wasRspack ? { ...cleaned, useRspack: true } : cleaned;
+  });
+}
+
+function readCprc(context: Context, path: string): CprcConfig | undefined {
+  if (!context.doesFileExist(path)) {
+    return undefined;
+  }
+  return readJsonFile<CprcConfig>(context, path);
+}
+
+function updateFeatures(
+  context: Context,
+  path: string,
+  update: (features: Record<string, unknown>) => Record<string, unknown>
+): void {
+  const config = readCprc(context, path);
+  if (!config) {
+    return;
+  }
+
+  const features = config.features ?? {};
+  const updatedFeatures = update(features);
+  if (JSON.stringify(updatedFeatures) === JSON.stringify(features)) {
+    return;
+  }
+
+  context.updateFile(path, JSON.stringify({ ...config, features: updatedFeatures }, null, 2));
+}
+
+function withoutExperimentalFlag(features: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(features).filter(([name]) => name !== EXPERIMENTAL_RSPACK_FLAG));
+}

package/src/codemods/utils.test.ts

@@ -236,8 +236,11 @@ describe('utils', () => {
 
     it('reads feature flags from the .cprc.json files', async () => {
       await mkdir(join(tmpDir, '.config'));
-      await writeFile(join(tmpDir, '.config/.cprc.json'), JSON.stringify({ features: { bundleGrafanaUI: true } }));
-      await writeFile(join(tmpDir, '.cprc.json'), JSON.stringify({ features: { useExperimentalRspack: true } }));
+      await writeFile(
+        join(tmpDir, '.config/.cprc.json'),
+        JSON.stringify({ features: { bundleGrafanaUI: true, useRspack: true } })
+      );
+      await writeFile(join(tmpDir, '.cprc.json'), JSON.stringify({ features: { bundleGrafanaUI: true } }));
       expect(getTemplateDataFromContext(pluginContext())).toMatchObject({
         bundleGrafanaUI: true,
         frontendBundler: 'rspack',