@grafana/create-plugin 7.12.3 → 7.14.0

package/src/codemods/utils.test.ts

@@ -2,6 +2,8 @@ import { dirSync } from 'tmp';
 import { Context } from './context.js';
 import {
   addDependenciesToPackageJson,
+  addTemplateFolder,
+  getTemplateDataFromContext,
   removeDependenciesFromPackageJson,
   flushChanges,
   formatFiles,
@@ -12,7 +14,8 @@ import {
 } from './utils.js';
 import { join } from 'node:path';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { execSync } from 'node:child_process';
 import which from 'which';
 import { output } from '../utils/utils.console.js';
@@ -23,6 +26,17 @@ vi.mock(import('node:child_process'), async (importOriginal) => ({
   execSync: vi.fn(),
 }));
 
+// codemods run under `update` or `add`. Without a command, the config would use generate's defaults
+vi.mock(import('../utils/utils.cli.js'), async (importOriginal) => ({
+  ...(await importOriginal()),
+  commandName: 'add',
+}));
+
+vi.mock(import('../utils/utils.packageManager.js'), async (importOriginal) => ({
+  ...(await importOriginal()),
+  getPackageManagerWithFallback: vi.fn(() => ({ packageManagerName: 'pnpm', packageManagerVersion: '10.4.1' })),
+}));
+
 vi.mock('which', () => ({
   default: { sync: vi.fn() },
 }));
@@ -182,6 +196,122 @@ describe('utils', () => {
       const context = new Context(tmpDir);
       expect(() => readJsonFile(context, 'file.json')).toThrowError();
     });
+
+    it.each(['[]', 'null', '"text"'])('should throw when the file contains %s instead of an object', (content) => {
+      const context = new Context(tmpDir);
+      context.addFile('file.json', content);
+      expect(() => readJsonFile(context, 'file.json')).toThrowError('does not contain a JSON object');
+    });
+  });
+
+  describe('getTemplateDataFromContext', () => {
+    function pluginContext() {
+      const context = new Context(tmpDir);
+      context.addFile(
+        'src/plugin.json',
+        JSON.stringify({ id: 'org-name-panel', name: 'Name', type: 'panel', info: { author: { name: 'Org' } } })
+      );
+      return context;
+    }
+
+    it('reads plugin.json from the context', () => {
+      expect(getTemplateDataFromContext(pluginContext())).toMatchObject({
+        pluginId: 'org-name-panel',
+        pluginName: 'Name',
+        pluginType: 'panel',
+        orgName: 'Org',
+        packageManagerName: 'pnpm',
+        packageManagerInstallCmd: 'pnpm install --frozen-lockfile --prefer-offline',
+        isAppType: false,
+        isNPM: false,
+        frontendBundler: 'webpack',
+      });
+    });
+
+    it('sees changes the codemod has not written yet', () => {
+      const context = pluginContext();
+      context.updateFile('src/plugin.json', JSON.stringify({ id: 'org-new-app', name: 'New', type: 'app' }));
+      expect(getTemplateDataFromContext(context)).toMatchObject({ pluginId: 'org-new-app', isAppType: true });
+    });
+
+    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 } }));
+      expect(getTemplateDataFromContext(pluginContext())).toMatchObject({
+        bundleGrafanaUI: true,
+        frontendBundler: 'rspack',
+      });
+    });
+  });
+
+  describe('addTemplateFolder', () => {
+    function templateFolder(files: Record<string, string>): string {
+      const dir = mkdtempSync(join(tmpdir(), 'codemod-templates-'));
+      for (const [file, content] of Object.entries(files)) {
+        mkdirSync(join(dir, file, '..'), { recursive: true });
+        writeFileSync(join(dir, file), content);
+      }
+      return dir;
+    }
+
+    const data = { pluginName: "Erik's & Co", packageManagerName: 'pnpm' };
+
+    it('renders every file with Handlebars into the target folder', () => {
+      const context = new Context(tmpDir);
+      const folderPath = templateFolder({
+        'index.md': '# {{{pluginName}}}\n',
+        'nested/setup.md': '{{#if_eq packageManagerName "pnpm"}}pnpm{{/if_eq}} {{dashCase "Some Name"}}\n',
+      });
+      const added = addTemplateFolder(context, { folderPath, targetPath: 'docs', data });
+      expect(added.sort()).toEqual(['docs/index.md', 'docs/nested/setup.md']);
+      expect(context.getFile('docs/index.md')).toBe("# Erik's & Co\n");
+      expect(context.getFile('docs/nested/setup.md')).toBe('pnpm some-name\n');
+    });
+
+    it('skips files that include rejects, matching on the output path relative to the target', () => {
+      const context = new Context(tmpDir);
+      const folderPath = templateFolder({ 'README.md': 'readme\n', 'nested/page.md.hbs': 'page\n', npmrc: 'x' });
+      const seen: string[] = [];
+      const added = addTemplateFolder(context, {
+        folderPath,
+        targetPath: 'docs',
+        data,
+        include: (file) => {
+          seen.push(file);
+          return file === 'README.md';
+        },
+      });
+      expect(seen.sort()).toEqual(['.npmrc', 'README.md', 'nested/page.md']);
+      expect(added).toEqual(['docs/README.md']);
+    });
+
+    it('strips .hbs and maps config file names like generate does', () => {
+      const context = new Context(tmpDir);
+      const folderPath = templateFolder({ 'page.md.hbs': 'x', npmrc: 'y' });
+      addTemplateFolder(context, { folderPath, targetPath: '', data });
+      expect(context.doesFileExist('page.md')).toBe(true);
+      expect(context.doesFileExist('.npmrc')).toBe(true);
+    });
+
+    it('leaves existing files alone', () => {
+      const context = new Context(tmpDir);
+      context.addFile('docs/index.md', 'mine');
+      const added = addTemplateFolder(context, {
+        folderPath: templateFolder({ 'index.md': 'new' }),
+        targetPath: 'docs',
+        data,
+      });
+      expect(added).toEqual([]);
+      expect(context.getFile('docs/index.md')).toBe('mine');
+    });
+
+    it('throws when the template folder is missing', () => {
+      const context = new Context(tmpDir);
+      expect(() =>
+        addTemplateFolder(context, { folderPath: join(tmpdir(), 'missing-templates'), targetPath: 'docs', data })
+      ).toThrow('Cannot find templates at');
+    });
   });
 
   describe('addDependenciesToPackageJson', () => {

package/src/codemods/utils.ts

@@ -1,7 +1,8 @@
-import { dirname, join } from 'node:path';
+import { dirname, join, posix } from 'node:path';
 import { createRequire } from 'node:module';
 import { Context } from './context.js';
-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { glob } from 'glob';
 import { styleText } from 'node:util';
 import { output } from '../utils/utils.console.js';
 import { getPackageManagerSilentInstallCmd, getPackageManagerWithFallback } from '../utils/utils.packageManager.js';
@@ -10,7 +11,10 @@ import which from 'which';
 import { clean, coerce, gt, gte } from 'semver';
 import { debug } from '../utils/utils.cli.js';
 import { renderHandlebarsTemplate } from '../utils/utils.handlebars.js';
-import { getTemplateData } from '../utils/utils.templates.js';
+import { buildTemplateData, getTemplateData } from '../utils/utils.templates.js';
+import { getConfig } from '../utils/utils.config.js';
+import { getExportFileName } from '../utils/utils.files.js';
+import type { TemplateData } from '../types.js';
 
 export function printChanges(context: Context, key: string, description: string) {
   const changes = context.listChanges();
@@ -176,11 +180,16 @@ export function readJsonFile<T extends object = any>(context: Context, path: str
   if (!context.doesFileExist(path)) {
     throw new Error(`Cannot find ${path}`);
   }
+  let parsed: unknown;
   try {
-    return JSON.parse(context.getFile(path) || '');
+    parsed = JSON.parse(context.getFile(path) || '');
   } catch (e) {
     throw new Error(`Cannot parse ${path}: ${e}`);
   }
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`${path} does not contain a JSON object.`);
+  }
+  return parsed as T;
 }
 
 export function addDependenciesToPackageJson(
@@ -342,10 +351,15 @@ function sortObjectByKeys<T extends Record<string, any>>(obj: T): T {
 
 export const migrationsDebug = debug.extend('migrations');
 export const additionsDebug = debug.extend('additions');
-
-export function renderTemplate(templatePath: string, includeWarning = false): string {
-  const templateData = getTemplateData();
-  let rendered = renderHandlebarsTemplate(readFileSync(templatePath, 'utf-8'), templateData);
+// for helpers that migrations and additions share
+export const codemodsDebug = debug.extend('codemods');
+
+export function renderTemplate(
+  templatePath: string,
+  includeWarning = false,
+  data: Record<string, unknown> = getTemplateData()
+): string {
+  let rendered = renderHandlebarsTemplate(readFileSync(templatePath, 'utf-8'), data);
   const regex = /DO NOT EDIT THIS FILE DIRECTLY\./g;
   if (includeWarning && !regex.test(rendered)) {
     rendered = `${warningComment}\n\n${rendered}`;
@@ -353,6 +367,63 @@ export function renderTemplate(templatePath: string, includeWarning = false): st
   return rendered;
 }
 
+/**
+ * The same data `getTemplateData` gives scaffold templates, with plugin.json read from the context, so it
+ * includes changes the codemod has made but not yet written.
+ */
+export function getTemplateDataFromContext(context: Context): TemplateData {
+  return buildTemplateData({
+    pluginJson: readJsonFile(context, 'src/plugin.json'),
+    packageManager: getPackageManagerWithFallback(),
+    features: getConfig(context.basePath).features,
+  });
+}
+
+/**
+ * Renders every file under `folderPath` into `targetPath`, the way `generate` scaffolds a template folder:
+ * `.hbs` is stripped and config file names are mapped. Files that already exist are left alone, and so are
+ * files `include` rejects, given each file's output path relative to `targetPath` with `/` separators.
+ * Returns the paths it added.
+ */
+export function addTemplateFolder(
+  context: Context,
+  {
+    folderPath,
+    targetPath,
+    data,
+    include = () => true,
+  }: {
+    folderPath: string;
+    targetPath: string;
+    data: Record<string, unknown>;
+    include?: (relativeFile: string) => boolean;
+  }
+): string[] {
+  if (!existsSync(folderPath)) {
+    throw new Error(
+      `Cannot find templates at ${folderPath}. This is a bug in @grafana/create-plugin - please report it.`
+    );
+  }
+
+  const added: string[] = [];
+  // relative to `cwd`, so glob characters in the install path (such as Windows backslashes) can't break the pattern
+  for (const relativeFile of glob.sync('**', { cwd: folderPath, dot: true, nodir: true, posix: true })) {
+    const file = join(folderPath, relativeFile);
+    const outputFile = posix.join(posix.dirname(relativeFile), getExportFileName(file));
+    if (!include(outputFile)) {
+      continue;
+    }
+    const filePath = join(targetPath, outputFile);
+    if (context.doesFileExist(filePath)) {
+      codemodsDebug(`${filePath} already exists, skipping`);
+      continue;
+    }
+    context.addFile(filePath, renderHandlebarsTemplate(readFileSync(file, 'utf-8'), data));
+    added.push(filePath);
+  }
+  return added;
+}
+
 const warningComment = `/*
  * ⚠️⚠️⚠️ THIS FILE WAS SCAFFOLDED BY \`@grafana/create-plugin\`. DO NOT EDIT THIS FILE DIRECTLY. ⚠️⚠️⚠️
  *

package/src/codemods/utils.workflows.test.ts

@@ -0,0 +1,153 @@
+import { Context } from './context.js';
+import { bumpActionRefs } from './utils.workflows.js';
+
+const WORKFLOW = '.github/workflows/release.yml';
+const BUILD_PLUGIN = 'grafana/plugin-actions/build-plugin';
+const PACKAGE_PLUGIN = 'grafana/plugin-actions/package-plugin';
+const MINIMUMS = { [BUILD_PLUGIN]: 'build-plugin/v1.2.0', [PACKAGE_PLUGIN]: 'package-plugin/v1.3.3' };
+
+// a release workflow with one step per `uses` value
+function workflowWith(...uses: string[]): string {
+  return `name: Release\njobs:\n  release:\n    runs-on: ubuntu-latest\n    steps:\n${uses.map((u) => `      - uses: ${u}\n`).join('')}`;
+}
+
+function bump(workflow: string, minimums: Record<string, string> = MINIMUMS) {
+  const context = new Context('/virtual');
+  context.addFile(WORKFLOW, workflow);
+  const result = bumpActionRefs(context, WORKFLOW, minimums);
+  return { result, content: context.getFile(WORKFLOW) };
+}
+
+describe('bumpActionRefs', () => {
+  it.each([
+    ['a prefixed tag', 'build-plugin/v1.0.2'],
+    ['a bare tag', 'v1.0.0'],
+  ])('raises %s to the minimum', (_, ref) => {
+    const { content, result } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+  });
+
+  it.each([
+    ['a floating minor tag', 'build-plugin/v1.1', 'build-plugin/v1.2'],
+    ['a bare floating minor tag', 'v1.0', 'build-plugin/v1.2'],
+    ['a floating major tag', 'v0', 'build-plugin/v1'],
+  ])('raises %s and keeps it floating', (_, ref, raised) => {
+    const { content } = bump(workflowWith(`${BUILD_PLUGIN}@${ref}`));
+    expect(content).toBe(workflowWith(`${BUILD_PLUGIN}@${raised}`));
+  });
+
+  it.each(['build-plugin/v1.2.0', 'build-plugin/v2.0.0', 'build-plugin/v1.2', 'build-plugin/v1', 'v1', 'v2', 'main'])(
+    'leaves %s alone',
+    (ref) => {
+      const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+      const { content, result } = bump(workflow);
+      expect(content).toBe(workflow);
+      expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [] });
+    }
+  );
+
+  it.each([
+    ['a branch', 'some-feature-branch'],
+    ['a commit SHA', 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'],
+    ["another action's tag", 'package-plugin/v1.0.0'],
+    ['a tag with a longer prefix', 'foo/build-plugin/v1.0.0'],
+  ])('leaves %s alone and reports it', (_, ref) => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}@${ref}`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [BUILD_PLUGIN], unrecognized: [BUILD_PLUGIN] });
+  });
+
+  it('bumps each use independently, to its own action minimum', () => {
+    const { content, result } = bump(
+      workflowWith(
+        `${BUILD_PLUGIN}@v1.0.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.2`
+      )
+    );
+    expect(content).toBe(
+      workflowWith(
+        `${BUILD_PLUGIN}@build-plugin/v1.2.0`,
+        `${BUILD_PLUGIN}@build-plugin/v2.0.0`,
+        `${PACKAGE_PLUGIN}@package-plugin/v1.3.3`
+      )
+    );
+    expect(result.found).toEqual([BUILD_PLUGIN, PACKAGE_PLUGIN]);
+  });
+
+  it('bumps a quoted ref and keeps the quotes and any trailing comment', () => {
+    const { content } = bump(workflowWith(`'${BUILD_PLUGIN}@v1.0.0' # pinned`));
+    expect(content).toBe(workflowWith(`'${BUILD_PLUGIN}@build-plugin/v1.2.0' # pinned`));
+  });
+
+  it('only bumps `uses` values, not incidental mentions', () => {
+    const mention = `# see ${BUILD_PLUGIN}@v1.0.0 for reference\nenv:\n  NOTE: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content } = bump(`${mention}${workflowWith(`${BUILD_PLUGIN}@v1.0.0`)}`);
+    expect(content).toBe(`${mention}${workflowWith(`${BUILD_PLUGIN}@build-plugin/v1.2.0`)}`);
+  });
+
+  it('keeps comments, blank lines and the rest of the workflow unchanged', () => {
+    const before = [
+      '# release on tag',
+      'name: Release',
+      '',
+      'on:',
+      '  push:',
+      "    tags: ['v*']",
+      '',
+      'jobs:',
+      '  release:',
+      '    runs-on: ubuntu-latest',
+      '    steps:',
+      '      - uses: actions/checkout@v6 # keep me',
+      `      - uses: ${BUILD_PLUGIN}@v1.0.0`,
+      '        with:',
+      '          policy_token: ${{ secrets.TOKEN }}',
+      '',
+    ].join('\n');
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves an indented commented-out block exactly as it was', () => {
+    const before = workflowWith(
+      `${BUILD_PLUGIN}@v1.0.0\n        #with:\n          # save the token in your repository secrets\n          #policy_token: \${{ secrets.TOKEN }}`
+    );
+    const { content } = bump(before);
+    expect(content).toBe(before.replace(`${BUILD_PLUGIN}@v1.0.0`, `${BUILD_PLUGIN}@build-plugin/v1.2.0`));
+  });
+
+  it('leaves a workflow it cannot parse alone', () => {
+    const workflow = `jobs: [\n  uses: ${BUILD_PLUGIN}@v1.0.0\n`;
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('does not match an action whose name only starts with the given one', () => {
+    const workflow = workflowWith(`${BUILD_PLUGIN}-extra@v1.0.0`);
+    const { content, result } = bump(workflow);
+    expect(content).toBe(workflow);
+    expect(result.found).toEqual([]);
+  });
+
+  it('reports nothing found when the workflow uses none of the actions', () => {
+    const { content, result } = bump('name: Release\n');
+    expect(content).toBe('name: Release\n');
+    expect(result).toEqual({ found: [], unrecognized: [] });
+  });
+
+  it('reports nothing found when the workflow does not exist', () => {
+    const context = new Context('/virtual');
+    expect(bumpActionRefs(context, WORKFLOW, MINIMUMS)).toEqual({ found: [], unrecognized: [] });
+    expect(context.doesFileExist(WORKFLOW)).toBe(false);
+  });
+
+  it('throws when a minimum is not a version tag', () => {
+    expect(() => bump(workflowWith(`${BUILD_PLUGIN}@v1.0.0`), { [BUILD_PLUGIN]: 'main' })).toThrow(
+      "The minimum ref 'main' for grafana/plugin-actions/build-plugin is not a version tag."
+    );
+  });
+});

