@wordpress/env 6.0.0 → 8.0.0

package/lib/config/test/validate-config.js

@@ -0,0 +1,363 @@
+'use strict';
+/**
+ * Internal dependencies
+ */
+const {
+	ValidationError,
+	checkString,
+	checkPort,
+	checkStringArray,
+	checkObjectWithValues,
+	checkVersion,
+	checkValidURL,
+} = require( '../validate-config' );
+
+describe( 'validate-config', () => {
+	describe( 'checkString', () => {
+		it( 'throws when not a string', () => {
+			expect( () => checkString( 'test.json', 'test', 1234 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string.'
+				)
+			);
+		} );
+
+		it( 'passes for string', () => {
+			expect( () =>
+				checkString( 'test.json', 'test', 'test' )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkPort', () => {
+		it( 'throws when not a number', () => {
+			expect( () => checkPort( 'test.json', 'test', 'test' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an integer.'
+				)
+			);
+
+			expect( () =>
+				checkPort( 'test.json', 'test', { test: 'test' } )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an integer.'
+				)
+			);
+		} );
+
+		it( 'throws when port out of range', () => {
+			expect( () => checkPort( 'test.json', 'test', -1 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid port.'
+				)
+			);
+
+			expect( () => checkPort( 'test.json', 'test', 99999999 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid port.'
+				)
+			);
+		} );
+
+		it( 'passes for valid port', () => {
+			expect( () =>
+				checkPort( 'test.json', 'test', 8888 )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkStringArray', () => {
+		it( 'throws when not an array', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', 'test' )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array.'
+				)
+			);
+
+			expect( () =>
+				checkStringArray( 'test.json', 'test', { test: 'test' } )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array.'
+				)
+			);
+		} );
+
+		it( 'throws when array contains non-strings', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 12 ] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array of strings.'
+				)
+			);
+
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 'test', 12 ] )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an array of strings.'
+				)
+			);
+		} );
+
+		it( 'passes for string arrays', () => {
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [] )
+			).not.toThrow();
+			expect( () =>
+				checkStringArray( 'test.json', 'test', [ 'test' ] )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkObjectWithValues', () => {
+		it( 'throws when not an object', () => {
+			expect( () =>
+				checkObjectWithValues( 'test.json', 'test', 'test', [], false )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an object.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					[ 'test' ],
+					[],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be an object.'
+				)
+			);
+		} );
+
+		it( 'throws when no allowed types are given', () => {
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: .'
+				)
+			);
+		} );
+
+		it( 'throws when type is not allowed', () => {
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[ 'number' ],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: number.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 1 },
+					[ 'string' ],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: string.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: [ 'test' ] },
+					[ 'object', 'string' ],
+					false
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: object or string.'
+				)
+			);
+
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: null },
+					[ 'object' ],
+					true
+				)
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test.test" must be of type: object.'
+				)
+			);
+		} );
+
+		it( 'passes when type is allowed', () => {
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 'test' },
+					[ 'string' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: '' },
+					[ 'string' ],
+					true
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: 1 },
+					[ 'number' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: { nested: 'test' } },
+					[ 'object' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: [ 'test' ] },
+					[ 'array' ],
+					false
+				)
+			).not.toThrow();
+			expect( () =>
+				checkObjectWithValues(
+					'test.json',
+					'test',
+					{ test: null },
+					[ 'null' ],
+					false
+				)
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkVersion', () => {
+		it( 'throws for invalid input', () => {
+			expect( () => checkVersion( 'test.json', 'test', 'test' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string of the format "X", "X.X", or "X.X.X".'
+				)
+			);
+
+			expect( () => checkVersion( 'test.json', 'test', 123 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a string.'
+				)
+			);
+		} );
+
+		it( 'passes for different version formats', () => {
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1.1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '1.1.1' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '15.7.2' )
+			).not.toThrow();
+			expect( () =>
+				checkVersion( 'test.json', 'test', '26634543' )
+			).not.toThrow();
+		} );
+	} );
+
+	describe( 'checkValidURL', () => {
+		it( 'throws for invaid URLs', () => {
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'localhost' )
+			).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+
+			expect( () => checkValidURL( 'test.json', 'test', '' ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+
+			expect( () => checkValidURL( 'test.json', 'test', 123 ) ).toThrow(
+				new ValidationError(
+					'Invalid test.json: "test" must be a valid URL.'
+				)
+			);
+		} );
+
+		it( 'passes for valid URLs', () => {
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test.com' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'https://test.com' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL(
+					'test.json',
+					'test',
+					'http://test/test?test=test'
+				)
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'http://test.co.uk' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL( 'test.json', 'test', 'https://test.co.uk:8888' )
+			).not.toThrow();
+			expect( () =>
+				checkValidURL(
+					'test.json',
+					'test',
+					'http://test.co.uk:8888/test?test=test#test'
+				)
+			).not.toThrow();
+		} );
+	} );
+} );

package/lib/config/validate-config.js

