@wordpress/build 0.2.0

package/src/dependency-graph.mjs

@@ -0,0 +1,271 @@
+/**
+ * Dependency graph utilities for WordPress packages.
+ *
+ * This module provides functions to analyze dependencies between @wordpress/* packages
+ * and determine the correct build order using topological sorting.
+ */
+
+/**
+ * External dependencies
+ */
+import toposort from 'toposort';
+
+/**
+ * Internal dependencies
+ */
+import { getPackageInfo } from './package-utils.mjs';
+
+/**
+ * Check if a package is a script or script module.
+ * A package is a script if it has wpScript or wpScriptModuleExports.
+ *
+ * @param {string} packageName The full package name (e.g., '@wordpress/blocks').
+ * @return {boolean} True if the package is a script or script module.
+ */
+function isScriptOrModule( packageName ) {
+	const packageJson = getPackageInfo( packageName );
+	if ( ! packageJson ) {
+		return false;
+	}
+	return !! ( packageJson.wpScript || packageJson.wpScriptModuleExports );
+}
+
+/**
+ * Get WordPress package dependencies from a package.json file.
+ *
+ * @param {string} packageName The full package name (e.g., '@wordpress/blocks').
+ * @return {string[]} Array of WordPress package names this package depends on.
+ */
+function getWordPressDependencies( packageName ) {
+	const packageJson = getPackageInfo( packageName );
+	if ( ! packageJson ) {
+		return [];
+	}
+
+	const deps = packageJson.dependencies || {};
+
+	// Extract @wordpress/* package names (keep full names)
+	return Object.keys( deps ).filter( ( dep ) =>
+		dep.startsWith( '@wordpress/' )
+	);
+}
+
+/**
+ * Build a dependency graph for the given packages.
+ *
+ * @param {string[]} packages Array of full package names to analyze.
+ * @return {Array<[string, string]>} Array of [dependent, dependency] edges.
+ */
+function buildDependencyGraph( packages ) {
+	/** @type {Array<[string, string]>} */
+	const edges = [];
+	const packagesSet = new Set( packages );
+
+	for ( const packageName of packages ) {
+		const deps = getWordPressDependencies( packageName );
+
+		// Only include edges where both packages are in our list
+		for ( const dep of deps ) {
+			if ( packagesSet.has( dep ) ) {
+				edges.push( [ packageName, dep ] );
+			}
+		}
+
+		// If package has no dependencies in our list, add a self-reference
+		// This ensures it appears in the sorted output
+		if ( deps.filter( ( dep ) => packagesSet.has( dep ) ).length === 0 ) {
+			edges.push( [ packageName, packageName ] );
+		}
+	}
+
+	return edges;
+}
+
+/**
+ * Sort packages in topological order based on their dependencies.
+ *
+ * @param {string[]} packages Array of full package names to sort.
+ * @return {string[]} Sorted array where dependencies come before dependents.
+ */
+function topologicalSort( packages ) {
+	const edges = buildDependencyGraph( packages );
+
+	try {
+		// toposort returns dependencies first, then dependents
+		/** @type {Array<string>} */
+		const sorted = toposort( edges );
+
+		// Filter to only include packages in our input list
+		// (toposort might include extra nodes)
+		const packagesSet = new Set( packages );
+		return sorted.filter( ( pkg ) => packagesSet.has( pkg ) );
+	} catch ( error ) {
+		if ( error instanceof Error && error.message.includes( 'cyclic' ) ) {
+			console.error(
+				'❌ Cyclic dependency detected in packages:',
+				error.message
+			);
+			throw new Error(
+				'Cannot build packages due to cyclic dependencies'
+			);
+		}
+		throw error;
+	}
+}
+
+/**
+ * Group packages by dependency depth level.
+ * Packages at the same depth level can be built in parallel.
+ *
+ * @param {string[]} packages Array of full package names to group.
+ * @return {string[][]} Array of arrays, where each inner array is a depth level.
+ */
+function groupByDepth( packages ) {
+	const packagesSet = new Set( packages );
+	const depths = new Map();
+	const visited = new Set();
+
+	/**
+	 * Calculate depth for a package recursively.
+	 *
+	 * @param {string} packageName Package name to calculate depth for.
+	 * @return {number} Depth level (0 = no dependencies).
+	 */
+	function calculateDepth( packageName ) {
+		if ( depths.has( packageName ) ) {
+			return depths.get( packageName );
+		}
+
+		// Prevent infinite loops in case of circular dependencies
+		if ( visited.has( packageName ) ) {
+			return 0;
+		}
+
+		visited.add( packageName );
+
+		const deps = getWordPressDependencies( packageName );
+		const relevantDeps = deps.filter( ( dep ) => packagesSet.has( dep ) );
+
+		if ( relevantDeps.length === 0 ) {
+			depths.set( packageName, 0 );
+			return 0;
+		}
+
+		const maxDepth = Math.max(
+			...relevantDeps.map( ( dep ) => calculateDepth( dep ) )
+		);
+		const depth = maxDepth + 1;
+		depths.set( packageName, depth );
+
+		return depth;
+	}
+
+	// Calculate depth for all packages
+	for ( const packageName of packages ) {
+		calculateDepth( packageName );
+	}
+
+	// Group by depth
+	const levels = [];
+	const maxDepth = Math.max( ...depths.values() );
+
+	for ( let depth = 0; depth <= maxDepth; depth++ ) {
+		const packagesAtDepth = packages.filter(
+			( pkg ) => depths.get( pkg ) === depth
+		);
+		if ( packagesAtDepth.length > 0 ) {
+			levels.push( packagesAtDepth );
+		}
+	}
+
+	return levels;
+}
+
+/**
+ * Get packages that depend on a given package (reverse dependencies).
+ *
+ * @param {string}   packageName The full package name to find dependents of.
+ * @param {string[]} allPackages Array of all full package names to search.
+ * @return {string[]} Array of package names that depend on the given package.
+ */
+function getReverseDependencies( packageName, allPackages ) {
+	const dependents = [];
+
+	for ( const pkg of allPackages ) {
+		const deps = getWordPressDependencies( pkg );
+		if ( deps.includes( packageName ) ) {
+			dependents.push( pkg );
+		}
+	}
+
+	return dependents;
+}
+
+/**
+ * Find scripts/script-modules that need to be rebundled when a bundled package changes.
+ * Uses BFS to traverse reverse dependencies, stopping at script/module boundaries.
+ *
+ * When a bundled package (no wpScript/wpScriptModuleExports) changes, we need to
+ * rebundle any scripts/modules that depend on it through a chain of bundled packages.
+ * We stop at script/module boundaries because they handle their own bundling.
+ *
+ * Example:
+ * - A (bundled) changes
+ * - B (bundled) depends on A
+ * - C (script) depends on B
+ * - D (script) depends on C
+ * Result: Only C needs rebundling (D stops at C boundary)
+ *
+ * @param {string}   changedPackage The full package name that changed.
+ * @param {string[]} allPackages    Array of all full package names.
+ * @return {string[]} Array of script/module package names to rebundle.
+ */
+function findScriptsToRebundle( changedPackage, allPackages ) {
+	// If the changed package itself is a script/module, no need to find others
+	// (it will be rebuilt by the regular watch logic)
+	if ( isScriptOrModule( changedPackage ) ) {
+		return [];
+	}
+
+	const scriptsToRebundle = new Set();
+	const visited = new Set();
+	const queue = [ changedPackage ];
+
+	while ( queue.length > 0 ) {
+		const currentPackage = queue.shift();
+
+		if ( ! currentPackage || visited.has( currentPackage ) ) {
+			continue;
+		}
+		visited.add( currentPackage );
+
+		// Get all packages that depend on the current package
+		const dependents = getReverseDependencies(
+			currentPackage,
+			allPackages
+		);
+
+		for ( const dependent of dependents ) {
+			// If this dependent is a script/module, add it to the result
+			// but don't traverse further (stop at script boundaries)
+			if ( isScriptOrModule( dependent ) ) {
+				scriptsToRebundle.add( dependent );
+			} else if ( ! visited.has( dependent ) ) {
+				// If it's a bundled package, continue traversing
+				queue.push( dependent );
+			}
+		}
+	}
+
+	return Array.from( scriptsToRebundle );
+}
+
+export {
+	getWordPressDependencies,
+	buildDependencyGraph,
+	topologicalSort,
+	groupByDepth,
+	isScriptOrModule,
+	getReverseDependencies,
+	findScriptsToRebundle,
+};

