Bundled packages: Add a check for transitive private API usage

.github/workflows/static-checks.yml

@@ -144,3 +144,36 @@ jobs:
 
             - name: License compatibility
               run: npm run other:check-licenses
+
+    # Fails when a bundled package pulls @wordpress/private-apis into its
+    # module graph, including transitively through another package.
+    check-private-apis:
+        name: Check private API usage in bundled packages
+        runs-on: ubuntu-24.04
+        permissions:
+            contents: read
+        if: ${{ github.repository == 'WordPress/gutenberg' || github.event_name == 'pull_request' }}
+        timeout-minutes: 10
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  show-progress: ${{ runner.debug == '1' && 'true' || 'false' }}
+                  persist-credentials: false
+
+            - name: Use desired version of Node.js
+              uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+              with:
+                  node-version-file: '.nvmrc'
+                  # No cache restoration: this workflow also runs on push,
+                  # and the job doesn't need the install speed.
+                  package-manager-cache: false
+
+            - name: npm install
+              # Not the setup-node composite action: its cached node_modules
+              # path skips `prepare` scripts, and bundling from source needs
+              # what they generate (e.g. the icons `src/library`).
+              run: npm install
+
+            - name: Check private API usage in bundled packages
+              run: npm run --workspace @wordpress/validation-tools check-private-apis