@@ -1,8 +1,7 @@
 'use strict';
 
 /**
- * @typedef {import('./config').WPServiceConfig} WPServiceConfig
- * @typedef {import('./config').WPSource} WPSource
+ * @typedef {import('./parse-source-string').WPSource} WPSource
  */
 
 /**
@@ -12,105 +11,171 @@
 class ValidationError extends Error {}
 
 /**
- * Validates a config object by throwing a ValidationError if any of its properties
- * do not match the required format.
+ * Validates that the value is a string.
  *
- * @param {Object}  config      A config object to validate.
- * @param {?string} envLocation Identifies if the error occurred in a specific environment property.
- * @return {Object} The passed config object with no modifications.
+ * @param {string} configFile The configuration file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {number} value      The value to check.
  */
-function validateConfig( config, envLocation ) {
-	const envPrefix = envLocation ? `env.${ envLocation }.` : '';
-	if ( config.core !== null && typeof config.core !== 'string' ) {
+function checkString( configFile, configKey, value ) {
+	if ( typeof value !== 'string' ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }core" must be null or a string.`
+			`Invalid ${ configFile }: "${ configKey }" must be a string.`
 		);
 	}
+}
 
-	if (
-		! Array.isArray( config.plugins ) ||
-		config.plugins.some( ( plugin ) => typeof plugin !== 'string' )
-	) {
+/**
+ * Validates the port and throws if it isn't valid.
+ *
+ * @param {string} configFile The configuration file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {number} port       The port to check.
+ */
+function checkPort( configFile, configKey, port ) {
+	if ( ! Number.isInteger( port ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }plugins" must be an array of strings.`
+			`Invalid ${ configFile }: "${ configKey }" must be an integer.`
 		);
 	}
 
-	if (
-		! Array.isArray( config.themes ) ||
-		config.themes.some( ( theme ) => typeof theme !== 'string' )
-	) {
+	if ( port < 0 || port > 65535 ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }themes" must be an array of strings.`
+			`Invalid ${ configFile }: "${ configKey }" must be a valid port.`
 		);
 	}
+}
 
-	if ( ! Number.isInteger( config.port ) ) {
+/**
+ * Validates the array and throws if it isn't valid.
+ *
+ * @param {string}   configFile The config file we're validating.
+ * @param {string}   configKey  The configuration key we're validating.
+ * @param {string[]} array      The array that we're checking.
+ */
+function checkStringArray( configFile, configKey, array ) {
+	if ( ! Array.isArray( array ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }port" must be an integer.`
+			`Invalid ${ configFile }: "${ configKey }" must be an array.`
 		);
 	}
 
-	if ( typeof config.config !== 'object' ) {
+	if ( array.some( ( value ) => typeof value !== 'string' ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }config" must be an object.`
+			`Invalid ${ configFile }: "${ configKey }" must be an array of strings.`
 		);
 	}
+}
 
-	if ( typeof config.mappings !== 'object' ) {
+/**
+ * Validates the object and throws if it isn't valid.
+ *
+ * @param {string}   configFile The config file we're validating.
+ * @param {string}   configKey  The configuration key we're validating.
+ * @param {string[]} obj        The object that we're checking.
+ * @param {string[]} allowTypes The types that are allowed.
+ * @param {boolean}  allowEmpty Indicates whether or not empty values are allowed.
+ */
+function checkObjectWithValues(
+	configFile,
+	configKey,
+	obj,
+	allowTypes,
+	allowEmpty
+) {
+	if ( allowTypes === undefined ) {
+		allowTypes = [];
+	}
+
+	if ( typeof obj !== 'object' || Array.isArray( obj ) ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }mappings" must be an object.`
+			`Invalid ${ configFile }: "${ configKey }" must be an object.`
 		);
 	}
 
-	for ( const [ wpDir, localDir ] of Object.entries( config.mappings ) ) {
-		if ( ! localDir || typeof localDir !== 'string' ) {
+	for ( const key in obj ) {
+		// Some values need to be uniquely validated.
+		switch ( obj[ key ] ) {
+			case null:
+			case undefined: {
+				break;
+			}
+
+			default: {
+				if ( ! obj[ key ] && ! allowEmpty ) {
+					throw new ValidationError(
+						`Invalid ${ configFile }: "${ configKey }.${ key }" must not be empty.`
+					);
+				}
+			}
+		}
+
+		// Some types need to be uniquely identified.
+		let type;
+		if ( obj[ key ] === undefined ) {
+			type = 'undefined';
+		} else if ( obj[ key ] === null ) {
+			type = 'null';
+		} else if ( Array.isArray( obj[ key ] ) ) {
+			type = 'array';
+		} else {
+			type = typeof obj[ key ];
+		}
+
+		if ( ! allowTypes.includes( type ) ) {
 			throw new ValidationError(
-				`Invalid .wp-env.json: "${ envPrefix }mappings.${ wpDir }" should be a string.`
+				`Invalid ${ configFile }: "${ configKey }.${ key }" must be of type: ${ allowTypes.join(
+					' or '
+				) }.`
 			);
 		}
 	}
+}
 
-	if (
-		config.phpVersion &&
-		! (
-			typeof config.phpVersion === 'string' &&
-			config.phpVersion.length === 3
-		)
-	) {
+/**
+ * Validates the version and throws if it isn't valid.
+ *
+ * @param {string} configFile The config file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {string} version    The version that we're checking.
+ */
+function checkVersion( configFile, configKey, version ) {
+	if ( typeof version !== 'string' ) {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }phpVersion" must be a string of the format "0.0".`
+			`Invalid ${ configFile }: "${ configKey }" must be a string.`
 		);
 	}
 
-	checkValidURL( envPrefix, config.config, 'WP_SITEURL' );
-	checkValidURL( envPrefix, config.config, 'WP_HOME' );
-
-	return config;
+	if ( ! version.match( /[0-9]+(?:\.[0-9]+)*/ ) ) {
+		throw new ValidationError(
+			`Invalid ${ configFile }: "${ configKey }" must be a string of the format "X", "X.X", or "X.X.X".`
+		);
+	}
 }
 
 /**
- * Validates the input and throws if it isn't a valid URL.
+ * Validates the url and throws if it isn't valid.
  *
- * @param {string} envPrefix The environment we're validating.
- * @param {Object} config    The configuration object we're looking at.
- * @param {string} configKey The configuration key we're validating.
+ * @param {string} configFile The config file we're validating.
+ * @param {string} configKey  The configuration key we're validating.
+ * @param {string} url        The URL that we're checking.
  */
