feat(generate:typetests)!: Make type tests configurable per-branch

build-tools/packages/build-cli/.eslintrc.cjs

@@ -26,6 +26,9 @@ module.exports = {
             {
                 allow: [
                     "@oclif/core/lib/interfaces",
+                    "@oclif/core/lib/util",
+                    "oclif/lib/commands/**",
+                    "oclif/lib/util",
                     "npm-check-updates/build/src/types/**",
                     "**/commands/**",
                 ],

build-tools/packages/build-cli/README.md

@@ -17,7 +17,7 @@ $ npm install -g @fluid-tools/build-cli
 $ flub COMMAND
 running command...
 $ flub (--version|-V)
-@fluid-tools/build-cli/0.5.0
+@fluid-tools/build-cli/0.6.0
 $ flub --help [COMMAND]
 USAGE
   $ flub COMMAND

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

@@ -114,18 +114,17 @@ Generates type tests based on the individual package settings in package.json.
 ```
 USAGE
   $ flub generate typetests [-d <value> | --packages | -g client|server|azure|build-tools] [--prepare | --generate]
-    (--exact <value> |  | -s
-    ^previousMajor|^previousMinor|~previousMajor|~previousMinor|previousMajor|previousMinor|baseMinor|baseMajor)
-    [--reset | ] [--generateInName] [-v]
+    [--exact <value> |  | -s ^previousMajor|^previousMinor|~previousMajor|~previousMinor|previousMajor|previousMinor|pre
+    viousPatch|baseMinor|baseMajor|~baseMinor] [--reset | ] [--generateInName] [-v]
 
 FLAGS
   -d, --dir=<value>                 Run on the package in this directory.
   -g, --releaseGroup=<option>       Run on all packages within this release group.
                                     <options: client|server|azure|build-tools>
-  -s, --versionConstraint=<option>  (required) The type of version constraint to use for previous versions. Only applies
-                                    to the prepare phase.
+  -s, --versionConstraint=<option>  The type of version constraint to use for previous versions. Only applies to the
+                                    prepare phase.
                                     <options: ^previousMajor|^previousMinor|~previousMajor|~previousMinor|previousMajor|
-                                    previousMinor|baseMinor|baseMajor>
+                                    previousMinor|previousPatch|baseMinor|baseMajor|~baseMinor>
   -v, --verbose                     Verbose logging.
   --exact=<value>                   An exact string to use as the previous version constraint. The string will be used
                                     as-is. Only applies to the prepare phase.
@@ -151,7 +150,10 @@ DESCRIPTION
   preparation. This is useful when resetting the type tests to a clean state, such as after a major release.
 
   Generating test modules takes the type test information from package.json, most notably any known broken type tests,
-  and generates an appropriate
+  and generates test files that should be committed.
+
+  To learn more about how to configure type tests, see the detailed documentation at
+  <https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/typetestDetails.md>.
 
 EXAMPLES
   Prepare the package.json for all packages in the client release group.

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

@@ -0,0 +1,154 @@
+# Further information about `generate typetests`
+
+The `generate typetests` command generates type compatibility tests based on the individual package settings in
+package.json.
+
+## What are type compatibility tests?
+
+Type compatibility tests are automatically generated test cases that check for type incompatibilities across package
+versions. They work by comparing types in the current version to the types in a previous version. The generated tests
+use the previous type in place of the new type, and vice-versa.
+
+See the [API Type Validation][] page in the Fluid Framework wiki for more information about type compatibility tests,
+including how to annotate expected type incompatibilities to fix failing tests.
+
+## Configuring type tests
+
+Type test generation is primarily configured in the package.json file of the package being tested, in the
+`typeValidation` section:
+
+```json
+"typeValidation": {
+  "disabled": false,
+  "version": "1.1.0",
+  "broken": {
+    "InterfaceDeclaration_AzureClientProps": {
+      "forwardCompat": false
+    }
+  }
+}
+```
+
+The `broken` section is used to indicate known breaking changes. Type tests can be completely disabled for a package
+using the `disabled1 property. See [API Type Validation][] for more information.
+
+Generating type tests has two parts: _preparing package.json_ and _generating test modules_. By default, both steps are
+run for each package. You can run only one part at a time using the `--prepare` and `--generate` flags.
+
+[api type validation]: https://github.com/microsoft/FluidFramework/wiki/API-Type-Validation
+
+## Preparing package.json
+
+_Preparing package.json_ determines the baseline previous version to use, then sets that version in package.json. If the
+previous version changes after running preparation, then `npm install` must be run before the generate step will run
+correctly.
+
+Optionally, any type tests that are marked "broken" in package.json can be reset using the `--reset` flag during
+preparation. This is useful when resetting the type tests to a clean state, such as after a major release.
+
+## Generating tests
+
+Generating test modules takes the type test information from package.json, most notably any known broken type tests, and
+generates test files that should be committed. By default, the generated files will contain `.generated` in their name,
+but this can be suppressed with the `--no-generateInName` flag.
+
+For more detailed usage information see the
+[bump deps command reference](bump.md#flub-bump-deps-packageorreleasegroup).
+
+## Branch configuration
+
+Type tests can be configured to use different baseline versions on a given branch depending on the type of release that
+the branch is designated for. For example, for the client release group, the _next_ branch is the _major version series
+branch_ and _main_ is the _minor version series branch_. This can be declared in the root package.json, in the
+`fluidBuild.repoPackages` section. For example, the following configuration designates the _main_ and _lts_ branches as
+minor version series branches, while the _next_ branch is designated for major releases.
+
+```json
+"fluidBuild": {
+  "repoPackages": {
+    "client": {
+      "directory": "",
+      "ignoredDirs": [],
+      "branchReleaseTypes": {
+        "main": "minor",
+        "lts": "minor",
+        "release/**": "patch",
+        "next": "major"
+      }
+    }
+  }
+}
+```
+
+The branch names can be globs. They are matched using [minimatch](https://www.npmjs.com/package/minimatch).
+
+The type test generator takes this information into account when calculating the baseline version to use when it's run
+on a particular branch. Baseline versions are set as follows based on the branch release designation:
+
+| Branch release designation | Baseline version | Example: version 2.3.4 |
+| -------------------------- | ---------------- | ---------------------- |
+| `patch`                    | `previousPatch`  | **2.3.3**              |
+| `minor`                    | `^previousMinor` | **^2.2.0**             |
+| `major`                    | `^previousMajor` | **^1.0.0**             |
+
+### Configuring a branch for a specific baseline
+
+It may be useful to configure a branch for a specific baseline instead of the default based on the branch release
+designation. To do this, you can use any of the following strings instead of major/minor/patch.
+
+- `baseMajor`
+- `baseMinor`
+- `~baseMinor`
+- `previousPatch`
+- `previousMinor`
+- `previousMajor`
+- `^previousMajor`
+- `^previousMinor`
+- `~previousMajor`
+- `~previousMinor`
+
+Given the version 3.4.5:
+
+| Previous version style | Baseline version for **3.4.5** |
+| ---------------------- | ------------------------------ |
+| `baseMajor`            | 3.0.0                          |
+| `baseMinor`            | 3.4.0                          |
+| `~baseMinor`           | ~3.4.0                         |
+| `previousPatch`        | 3.4.4                          |
+| `previousMajor`        | 2.0.0                          |
+| `previousMinor`        | 3.3.0                          |
+| `^previousMajor`       | ^2.0.0                         |
+| `^previousMinor`       | ^3.3.0                         |
+| `~previousMajor`       | ~2.0.0                         |
+| `~previousMinor`       | ~3.3.0                         |
+
+
+Given the version 2.0.0-internal.2.3.5:
+
+| Previous version style | Baseline version for **2.0.0-internal.2.3.5** |
+| ---------------------- | --------------------------------------------- |
+| `baseMajor`            | 2.0.0-internal.2.0.0                          |
+| `baseMinor`            | 2.0.0-internal.2.3.0                          |
+| `~baseMinor`           | >=2.0.0-internal.2.3.0 <2.0.0-internal.3.0.0  |
+| `previousPatch`        | 2.0.0-internal.2.3.4                          |
+| `previousMajor`        | 2.0.0-internal.1.0.0                          |
+| `previousMinor`        | 2.0.0-internal.2.2.0                          |
+| `^previousMajor`       | >=2.0.0-internal.1.0.0 <2.0.0-internal.2.0.0  |
+| `^previousMinor`       | >=2.0.0-internal.2.2.0 <2.0.0-internal.3.0.0  |
+| `~previousMajor`       | >=2.0.0-internal.1.0.0 <2.0.0-internal.1.1.0  |
+| `~previousMinor`       | >=2.0.0-internal.2.2.0 <2.0.0-internal.2.2.0  |
+
+Given the version 2.0.0-internal.2.0.0:
+
+| Previous version style | Baseline version for **2.0.0-internal.2.0.0** |
+| ---------------------- | --------------------------------------------- |
+| `baseMajor`            | 2.0.0-internal.2.0.0                          |
+| `baseMinor`            | 2.0.0-internal.2.0.0                          |
+| `~baseMinor`           | >=2.0.0-internal.2.0.0 <2.0.0-internal.2.1.0  |
+| `previousPatch`        | 2.0.0-internal.2.0.0                          |
+| `previousMajor`        | 2.0.0-internal.1.0.0                          |
+| `previousMinor`        | 2.0.0-internal.2.0.0                          |
+| `^previousMajor`       | >=2.0.0-internal.1.0.0 <2.0.0-internal.2.0.0  |
+| `^previousMinor`       | >=2.0.0-internal.2.0.0 <2.0.0-internal.3.0.0  |
+| `~previousMajor`       | >=2.0.0-internal.1.0.0 <2.0.0-internal.1.1.0  |
+| `~previousMinor`       | >=2.0.0-internal.2.0.0 <2.0.0-internal.2.1.0  |

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

@@ -5,24 +5,29 @@
 import { CliUx, Flags } from "@oclif/core";
 import chalk from "chalk";
 
-import { generateTests, getAndUpdatePackageDetails } from "@fluidframework/build-tools";
+import {
+    PreviousVersionStyle,
+    generateTests,
+    getAndUpdatePackageDetails,
+} from "@fluidframework/build-tools";
 
 import { BaseCommand } from "../../base";
 import { releaseGroupFlag } from "../../flags";
 
 export default class GenerateTypeTestsCommand extends BaseCommand<
     typeof GenerateTypeTestsCommand.flags
 > {
-    static summary =
-        "Generates type tests based on the individual package settings in package.json.";
+    static description = `Generates type tests based on the individual package settings in package.json.
 
-    static description = `Generating type tests has two parts: preparing package.json and generating test modules. By default, both steps are run for each package. You can run only one part at a time using the --prepare and --generate flags.
+    Generating type tests has two parts: preparing package.json and generating test modules. By default, both steps are run for each package. You can run only one part at a time using the --prepare and --generate flags.
 
     Preparing package.json determines the baseline previous version to use, then sets that version in package.json. If the previous version changes after running preparation, then npm install must be run before the generate step will run correctly.
 
     Optionally, any type tests that are marked "broken" in package.json can be reset using the --reset flag during preparation. This is useful when resetting the type tests to a clean state, such as after a major release.
 
-    Generating test modules takes the type test information from package.json, most notably any known broken type tests, and generates an appropriate `;
+    Generating test modules takes the type test information from package.json, most notably any known broken type tests, and generates test files that should be committed.
+
+    To learn more about how to configure type tests, see the detailed documentation at <https://github.com/microsoft/FluidFramework/blob/main/build-tools/packages/build-cli/docs/typetestDetails.md>.`;
 
     static flags = {
         dir: Flags.directory({
@@ -59,10 +64,11 @@ export default class GenerateTypeTestsCommand extends BaseCommand<
                 "~previousMinor",
                 "previousMajor",
                 "previousMinor",
+                "previousPatch",
                 "baseMinor",
                 "baseMajor",
+                "~baseMinor",
             ],
-            required: true,
         }),
         exact: Flags.string({
             description:
@@ -140,6 +146,7 @@ export default class GenerateTypeTestsCommand extends BaseCommand<
             this.info(`Finding package in directory: ${dir}`);
             packageDirs.push(dir);
         } else {
+            // eslint-disable-next-line @typescript-eslint/no-shadow
             const context = await this.getContext();
             if (independentPackages) {
                 this.info(`Finding independent packages`);
@@ -160,8 +167,10 @@ export default class GenerateTypeTestsCommand extends BaseCommand<
             });
         }
 
+        const context = await this.getContext();
         const concurrency = 25;
         const runningGenerates: Promise<boolean>[] = [];
+
         // this loop incrementally builds up the runningGenerates promise list
         // each dir with an index greater than concurrency looks back the concurrency value
         // to determine when to run
@@ -184,9 +193,10 @@ export default class GenerateTypeTestsCommand extends BaseCommand<
                     try {
                         const start = Date.now();
                         const packageData = await getAndUpdatePackageDetails(
+                            context,
                             packageDir,
                             /* writeUpdates */ runPrepare,
-                            flags.versionConstraint as any,
+                            flags.versionConstraint as PreviousVersionStyle | undefined,
                             flags.exact,
                             flags.reset,
                         ).finally(() => output.push(`Loaded(${Date.now() - start}ms)`));

build-tools/packages/build-tools/src/bumpVersion/context.ts

@@ -23,7 +23,7 @@ export class Context {
     public readonly fullPackageMap: Map<string, Package>;
 
     private readonly timer: Timer;
-    private readonly packageManifest: IPackageManifest;
+    public readonly packageManifest: IPackageManifest;
     private readonly newBranches: string[] = [];
     private readonly newTags: string[] = [];
 

build-tools/packages/build-tools/src/common/fluidRepo.ts

@@ -4,6 +4,9 @@
  */
 import * as path from "path";
 
+import { VersionBumpType } from "@fluid-tools/version-tools";
+
+import { PreviousVersionStyle } from "../typeValidator/packageJson";
 import { getPackageManifest } from "./fluidUtils";
 import { Logger, defaultLogger } from "./logging";
 import { MonoRepo, MonoRepoKind, isMonoRepoKind } from "./monoRepo";
@@ -33,6 +36,9 @@ export interface PolicyConfig {
 export interface IFluidRepoPackage {
     directory: string;
     ignoredDirs?: string[];
+    branchReleaseTypes?: {
+        [name: string]: VersionBumpType | PreviousVersionStyle;
+    };
 }
 
 export type IFluidRepoPackageEntry = string | IFluidRepoPackage | (string | IFluidRepoPackage)[];

build-tools/packages/build-tools/src/index.ts

@@ -35,3 +35,4 @@ export { policyHandlers } from "./repoPolicyCheck/handlers";
 export { generateMonoRepoInstallPackageJson } from "./genMonoRepoPackageJson/lib";
 export { findPackagesUnderPath, getAndUpdatePackageDetails } from "./typeValidator/packageJson";
 export { generateTests } from "./typeValidator/testGeneration";
+export { type PreviousVersionStyle } from "./typeValidator/packageJson";