package/src/package-utils.mjs

@@ -0,0 +1,71 @@
+/**
+ * External dependencies
+ */
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+/**
+ * Shared cache for package.json files to avoid redundant reads.
+ * Cache is keyed by the full package name from package.json's name field.
+ */
+const packageJsonCache = new Map();
+const packagePathCache = new Map();
+
+/**
+ * @typedef  {Object} PackageJson
+ *
+ * @property {string}                 name                    Package name.
+ * @property {string}                 version                 Package version.
+ * @property {string}                 [description]           Package description.
+ * @property {string}                 [author]                Package author.
+ * @property {string}                 [license]               Package license.
+ * @property {string}                 [main]                  Main entry point.
+ * @property {string}                 [module]                ES module entry point.
+ * @property {string}                 [react-native]          React Native entry point.
+ * @property {Record<string, string>} [dependencies]          Runtime dependencies.
+ * @property {Record<string, string>} [devDependencies]       Development dependencies.
+ * @property {Record<string, string>} [peerDependencies]      Peer dependencies.
+ * @property {string[]}               [wpScript]              WordPress script handles for dependency extraction.
+ * @property {Record<string, string>} [wpScriptModuleExports] WordPress script module exports.
+ * @property {Object}                 [sideEffects]           Side effects configuration for tree shaking.
+ * @property {string}                 [publishConfig]         NPM publish configuration.
+ * @property {Record<string, string>} [scripts]               NPM scripts.
+ * @property {string[]}               [files]                 Files to include in package.
+ * @property {string}                 [repository]            Repository URL.
+ * @property {string[]}               [keywords]              Package keywords.
+ */
+
+/**
+ * Get package.json info using Node's module resolution.
+ * Resolves the package using import.meta.resolve and reads its package.json.
+ *
+ * @param {string} fullPackageName The full package name (e.g., '@wordpress/blocks').
+ * @return {PackageJson|null} Package.json object or null if not found.
+ */
+export function getPackageInfo( fullPackageName ) {
+	if ( packageJsonCache.has( fullPackageName ) ) {
+		return packageJsonCache.get( fullPackageName );
+	}
+
+	const resolved = import.meta.resolve( `${ fullPackageName }/package.json` );
+	const result = getPackageInfoFromFile( fileURLToPath( resolved ) );
+	packageJsonCache.set( fullPackageName, result );
+
+	return result;
+}
+
+/**
+ * Get package.json info from an explicit file path.
+ * Reads the package.json file and caches it by its name field.
+ *
+ * @param {string} packageJsonPath Absolute path to package.json file.
+ * @return {PackageJson|null} Package.json object or null if not found.
+ */
+export function getPackageInfoFromFile( packageJsonPath ) {
+	if ( packagePathCache.has( packageJsonPath ) ) {
+		return packagePathCache.get( packageJsonPath );
+	}
+	const packageJson = JSON.parse( readFileSync( packageJsonPath, 'utf8' ) );
+	packagePathCache.set( packageJsonPath, packageJson );
+	return packageJson;
+}