-function checkValidURL( envPrefix, config, configKey ) {
-	if ( config[ configKey ] === undefined ) {
-		return;
-	}
-
+function checkValidURL( configFile, configKey, url ) {
 	try {
-		new URL( config[ configKey ] );
+		new URL( url );
 	} catch {
 		throw new ValidationError(
-			`Invalid .wp-env.json: "${ envPrefix }config.${ configKey }" must be a valid URL.`
+			`Invalid ${ configFile }: "${ configKey }" must be a valid URL.`
 		);
 	}
 }
 
 module.exports = {
-	validateConfig,
 	ValidationError,
+	checkString,
+	checkPort,
+	checkStringArray,
+	checkObjectWithValues,
+	checkVersion,
+	checkValidURL,
 };

package/lib/env.js

@@ -3,9 +3,11 @@
  * Internal dependencies
  */
 const { ValidationError } = require( './config' );
+const { LifecycleScriptError } = require( './execute-lifecycle-script' );
 const commands = require( './commands' );
 
 module.exports = {
 	...commands,
 	ValidationError,
+	LifecycleScriptError,
 };

package/lib/execute-lifecycle-script.js

@@ -0,0 +1,86 @@
+'use strict';
+/**
+ * External dependencies
+ */
+const { exec } = require( 'child_process' );
+
+/**
+ * @typedef {import('./config').WPConfig} WPConfig
+ */
+
+/**
+ * Error subtype which indicates that the lifecycle script failed.
+ */
+class LifecycleScriptError extends Error {
+	constructor( event, stderr ) {
+		super( `${ event } Error:\n${ stderr }` );
+
+		this.event = event;
+	}
+}
+
+/**
+ * Executes any defined life cycle script.
+ *
+ * @param {string}   event   The lifecycle event to run the script for.
+ * @param {WPConfig} config  The config object to use.
+ * @param {Object}   spinner A CLI spinner which indciates progress.
+ *
+ * @return {Promise} Resolves when the script has completed and rejects when there is an error.
+ */
+function executeLifecycleScript( event, config, spinner ) {
+	if ( ! config.lifecycleScripts[ event ] ) {
+		return Promise.resolve();
+	}
+
+	return new Promise( ( resolve, reject ) => {
+		// We're going to append the script output to the spinner while it's executing.
+		const spinnerMessage = `Executing ${ event } Script`;
+		spinner.text = spinnerMessage;
+
+		// Execute the script asynchronously so that it won't block the spinner.
+		const childProc = exec( config.lifecycleScripts[ event ], {
+			encoding: 'utf-8',
+			stdio: 'pipe',
+			env: process.env,
+		} );
+
+		// Collect all of the output so that we can make use of it.
+		let output = '';
+		childProc.stdout.on( 'data', ( data ) => {
+			output += data;
+
+			// Keep the spinner updated with the command output.
+			spinner.text = `${ spinnerMessage }\n${ output }`;
+		} );
+
+		// Listen for any error output so we can display it if the command fails.
+		let error = '';
+		childProc.stderr.on( 'data', ( data ) => {
+			error += data;
+		} );
+
+		// Pass any process creation errors directly up.
+		childProc.on( 'error', reject );
+
+		// Handle the completion of the command based on whether it was successful or not.
+		childProc.on( 'exit', ( code ) => {
+			if ( code === 0 ) {
+				// Keep the output of the command in debug mode.
+				if ( config.debug ) {
+					spinner.info( `${ event } Script:\n${ output.trimEnd() }` );
+				}
+
+				resolve();
+				return;
+			}
+
+			reject( new LifecycleScriptError( event, error.trimEnd() ) );
+		} );
+	} );
+}
+
+module.exports = {
+	LifecycleScriptError,
+	executeLifecycleScript,
+};