@grafana/create-plugin 5.17.0 → 5.18.0

package/src/migrations/manager.test.ts

@@ -0,0 +1,217 @@
+import { vi } from 'vitest';
+import { getMigrationsToRun, runMigration, runMigrations } from './manager.js';
+import migrationFixtures from './fixtures/migrations.js';
+import { Context } from './context.js';
+import { gitCommitNoVerify } from '../utils/utils.git.js';
+import { flushChanges, printChanges } from './utils.js';
+import { setRootConfig } from '../utils/utils.config.js';
+import { MigrationMeta } from './migrations.js';
+
+vi.mock('./utils.js', () => ({
+  flushChanges: vi.fn(),
+  printChanges: vi.fn(),
+  migrationsDebug: vi.fn(),
+}));
+
+vi.mock('../utils/utils.config.js', () => ({
+  setRootConfig: vi.fn(),
+}));
+vi.mock('../utils/utils.git.js', () => ({
+  gitCommitNoVerify: vi.fn(),
+}));
+
+describe('Migrations', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('getMigrationsToRun', () => {
+    it('should return the migrations that need to be run', () => {
+      const fromVersion = '3.0.0';
+      const toVersion = '5.0.0';
+      const migrations = getMigrationsToRun(fromVersion, toVersion, migrationFixtures.migrations);
+      expect(migrations).toEqual({
+        'migration-key1': {
+          version: '5.0.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './5-0-0-cache-directory.js',
+        },
+      });
+
+      const fromVersion2 = '5.0.0';
+      const toVersion2 = '5.5.0';
+      const migrations2 = getMigrationsToRun(fromVersion2, toVersion2, migrationFixtures.migrations);
+      expect(migrations2).toEqual({
+        'migration-key1': {
+          version: '5.0.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './5-0-0-cache-directory.js',
+        },
+        'migration-key2': {
+          version: '5.4.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './5-4-0-cache-directory.js',
+        },
+      });
+
+      const fromVersion3 = '5.5.0';
+      const toVersion3 = '6.0.0';
+      const migrations3 = getMigrationsToRun(fromVersion3, toVersion3, migrationFixtures.migrations);
+      expect(migrations3).toEqual({
+        'migration-key3': {
+          version: '6.0.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './5-4-0-cache-directory.js',
+        },
+      });
+    });
+
+    it('should sort migrations by version', () => {
+      const fromVersion = '2.0.0';
+      const toVersion = '6.0.0';
+      const migrations = getMigrationsToRun(fromVersion, toVersion, {
+        'migration-key1': {
+          version: '5.3.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './5.3.0-migration.js',
+        },
+        'migration-key2': {
+          version: '2.3.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './2.3.0-migration.js',
+        },
+        'migration-key3': {
+          version: '2.0.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './2.0.0-migration.js',
+        },
+        'migration-key4': {
+          version: '2.0.0',
+          description: 'Update project to use new cache directory',
+          migrationScript: './2.0.0-migration.js',
+        },
+      });
+
+      expect(Object.keys(migrations)).toEqual(['migration-key3', 'migration-key4', 'migration-key2', 'migration-key1']);
+    });
+  });
+
+  describe('runMigration', () => {
+    it('should pass a context to the migration script', async () => {
+      const mockContext = new Context('/virtual');
+      const migrationFn = vi.fn().mockResolvedValue(mockContext);
+
+      vi.doMock('./test-migration.js', () => ({
+        default: migrationFn,
+      }));
+
+      const migration: MigrationMeta = {
+        version: '1.0.0',
+        description: 'test migration',
+        migrationScript: './test-migration.js',
+      };
+
+      const result = await runMigration(migration, mockContext);
+
+      expect(migrationFn).toHaveBeenCalledWith(mockContext);
+      expect(result).toBe(mockContext);
+    });
+  });
+
+  describe('runMigrations', () => {
+    const migrationOneFn = vi.fn();
+    const migrationTwoFn = vi.fn();
+    const consoleMock = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+
+    vi.doMock('./migration-one.js', () => ({
+      default: migrationOneFn,
+    }));
+    vi.doMock('./migration-two.js', () => ({
+      default: migrationTwoFn,
+    }));
+
+    const migrations: Record<string, MigrationMeta> = {
+      'migration-one': {
+        version: '1.0.0',
+        description: '...',
+        migrationScript: './migration-one.js',
+      },
+      'migration-two': {
+        version: '1.2.0',
+        description: '...',
+        migrationScript: './migration-two.js',
+      },
+    };
+
+    beforeEach(() => {
+      migrationOneFn.mockImplementation(async (context: Context) => {
+        await context.addFile('one.ts', '');
+
+        return context;
+      });
+      migrationTwoFn.mockImplementation(async (context: Context) => {
+        await context.addFile('two.ts', '');
+
+        return context;
+      });
+    });
+
+    afterAll(() => {
+      consoleMock.mockReset();
+    });
+
+    it('should flush the changes for each migration', async () => {
+      await runMigrations(migrations);
+
+      expect(flushChanges).toHaveBeenCalledTimes(2);
+    });
+
+    it('should print the changes for each migration', async () => {
+      await runMigrations(migrations);
+
+      expect(printChanges).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not commit the changes for each migration by default', async () => {
+      await runMigrations(migrations);
+
+      expect(gitCommitNoVerify).toHaveBeenCalledTimes(0);
+    });
+
+    it('should commit the changes for each migration if the CLI arg is present', async () => {
+      await runMigrations(migrations, { commitEachMigration: true });
+
+      expect(gitCommitNoVerify).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not create a commit for a migration that has no changes', async () => {
+      migrationTwoFn.mockImplementation(async (context: Context) => context);
+
+      await runMigrations(migrations, { commitEachMigration: true });
+
+      expect(gitCommitNoVerify).toHaveBeenCalledTimes(1);
+    });
+
+    it('should update version in ".config/.cprc.json" on a successful update', async () => {
+      await runMigrations(migrations);
+
+      expect(setRootConfig).toHaveBeenCalledTimes(1);
+
+      // The latest version in the migrations
+      // (For `runMigrations()` this means the last key in the object according to `getMigrationsToRun()`)
+      expect(setRootConfig).toHaveBeenCalledWith({ version: '1.2.0' });
+    });
+
+    it('should NOT update version in ".config/.cprc.json" if any of the migrations fail', async () => {
+      migrationTwoFn.mockImplementation(async () => {
+        throw new Error('Unknown error.');
+      });
+
+      await expect(async () => {
+        await runMigrations(migrations);
+      }).rejects.toThrow();
+
+      expect(setRootConfig).not.toHaveBeenCalled();
+    });
+  });
+});