package/src/php-generator.mjs

@@ -0,0 +1,72 @@
+/**
+ * External dependencies
+ */
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * Internal dependencies
+ */
+import { getPackageInfoFromFile } from './package-utils.mjs';
+
+const __dirname = path.dirname( fileURLToPath( import.meta.url ) );
+
+/**
+ * Get PHP replacements from root package.json.
+ *
+ * @param {string} rootDir Root directory path.
+ * @return {Promise<Record<string, string>>} Replacements object with {{PREFIX}}, {{VERSION}}, {{VERSION_CONSTANT}}.
+ */
+export async function getPhpReplacements( rootDir ) {
+	const rootPackageJson = getPackageInfoFromFile(
+		path.join( rootDir, 'package.json' )
+	);
+	if ( ! rootPackageJson ) {
+		throw new Error( 'Could not read root package.json' );
+	}
+
+	// @ts-expect-error specific override to package.json
+	const name = rootPackageJson.wpPlugin?.name || 'gutenberg';
+	const version = rootPackageJson.version;
+	const versionConstant =
+		name.toUpperCase().replace( /-/g, '_' ) + '_VERSION';
+
+	return {
+		'{{PREFIX}}': name,
+		'{{VERSION}}': version,
+		'{{VERSION_CONSTANT}}': versionConstant,
+	};
+}
+
+/**
+ * Generate a PHP file from a template with replacements.
+ *
+ * @param {string}                 templateName Template file name.
+ * @param {string}                 outputPath   Full output path.
+ * @param {Record<string, string>} replacements Replacements object (e.g. {'{{PREFIX}}': 'gutenberg'}).
+ */
+export async function generatePhpFromTemplate(
+	templateName,
+	outputPath,
+	replacements
+) {
+	// Templates directory
+	const templatesDir = path.join( __dirname, '..', 'templates' );
+
+	// Read template
+	const template = await readFile(
+		path.join( templatesDir, templateName ),
+		'utf8'
+	);
+
+	// Apply all replacements
+	let content = template;
+	for ( const [ placeholder, value ] of Object.entries( replacements ) ) {
+		content = content.replaceAll( placeholder, value );
+	}
+
+	// Write output file
+	await mkdir( path.dirname( outputPath ), { recursive: true } );
+	await writeFile( outputPath, content );
+}