(compat) Add PackageCommand to auto update layer compatibility generation (microsoft#25670)

## Description
Each layer within a client (Loader, Driver, Runtime and Datastore) has a
generation property which should be incremented monthly. It provides a
simple way to determine if two layers are compatible with each other by
comparing their generations since layer compatibility is expressed in
number of months. For example, between the Runtime and Datastore layers,
we support a 3 months compatibility. So, they are compatible if the
difference in their generation is <3. See microsoft#22877 for more details on how
this will work.

This change adds an automated way to increment the generation of these
layers for simplicity and consistency. Here is how it works:
- A new `PackageCommand` called `UpdateGenerationCommand` is added. The
flub command `flub generate:layerCompatGeneration` can be run this
command for a package.
- Added a new node to package.json file called `fluidCompatMetadata`
which will contain the generation information as per the last update. It
is of type `IFluidCompatibilityMetadata` and contains the last
generation, last release date and last release package version.
- If the command is run for the first time in a package, it will
auto-generate `fluidCompatMetadata` and add it to the package.json file.
It will also auto-generate a filed called `layerGenerationState.ts`
under the .src directory.
- If the command is run subsequently, it will read `fluidCompatMetadata`
from package.json and update the generation (if needed) as follows:
- If the package version has changed, i.e., a new release has happened,
it will update the generation to `New generation = Old generation + no.
of months since last release`.
- An important requirement is that in between two subsequent releases,
the generation should not be incremented by more than the minimum compat
window between 2 layers across all layers boundaries. For example, say
compat window between Loader / Runtime is 12 months but between Runtime
/ Datastore it is only 3 months. Then between 2 subsequent releases,
generation should not increment by more than 2. If that happens, it
doesn't give customers enough time to upgrade their packages and
saturate a release before upgrading to the next one. Layer compatiility
will break as soon they upgrade.
- So, the logic for new generation is updated to: `New generation = Old
generation + min (no. of months since last release, min. compat window
between layers across all layer boundaries)`.
- The `flub generate:layerGeneration` command will be added to the
scripts in `client-utils`'s `package.json` file in a subsequent PR. The
generation information for all the layers will be present in this
package. The associated chagnes to the build system to run this command
on releases will also be added in a subsequent PR.


[AB#51926](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/51926)

Author: agarwal-navin

.prettierignore

@@ -24,6 +24,7 @@ build-tools/packages/build-cli/README.md
 build-tools/packages/version-tools/README.md
 **/src/**/test/types/*.generated.ts
 **/src/packageVersion.ts
+**/src/layerGenerationState.ts
 **/build-tools/CHANGELOG.md
 **/*.done.build.log
 

biome.jsonc

@@ -28,6 +28,7 @@
 			// Generated files
 			"**/src/**/test/types/*.generated.ts",
 			"**/src/packageVersion.ts",
+			"**/src/layerGenerationState.ts",
 
 			// Dependencies
 			"**/node_modules/*",

build-tools/packages/build-cli/docs/generate.md

@@ -9,6 +9,7 @@ Generate commands are used to create/update code, docs, readmes, etc.
 * [`flub generate changelog`](#flub-generate-changelog)
 * [`flub generate changeset`](#flub-generate-changeset)
 * [`flub generate entrypoints`](#flub-generate-entrypoints)
+* [`flub generate layerCompatGeneration`](#flub-generate-layercompatgeneration)
 * [`flub generate node10Entrypoints`](#flub-generate-node10entrypoints)
 * [`flub generate packlist`](#flub-generate-packlist)
 * [`flub generate releaseNotes`](#flub-generate-releasenotes)
@@ -268,6 +269,60 @@ DESCRIPTION
 
 _See code: [src/commands/generate/entrypoints.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/generate/entrypoints.ts)_
 
+## `flub generate layerCompatGeneration`
+
+Updates the generation and release date for layer compatibility.
+
+```
+USAGE
+  $ flub generate layerCompatGeneration [-v | --quiet] [--generationDir <value>] [--outFile <value>] [--minimumCompatWindowMonths
+    <value>] [--concurrency <value>] [--branch <value> [--changed | [--all | --dir <value>... | --packages | -g
+    client|server|azure|build-tools|gitrest|historian|all... | --releaseGroupRoot
+    client|server|azure|build-tools|gitrest|historian|all...]]] [--private] [--scope <value>... | --skipScope
+    <value>...]
+
+FLAGS
+  --concurrency=<value>                [default: 25] The number of tasks to execute concurrently.
+  --generationDir=<value>              [default: ./src] The directory where the generation file is located.
+  --minimumCompatWindowMonths=<value>  [default: 3] The minimum compatibility window in months that is supported across
+                                       all Fluid layers.
+  --outFile=<value>                    [default: layerGenerationState.ts] Output the results to this file.
+
+PACKAGE SELECTION FLAGS
+  -g, --releaseGroup=<option>...      Run on all child packages within the specified release groups. This does not
+                                      include release group root packages. To include those, use the --releaseGroupRoot
+                                      argument. Cannot be used with --all.
+                                      <options: client|server|azure|build-tools|gitrest|historian|all>
+      --all                           Run on all packages and release groups. Cannot be used with --dir, --packages,
+                                      --releaseGroup, or --releaseGroupRoot.
+      --branch=<value>                [default: main] Select only packages that have been changed when compared to this
+                                      base branch. Can only be used with --changed.
+      --changed                       Select packages that have changed when compared to a base branch. Use the --branch
+                                      option to specify a different base branch. Cannot be used with --all.
+      --dir=<value>...                Run on the package in this directory. Cannot be used with --all.
+      --packages                      Run on all independent packages in the repo. Cannot be used with --all.
+      --releaseGroupRoot=<option>...  Run on the root package of the specified release groups. This does not include any
+                                      child packages within the release group. To include those, use the --releaseGroup
+                                      argument. Cannot be used with --all.
+                                      <options: client|server|azure|build-tools|gitrest|historian|all>
+
+LOGGING FLAGS
+  -v, --verbose  Enable verbose logging.
+      --quiet    Disable all logging.
+
+PACKAGE FILTER FLAGS
+  --[no-]private          Only include private packages. Use --no-private to exclude private packages instead.
+  --scope=<value>...      Package scopes to filter to. If provided, only packages whose scope matches the flag will be
+                          included. Cannot be used with --skipScope.
+  --skipScope=<value>...  Package scopes to filter out. If provided, packages whose scope matches the flag will be
+                          excluded. Cannot be used with --scope.
+
+DESCRIPTION
+  Updates the generation and release date for layer compatibility.
+```
+
+_See code: [src/commands/generate/layerCompatGeneration.ts](https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/src/commands/generate/layerCompatGeneration.ts)_
+
 ## `flub generate node10Entrypoints`
 
 Generates node10 type declaration entrypoints for Fluid Framework API levels (/alpha, /beta, /internal etc.) as found in package.json "exports"

build-tools/packages/build-cli/src/commands/generate/layerCompatGeneration.ts

@@ -0,0 +1,214 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+import { updatePackageJsonFile } from "@fluid-tools/build-infrastructure";
+import type {
+	IFluidCompatibilityMetadata,
+	Logger,
+	Package,
+	PackageJson,
+} from "@fluidframework/build-tools";
+import { Flags } from "@oclif/core";
+import { formatISO, isDate, isValid, parseISO } from "date-fns";
+import { diff, parse } from "semver";
+import { PackageCommand } from "../../BasePackageCommand.js";
+import type { PackageSelectionDefault } from "../../flags.js";
+
+// Approximate month as 33 days to add some buffer and avoid over-counting months in longer spans.
+export const daysInMonthApproximation = 33;
+
+export default class UpdateGenerationCommand extends PackageCommand<
+	typeof UpdateGenerationCommand
+> {
+	static readonly description =
+		"Updates the generation and release date for layer compatibility.";
+
+	static readonly flags = {
+		generationDir: Flags.directory({
+			description: "The directory where the generation file is located.",
+			default: "./src",
+			exists: true,
+		}),
+		outFile: Flags.string({
+			description: `Output the results to this file.`,
+			default: `layerGenerationState.ts`,
+		}),
+		minimumCompatWindowMonths: Flags.integer({
+			description: `The minimum compatibility window in months that is supported across all Fluid layers.`,
+			default: 3,
+		}),
+		...PackageCommand.flags,
+	} as const;
+
+	protected defaultSelection = "dir" as PackageSelectionDefault;
+
+	protected async processPackage(pkg: Package): Promise<void> {
+		const { generationDir, outFile, minimumCompatWindowMonths } = this.flags;
+		const generationFileFullPath = path.join(pkg.directory, generationDir, outFile);
+
+		const currentPkgVersion = pkg.version;
+		// "patch" versions do trigger generation updates.
+		if (isCurrentPackageVersionPatch(currentPkgVersion)) {
+			this.verbose(`Patch version detected; skipping generation update.`);
+			return;
+		}
+
+		// Default to generation 1 if no existing file.
+		let newGeneration: number | undefined = 1;
+		const { fluidCompatMetadata } = pkg.packageJson;
+		if (fluidCompatMetadata !== undefined) {
+			this.verbose(
+				`Layer compatibility metadata from package.json: Generation: ${fluidCompatMetadata.generation}, ` +
+					`Release Date: ${fluidCompatMetadata.releaseDate}, Package Version: ${fluidCompatMetadata.releasePkgVersion}`,
+			);
+			newGeneration = maybeGetNewGeneration(
+				currentPkgVersion,
+				fluidCompatMetadata,
+				minimumCompatWindowMonths,
+				this.logger,
+			);
+			if (newGeneration === undefined) {
+				// No update needed; early exit.
+				this.verbose(`No generation update needed; skipping.`);
+				return;
+			}
+		}
+
+		const currentReleaseDate = formatISO(new Date(), { representation: "date" });
+		const newFluidCompatMetadata: IFluidCompatibilityMetadata = {
+			generation: newGeneration,
+			releaseDate: currentReleaseDate,
+			releasePkgVersion: currentPkgVersion,
+		};
+		updatePackageJsonFile(pkg.directory, (json: PackageJson) => {
+			json.fluidCompatMetadata = newFluidCompatMetadata;
+		});
+		await writeFile(generationFileFullPath, generateLayerFileContent(newGeneration), {
+			encoding: "utf8",
+		});
+		this.info(`Layer generation updated to ${newGeneration}`);
+	}
+}
+
+/**
+ * Determines if the current package version represents a patch release.
+ *
+ * @param pkgVersion - The semantic version of the package (e.g., "2.0.1")
+ * @returns True if the version is a patch release, false otherwise
+ *
+ * @throws Error When the provided version string is not a valid semantic version
+ *
+ * @example
+ * ```typescript
+ * isCurrentPackageVersionPatch("2.0.1"); // returns true
+ * isCurrentPackageVersionPatch("2.1.0"); // returns false
+ * isCurrentPackageVersionPatch("3.0.0"); // returns false
+ * ```
+ */
+export function isCurrentPackageVersionPatch(pkgVersion: string): boolean {
+	const parsed = parse(pkgVersion);
+	if (parsed === null) {
+		throw new Error(`Package version ${pkgVersion} is not a valid semver`);
+	}
+	return parsed.patch > 0;
+}
+
+/**
+ * Generates the complete content for a layer generation TypeScript file.
+ *
+ * Creates a properly formatted TypeScript file with copyright header, autogenerated warning,
+ * and export for generation number.
+ *
+ * @param generation - The layer compatibility generation number
+ * @returns The complete file content as a string ready to be written to disk
+ *
+ * @example
+ * ```typescript
+ * const content = generateLayerFileContent(5);
+ * // Returns a complete TypeScript file with exports:
+ * // export const generation = 5;
+ * ```
+ */
+export function generateLayerFileContent(generation: number): string {
+	return `/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ *
+ * THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY.
+ */
+
+export const generation = ${generation};
+`;
+}
+
+/**
+ * Determines if a new generation should be generated based on package version changes and time since
+ * the last release.
+ *
+ * This function parses an existing layer generation file and decides whether to increment the generation
+ * number based on:
+ * 1. Whether the package version has changed since the last update
+ * 2. How much time has elapsed since the previous release date
+ * 3. The minimum compatibility window constraints
+ *
+ * The generation increment is calculated as the number of months since the previous release,
+ * but capped at (minimumCompatWindowMonths - 1) to maintain compatibility requirements.
+ *
+ * @param currentPkgVersion - The current package version to compare against the stored version
+ * @param fluidCompatMetadata - The existing Fluid compatibility metadata from the previous generation
+ * @param minimumCompatWindowMonths - The maximum number of months of compatibility to maintain across layers
+ * @param log - Logger instance for verbose output about the calculation process
+ * @returns The new generation number if an update is needed, or undefined if no update is required
+ *
+ * @throws Error When the generation file content doesn't match the expected format
+ * @throws Error When the current date is older than the previous release date
+ */
+export function maybeGetNewGeneration(
+	currentPkgVersion: string,
+	fluidCompatMetadata: IFluidCompatibilityMetadata,
+	minimumCompatWindowMonths: number,
+	log: Logger,
+): number | undefined {
+	// Only "minor" or "major" version changes trigger generation updates.
+	const result = diff(currentPkgVersion, fluidCompatMetadata.releasePkgVersion);
+	if (result === null || (result !== "minor" && result !== "major")) {
+		log.verbose(`No minor or major release since last update; skipping generation update.`);
+		return undefined;
+	}
+
+	log.verbose(
+		`Previous package version: ${fluidCompatMetadata.releasePkgVersion}, Current package version: ${currentPkgVersion}`,
+	);
+
+	const previousReleaseDate = parseISO(fluidCompatMetadata.releaseDate);
+	if (!isValid(previousReleaseDate) || !isDate(previousReleaseDate)) {
+		throw new Error(
+			`Previous release date "${fluidCompatMetadata.releaseDate}" is not a valid date.`,
+		);
+	}
+
+	const today = new Date();
+	const timeDiff = today.getTime() - previousReleaseDate.getTime();
+	if (timeDiff < 0) {
+		throw new Error("Current date is older that previous release date");
+	}
+	const daysBetweenReleases = Math.round(timeDiff / (1000 * 60 * 60 * 24));
+	const monthsBetweenReleases = Math.floor(daysBetweenReleases / daysInMonthApproximation);
+	log.verbose(`Previous release date: ${previousReleaseDate}, Today: ${today}`);
+	log.verbose(
+		`Time between releases: ${daysBetweenReleases} day(s) or ~${monthsBetweenReleases} month(s)`,
+	);
+
+	const newGeneration =
+		fluidCompatMetadata.generation +
+		Math.min(monthsBetweenReleases, minimumCompatWindowMonths - 1);
+	if (newGeneration === fluidCompatMetadata.generation) {
+		log.verbose(`Generation remains the same (${newGeneration}); skipping generation update.`);
+		return undefined;
+	}
+	return newGeneration;
+}