@wordpress/env 6.0.0 → 8.0.0

package/lib/config/parse-source-string.js

@@ -0,0 +1,164 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const path = require( 'path' );
+const os = require( 'os' );
+
+/**
+ * Internal dependencies
+ */
+const { ValidationError } = require( './validate-config' );
+
+/**
+ * A WordPress installation, plugin or theme to be loaded into the environment.
+ *
+ * @typedef WPSource
+ * @property {'local'|'git'|'zip'} type     The source type.
+ * @property {string}              path     The path to the WordPress installation, plugin or theme.
+ * @property {?string}             url      The URL to the source download if the source type is not local.
+ * @property {?string}             ref      The git ref for the source if the source type is 'git'.
+ * @property {string}              basename Name that identifies the WordPress installation, plugin or theme.
+ */
+
+/**
+ * The string at the beginning of a source path that points to a home-relative
+ * directory. Will be '~/' on unix environments and '~\' on Windows.
+ */
+const HOME_PATH_PREFIX = `~${ path.sep }`;
+
+/**
+ * Parses a source string into a source object.
+ *
+ * @param {?string} sourceString               The source string. See README.md for documentation on valid source string patterns.
+ * @param {Object}  options
+ * @param {string}  options.cacheDirectoryPath Path to the work directory located in ~/.wp-env.
+ *
+ * @return {?WPSource} A source object.
+ */
+function parseSourceString( sourceString, { cacheDirectoryPath } ) {
+	if ( sourceString === null ) {
+		return null;
+	}
+
+	if (
+		sourceString.startsWith( '.' ) ||
+		sourceString.startsWith( HOME_PATH_PREFIX ) ||
+		path.isAbsolute( sourceString )
+	) {
+		let sourcePath;
+		if ( sourceString.startsWith( HOME_PATH_PREFIX ) ) {
+			sourcePath = path.resolve(
+				os.homedir(),
+				sourceString.slice( HOME_PATH_PREFIX.length )
+			);
+		} else {
+			sourcePath = path.resolve( sourceString );
+		}
+		const basename = path.basename( sourcePath );
+		return {
+			type: 'local',
+			path: sourcePath,
+			basename,
+		};
+	}
+
+	const zipFields = sourceString.match(
+		/^https?:\/\/([^\s$.?#].[^\s]*)\.zip(\?.+)?$/
+	);
+
+	if ( zipFields ) {
+		const wpOrgFields = sourceString.match(
+			/^https?:\/\/downloads\.wordpress\.org\/(?:plugin|theme)\/([^\s\.]*)([^\s]*)?\.zip$/
+		);
+		const basename = wpOrgFields
+			? encodeURIComponent( wpOrgFields[ 1 ] )
+			: encodeURIComponent( path.basename( zipFields[ 1 ] ) );
+
+		return {
+			type: 'zip',
+			url: sourceString,
+			path: path.resolve( cacheDirectoryPath, basename ),
+			basename,
+		};
+	}
+
+	// SSH URLs (git)
+	const supportedProtocols = [ 'ssh:', 'git+ssh:' ];
+	try {
+		const sshUrl = new URL( sourceString );
+		if ( supportedProtocols.includes( sshUrl.protocol ) ) {
+			const pathElements = sshUrl.pathname
+				.split( '/' )
+				.filter( ( e ) => !! e );
+			const basename = pathElements
+				.slice( -1 )[ 0 ]
+				.replace( /\.git/, '' );
+			const workingPath = path.resolve(
+				cacheDirectoryPath,
+				...pathElements.slice( 0, -1 ),
+				basename
+			);
+			return {
+				type: 'git',
+				url: sshUrl.href.split( '#' )[ 0 ],
+				ref: sshUrl.hash.slice( 1 ) || undefined,
+				path: workingPath,
+				clonePath: workingPath,
+				basename,
+			};
+		}
+	} catch ( err ) {}
+
+	const gitHubFields = sourceString.match(
+		/^([^\/]+)\/([^#\/]+)(\/([^#]+))?(?:#(.+))?$/
+	);
+
+	if ( gitHubFields ) {
+		return {
+			type: 'git',
+			url: `https://github.com/${ gitHubFields[ 1 ] }/${ gitHubFields[ 2 ] }.git`,
+			ref: gitHubFields[ 5 ],
+			path: path.resolve(
+				cacheDirectoryPath,
+				gitHubFields[ 2 ],
+				gitHubFields[ 4 ] || '.'
+			),
+			clonePath: path.resolve( cacheDirectoryPath, gitHubFields[ 2 ] ),
+			basename: gitHubFields[ 4 ] || gitHubFields[ 2 ],
+		};
+	}
+
+	throw new ValidationError(
+		`Invalid or unrecognized source: "${ sourceString }".`
+	);
+}
+
+/**
+ * Given a source object, returns a new source object with the testsPath
+ * property set correctly. Only the 'core' source requires a testsPath.
+ *
+ * @param {?WPSource} source                     A source object.
+ * @param {Object}    options
+ * @param {string}    options.cacheDirectoryPath Path to the work directory located in ~/.wp-env.
+ *
+ * @return {?WPSource} A source object.
+ */
+function includeTestsPath( source, { cacheDirectoryPath } ) {
+	if ( source === null ) {
+		return null;
+	}
+
+	return {
+		...source,
+		testsPath: path.resolve(
+			cacheDirectoryPath,
+			'tests-' + path.basename( source.path )
+		),
+	};
+}
+
+module.exports = {
+	parseSourceString,
+	includeTestsPath,
+};

package/lib/config/post-process-config.js

@@ -0,0 +1,202 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const mergeConfigs = require( './merge-configs' );
+const addOrReplacePort = require( './add-or-replace-port' );
+const { ValidationError } = require( './validate-config' );
+
+/**
+ * @typedef {import('./parse-config').WPRootConfig} WPRootConfig
+ * @typedef {import('./parse-config').WPEnvironmentConfig} WPEnvironmentConfig
+ */
+
+/**
+ * Performs any additional post-processing on the config object.
+ *
+ * @param {WPEnvironmentConfig} config The config to process.
+ *
+ * @return {WPEnvironmentConfig} The config after post-processing.
+ */
+module.exports = function postProcessConfig( config ) {
+	// Make sure that we're operating on a config object that has
+	// complete environment configs for convenience.
+	config = mergeRootToEnvironments( config );
+
+	config = appendPortToWPConfigs( config );
+
+	validate( config );
+	return config;
+};
+
+/**
+ * Merges the root config and each environment together in order to make sure each environment has
+ * a full config object to work with internally. This makes it easier than having to try and
+ * resolve the full config options every time we want to use them for something.
+ *
+ * @param {WPEnvironmentConfig} config The config to process.
+ *
+ * @return {WPRootConfig} The config object with the root options merged together with the environment-specific options.
+ */
+function mergeRootToEnvironments( config ) {
+	// Some root-level options need to be handled early because they have a special
+	// cascade behavior that would break the normal merge. After merging we then
+	// delete them to avoid that breakage and add them back before we return.
+	const removedRootOptions = {};
+	if (
+		config.port !== undefined &&
+		config.env.development.port === undefined
+	) {
+		removedRootOptions.port = config.port;
+		config.env.development.port = config.port;
+		delete config.port;
+	}
+	if (
+		config.testsPort !== undefined &&
+		config.env.tests.port === undefined
+	) {
+		removedRootOptions.testsPort = config.testsPort;
+		config.env.tests.port = config.testsPort;
+		delete config.testsPort;
+	}
+	if ( config.lifecycleScripts !== undefined ) {
+		removedRootOptions.lifecycleScripts = config.lifecycleScripts;
+		delete config.lifecycleScripts;
+	}
+
+	// Merge the root config and the environment configs together so that
+	// we can ignore the root config and have full environment configs.
+	for ( const env in config.env ) {
+		config.env[ env ] = mergeConfigs(
+			deepCopyRootOptions( config ),
+			config.env[ env ]
+		);
+	}
+
+	// Set any root-level options we reset back.
+	for ( const option in removedRootOptions ) {
+		config[ option ] = removedRootOptions[ option ];
+	}
+
+	return config;
+}
+
+/**
+ * Appends the configured port to certain wp-config options.
+ *
+ * @param {WPRootConfig} config The config to process.
+ *
+ * @return {WPRootConfig} The config after post-processing.
+ */
+function appendPortToWPConfigs( config ) {
+	const options = [ 'WP_TESTS_DOMAIN', 'WP_SITEURL', 'WP_HOME' ];
+
+	// We are only interested in editing the config options for environment-specific configs.
+	// If we made this change to the root config it would cause problems since they would
+	// be mapped to all environments even though the ports will be different.
+	for ( const env in config.env ) {
+		// There's nothing to do without any wp-config options set.
+		if ( config.env[ env ].config === undefined ) {
+			continue;
+		}
+
+		if ( config.env[ env ].port === undefined ) {
+			continue;
+		}
+
+		// Make sure that the port is on the option if it's present.
+		for ( const option of options ) {
+			if ( config.env[ env ].config[ option ] === undefined ) {
+				continue;
+			}
+
+			config.env[ env ].config[ option ] = addOrReplacePort(
+				config.env[ env ].config[ option ],
+				config.env[ env ].port,
+				// Don't replace the port if one is already set on WP_HOME.
+				option !== 'WP_HOME'
+			);
+		}
+	}
+
+	return config;
+}
+
+/**
+ * Examines the config to make sure that none of the environments share the same port.
+ *
+ * @param {WPRootConfig} config The config to process.
+ */
+function validatePortUniqueness( config ) {
+	// We're going to build a map of the environments and their port
+	// so we can accomodate root-level config options more easily.
+	const environmentPorts = {};
+
+	// Add all of the environments to the map. This will
+	// overwrite any root-level options if necessary.
+	for ( const env in config.env ) {
+		if ( config.env[ env ].port === undefined ) {
+			throw new ValidationError(
+				`The "${ env }" environment has an invalid port.`
+			);
+		}
+
+		environmentPorts[ env ] = config.env[ env ].port;
+	}
+
+	// This search isn't very performant, but, we won't ever be
+	// checking more than a few entries so it doesn't matter.
+	for ( const env in environmentPorts ) {
+		for ( const check in environmentPorts ) {
+			if ( env === check ) {
+				continue;
+			}
+
+			if ( environmentPorts[ env ] === environmentPorts[ check ] ) {
+				throw new ValidationError(
+					`The "${ env }" and "${ check }" environments may not have the same port.`
+				);
+			}
+		}
+	}
+}
+
+/**
+ * Perform any validation that can only happen after post-processing has occurred.
+ *
+ * @param {WPRootConfig} config The config to validate.
+ */
+function validate( config ) {
+	validatePortUniqueness( config );
+}
+
+/**
+ * Creates a deep copy of the root options in the config object that we can use to avoid
+ * accidentally sharing object state between different environments.
+ *
+ * @param {WPRootConfig} config The root config object to copy.
+ *
+ * @return {WPRootConfig} A deep copy of the root config object.
+ */
+function deepCopyRootOptions( config ) {
+	// Create a shallow clone of the object first so we can operate on it safetly.
+	const rootConfig = Object.assign( {}, config );
+
+	// Since we're only dealing with the root options we don't want the environments.
+	delete rootConfig.env;
+
+	if ( rootConfig.config !== undefined ) {
+		rootConfig.config = Object.assign( {}, rootConfig.config );
+	}
+	if ( rootConfig.mappings !== undefined ) {
+		rootConfig.mappings = Object.assign( {}, rootConfig.mappings );
+	}
+	if ( rootConfig.pluginSources !== undefined ) {
+		rootConfig.pluginSources = [ ...rootConfig.pluginSources ];
+	}
+	if ( rootConfig.themeSources !== undefined ) {
+		rootConfig.themeSources = [ ...rootConfig.themeSources ];
+	}
+
+	return rootConfig;
+}

package/lib/config/read-raw-config-file.js

@@ -4,6 +4,7 @@
  */
 const fs = require( 'fs' ).promises;
 
+const path = require( 'path' );
 /**
  * Internal dependencies
  */
@@ -13,53 +14,26 @@ const { ValidationError } = require( './validate-config' );
  * Reads the config JSON from the filesystem and returns it as a JS object
  * compatible with the env package.
  *
- * @param {string} name       The name of the file for error messages.
  * @param {string} configPath The path to the JSON file to read.
  *
  * @return {Object} the raw config data.
  */
-module.exports = async function readRawConfigFile( name, configPath ) {
+module.exports = async function readRawConfigFile( configPath ) {
 	try {
-		return withBackCompat(
-			JSON.parse( await fs.readFile( configPath, 'utf8' ) )
-		);
+		return JSON.parse( await fs.readFile( configPath, 'utf8' ) );
 	} catch ( error ) {
+		const fileName = path.basename( configPath );
+
 		if ( error.code === 'ENOENT' ) {
 			return null;
 		} else if ( error instanceof SyntaxError ) {
 			throw new ValidationError(
-				`Invalid ${ name }: ${ error.message }`
+				`Invalid ${ fileName }: ${ error.message }`
 			);
 		} else {
 			throw new ValidationError(
-				`Could not read ${ name }: ${ error.message }`
+				`Could not read ${ fileName }: ${ error.message }`
 			);
 		}
 	}
 };
-
-/**
- * Used to maintain back compatibility with older versions of the .wp-env.json
- * file. Returns an object in the shape of the currently expected .wp-env.json
- * version.
- *
- * @param {Object} rawConfig config right after being read from a file.
- * @return {Object} Same config with any old-format values converted into the
- *                  shape of the currently expected format.
- */
-function withBackCompat( rawConfig ) {
-	// Convert testsPort into new env.tests format.
-	if ( rawConfig.testsPort !== undefined ) {
-		rawConfig.env = {
-			...( rawConfig.env || {} ),
-			tests: {
-				port: rawConfig.testsPort,
-				...( rawConfig.env && rawConfig.env.tests
-					? rawConfig.env.tests
-					: {} ),
-			},
-		};
-	}
-	delete rawConfig.testsPort;
-	return rawConfig;
-}