diff --git a/packages/env/lib/build-docker-compose-config.js b/packages/env/lib/build-docker-compose-config.js index c95cd875ba4e2e..9390b747185e0e 100644 --- a/packages/env/lib/build-docker-compose-config.js +++ b/packages/env/lib/build-docker-compose-config.js @@ -6,14 +6,15 @@ const fs = require( 'fs' ); const path = require( 'path' ); /** - * @typedef {import('./config').Config} Config + * @typedef {import('./config').WPConfig} WPConfig */ /** * Creates a docker-compose config object which, when serialized into a * docker-compose.yml file, tells docker-compose how to run the environment. * - * @param {Config} config A wp-env config object. + * @param {WPConfig} config A wp-env config object. + * * @return {Object} A docker-compose config object, ready to serialize into YAML. */ module.exports = function buildDockerComposeConfig( config ) { diff --git a/packages/env/lib/commands/clean.js b/packages/env/lib/commands/clean.js index 1a24adca8cadbc..ac424323b899b3 100644 --- a/packages/env/lib/commands/clean.js +++ b/packages/env/lib/commands/clean.js @@ -4,13 +4,18 @@ const initConfig = require( '../init-config' ); const { configureWordPress, resetDatabase } = require( '../wordpress' ); +/** + * @typedef {import('../wordpress').WPEnvironment} WPEnvironment + * @typedef {import('../wordpress').WPEnvironmentSelection} WPEnvironmentSelection + */ + /** * Wipes the development server's database, the tests server's database, or both. * - * @param {Object} options - * @param {string} options.environment The environment to clean. Either 'development', 'tests', or 'all'. - * @param {Object} options.spinner A CLI spinner which indicates progress. - * @param {boolean} options.debug True if debug mode is enabled. + * @param {Object} options + * @param {WPEnvironmentSelection} options.environment The environment to clean. Either 'development', 'tests', or 'all'. + * @param {Object} options.spinner A CLI spinner which indicates progress. + * @param {boolean} options.debug True if debug mode is enabled. */ module.exports = async function clean( { environment, spinner, debug } ) { const config = await initConfig( { spinner, debug } ); diff --git a/packages/env/lib/config.js b/packages/env/lib/config.js index 31e0d4bbb37156..fffc4316e1bede 100644 --- a/packages/env/lib/config.js +++ b/packages/env/lib/config.js @@ -27,14 +27,14 @@ const HOME_PATH_PREFIX = `~${ path.sep }`; /** * A wp-env config object. * - * @typedef Config + * @typedef WPConfig * @property {string} name Name of the environment. * @property {string} configDirectoryPath Path to the .wp-env.json file. * @property {string} workDirectoryPath Path to the work directory located in ~/.wp-env. * @property {string} dockerComposeConfigPath Path to the docker-compose.yml file. - * @property {Source|null} coreSource The WordPress installation to load in the environment. - * @property {Source[]} pluginSources Plugins to load in the environment. - * @property {Source[]} themeSources Themes to load in the environment. + * @property {?WPSource} coreSource The WordPress installation to load in the environment. + * @property {WPSource[]} pluginSources Plugins to load in the environment. + * @property {WPSource[]} themeSources Themes to load in the environment. * @property {number} port The port on which to start the development WordPress environment. * @property {number} testsPort The port on which to start the testing WordPress environment. * @property {Object} config Mapping of wp-config.php constants to their desired values. @@ -44,7 +44,7 @@ const HOME_PATH_PREFIX = `~${ path.sep }`; /** * A WordPress installation, plugin or theme to be loaded into the environment. * - * @typedef Source + * @typedef WPSource * @property {string} type The source type. Can be 'local' or 'git'. * @property {string} path The path to the WordPress installation, plugin or theme. * @property {string} basename Name that identifies the WordPress installation, plugin or theme. @@ -57,7 +57,8 @@ module.exports = { * Reads and parses the given .wp-env.json file into a wp-env config object. * * @param {string} configPath Path to the .wp-env.json file. - * @return {Config} A wp-env config object. + * + * @return {WPConfig} A wp-env config object. */ async readConfig( configPath ) { const configDirectoryPath = path.dirname( configPath ); @@ -224,11 +225,12 @@ module.exports = { /** * Parses a source string into a source object. * - * @param {string|null} sourceString The source string. See README.md for documentation on valid source string patterns. + * @param {?string} sourceString The source string. See README.md for documentation on valid source string patterns. * @param {Object} options * @param {boolean} options.hasTests Whether or not a `testsPath` is required. Only the 'core' source needs this. * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. - * @return {Source|null} A source object. + * + * @return {?WPSource} A source object. */ function parseSourceString( sourceString, { workDirectoryPath } ) { if ( sourceString === null ) { @@ -292,10 +294,11 @@ function parseSourceString( sourceString, { workDirectoryPath } ) { * Given a source object, returns a new source object with the testsPath * property set correctly. Only the 'core' source requires a testsPath. * - * @param {Source|null} source A source object. - * @param {Object} options - * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. - * @return {Source|null} A source object. + * @param {?WPSource} source A source object. + * @param {Object} options + * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env. + * + * @return {?WPSource} A source object. */ function includeTestsPath( source, { workDirectoryPath } ) { if ( source === null ) { diff --git a/packages/env/lib/download-source.js b/packages/env/lib/download-source.js index 0e594312f37273..1973c1a0a2636b 100644 --- a/packages/env/lib/download-source.js +++ b/packages/env/lib/download-source.js @@ -17,14 +17,14 @@ const rimraf = util.promisify( require( 'rimraf' ) ); const copyDir = util.promisify( require( 'copy-dir' ) ); /** - * @typedef {import('./config').Source} Source + * @typedef {import('./config').WPSource} WPSource */ /** * Downloads the given source if necessary. The specific action taken depends * on the source type. * - * @param {Source} source The source to download. + * @param {WPSource} source The source to download. * @param {Object} options * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source. * @param {Object} options.spinner A CLI spinner which indicates progress. @@ -42,7 +42,7 @@ module.exports = async function downloadSource( source, options ) { * Clones the git repository at `source.url` into `source.path`. If the * repository already exists, it is updated instead. * - * @param {Source} source The source to download. + * @param {WPSource} source The source to download. * @param {Object} options * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source. * @param {Object} options.spinner A CLI spinner which indicates progress. @@ -113,7 +113,7 @@ async function downloadGitSource( source, { onProgress, spinner, debug } ) { /** * Downloads and extracts the zip file at `source.url` into `source.path`. * - * @param {Source} source The source to download. + * @param {WPSource} source The source to download. * @param {Object} options * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source. * @param {Object} options.spinner A CLI spinner which indicates progress. diff --git a/packages/env/lib/init-config.js b/packages/env/lib/init-config.js index 6d417954428375..02f4f3ed5e6cd7 100644 --- a/packages/env/lib/init-config.js +++ b/packages/env/lib/init-config.js @@ -12,7 +12,7 @@ const { readConfig } = require( './config' ); const buildDockerComposeConfig = require( './build-docker-compose-config' ); /** - * @typedef {import('./config').Config} Config + * @typedef {import('./config').WPConfig} WPConfig */ /** @@ -20,10 +20,10 @@ const buildDockerComposeConfig = require( './build-docker-compose-config' ); * ./.wp-env.json, creates ~/.wp-env, and creates ~/.wp-env/docker-compose.yml. * * @param {Object} options - * @param {Object} options.spinner initConfigA CLI spinner which indicates progress. + * @param {Object} options.spinner A CLI spinner which indicates progress. * @param {boolean} options.debug True if debug mode is enabled. * - * @return {Config} The-env config object. + * @return {WPConfig} The-env config object. */ module.exports = async function initConfig( { spinner, debug } ) { const configPath = path.resolve( '.wp-env.json' ); diff --git a/packages/env/lib/wordpress.js b/packages/env/lib/wordpress.js index 48910b49d38cf1..c4eb24630cbec1 100644 --- a/packages/env/lib/wordpress.js +++ b/packages/env/lib/wordpress.js @@ -10,7 +10,9 @@ const util = require( 'util' ); const copyDir = util.promisify( require( 'copy-dir' ) ); /** - * @typedef {import('./config').Config} Config + * @typedef {import('./config').WPConfig} WPConfig + * @typedef {'development'|'tests'} WPEnvironment + * @typedef {'development'|'tests'|'all'} WPEnvironmentSelection */ /** @@ -25,8 +27,8 @@ const copyDir = util.promisify( require( 'copy-dir' ) ); * * See https://github.com/docker-library/wordpress/issues/436. * - * @param {string} environment The environment to check. Either 'development' or 'tests'. - * @param {Config} config The wp-env config object. + * @param {WPEnvironment} environment The environment to check. Either 'development' or 'tests'. + * @param {WPConfig} config The wp-env config object. */ async function makeContentDirectoriesWritable( environment, @@ -46,7 +48,7 @@ async function makeContentDirectoriesWritable( * Checks a WordPress database connection. An error is thrown if the test is * unsuccessful. * - * @param {Config} config The wp-env config object. + * @param {WPConfig} config The wp-env config object. */ async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) { await dockerCompose.run( 'cli', 'wp db check', { @@ -61,8 +63,8 @@ async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) { * activating all plugins, and activating the first theme. These steps are * performed sequentially so as to not overload the WordPress instance. * - * @param {string} environment The environment to configure. Either 'development' or 'tests'. - * @param {Config} config The wp-env config object. + * @param {WPEnvironment} environment The environment to configure. Either 'development' or 'tests'. + * @param {WPConfig} config The wp-env config object. */ async function configureWordPress( environment, config ) { const options = { @@ -126,8 +128,8 @@ async function configureWordPress( environment, config ) { /** * Resets the development server's database, the tests server's database, or both. * - * @param {string} environment The environment to clean. Either 'development', 'tests', or 'all'. - * @param {Config} config The wp-env config object. + * @param {WPEnvironmentSelection} environment The environment to clean. Either 'development', 'tests', or 'all'. + * @param {WPConfig} config The wp-env config object. */ async function resetDatabase( environment,