Build: Detect stale node_modules at build/dev time

bin/build.mjs

@@ -85,8 +85,20 @@ async function build() {
 	const startTime = Date.now();
 
 	try {
+		// Step 0: Verify node_modules is in sync with package-lock.json
+		console.log( '🔍 Checking dependencies...' );
+		await exec( 'npm', [
+			'run',
+			'check-installed-deps',
+			'--workspace',
+			'@wordpress/validation-tools',
+			'--silent',
+		] ).catch( () => {
+			throw new Error( 'Run `npm install` to update.' );
+		} );
+
 		// Step 1: Clean packages
-		console.log( '🧹 Cleaning packages...' );
+		console.log( '\n🧹 Cleaning packages...' );
 		await exec( 'npm', [ 'run', 'clean:packages' ], { silent: true } );
 
 		// Step 2: Build workspaces
@@ -97,20 +109,14 @@ async function build() {
 			{ silent: true }
 		);
 
-		// Step 2.5: Generate worker placeholders
+		// Step 3: Generate worker placeholders
 		// This must happen before TypeScript compilation because some packages
 		// (like vips) have source files that import from generated worker-code.ts
 		await exec( 'node', [
 			'./bin/packages/generate-worker-placeholders.mjs',
 		] );
 
 		if ( ! skipTypes ) {
-			// Step 3: Validate TypeScript version
-			console.log( '\n🔍 Validating TypeScript version...' );
-			await exec( 'node', [
-				'./bin/packages/validate-typescript-version.js',
-			] );
-
 			// Step 4: Build TypeScript types
 			console.log( '\n📘 Building TypeScript types...\n' );
 			const tsStartTime = Date.now();

bin/dev.mjs

@@ -122,8 +122,20 @@ async function dev() {
 	readyMarkerFile.cleanup();
 
 	try {
+		// Step 0: Verify node_modules is in sync with package-lock.json
+		console.log( '🔍 Checking dependencies...' );
+		await exec( 'npm', [
+			'run',
+			'check-installed-deps',
+			'--workspace',
+			'@wordpress/validation-tools',
+			'--silent',
+		] ).catch( () => {
+			throw new Error( 'Run `npm install` to update.' );
+		} );
+
 		// Step 1: Clean packages
-		console.log( '🧹 Cleaning packages...' );
+		console.log( '\n🧹 Cleaning packages...' );
 		await exec( 'npm', [ 'run', 'clean:packages' ], { silent: true } );
 
 		// Step 2: Build workspaces
@@ -134,19 +146,13 @@ async function dev() {
 			{ silent: true }
 		);
 
-		// Step 2.5: Generate worker placeholders
+		// Step 3: Generate worker placeholders
 		// This must happen before TypeScript compilation because some packages
 		// (like vips) have source files that import from generated worker-code.ts
 		await exec( 'node', [
 			'./bin/packages/generate-worker-placeholders.mjs',
 		] );
 
-		// Step 3: Validate TypeScript version
-		console.log( '\n🔍 Validating TypeScript version...' );
-		await exec( 'node', [
-			'./bin/packages/validate-typescript-version.js',
-		] );
-
 		// Step 4: Build TypeScript types
 		console.log( '\n📘 Building TypeScript types...\n' );
 		const tsStartTime = Date.now();

package.json

@@ -115,7 +115,7 @@
 	},
 	"scripts": {
 		"build": "node ./bin/build.mjs",
-		"build:profile-types": "rimraf ./ts-traces && npm run clean:package-types && node ./bin/packages/validate-typescript-version.js && ( tsgo --build --extendedDiagnostics --generateTrace ./ts-traces || ( echo 'tsc failed.'; exit 1 ) ) && node ./bin/packages/check-build-type-declaration-files.js && npx --yes @typescript/analyze-trace ts-traces > ts-traces/analysis.txt && node -p \"'\\n\\nDone! Build traces saved to ts-traces/ directory.\\nTrace analysis saved to ts-traces/analysis.txt.'\"",
+		"build:profile-types": "rimraf ./ts-traces && npm run clean:package-types && npm run check-installed-deps --workspace @wordpress/validation-tools --silent && ( tsgo --build --extendedDiagnostics --generateTrace ./ts-traces || ( echo 'tsc failed.'; exit 1 ) ) && node ./bin/packages/check-build-type-declaration-files.js && npx --yes @typescript/analyze-trace ts-traces > ts-traces/analysis.txt && node -p \"'\\n\\nDone! Build traces saved to ts-traces/ directory.\\nTrace analysis saved to ts-traces/analysis.txt.'\"",
 		"build:plugin-zip": "bash ./bin/build-plugin-zip.sh",
 		"clean:package-types": "tsgo --build --clean && rimraf --glob \"./packages/*/build-types\"",
 		"clean:packages": "rimraf --glob \"./packages/*/{build,build-module,build-wp,build-style}\" \"./build\"",

tools/eslint/config.mjs

@@ -554,6 +554,8 @@ export default dedupePlugins( [
 		files: [
 			'bin/**/*.js',
 			'bin/**/*.mjs',
+			'tools/**/*.js',
+			'tools/**/*.mjs',
 			'packages/env/**',
 			'packages/theme/bin/**/*.[tj]s?(x)',
 		],

tools/validation/check-installed-deps.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+
+/**
+ * Verifies that node_modules is in sync with package-lock.json by comparing
+ * `package-lock.json` against `node_modules/.package-lock.json` (npm's hidden
+ * lockfile, written on every install to record the actual installed tree).
+ *
+ * Exits non-zero with a hint to run `npm install` if the trees diverge.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname( fileURLToPath( import.meta.url ) );
+const ROOT = path.resolve( __dirname, '../..' );
+const LOCKFILE = path.join( ROOT, 'package-lock.json' );
+const HIDDEN_LOCKFILE = path.join( ROOT, 'node_modules', '.package-lock.json' );
+
+const verbose = process.argv.includes( '--verbose' );
+
+function fail( summary, details = '' ) {
+	let msg = `\n   ⚠️  Dependencies are out of sync: ${ summary }`;
+	if ( verbose && details ) {
+		msg += os.EOL + details;
+	}
+	console.error( msg );
+	process.exit( 1 );
+}
+
+if ( ! fs.existsSync( HIDDEN_LOCKFILE ) ) {
+	fail(
+		'node_modules is missing or incomplete.',
+		`\t${ path.relative( ROOT, HIDDEN_LOCKFILE ) } not found.`
+	);
+}
+
+const lock = JSON.parse( fs.readFileSync( LOCKFILE, 'utf8' ) );
+const hidden = JSON.parse( fs.readFileSync( HIDDEN_LOCKFILE, 'utf8' ) );
+
+const lockPkgs = lock.packages || {};
+const hiddenPkgs = hidden.packages || {};
+
+const reportedMismatches = [];
+const MAX_REPORTED = 5;
+let totalMismatches = 0;
+
+for ( const [ pkgPath, info ] of Object.entries( lockPkgs ) ) {
+	/*
+	 * Skip entries without an `integrity` field — these are the root project
+	 * and workspace/link packages (file: or workspace: refs), which aren't
+	 * fetched from a registry and have no installed counterpart to verify.
+	 */
+	if ( ! info.integrity ) {
+		continue;
+	}
+
+	const installed = hiddenPkgs[ pkgPath ];
+
+	let mismatch;
+	if ( ! installed ) {
+		/*
+		 * Optional deps may be skipped by npm on the current platform
+		 * (e.g. macOS-only fsevents on Linux). Don't flag them as missing.
+		 * Real drift on an optional dep would still be caught below as
+		 * an integrity mismatch.
+		 */
+		if ( info.optional ) {
+			continue;
+		}
+		mismatch = `missing: ${ pkgPath }`;
+	} else if ( installed.integrity !== info.integrity ) {
+		mismatch = `integrity mismatch: ${ pkgPath }`;
+	}
+
+	if ( ! mismatch ) {
+		continue;
+	}
+
+	totalMismatches++;
+	if ( reportedMismatches.length < MAX_REPORTED ) {
+		reportedMismatches.push( mismatch );
+	}
+}
+
+if ( totalMismatches > 0 ) {
+	const detailLines = reportedMismatches.map( ( m ) => `\t${ m }` );
+	if ( totalMismatches > reportedMismatches.length ) {
+		detailLines.push(
+			`\t... and ${ totalMismatches - reportedMismatches.length } more.`
+		);
+	}
+	fail(
+		`Mismatches found: ${ totalMismatches }`,
+		detailLines.join( os.EOL )
+	);
+}
+
+console.log( '\n   ✔ All good.' );

tools/validation/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@wordpress/validation-tools",
+	"version": "0.0.0",
+	"description": "Validation scripts used across the Gutenberg monorepo.",
+	"private": true,
+	"author": "The WordPress Contributors",
+	"license": "GPL-2.0-or-later",
+	"keywords": [
+		"wordpress",
+		"gutenberg",
+		"validation"
+	],
+	"homepage": "https://github.com/WordPress/gutenberg/tree/HEAD/tools/validation",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/WordPress/gutenberg.git",
+		"directory": "tools/validation"
+	},
+	"bugs": {
+		"url": "https://github.com/WordPress/gutenberg/issues"
+	},
+	"type": "module",
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"check-installed-deps": "node ./check-installed-deps.mjs"
+	}
+}