Add @rushstack/heft-zod-schema-plugin and pilot it on rush-lib's experiments.json

common/changes/@microsoft/rush-lib/zod-schema-pilot_2026-04-19.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/rush-lib",
+      "comment": "Move the IExperimentsJson interface declaration to the new @rushstack/rush-schemas package. rush-lib re-exports the interface so existing imports remain stable.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@microsoft/rush-lib"
+}

common/changes/@rushstack/heft-zod-schema-plugin/zod-schema-plugin_2026-04-19.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-zod-schema-plugin",
+      "comment": "Initial release. A Heft task plugin that converts zod validators into *.schema.json build outputs using zod 4's built-in z.toJSONSchema(). Includes a withSchemaMeta() helper for attaching $schema/title/description/x-tsdoc-release-tag metadata to a zod schema.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-zod-schema-plugin"
+}

common/changes/@rushstack/rush-schemas/rush-schemas-init_2026-04-19.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/rush-schemas",
+      "comment": "Initial release. Pilots a dedicated home for zod-authored Rush configuration schemas (experiments, cobuild, repo-state, build-cache) that emits both runtime validators and *.schema.json artifacts.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@rushstack/rush-schemas"
+}

common/config/rush/browser-approved-packages.json

@@ -38,10 +38,18 @@
       "name": "@reduxjs/toolkit",
       "allowedCategories": [ "libraries", "vscode-extensions" ]
     },
+    {
+      "name": "@rushstack/heft-zod-schema-plugin",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "@rushstack/problem-matcher",
       "allowedCategories": [ "libraries" ]
     },
+    {
+      "name": "@rushstack/rush-schemas",
+      "allowedCategories": [ "libraries" ]
+    },
     {
       "name": "@rushstack/rush-themed-ui",
       "allowedCategories": [ "libraries" ]

common/config/subspaces/build-tests-subspace/repo-state.json

@@ -1,6 +1,6 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "1266218fdf9ed4d67e625f96e8c1cc4bae29dc68",
+  "pnpmShrinkwrapHash": "0d3fa0f98a02504bf1f36a2cea15fadf76e1f0b9",
   "preferredVersionsHash": "550b4cee0bef4e97db6c6aad726df5149d20e7d9",
-  "packageJsonInjectedDependenciesHash": "9c068bf4931bd84aa82934f391073bf027e52b69"
+  "packageJsonInjectedDependenciesHash": "c4fba4181349178d4b8b8aa1fee6cfe76e3639c0"
 }

common/config/subspaces/default/common-versions.json

@@ -117,6 +117,12 @@
       "2.2.1",
       "1.1.3" // heft plugin is using an older version of tapable
     ],
+    "zod": [
+      // rush-mcp-server pins to zod 3 to remain compatible with @modelcontextprotocol/sdk;
+      // heft-zod-schema-plugin and the rush-lib pilot use zod 4 for its built-in
+      // z.toJSONSchema() API.
+      "~3.25.76"
+    ],
     // --- For Webpack 4 projects ----
     "css-loader": ["~5.2.7"],
     "html-webpack-plugin": ["~4.5.2"],

common/config/subspaces/default/repo-state.json

@@ -1,5 +1,5 @@
 // DO NOT MODIFY THIS FILE MANUALLY BUT DO COMMIT IT. It is generated and used by Rush.
 {
-  "pnpmShrinkwrapHash": "b649b4390090c37d5feb374b0c04bf100edc8047",
+  "pnpmShrinkwrapHash": "a2c8f7f19f774ed72d75aa83c6639ac8e034c8ba",
   "preferredVersionsHash": "029c99bd6e65c5e1f25e2848340509811ff9753c"
 }

common/reviews/api/rush-lib.api.md

@@ -17,6 +17,7 @@ import { CredentialCache } from '@rushstack/credential-cache';
 import { HookMap } from 'tapable';
 import { ICredentialCacheEntry } from '@rushstack/credential-cache';
 import { ICredentialCacheOptions } from '@rushstack/credential-cache';
+import type { IExperimentsJson } from '@rushstack/rush-schemas/lib/experiments.zod';
 import { IFileDiffStatus } from '@rushstack/package-deps-hash';
 import { IPackageJson } from '@rushstack/node-core-library';
 import { IPrefixMatch } from '@rushstack/lookup-by-path';
@@ -466,28 +467,7 @@ export interface IExecutionResult {
     readonly status: OperationStatus;
 }
 
-// @beta
-export interface IExperimentsJson {
-    allowCobuildWithoutCache?: boolean;
-    buildCacheWithAllowWarningsInSuccessfulBuild?: boolean;
-    buildSkipWithAllowWarningsInSuccessfulBuild?: boolean;
-    cleanInstallAfterNpmrcChanges?: boolean;
-    enableSubpathScan?: boolean;
-    exemptDecoupledDependenciesBetweenSubspaces?: boolean;
-    forbidPhantomResolvableNodeModulesFolders?: boolean;
-    generateProjectImpactGraphDuringRushUpdate?: boolean;
-    noChmodFieldInTarHeaderNormalization?: boolean;
-    omitAppleDoubleFilesFromBuildCache?: boolean;
-    omitImportersFromPreventManualShrinkwrapChanges?: boolean;
-    printEventHooksOutputToConsole?: boolean;
-    rushAlerts?: boolean;
-    strictChangefileValidation?: boolean;
-    useIPCScriptsInWatchMode?: boolean;
-    usePnpmFrozenLockfileForRushInstall?: boolean;
-    usePnpmLockfileOnlyThenFrozenLockfileForRushUpdate?: boolean;
-    usePnpmPreferFrozenLockfileForRushUpdate?: boolean;
-    usePnpmSyncForInjectedDependencies?: boolean;
-}
+export { IExperimentsJson }
 
 // @beta
 export interface IFileSystemBuildCacheProviderOptions {

heft-plugins/heft-zod-schema-plugin/CHANGELOG.json

@@ -0,0 +1,4 @@
+{
+  "name": "@rushstack/heft-zod-schema-plugin",
+  "entries": []
+}

heft-plugins/heft-zod-schema-plugin/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Change Log - @rushstack/heft-zod-schema-plugin
+
+This log was last generated on Sat, 19 Apr 2026 00:00:00 GMT and should not be manually modified.

heft-plugins/heft-zod-schema-plugin/LICENSE

@@ -0,0 +1,24 @@
+@rushstack/heft-zod-schema-plugin
+
+Copyright (c) Microsoft Corporation. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.