From 73cd2b03066cf4ac5a9aa2e32d2c7cbf29fb9ad3 Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Wed, 27 Jul 2022 11:34:02 -0400 Subject: [PATCH] Add comments to build script (#15319) This is a follow-up to #15318, which fixed a problem with environment variables. Every function in this module that passes options related to environment variables has been updated with a doc comment. This should make it clearer which options are mandatory and which are optional, hopefully preventing a similar mistake from happening in the future. --- development/build/scripts.js | 191 +++++++++++++++++++++++++++++++++-- 1 file changed, 181 insertions(+), 10 deletions(-) diff --git a/development/build/scripts.js b/development/build/scripts.js index 75ef3f264..923ee7849 100644 --- a/development/build/scripts.js +++ b/development/build/scripts.js @@ -182,6 +182,31 @@ const noopWriteStream = through.obj((_file, _fileEncoding, callback) => module.exports = createScriptTasks; +/** + * Create tasks for building JavaScript bundles and templates. One + * task is returned for each build target. These build target tasks are + * each composed of smaller tasks. + * + * @param {object} options - Build options. + * @param {boolean} options.applyLavaMoat - Whether the build should use + * LavaMoat at runtime or not. + * @param {string[]} options.browserPlatforms - A list of browser platforms to + * build bundles for. + * @param {BuildType} options.buildType - The current build type (e.g. "main", + * "flask", etc.). + * @param {string[] | null} options.ignoredFiles - A list of files to exclude + * from the current build. + * @param {boolean} options.isLavaMoat - Whether this build script is being run + * using LavaMoat or not. + * @param {object} options.livereload - The "gulp-livereload" server instance. + * @param {boolean} options.policyOnly - Whether to stop the build after + * generating the LavaMoat policy, skipping any writes to disk other than the + * LavaMoat policy itself. + * @param {boolean} options.shouldLintFenceFiles - Whether files with code + * fences should be linted after fences have been removed. + * @param {string} options.version - The current version of the extension. + * @returns {object} A set of tasks, one for each build target. + */ function createScriptTasks({ applyLavaMoat, browserPlatforms, @@ -189,8 +214,8 @@ function createScriptTasks({ ignoredFiles, isLavaMoat, livereload, - shouldLintFenceFiles, policyOnly, + shouldLintFenceFiles, version, }) { // internal tasks @@ -219,6 +244,19 @@ function createScriptTasks({ const { dev, test, testDev, prod } = core; return { dev, test, testDev, prod }; + /** + * Define tasks for building the JavaScript modules used by the extension. + * This function returns a single task that builds JavaScript modules in + * parallel for a single type of build (e.g. dev, testing, production). + * + * @param {object} options - The build options. + * @param {string} options.taskPrefix - The prefix to use for the name of + * each defined task. + * @param {boolean} [options.devMode] - Whether the build is being used for + * development. + * @param {boolean} [options.testing] - Whether the build is intended for + * running end-to-end (e2e) tests. + */ function createTasksForScriptBundles({ taskPrefix, devMode = false, @@ -300,6 +338,16 @@ function createScriptTasks({ return composeParallel(initiateLiveReload, ...allSubtasks); } + /** + * Create a bundle for the "disable-console" module. + * + * @param {object} options - The build options. + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @returns {Function} A function that creates the bundle. + */ function createDisableConsoleBundle({ devMode, testing }) { const label = 'disable-console'; return createNormalBundle({ @@ -317,6 +365,16 @@ function createScriptTasks({ }); } + /** + * Create a bundle for the "sentry-install" module. + * + * @param {object} options - The build options. + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @returns {Function} A function that creates the bundle. + */ function createSentryBundle({ devMode, testing }) { const label = 'sentry-install'; return createNormalBundle({ @@ -334,7 +392,18 @@ function createScriptTasks({ }); } - // the "contentscript" bundle contains the "inpage" bundle + /** + * Create bundles for the "contentscript" and "inpage" modules. The inpage + * module is created first because it gets embedded in the contentscript + * module. + * + * @param {object} options - The build options. + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @returns {Function} A function that creates the bundles. + */ function createContentscriptBundle({ devMode, testing }) { const inpage = 'inpage'; const contentscript = 'contentscript'; @@ -393,18 +462,46 @@ const postProcessServiceWorker = ( }); }; -// Function generates app-init.js for browsers chrome, brave and opera. -// It dynamically injects list of files generated in the build. +/** + * Create the bundle for the app initialization module used in manifest v3 + * builds. + * + * This must be called after the "background" bundles have been created, so + * that the list of all background bundles can be injected into this bundle. + * + * @param {object} options - Build options. + * @param {boolean} options.applyLavaMoat - Whether the build should use + * LavaMoat at runtime or not. + * @param {string[]} options.browserPlatforms - A list of browser platforms to + * build bundles for. + * @param {BuildType} options.buildType - The current build type (e.g. "main", + * "flask", etc.). + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {string[] | null} options.ignoredFiles - A list of files to exclude + * from the current build. + * @param {string[]} options.jsBundles - A list of JavaScript bundles to be + * injected into this bundle. + * @param {boolean} options.policyOnly - Whether to stop the build after + * generating the LavaMoat policy, skipping any writes to disk other than the + * LavaMoat policy itself. + * @param {boolean} options.shouldLintFenceFiles - Whether files with code + * fences should be linted after fences have been removed. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @param {string} options.version - The current version of the extension. + * @returns {Function} A function that creates the set of bundles. + */ async function createManifestV3AppInitializationBundle({ - jsBundles, + applyLavaMoat, browserPlatforms, buildType, devMode, ignoredFiles, - testing, + jsBundles, policyOnly, shouldLintFenceFiles, - applyLavaMoat, + testing, version, }) { const label = 'app-init'; @@ -465,6 +562,39 @@ async function createManifestV3AppInitializationBundle({ console.log(`Bundle end: service worker app-init.js`); } +/** + * Return a function that creates a set of factored bundles. + * + * For each entry point, a series of one or more bundles is created. These are + * split up roughly by size, to ensure no single bundle exceeds the maximum + * JavaScript file size imposed by Firefox. + * + * Modules that are common between all entry points are bundled separately, as + * a set of one or more "common" bundles. + * + * @param {object} options - Build options. + * @param {boolean} options.applyLavaMoat - Whether the build should use + * LavaMoat at runtime or not. + * @param {string[]} options.browserPlatforms - A list of browser platforms to + * build bundles for. + * @param {BuildType} options.buildType - The current build type (e.g. "main", + * "flask", etc.). + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {string[]} options.entryFiles - A list of entry point file paths, + * relative to the repository root directory. + * @param {string[] | null} options.ignoredFiles - A list of files to exclude + * from the current build. + * @param {boolean} options.policyOnly - Whether to stop the build after + * generating the LavaMoat policy, skipping any writes to disk other than the + * LavaMoat policy itself. + * @param {boolean} options.shouldLintFenceFiles - Whether files with code + * fences should be linted after fences have been removed. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @param {string} options.version - The current version of the extension. + * @returns {Function} A function that creates the set of bundles. + */ function createFactoredBuild({ applyLavaMoat, browserPlatforms, @@ -629,15 +759,15 @@ function createFactoredBuild({ ...groupSet.values(), ].map((label) => `./${label}.js`); await createManifestV3AppInitializationBundle({ - jsBundles, + applyLavaMoat, browserPlatforms, buildType, devMode, ignoredFiles, - testing, + jsBundles, policyOnly, shouldLintFenceFiles, - applyLavaMoat, + testing, version, }); } @@ -666,6 +796,34 @@ function createFactoredBuild({ }; } +/** + * Return a function that creates a single JavaScript bundle. + * + * @param {object} options - Build options. + * @param {string[]} options.browserPlatforms - A list of browser platforms to + * build the bundle for. + * @param {BuildType} options.buildType - The current build type (e.g. "main", + * "flask", etc.). + * @param {string} options.destFilepath - The file path the bundle should be + * written to. + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {string[]} options.entryFilepath - The entry point file path, + * relative to the repository root directory. + * @param {string[] | null} options.ignoredFiles - A list of files to exclude + * from the current build. + * @param {string} options.label - A label used to describe this bundle in any + * diagnostic messages. + * @param {boolean} options.policyOnly - Whether to stop the build after + * generating the LavaMoat policy, skipping any writes to disk other than the + * LavaMoat policy itself. + * @param {boolean} options.shouldLintFenceFiles - Whether files with code + * fences should be linted after fences have been removed. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @param {string} options.version - The current version of the extension. + * @returns {Function} A function that creates the bundle. + */ function createNormalBundle({ browserPlatforms, buildType, @@ -939,6 +1097,19 @@ async function createBundle(buildConfiguration, { reloadOnChange }) { } } +/** + * Get environment variables to inject in the current build. + * + * @param {object} options - Build options. + * @param {BuildType} options.buildType - The current build type (e.g. "main", + * "flask", etc.). + * @param {boolean} options.devMode - Whether the build is being used for + * development. + * @param {boolean} options.testing - Whether the build is intended for + * running end-to-end (e2e) tests. + * @param {string} options.version - The current version of the extension. + * @returns {object} A map of environment variables to inject. + */ function getEnvironmentVariables({ buildType, devMode, testing, version }) { const environment = getEnvironment({ devMode, testing }); if (environment === ENVIRONMENT.PRODUCTION && !process.env.SENTRY_DSN) {