packages/dataviews/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 -   Remove unused dependency `@wordpress/primitives` ([#82103](https://github.com/WordPress/gutenberg/pull/82103)).
 -   Remove tsconfig project references to packages that are not dependencies ([#82106](https://github.com/WordPress/gutenberg/pull/82106)).
+-   Note in the `/wp` bundle build script that its singleton externals list must stay in sync with the transitive private API usage check ([#82027](https://github.com/WordPress/gutenberg/pull/82027)).
 
 ## 18.1.0 (2026-08-26)
 

packages/dataviews/build.cjs

@@ -6,7 +6,9 @@ const wpExternals = {
 		build.onResolve(
 			{ filter: /^@wordpress\/(data|hooks|i18n|date)(\/|$)/ },
 			( args ) => {
-				// Don't bundle WordPress signleton packages
+				// Don't bundle WordPress singleton packages. Keep the list in
+				// sync with `SINGLETONS` in
+				// `tools/validation/check-private-apis.mjs`.
 				return { path: args.path, external: true };
 			}
 		);

tools/validation/check-private-apis.config.json

@@ -0,0 +1,165 @@
+{
+	"comment": "The direct-import counterpart of the lock-unlock entries lives in tools/eslint/suppressions.json (no-restricted-imports). The two lists are enforced independently — a stale entry fails CI in each — but a package dropping private APIs needs an edit in both.",
+	"exceptions": [
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "dataviews",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "fields",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/core-data, whose internals unlock private APIs across api-fetch, sync, blocks, block-editor, and global-styles-engine. Remove when the core-data dependency is dropped or those internals stop using private APIs.",
+			"package": "fields",
+			"via": "packages/core-data/src/index.js"
+		},
+		{
+			"comment": "Depends on @wordpress/blocks, whose store unlocks private APIs internally (and pulls rich-text, reviving the components/compose private registries). Remove when those internals stop using private APIs.",
+			"package": "fields",
+			"via": "packages/blocks/src/index.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/patterns (see the pattern-sync-status field), whose store pulls block-editor and its private-API cascade (rich-text, global-styles-engine, upload-media, commands). Remove when the patterns dependency is dropped or its store no longer pulls block-editor.",
+			"package": "fields",
+			"via": "packages/patterns/src/index.js"
+		},
+		{
+			"comment": "Unlocks private APIs of @wordpress/components. Remove when the unlocked surface goes public.",
+			"package": "fields",
+			"via": "packages/components/src/private-apis.ts"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "fields",
+			"via": "packages/fields/src/lock-unlock.ts"
+		},
+		{
+			"comment": "Unlocks private APIs of @wordpress/media-utils (see its media-edit component). Remove when the unlocked surface goes public.",
+			"package": "fields",
+			"via": "packages/media-utils/src/private-apis.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/api-fetch, whose internals unlock private APIs. Remove when api-fetch no longer does.",
+			"package": "fields",
+			"via": "packages/api-fetch/src/index.ts"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "global-styles-engine",
+			"via": "packages/global-styles-engine/src/lock-unlock.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/blocks, whose store unlocks private APIs internally. Remove when blocks' store no longer does.",
+			"package": "global-styles-engine",
+			"via": "packages/blocks/src/index.ts"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "global-styles-ui",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/blocks, whose store unlocks private APIs internally (and pulls rich-text, reviving the components/compose private registries). Remove when those internals stop using private APIs.",
+			"package": "global-styles-ui",
+			"via": "packages/blocks/src/index.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/block-editor, which unlocks private APIs throughout its store and components. Remove when the block-editor dependency is dropped or that stops.",
+			"package": "global-styles-ui",
+			"via": "packages/block-editor/src/index.js"
+		},
+		{
+			"comment": "Depends on @wordpress/global-styles-engine, which has its own private API surface. Remove when that surface goes public.",
+			"package": "global-styles-ui",
+			"via": "packages/global-styles-engine/src/index.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/core-data, whose internals unlock private APIs across api-fetch, sync, blocks, block-editor, and global-styles-engine. Remove when the core-data dependency is dropped or those internals stop using private APIs.",
+			"package": "global-styles-ui",
+			"via": "packages/core-data/src/index.js"
+		},
+		{
+			"comment": "Depends on @wordpress/api-fetch, whose internals unlock private APIs. Remove when api-fetch no longer does.",
+			"package": "global-styles-ui",
+			"via": "packages/api-fetch/src/index.ts"
+		},
+		{
+			"comment": "Unlocks private APIs of @wordpress/components. Remove when the unlocked surface goes public.",
+			"package": "global-styles-ui",
+			"via": "packages/components/src/private-apis.ts"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "global-styles-ui",
+			"via": "packages/global-styles-ui/src/lock-unlock.ts"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "media-editor",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/core-data, whose internals unlock private APIs across api-fetch, sync, blocks, block-editor, and global-styles-engine. Remove when the core-data dependency is dropped or those internals stop using private APIs.",
+			"package": "media-editor",
+			"via": "packages/core-data/src/index.js"
+		},
+		{
+			"comment": "Depends on @wordpress/api-fetch, whose internals unlock private APIs. Remove when api-fetch no longer does.",
+			"package": "media-editor",
+			"via": "packages/api-fetch/src/index.ts"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "media-editor",
+			"via": "packages/media-editor/src/lock-unlock.ts"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "media-fields",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/core-data, whose internals unlock private APIs across api-fetch, sync, blocks, block-editor, and global-styles-engine. Remove when the core-data dependency is dropped or those internals stop using private APIs.",
+			"package": "media-fields",
+			"via": "packages/core-data/src/index.js"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "ui",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/core-data, whose internals unlock private APIs across api-fetch, sync, blocks, block-editor, and global-styles-engine. Remove when the core-data dependency is dropped or those internals stop using private APIs.",
+			"package": "views",
+			"via": "packages/core-data/src/index.js"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "views",
+			"via": "packages/views/src/lock-unlock.ts"
+		},
+		{
+			"comment": "ThemeProvider falls back to the WP 7.2 theme/ui private APIs when the public API is unavailable. Remove when the fallback is deleted (scheduled for WP 7.3; see the TODO in the file).",
+			"package": "widget-dashboard",
+			"via": "packages/ui/src/utils/theme-provider.ts"
+		},
+		{
+			"comment": "Unlocks private APIs of @wordpress/components (see its actions-menu component). Remove when the unlocked components go public.",
+			"package": "widget-dashboard",
+			"via": "packages/components/src/private-apis.ts"
+		},
+		{
+			"comment": "Depends on @wordpress/commands, whose store and private surface use private APIs. Remove when commands no longer does or the dependency is dropped.",
+			"package": "widget-dashboard",
+			"via": "packages/commands/src/index.js"
+		},
+		{
+			"comment": "The package's own private cross-package API usage, tracked file-by-file by the private-apis lint suppressions. Remove when the package stops using private APIs.",
+			"package": "widget-dashboard",
+			"via": "packages/widget-dashboard/src/lock-unlock.ts"
+		}
+	]
+}