package/src/migrations/manager.ts

@@ -0,0 +1,70 @@
+import { satisfies, gte } from 'semver';
+import { Context } from './context.js';
+import defaultMigrations, { MigrationMeta } from './migrations.js';
+import { flushChanges, printChanges, migrationsDebug } from './utils.js';
+import { gitCommitNoVerify } from '../utils/utils.git.js';
+import { setRootConfig } from '../utils/utils.config.js';
+
+export type MigrationFn = (context: Context) => Context | Promise<Context>;
+
+export function getMigrationsToRun(
+  fromVersion: string,
+  toVersion: string,
+  migrations: Record<string, MigrationMeta> = defaultMigrations.migrations
+): Record<string, MigrationMeta> {
+  const semverRange = `${fromVersion} - ${toVersion}`;
+
+  const migrationsToRun = Object.entries(migrations)
+    .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;
+}
+
+type RunMigrationsOptions = {
+  commitEachMigration?: boolean;
+};
+
+export async function runMigrations(migrations: Record<string, MigrationMeta>, options: RunMigrationsOptions = {}) {
+  const basePath = process.cwd();
+
+  console.log('');
+  console.log('Running the following migrations:');
+  Object.entries(migrations).map(([key, migrationMeta]) => console.log(`- ${key} (${migrationMeta.description})`));
+  console.log('');
+
+  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());
+
+      flushChanges(context);
+      printChanges(context, key, migration);
+
+      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}`);
+      }
+    }
+  }
+  setRootConfig({ version: Object.values(migrations).at(-1)!.version });
+}
+
+export async function runMigration(migration: MigrationMeta, context: Context): Promise<Context> {
+  const module: { default: MigrationFn } = await import(migration.migrationScript);
+
+  return module.default(context);
+}

package/src/migrations/migrations.test.ts

@@ -0,0 +1,12 @@
+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();
+    });
+  });
+});

package/src/migrations/migrations.ts

@@ -0,0 +1,20 @@
+export type MigrationMeta = {
+  version: string;
+  description: string;
+  migrationScript: string;
+};
+
+type Migrations = {
+  migrations: Record<string, MigrationMeta>;
+};
+
+export default {
+  migrations: {
+    // Example migration entry (DO NOT UNCOMMENT!)
+    // 'example-migration': {
+    //   version: '5.13.0',
+    //   description: 'Update build command to use webpack profile flag.',
+    //   migrationScript: './scripts/example-migration.js',
+    // },
+  },
+} as Migrations;

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

@@ -0,0 +1,40 @@
+import migrate from './example-migration.js';
+import { createDefaultContext } from '../test-utils.js';
+
+describe('Migration - append profile to webpack', () => {
+  test('should update the package.json', async () => {
+    const context = createDefaultContext();
+
+    context.updateFile(
+      './package.json',
+      JSON.stringify({
+        scripts: {
+          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
+        },
+      })
+    );
+
+    const updatedContext = await migrate(context);
+
+    expect(updatedContext.getFile('./package.json')).toMatch(
+      'webpack -c ./.config/webpack/webpack.config.ts --profile --env production'
+    );
+
+    expect(updatedContext.readDir('./src')).toEqual(['src/FOO.md', 'src/foo.json']);
+  });
+
+  it('should not make additional changes when run multiple times', async () => {
+    const context = await createDefaultContext();
+
+    await context.updateFile(
+      './package.json',
+      JSON.stringify({
+        scripts: {
+          build: 'webpack -c ./.config/webpack/webpack.config.ts --env production',
+        },
+      })
+    );
+
+    await expect(migrate).toBeIdempotent(context);
+  });
+});

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

@@ -0,0 +1,34 @@
+import type { Context } from '../context.js';
+
+export default function migrate(context: Context): Context {
+  const rawPkgJson = context.getFile('./package.json') ?? '{}';
+  const packageJson = JSON.parse(rawPkgJson);
+
+  if (packageJson.scripts && packageJson.scripts.build) {
+    const buildScript = packageJson.scripts.build;
+
+    const pattern = /(webpack.+-c\s.+\.ts)\s(.+)/;
+
+    if (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')) {
+    context.deleteFile('./src/README.md');
+  }
+
+  if (!context.doesFileExist('./src/foo.json')) {
+    context.addFile('./src/foo.json', JSON.stringify({ foo: 'bar' }));
+  }
+
+  if (context.doesFileExist('.eslintrc')) {
+    context.renameFile('.eslintrc', '.eslint.config.json');
+  }
+
+  context.readDir('./src');
+
+  return context;
+}

package/src/migrations/test-utils.ts

@@ -0,0 +1,12 @@
+import { Context } from './context.js';
+
+export function createDefaultContext() {
+  const context = new Context('/virtual');
+
+  context.addFile('.eslintrc', '{}');
+  context.addFile('./package.json', '{}');
+  context.addFile('./src/README.md', '');
+  context.addFile('./src/FOO.md', '');
+
+  return context;
+}

package/src/migrations/utils.test.ts

@@ -0,0 +1,81 @@
+import { dirSync } from 'tmp';
+import { Context } from './context.js';
+import { flushChanges, printChanges } from './utils.js';
+import { join } from 'node:path';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+
+describe('utils', () => {
+  const tmpObj = dirSync({ unsafeCleanup: true });
+  const tmpDir = join(tmpObj.name, 'cp-test-migration');
+
+  beforeEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+    await mkdir(tmpDir, { recursive: true });
+
+    await writeFile(join(tmpDir, 'bar.ts'), 'content');
+    await writeFile(join(tmpDir, 'baz.ts'), 'content');
+  });
+
+  afterAll(() => {
+    tmpObj.removeCallback();
+  });
+
+  describe('flushChanges', () => {
+    it('should write files to disk', async () => {
+      const context = new Context(tmpDir);
+      await context.addFile('file.txt', 'content');
+      await context.addFile('deeper/path/to/file.txt', 'content');
+      flushChanges(context);
+      expect(readFileSync(join(tmpDir, 'file.txt'), 'utf-8')).toBe('content');
+      expect(readFileSync(join(tmpDir, 'deeper/path/to/file.txt'), 'utf-8')).toBe('content');
+    });
+
+    it('should update files on disk', async () => {
+      const context = new Context(tmpDir);
+      await context.updateFile('bar.ts', 'new content');
+      flushChanges(context);
+      expect(readFileSync(join(tmpDir, 'bar.ts'), 'utf-8')).toBe('new content');
+    });
+
+    it('should delete files from disk', async () => {
+      const context = new Context(tmpDir);
+      await context.deleteFile('bar.ts');
+      flushChanges(context);
+      expect(() => readFileSync(join(tmpDir, 'bar.ts'), 'utf-8')).toThrowError();
+    });
+  });
+
+  describe('printChanges', () => {
+    const originalConsoleLog = console.log;
+
+    beforeEach(() => {
+      vitest.spyOn(console, 'log').mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      console.log = originalConsoleLog;
+    });
+
+    it('should print changes', async () => {
+      const context = new Context(tmpDir);
+      await context.addFile('file.txt', 'content');
+      await context.updateFile('baz.ts', 'new content');
+      await context.deleteFile('bar.ts');
+
+      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+
+      expect(console.log).toHaveBeenCalledWith(expect.stringMatching(/ADD.+file\.txt/));
+      expect(console.log).toHaveBeenCalledWith(expect.stringMatching(/UPDATE.+baz\.ts/));
+      expect(console.log).toHaveBeenCalledWith(expect.stringMatching(/DELETE.+bar\.ts/));
+    });
+
+    it('should print no changes', async () => {
+      const context = new Context(tmpDir);
+
+      printChanges(context, 'key', { migrationScript: 'test', description: 'test', version: '1.0.0' });
+
+      expect(console.log).toHaveBeenCalledWith(expect.stringMatching(/No changes were made/));
+    });
+  });
+});

package/src/migrations/utils.ts

@@ -0,0 +1,50 @@
+import { dirname, join } from 'node:path';
+import { Context } from './context.js';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { debug } from '../utils/utils.cli.js';
+import chalk from 'chalk';
+import { MigrationMeta } from './migrations.js';
+
+export function printChanges(context: Context, key: string, migration: MigrationMeta) {
+  const changes = context.listChanges();
+  const lines = [];
+
+  for (const [filePath, { changeType }] of Object.entries(changes)) {
+    if (changeType === 'add') {
+      lines.push(`${chalk.green('ADD')} ${filePath}`);
+    } else if (changeType === 'update') {
+      lines.push(`${chalk.yellow('UPDATE')} ${filePath}`);
+    } else if (changeType === 'delete') {
+      lines.push(`${chalk.red('DELETE')} ${filePath}`);
+    }
+  }
+
+  console.log('--------------------------------');
+  console.log('Running migration:', key, chalk.bold(migration.migrationScript));
+
+  if (lines.length === 0) {
+    console.log('No changes were made');
+  } else {
+    console.log(`${chalk.bold('Changes:')}\n  ${lines.join('\n  ')}`);
+  }
+  console.log('');
+}
+
+export function flushChanges(context: Context) {
+  const basePath = context.basePath;
+  const changes = context.listChanges();
+
+  for (const [filePath, { changeType, content }] of Object.entries(changes)) {
+    const resolvedPath = join(basePath, filePath);
+    if (changeType === 'add') {
+      mkdirSync(dirname(resolvedPath), { recursive: true });
+      writeFileSync(resolvedPath, content!);
+    } else if (changeType === 'update') {
+      writeFileSync(resolvedPath, content!);
+    } else if (changeType === 'delete') {
+      rmSync(resolvedPath);
+    }
+  }
+}
+
+export const migrationsDebug = debug.extend('migrations');

package/src/utils/utils.cli.ts

@@ -1,4 +1,7 @@
 import minimist from 'minimist';
+import createDebug from 'debug';
+
+export const debug = createDebug('create-plugin');
 
 export const args = process.argv.slice(2);
 
@@ -10,6 +13,8 @@ export const argv = minimist(args, {
     hasBackend: 'backend',
     pluginName: 'plugin-name',
     orgName: 'org-name',
+    // temporary flag whilst we work on the migration updates
+    experimentalUpdates: 'experimental-updates',
   },
 });
 

package/src/utils/utils.config.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import { writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { getVersion } from './utils.version.js';
 import { argv, commandName } from './utils.cli.js';
@@ -91,7 +92,7 @@ function readRCFileSync(path: string): CreatePluginConfig | undefined {
 // This function creates feature flags based on the defaults for generate command else flags read from config.
 // In all cases it will override the flags with the featureFlag cli arg values.
 function createFeatureFlags(flags?: FeatureFlags): FeatureFlags {
-  const featureFlags = commandName === 'generate' ? DEFAULT_FEATURE_FLAGS : flags ?? {};
+  const featureFlags = commandName === 'generate' ? DEFAULT_FEATURE_FLAGS : (flags ?? {});
   const cliArgFlags = parseFeatureFlagsFromCliArgs();
   return { ...featureFlags, ...cliArgFlags };
 }
@@ -117,3 +118,13 @@ function parseFeatureFlagsFromCliArgs() {
     return { ...acc, [flag]: true };
   }, {} as FeatureFlags);
 }
+
+export async function setRootConfig(configOverride: Partial<CreatePluginConfig> = {}): Promise<CreatePluginConfig> {
+  const rootConfig = getRootConfig();
+  const rootConfigPath = path.resolve(process.cwd(), '.config/.cprc.json');
+  const updatedConfig = { ...rootConfig, ...configOverride };
+
+  await writeFile(rootConfigPath, JSON.stringify(updatedConfig, null, 2));
+
+  return updatedConfig;
+}

package/src/utils/utils.console.ts

@@ -13,6 +13,13 @@ marked.use(
   }) as MarkedExtension
 );
 
+export function printHeader(message: string, status: 'success' | 'info' | 'error' = 'success') {
+  const color = status === 'success' ? 'green' : status === 'info' ? 'blue' : 'red';
+  let prefix = chalk.reset.inverse.bold[color](` CREATE PLUGIN `);
+  let txt = chalk[color](message);
+  console.log(`${prefix}  ${txt}`);
+}
+
 export function displayAsMarkdown(msg: string) {
   return marked(msg);
 }

package/src/utils/utils.git.ts

@@ -27,3 +27,17 @@ export async function isGitDirectoryClean() {
     return false;
   }
 }
+
+export async function gitCommitNoVerify(commitMsg: string) {
+  try {
+    let addAllCommand = 'git add -A';
+    let commitCommand = `git commit --no-verify -m ${commitMsg}`;
+
+    await exec(addAllCommand);
+    await exec(commitCommand);
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new Error(`Error committing changes:\n${error.message}`);
+    }
+  }
+}

package/src/utils/utils.goSdk.ts

@@ -1,11 +1,11 @@
 import which from 'which';
 import fs from 'node:fs';
-import createDebug from 'debug';
 import { exec } from 'node:child_process';
+import { debug } from './utils.cli.js';
 
 const SDK_GO_MODULE = 'github.com/grafana/grafana-plugin-sdk-go';
 
-const debug = createDebug('create-plugin:update-go');
+const updateGoDebugger = debug.extend('update-go');
 
 export async function updateGoSdkAndModules(exportPath: string) {
   // check if there is a go.mod file in exportPath
@@ -40,7 +40,7 @@ function updateSdk(exportPath: string): Promise<void> {
     const command = `go get ${SDK_GO_MODULE}`;
     exec(command, { cwd: exportPath }, (error) => {
       if (error) {
-        debug(error);
+        updateGoDebugger(error);
         reject();
       }
       resolve();
@@ -54,7 +54,7 @@ function updateGoMod(exportPath: string): Promise<void> {
     const command = `go mod tidy`;
     exec(command, { cwd: exportPath }, (error) => {
       if (error) {
-        debug(error);
+        updateGoDebugger(error);
         reject();
       }
       resolve();
@@ -68,7 +68,7 @@ function getLatestSdkVersion(exportPath: string): Promise<string> {
     const command = `go list -m -json ${SDK_GO_MODULE}@latest`;
     exec(command, { cwd: exportPath }, (error, stdout) => {
       if (error) {
-        debug(error);
+        updateGoDebugger(error);
         reject();
       }
 
@@ -76,7 +76,7 @@ function getLatestSdkVersion(exportPath: string): Promise<string> {
         const version = JSON.parse(stdout).Version;
         resolve(version);
       } catch (e) {
-        debug(e);
+        updateGoDebugger(e);
         reject();
       }
     });