/*! * Copyright (c) Microsoft Corporation and contributors. All rights reserved. * Licensed under the MIT License. */ /** * Update script for the compat test workspaces. * * Run this script after: * - A Fluid Framework version bump as part of the release process * - Any change to `src/checkpoints.ts` (e.g. designating a new compatibility * checkpoint, correcting a date, or adjusting a future estimate), since step 7 * regenerates the `CompatibilityCheckpoints.md` table from that file * * Before running this script, make sure the repo is sufficiently built by executing: * `pnpm exec fluid-build --task build:esm /test-version-utils$` * * Running the update script: * `pnpm -r --filter @fluid-private/test-version-utils run update-compat-versions` * * The script: * 1. Reads the current package version from `src/packageVersion.ts`. * 2. Queries the npm registry to resolve the in-window prior Compatibility Checkpoints * (see `src/checkpoints.ts`) and all full back-compat versions. * 3. Writes `compat-workspaces/generated-versions.cjs` with the resolved exact versions. * 4. Creates or updates per-version `package.json` files in `compat-workspaces/full/`. * 5. Removes version directories that are no longer needed. * 6. Runs `pnpm install --no-frozen-lockfile` in the workspace to regenerate the lockfile. * 7. Regenerates the checkpoints table in `CompatibilityCheckpoints.md` from * the single source of truth in `src/checkpoints.ts`. * * Commit all files produced by this script, including the updated `pnpm-lock.yaml` * and `CompatibilityCheckpoints.md`. * * Files which are MACHINE-MAINTAINED (should not be edited by hand — regenerated by this script): * compat-workspaces/generated-versions.cjs * compat-workspaces/full//package.json (one per version) * compat-workspaces/full/pnpm-lock.yaml * The auto-generated table block in CompatibilityCheckpoints.md */ import { execSync } from "node:child_process"; import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs"; import * as path from "node:path"; import { fileURLToPath, pathToFileURL } from "node:url"; import { findGitRootSync } from "@fluid-tools/build-infrastructure"; import { lowestMinVersionForCollab } from "@fluidframework/runtime-utils/internal"; import * as semver from "semver"; // Re-use version arithmetic and package list from the main source to keep them in sync. // jiti (used to run this script) resolves .js imports to .ts files automatically. import { getRequestedVersion, resolveRangeViaRegistry } from "../src/versionUtils.js"; import { packageListToInstall } from "../src/compatPackageList.js"; import { getFullBackCompatVersionDeltas, oldestCompatibleVersion, } from "../src/compatConfig.js"; import { checkpointResolutionRange, compatibilityCheckpointsDocRelativePath, getCurrentCheckpoint, getInWindowPriorCheckpoints, injectCheckpointsTable, } from "../src/checkpoints.js"; // --------------------------------------------------------------------------- // Configuration // --------------------------------------------------------------------------- const scriptDir = fileURLToPath(new URL(".", import.meta.url)); const pkgRoot = path.resolve(scriptDir, ".."); const gitRoot = findGitRootSync(pkgRoot); const compatWorkspacesDir = path.join(pkgRoot, "compat-workspaces"); const generatedVersionsCjsPath = path.join(compatWorkspacesDir, "generated-versions.cjs"); // --------------------------------------------------------------------------- // Version resolution // --------------------------------------------------------------------------- /** * Resolves a minor-version delta relative to `pkgVer` against the npm registry. * A delta of -1 means "the release group one minor-version step older than pkgVer" * (e.g. the previous 10-minor-version band for 2.x, or the previous RC/internal tier). */ function resolveVersionForMinorDelta(pkgVer: string, delta: number): string | undefined { try { return getRequestedVersion({ baseVersion: pkgVer, requested: delta, useOnlineRegistry: true, }); } catch (error) { console.warn(`Warning: ${error instanceof Error ? error.message : error}`); return undefined; } } // --------------------------------------------------------------------------- // Workspace file generation // --------------------------------------------------------------------------- /** * Builds the `package.json` content for a per-version workspace directory. * Includes only the Fluid packages that existed at `version` (filtered by `minVersion`). */ function buildVersionPackageJson(versionDir: string, version: string): string { const deps: Record = {}; for (const entry of packageListToInstall) { if (semver.gte(version, entry.minVersion)) { deps[entry.pkgName] = version; } } deps["@fluid-experimental/sequence-deprecated"] = version; const sortedDeps = Object.fromEntries( Object.entries(deps).sort(([a], [b]) => a.localeCompare(b)), ); const repoDirectory = path.relative(gitRoot, versionDir).replace(/\\/g, "/"); // Field order must match sort-package-json output to pass the npm-package-metadata-and-sorting policy. return `${JSON.stringify( { name: `compat-${version}`, version: "1.0.0", private: true, homepage: "https://fluidframework.com", repository: { type: "git", url: "https://github.com/microsoft/FluidFramework.git", directory: repoDirectory, }, license: "MIT", author: "Microsoft and contributors", dependencies: sortedDeps, }, undefined, 2, )}\n`; } /** * Creates or updates `//package.json`. Skips the write if the * content is already up to date. Returns `true` iff any changes were made. */ function syncVersionDirectory(workspaceDir: string, version: string): boolean { const versionDir = path.join(workspaceDir, version); const pkgJsonPath = path.join(versionDir, "package.json"); const newContent = buildVersionPackageJson(versionDir, version); const existed = existsSync(pkgJsonPath); if (existed) { const existing = readFileSync(pkgJsonPath, "utf8"); if (existing === newContent) return false; // no change } mkdirSync(versionDir, { recursive: true }); writeFileSync(pkgJsonPath, newContent, "utf8"); console.log(` ${existed ? "Updated" : "Created"} ${path.relative(pkgRoot, pkgJsonPath)}`); return true; } /** * Deletes any subdirectory (excluding `node_modules`) of `workspaceDir` whose name is * not in `keepVersions`. Returns `true` iff at least one directory was removed. */ function removeStaleVersionDirs(workspaceDir: string, keepVersions: Set): boolean { if (!existsSync(workspaceDir)) return false; let removed = false; for (const entry of readdirSync(workspaceDir, { withFileTypes: true })) { if (!entry.isDirectory()) continue; if (entry.name === "node_modules") continue; if (!keepVersions.has(entry.name)) { const dirPath = path.join(workspaceDir, entry.name); rmSync(dirPath, { recursive: true }); console.log(` Removed stale ${path.relative(pkgRoot, dirPath)}`); removed = true; } } return removed; } function pnpmInstallWorkspace(workspaceDir: string): void { console.log(`\nRunning pnpm install in ${path.relative(pkgRoot, workspaceDir)} ...`); execSync(`pnpm --config.minimum-release-age=10080 install --no-frozen-lockfile`, { cwd: workspaceDir, env: { ...process.env, NODE_OPTIONS: "" }, stdio: "inherit", }); } // --------------------------------------------------------------------------- // Main // --------------------------------------------------------------------------- async function main(): Promise { // Read current package version const pkgJsonPath = path.join(pkgRoot, "package.json"); const { version: pkgVer } = JSON.parse(readFileSync(pkgJsonPath, "utf8")) as { version: string; }; console.log(`Current package version: ${pkgVer}`); // Resolve the in-window prior Compatibility Checkpoints that drive the // cross-client and layer-compat e2e matrices. console.log("\nResolving in-window compatibility checkpoints..."); const currentCheckpoint = getCurrentCheckpoint(pkgVer); console.log( ` Current: ${currentCheckpoint.name} (>= ${currentCheckpoint.lowerBoundVersion})`, ); const checkpointVersions: string[] = []; // Used to ensure versions are only installed once across all types of compat testing. // `oldestCompatibleVersion` is added at the start to ensure it is installed. const seenVersions = new Set([oldestCompatibleVersion]); // The current checkpoint is included (first) so its lower-bound version is installed for // the cross-client matrix (current build vs. current checkpoint lower bound). The prior // in-window checkpoints follow. for (const checkpoint of [ currentCheckpoint, ...getInWindowPriorCheckpoints(currentCheckpoint, lowestMinVersionForCollab), ]) { const range = checkpointResolutionRange(checkpoint); // Unlike the back-compat deltas below, designated checkpoints are expected to always // resolve to a published version, so we let resolveRangeViaRegistry throw to surface a // misconfigured checkpoint loudly. const resolved = resolveRangeViaRegistry(range); if (seenVersions.has(resolved)) { console.log(` ${checkpoint.name} (${range}): ${resolved} (duplicate, skipping)`); continue; } seenVersions.add(resolved); checkpointVersions.push(resolved); console.log(` ${checkpoint.name} (${range}): ${resolved}`); } console.log(` ocv: ${oldestCompatibleVersion}`); // Resolve the layer-compat adjacent-minor version (N-1). Used by `defaultVersionsForLayerCompat`, // which keeps adjacent-minor semantics because Fluid's intra-client layer-compat checks are // stricter than the cross-client window. N-1 and OCV are the only versions layer-compat needs; // cross-client version will come from the checkpoints (resolved above). console.log("\nResolving layer-compat (N-1)..."); const nMinus1 = resolveVersionForMinorDelta(pkgVer, -1); if (nMinus1 === undefined) { throw new Error("Could not resolve N-1. Check registry connectivity."); } if (!seenVersions.has(nMinus1)) { seenVersions.add(nMinus1); } console.log(` N-1: ${nMinus1}`); // Resolve stable back-compat release bands down to the OCV floor. console.log("\nResolving full back-compat versions..."); const fullAdditional: string[] = []; for (const delta of getFullBackCompatVersionDeltas(pkgVer)) { const resolved = resolveVersionForMinorDelta(pkgVer, delta); if (resolved === undefined) { console.warn(` Delta ${delta}: not found, skipping`); continue; } if (seenVersions.has(resolved)) { console.log(` Delta ${delta}: ${resolved} (duplicate, skipping)`); continue; } seenVersions.add(resolved); fullAdditional.push(resolved); console.log(` Delta ${delta}: ${resolved}`); } const { explicitVersions } = (await import( pathToFileURL(path.join(compatWorkspacesDir, "explicit-versions.mjs")).href )) as { explicitVersions: string[] }; if (explicitVersions.length > 0) { console.log( `\nLoaded ${explicitVersions.length} explicit version(s): ${explicitVersions.join(", ")}`, ); } // allVersions is the single set of versions installed in the workspace and recorded in the manifest. const allVersions = new Set([ nMinus1, ...checkpointVersions, oldestCompatibleVersion, ...explicitVersions, ...fullAdditional, ]); // Write generated-versions.cjs — flat list of all installed versions, newest first. // .cjs (CommonJS) so it can be loaded synchronously via createRequire() in versionUtils.ts. const manifest = { versions: [...allVersions].sort(semver.rcompare) }; const manifestContent = [ "/*!", " * Copyright (c) Microsoft Corporation and contributors. All rights reserved.", " * Licensed under the MIT License.", " */", "", "// MACHINE-GENERATED by scripts/updateCompatVersions.ts — do not edit by hand.", "// Run `pnpm run update-compat-versions` from packages/test/test-version-utils to regenerate.", "//", "// .cjs (CommonJS) so it can be loaded synchronously via createRequire() in versionUtils.ts.", `module.exports = ${JSON.stringify(manifest, undefined, "\t")};`, "", ].join("\n"); writeFileSync(generatedVersionsCjsPath, manifestContent, "utf8"); console.log(`\nWrote ${path.relative(pkgRoot, generatedVersionsCjsPath)}`); let anyChanged = false; // Sync the single full workspace (contains all versions) console.log("\nSyncing full workspace..."); const fullDir = path.join(compatWorkspacesDir, "full"); if (removeStaleVersionDirs(fullDir, allVersions)) anyChanged = true; for (const version of allVersions) { const changed = syncVersionDirectory(fullDir, version); if (changed) anyChanged = true; } if (anyChanged) { // Regenerate lockfile pnpmInstallWorkspace(fullDir); console.log("\nDone. Commit all changes in compat-workspaces/ to the repository."); } else { console.log("\nNo package.json changes — versions are up to date."); } // Regenerate the checkpoints table in CompatibilityCheckpoints.md. const docPath = path.join(gitRoot, compatibilityCheckpointsDocRelativePath); const original = readFileSync(docPath, "utf8"); const updated = injectCheckpointsTable(original); if (updated !== original) { writeFileSync(docPath, updated, "utf8"); console.log(`\nUpdated table in ${path.relative(gitRoot, docPath)}`); } else { console.log(`\n${compatibilityCheckpointsDocRelativePath} table is already up to date.`); } } main().catch((e) => { console.error(e); process.exit(1); });