package/src/codemods/utils.workflows.ts

@@ -0,0 +1,140 @@
+import { isScalar, parseDocument, visit } from 'yaml';
+import type { Context } from './context.js';
+import { codemodsDebug } from './utils.js';
+
+export interface BumpActionRefsResult {
+  /** The actions used in the workflow. */
+  found: string[];
+  /** The actions pinned to something other than a version tag, such as a branch or a commit SHA. */
+  unrecognized: string[];
+}
+
+/**
+ * Raises each `uses: <action>@<ref>` in a workflow to at least the given minimum ref, the way
+ * addDependenciesToPackageJson raises dependency versions. A ref is never lowered.
+ *
+ * Refs are compared as `vX[.Y[.Z]]` tags, optionally prefixed with the action's own name as monorepo
+ * tags are (`build-plugin/v1.2.0`). A shorter tag floats, so `v1` already runs the latest 1.x and is
+ * left alone, and a floating tag that is too low is raised at its own precision (`v1.1` to `v1.2`).
+ * Other refs are left as-is and reported, except `main`, which always runs the latest release.
+ *
+ * The parser finds each `uses` value, then only that value's source text is replaced, so comments and
+ * formatting elsewhere stay byte-for-byte the same.
+ */
+export function bumpActionRefs(
+  context: Context,
+  workflowPath: string,
+  minimumRefs: Record<string, string>
+): BumpActionRefsResult {
+  const minimums = new Map(
+    Object.entries(minimumRefs).map(([action, minimumRef]) => {
+      const minimum = parseTag(action, minimumRef);
+      if (!minimum) {
+        throw new Error(`The minimum ref '${minimumRef}' for ${action} is not a version tag.`);
+      }
+      return [action, minimum];
+    })
+  );
+
+  const content = context.getFile(workflowPath);
+  if (!content) {
+    codemodsDebug(`Could not find ${workflowPath}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+
+  const doc = parseDocument(content);
+  if (doc.errors.length > 0) {
+    codemodsDebug(`Failed to parse ${workflowPath}: ${doc.errors[0].message}. Skipping action bumps.`);
+    return { found: [], unrecognized: [] };
+  }
+
+  const found = new Set<string>();
+  const unrecognized = new Set<string>();
+  const edits: Array<{ start: number; end: number; text: string }> = [];
+
+  visit(doc, {
+    Pair: (_, pair) => {
+      if (!isScalar(pair.key) || pair.key.value !== 'uses' || !isScalar(pair.value)) {
+        return;
+      }
+      const uses = pair.value;
+      if (typeof uses.value !== 'string' || !uses.value.includes('@')) {
+        return;
+      }
+      const separator = uses.value.lastIndexOf('@');
+      const action = uses.value.slice(0, separator);
+      const ref = uses.value.slice(separator + 1);
+      const minimum = minimums.get(action);
+      if (!minimum) {
+        return;
+      }
+
+      found.add(action);
+      if (ref === 'main') {
+        return;
+      }
+      const tag = parseTag(action, ref);
+      if (!tag) {
+        codemodsDebug(`${workflowPath} pins ${action}@${ref}, which is not a version tag. Leaving it as-is.`);
+        unrecognized.add(action);
+        return;
+      }
+      if (meetsMinimum(tag.version, minimum.version)) {
+        codemodsDebug(`${workflowPath} already pins ${action}@${ref}. Skipping.`);
+        return;
+      }
+      if (!uses.range) {
+        return;
+      }
+      const [start, end] = uses.range;
+      edits.push({ start, end, text: content.slice(start, end).replace(`@${ref}`, `@${raisedRef(tag, minimum)}`) });
+    },
+  });
+
+  if (edits.length > 0) {
+    // apply from the end so earlier offsets stay valid
+    const updated = edits
+      .sort((a, b) => b.start - a.start)
+      .reduce((acc, { start, end, text }) => `${acc.slice(0, start)}${text}${acc.slice(end)}`, content);
+    context.updateFile(workflowPath, updated);
+  }
+  return { found: [...found], unrecognized: [...unrecognized] };
+}
+
+interface Tag {
+  /** The text before `v`, such as `build-plugin/`, or empty for a bare tag. */
+  prefix: string;
+  /** One to three numbers, fewer for a floating tag. */
+  version: number[];
+}
+
+// reads `vX[.Y[.Z]]`, or `<name>/vX[.Y[.Z]]` where name is the action's last path segment
+function parseTag(action: string, ref: string): Tag | undefined {
+  const match = /^(?:([^/]+)\/)?v(\d+)(?:\.(\d+))?(?:\.(\d+))?$/.exec(ref);
+  if (!match || (match[1] !== undefined && match[1] !== action.split('/').at(-1))) {
+    return undefined;
+  }
+  return {
+    prefix: match[1] === undefined ? '' : `${match[1]}/`,
+    version: match
+      .slice(2)
+      .filter((part) => part !== undefined)
+      .map(Number),
+  };
+}
+
+// compares only the numbers the tag has, since a floating tag runs the latest release below it
+function meetsMinimum(version: number[], minimum: number[]): boolean {
+  for (const [i, part] of version.entries()) {
+    const minimumPart = minimum[i] ?? 0;
+    if (part !== minimumPart) {
+      return part > minimumPart;
+    }
+  }
+  return true;
+}
+
+function raisedRef(tag: Tag, minimum: Tag): string {
+  const version = Array.from({ length: tag.version.length }, (_, i) => minimum.version[i] ?? 0);
+  return `${minimum.prefix}v${version.join('.')}`;
+}