/*! * Copyright (c) Microsoft Corporation and contributors. All rights reserved. * Licensed under the MIT License. */ /** * Fluid Framework Compatibility Checkpoints — single source of truth. * * Designated checkpoints drive the runtime test matrix. Future / TBD checkpoints are * listed below for documentation purposes only. Both sets populate the table in * `CompatibilityCheckpoints.md` at the repo root; from a sufficiently built repo * (`pnpm exec fluid-build --task build:esm /test-version-utils$`), run * `pnpm -r --filter @fluid-private/test-version-utils run update-compat-versions` * after any change to regenerate that table (and the compat workspaces). * * For more information, see CrossClientCompatibility.md, CrossClientCompatibilityDevGuide.md, * and CompatibilityCheckpoints.md. */ import * as semver from "semver"; /** * A designated compatibility checkpoint. Drives both the cross-client e2e test * matrix (via {@link getInWindowPriorCheckpoints}) and the generated table in * `CompatibilityCheckpoints.md` at the repo root. * * @internal */ export interface Checkpoint { /** * Identifier for the checkpoint (i.e."CC#3"). */ readonly name: string; /** * Position in the checkpoint sequence (i.e. 1, 2, 3, ...). Must be unique and * contiguous across {@link checkpoints} and {@link futureCheckpoints}. * Used to determine which checkpoints are within the cross-client compat range. */ readonly index: number; /** * Inclusive lower bound of this checkpoint's version range. */ readonly lowerBoundVersion: string; /** * ISO `YYYY-MM-DD` date. For designated checkpoints, the release date of * `lowerBoundVersion`. For TBD entries in {@link futureCheckpoints}, the estimated * earliest date the checkpoint could be designated (6-month-cadence floor). */ readonly startDate: string; /** * Extra semver ranges for versions that generic semver ranges do not * capture (i.e. the `2.0.0-internal.x.y.z` releases for CC#1). */ readonly additionalRanges?: readonly string[]; } /** * A {@link Checkpoint} extended with fields used only when rendering the * generated table in `CompatibilityCheckpoints.md`. Not used by any runtime * or test-matrix logic. */ interface DocumentedCheckpoint extends Checkpoint { /** `"designated"` rows have real versions/dates; `"tbd"` rows are estimates. */ readonly status: "designated" | "tbd"; /** * Explicit upper bound (exclusive). When omitted, the upper bound is the next * checkpoint's `lowerBoundVersion`. Set for the last designated checkpoint and the * last checkpoint overall. */ readonly closingVersion?: string; } /** * Designated compatibility checkpoints. Append a new entry here only once a * checkpoint is officially designated, and remove the corresponding entry from * {@link futureCheckpoints} below. * * @internal */ export const checkpoints: readonly Checkpoint[] = [ { name: "CC#1", index: 1, lowerBoundVersion: "1.4.0", startDate: "2024-04-09", additionalRanges: ["2.0.0-internal*", "2.0.0-rc*"], }, { name: "CC#2", index: 2, lowerBoundVersion: "2.0.0", startDate: "2024-06-26", }, { name: "CC#3", index: 3, lowerBoundVersion: "2.40.0", startDate: "2025-05-12", }, { name: "CC#4", index: 4, lowerBoundVersion: "2.80.0", startDate: "2026-01-06", }, { name: "CC#5", index: 5, lowerBoundVersion: "3.0.0", startDate: "2026-09-03", }, ]; /** * Forecast of upcoming checkpoints, for documentation purposes only. Included so * the generated `CompatibilityCheckpoints.md` table shows any planned future checkpoints. * These are not consumed by any runtime or test-matrix logic. * When a checkpoint is officially designated, move its entry from here into * {@link checkpoints} above (and update its `startDate` to the actual release date). */ const futureCheckpoints: readonly DocumentedCheckpoint[] = [ { name: "CC#6", index: 6, lowerBoundVersion: "4.0.0", startDate: "2027-04-19", status: "tbd", }, { name: "CC#7", index: 7, lowerBoundVersion: "5.0.0", startDate: "2027-12-06", status: "tbd", closingVersion: "6.0.0", }, ]; /** * Size of the cross-client compatibility window in both directions (older and newer). * Two clients are guaranteed compatible if their checkpoints are within * `fullCompatibilityWindowSize` indexes of each other (currently 3, ~18 months given * the 6-month cadence). * * @internal */ export const fullCompatibilityWindowSize = 3; /** * Returns the highest checkpoint whose `lowerBoundVersion` is at or below * `version`. * * @internal */ export function getCurrentCheckpoint(version: string): Checkpoint { if (!semver.valid(version)) { throw new Error(`Invalid version: "${version}"`); } // `additionalRanges` entries override the standard `lowerBoundVersion` // comparison. They exist for legacy prereleases (e.g. `2.0.0-internal*`) // that should map to an earlier checkpoint despite sorting at or above a // later one's lower bound version under semver rules. for (const c of checkpoints) { if (c.additionalRanges?.some((r) => matchesRange(version, r))) { return c; } } const parsed = semver.parse(version); const sorted = [...checkpoints].sort((a, b) => b.index - a.index); for (const c of sorted) { if (semver.gte(version, c.lowerBoundVersion)) { return c; } // A prerelease whose `major.minor.patch` equals a checkpoint's // `lowerBoundVersion` belongs to that checkpoint — `2.100.0-rc.0` is the // release-candidate of CC#4, not the tail end of CC#3, even though // `semver.gte("2.100.0-rc.0", "2.100.0")` is `false`. if (parsed !== null && parsed.prerelease.length > 0) { const lowerBound = semver.parse(c.lowerBoundVersion); if ( lowerBound !== null && parsed.major === lowerBound.major && parsed.minor === lowerBound.minor && parsed.patch === lowerBound.patch ) { return c; } } } // Throw if we reach here. Should be unreachable in practice since only versions before 1.4.0 would not match any checkpoint. throw new Error(`Version "${version}" is not associated with any checkpoint.`); } /** * Returns the prior in-window checkpoints relative to `current` from newest * to oldest. * * @param minimumVersion - When provided, checkpoints below this deployed-client * compatibility floor are omitted. * * May return fewer than `fullCompatibilityWindowSize` entries when `current` * is near the start of the checkpoint list (e.g., `current === CC#1` returns * `[]`) or when older checkpoints fall below `minimumVersion`. * * @internal */ export function getInWindowPriorCheckpoints( current: Checkpoint, minimumVersion?: string, ): Checkpoint[] { const result: Checkpoint[] = []; for (let i = 1; i <= fullCompatibilityWindowSize; i++) { const target = checkpoints.find((c) => c.index === current.index - i); if ( target !== undefined && (minimumVersion === undefined || semver.gte(target.lowerBoundVersion, minimumVersion)) ) { result.push(target); } } return result; } /** * Returns the semver range used to resolve a checkpoint to a single version. * We use tilde to get the latest patch for the earliest minor of a given checkpoint. * * @internal */ export function checkpointResolutionRange(checkpoint: Checkpoint): string { return `~${checkpoint.lowerBoundVersion}`; } /** Returns `true` iff `version` matches `range`, handling wildcard-suffix entries like `2.0.0-internal*`. */ function matchesRange(version: string, range: string): boolean { if (range.endsWith("*")) { return version.startsWith(range.slice(0, -1)); } if (semver.validRange(range)) { return semver.satisfies(version, range, { includePrerelease: true }); } throw new Error(`Invalid additionalRanges entry: "${range}"`); } // --------------------------------------------------------------------------- // Documentation table generation // --------------------------------------------------------------------------- /** Path of the documentation file, relative to the repository root. @internal */ export const compatibilityCheckpointsDocRelativePath = "CompatibilityCheckpoints.md"; const designatedSourceRelativePath = "packages/test/test-version-utils/src/checkpoints.ts"; /** Sentinel marking the start of the auto-generated table block. */ const tableStartMarker = ""; /** Sentinel marking the end of the auto-generated table block. */ const tableEndMarker = ""; const doNotEditNotice = [ "", ``, ].join("\n"); /** * Explicit upper bounds for designated checkpoints whose range does not end at * the next checkpoint's `lowerBoundVersion`. Normally empty: a designated * checkpoint's range runs up to the next checkpoint's lower bound (the next * entry in {@link futureCheckpoints} when it is the latest designated one). */ const designatedClosingVersions: Readonly> = {}; const documentedCheckpoints: readonly DocumentedCheckpoint[] = [ ...checkpoints.map( (c): DocumentedCheckpoint => ({ ...c, status: "designated", ...(designatedClosingVersions[c.name] === undefined ? {} : { closingVersion: designatedClosingVersions[c.name] }), }), ), ...futureCheckpoints, ].sort((a, b) => a.index - b.index); function escapeCell(value: string): string { return value.replace(/\|/g, "\\|"); } function closingVersionOf( checkpoint: DocumentedCheckpoint, index: number, ): { version: string; estimated: boolean } { if (checkpoint.closingVersion !== undefined) { return { version: checkpoint.closingVersion, estimated: checkpoint.status === "tbd" }; } const next = documentedCheckpoints[index + 1]; if (next === undefined) { throw new Error( `Checkpoint "${checkpoint.name}" has no following checkpoint and no closingVersion.`, ); } // The upper bound is the next checkpoint's lower bound; it is an estimate when // that next checkpoint is not yet designated (e.g. the latest designated // checkpoint closes at the first forecasted future checkpoint). return { version: next.lowerBoundVersion, estimated: next.status === "tbd" }; } function renderName(c: DocumentedCheckpoint): string { return c.status === "tbd" ? `${c.name} (TBD)` : c.name; } function renderDate(c: DocumentedCheckpoint): string { return c.status === "tbd" ? `~${c.startDate}` : c.startDate; } function renderVersionRange(c: DocumentedCheckpoint, i: number): string { const closing = closingVersionOf(c, i); const additional = (c.additionalRanges ?? []).map((r) => ` | ${r}`).join(""); const range = `\`>=${c.lowerBoundVersion} <${closing.version}${additional}\``; return closing.estimated ? `${range}(estimated)` : range; } function compatibleCheckpointsOf(c: DocumentedCheckpoint): DocumentedCheckpoint[] { return documentedCheckpoints.filter( (x) => Math.abs(x.index - c.index) <= fullCompatibilityWindowSize, ); } function renderCompatibleCheckpoints(c: DocumentedCheckpoint): string { return compatibleCheckpointsOf(c) .map((x) => x.name) .join(", "); } function renderCompatibleSemanticVersions(c: DocumentedCheckpoint): string { const window = compatibleCheckpointsOf(c); const lowest = window[0]; const highest = window[window.length - 1]; const closing = closingVersionOf(highest, documentedCheckpoints.indexOf(highest)); const estimated = closing.estimated ? "(estimated)" : ""; const additionalRanges = window.flatMap((x) => x.additionalRanges ?? []); // Wrap additional ranges in their own code span (e.g. `| 2.0.0-internal* | 2.0.0-rc*`), // adjacent to the version range span. The `|` chars are escaped by escapeCell later. const additionalPart = additionalRanges.length > 0 ? `\` | ${additionalRanges.join(" | ")}\`` : ""; return `\`>=${lowest.lowerBoundVersion} <${closing.version}\`${estimated}${additionalPart}`; } function renderRow(c: DocumentedCheckpoint, i: number): string { const cells = [ renderName(c), renderVersionRange(c, i), renderDate(c), renderCompatibleCheckpoints(c), renderCompatibleSemanticVersions(c), ].map(escapeCell); return `| ${cells.join(" | ")} |`; } /** * Renders the generated table block (do-not-edit notice + header + data rows). */ function renderCheckpointsTable(): string { const rows = documentedCheckpoints.map((c, i) => renderRow(c, i)).join("\n"); return [ doNotEditNotice, "", "", "| Checkpoint | Version Range | Start Date | Compatible Checkpoints | Compatible Semantic Versions |", "| --- | --- | --- | --- | --- |", rows, ].join("\n"); } /** * Replaces the content between {@link tableStartMarker} and {@link tableEndMarker} * in `docContent` with the freshly rendered table, preserving all surrounding prose. * @internal */ export function injectCheckpointsTable(docContent: string): string { const start = docContent.indexOf(tableStartMarker); const end = docContent.indexOf(tableEndMarker); if (start === -1 || end === -1) { throw new Error( `Could not find table sentinels in ${compatibilityCheckpointsDocRelativePath}. ` + `Expected both "${tableStartMarker}" and "${tableEndMarker}".`, ); } const before = docContent.slice(0, start + tableStartMarker.length); const after = docContent.slice(end); // A blank line before the END marker keeps output stable under Prettier. return `${before}\n${renderCheckpointsTable()}\n\n${after}`; }