umberto 4.3.0 → 4.4.0-alpha.1

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 Changelog
 =========
 
+## [4.4.0-alpha.1](https://github.com/cksource/umberto/compare/v4.4.0-alpha.0...v4.4.0-alpha.1) (2024-09-24)
+
+Internal changes only (updated dependencies, documentation, etc.).
+
+
+## [4.4.0-alpha.0](https://github.com/cksource/umberto/compare/v4.3.0...v4.4.0-alpha.0) (2024-09-20)
+
+### Features
+
+* Added support for loading hooks (`beforeHexo` and `afterHexo`) and `scripts` in ESM format in Umberto. Closes [#1214](https://github.com/cksource/umberto/issues/1214). ([commit](https://github.com/cksource/umberto/commit/2849bef1e59108f863ea0a64314ab980a7f543b6))
+
+
 ## [4.3.0](https://github.com/cksource/umberto/compare/v4.2.6...v4.3.0) (2024-09-16)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "4.3.0",
+  "version": "4.4.0-alpha.1",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -17,7 +17,7 @@
     "@babel/core": "^7.18.10",
     "@babel/polyfill": "^7.12.1",
     "@babel/preset-env": "^7.18.10",
-    "@ckeditor/jsdoc-plugins": "^32.0.1",
+    "@ckeditor/jsdoc-plugins": "^43.0.0",
     "babel-loader": "^8.2.5",
     "chalk": "^4.1.0",
     "cheerio": "^1.0.0",
@@ -25,7 +25,7 @@
     "del": "^6.1.1",
     "element-closest": "^3.0.2",
     "escape-string-regexp": "^4.0.0",
-    "fs-extra": "^10.1.0",
+    "fs-extra": "^11.0.0",
     "fuse.js": "^6.6.2",
     "glob": "^7.2.3",
     "hexo": "^6.2.0",
@@ -54,7 +54,7 @@
     "tree-model": "^1.0.7",
     "upath": "^2.0.1",
     "vnu-jar": "^21.10.12",
-    "webpack": "^5.74.0"
+    "webpack": "^5.94.0"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -68,7 +68,7 @@
     "url": "https://github.com/cksource/umberto.git"
   },
   "lint-staged": {
-    "**/*.js": [
+    "**/*.{js,mjs,cjs}": [
       "eslint --quiet"
     ]
   },

package/scripts/utils/execute-and-insert-function-results.js

@@ -9,7 +9,7 @@ const upath = require( 'upath' );
 const fs = require( 'fs' );
 
 const EXEC_REGEXP = /\\?{@exec ([^}]+)\\?}/g;
-const PATH_REGEXP = /[\w.\\/-]+\.js$/;
+const PATH_REGEXP = /[\w.\\/-]+\.c?js$/;
 
 /**
  * Replaces the `{@exec path/to/function.js}` expression with the module results.

package/src/helpers/import-module.js

@@ -0,0 +1,31 @@
+/**
+ * @license Copyright (c) 2017-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const upath = require( 'upath' );
+const { pathToFileURL } = require( 'url' );
+
+/**
+ * Loads the specified module using `import()` call.
+ *
+ * @param {String} modulePath
+ * @returns {Promise.<Function>}
+ */
+module.exports = async function importModule( modulePath ) {
+	const modulePathAsFileURL = getPathAsFileURL( modulePath );
+
+	return ( await import( modulePathAsFileURL ) ).default;
+};
+
+function getPathAsFileURL( modulePath ) {
+	const extension = upath.extname( modulePath );
+
+	if ( extension === '.js' || extension === '.mjs' || extension === '.cjs' ) {
+		return pathToFileURL( modulePath );
+	}
+
+	return pathToFileURL( modulePath + '.js' );
+}

package/src/index.js

@@ -47,25 +47,27 @@ module.exports = {
 	 * @returns {Promise}
 	 */
 	buildSingleProject( options ) {
-		const pConfig = getProjectConfig( process.cwd(), options );
 		const timer = process.hrtime();
 
-		return buildDocumentation( Object.assign(
-			options,
-			{
-				mainConfig: {
-					projects: [ '.' ],
-					docsearch: pConfig.docsearch,
-					googleoptimize: pConfig.googleoptimize,
-					googletagmanager: pConfig.googletagmanager,
-					googleanalytics: pConfig.googleanalytics,
-					feedbackWidget: pConfig.feedbackWidget,
-					isSingleProject: true,
-					canonicalUrlBeginning: pConfig.canonicalUrlBeginning,
-					vwo: pConfig.vwo
-				}
-			}
-		) )
+		return getProjectConfig( process.cwd(), options )
+			.then( pConfig => {
+				return buildDocumentation( Object.assign(
+					options,
+					{
+						mainConfig: {
+							projects: [ '.' ],
+							docsearch: pConfig.docsearch,
+							googleoptimize: pConfig.googleoptimize,
+							googletagmanager: pConfig.googletagmanager,
+							googleanalytics: pConfig.googleanalytics,
+							feedbackWidget: pConfig.feedbackWidget,
+							isSingleProject: true,
+							canonicalUrlBeginning: pConfig.canonicalUrlBeginning,
+							vwo: pConfig.vwo
+						}
+					}
+				) );
+			} )
 			.then( hexoManager => postBuild( options, hexoManager ) )
 			.then( hexoManager => {
 				const time = process.hrtime( timer );

package/src/tasks/build-documentation.js

@@ -127,7 +127,11 @@ module.exports = options => {
 				variables: mainConfig.variables
 			} );
 		} )
-		.then( () => executeHooks( getProjectConfigs( rootPath, projectPaths ), 'beforeHexo' ) )
+		.then( async () => {
+			const configs = await getProjectConfigs( rootPath, projectPaths );
+
+			return executeHooks( configs, 'beforeHexo' );
+		} )
 		.then( () => {
 			return buildProjects( rootPath, projectPaths, {
 				skipApi,
@@ -155,12 +159,12 @@ module.exports = options => {
 		.then( () => copyProjectIcons( hexoManager.hexo.projectGlobals, hexoManager.getPublicDir() ) )
 		// A workaround for API guides when API generation is skipped.
 		// Used for a local build (dev==true) to reuse existing API doc files.
-		.then( () => {
+		.then( async () => {
 			if ( !dev ) {
 				return Promise.resolve();
 			}
 
-			const projectConfigs = getProjectConfigs( rootPath, projectPaths, {
+			const projectConfigs = await getProjectConfigs( rootPath, projectPaths, {
 				skipLiveSnippets
 			} );
 			const buildDir = hexoManager.getPublicDir();
@@ -192,8 +196,8 @@ module.exports = options => {
 			return Promise.resolve();
 		} )
 		// Links validation.
-		.then( () => {
-			const projectConfigs = getProjectConfigs( rootPath, projectPaths, {
+		.then( async () => {
+			const projectConfigs = await getProjectConfigs( rootPath, projectPaths, {
 				skipLiveSnippets
 			} );
 
@@ -219,10 +223,10 @@ module.exports = options => {
 			} );
 		} )
 		// Create sitemap.xml file.
-		.then( () => {
+		.then( async () => {
 			let hostname;
 			let dst = '';
-			const projectConfigs = getProjectConfigs( rootPath, projectPaths );
+			const projectConfigs = await getProjectConfigs( rootPath, projectPaths );
 			const config = mainConfig.isSingleProject && projectConfigs && projectConfigs.length > 0 ?
 				projectConfigs[ 0 ] : {};
 			const sitemapConfig = mainConfig.sitemap ? mainConfig.sitemap : config.sitemap;
@@ -275,7 +279,12 @@ module.exports = options => {
 				extraUrlSettings
 			} );
 		} )
-		.then( () => executeHooks( getProjectConfigs( rootPath, projectPaths ), 'afterHexo' ) )
+
+		.then( async () => {
+			const configs = await getProjectConfigs( rootPath, projectPaths );
+
+			return executeHooks( configs, 'afterHexo' );
+		} )
 		.then( () => hexoManager );
 };
 
@@ -291,8 +300,8 @@ module.exports = options => {
  * @param {Boolean} options.skipGuides Whether to skip processing guides.
  * @return {Promise}
  */
-function buildProjects( rootPath, projectPaths, options = {} ) {
-	const projectConfigs = getProjectConfigs( rootPath, projectPaths, options );
+async function buildProjects( rootPath, projectPaths, options = {} ) {
+	const projectConfigs = await getProjectConfigs( rootPath, projectPaths, options );
 	const promises = [];
 
 	// If the `guides` (non-empty array) or `skipGuides` options are specified, disable the `{@link...}` validator.
@@ -416,19 +425,22 @@ function buildProjects( rootPath, projectPaths, options = {} ) {
 }
 
 // Gets every project's umberto.json config file.
-function getProjectConfigs( rootPath, projectPaths, options = {} ) {
-	return projectPaths.map( pPath => {
+async function getProjectConfigs( rootPath, projectPaths, options = {} ) {
+	const promises = projectPaths.map( async pPath => {
 		const projectRootPath = upath.join( rootPath, pPath );
 
 		return Object.assign(
-			getProjectConfig( projectRootPath, {
-				skipLiveSnippets: options.skipLiveSnippets
-			} ),
+			{},
 			{
+				...await getProjectConfig( projectRootPath, {
+					skipLiveSnippets: options.skipLiveSnippets
+				} ),
 				projectRootPath
 			}
 		);
 	} );
+
+	return Promise.all( promises );
 }
 
 // Renders API docs HTML. API docs are rendered separate from hexo so hexo filters and helpers are not available.

package/src/tasks/create-sym-links.js

@@ -11,19 +11,20 @@ const upath = require( 'upath' );
 const fs = require( 'fs' );
 const chalk = require( 'chalk' );
 
-module.exports = ( {
+module.exports = async ( {
 	rootPath,
 	isSingleProject = false
 } ) => {
 	const configs = [];
 
 	if ( isSingleProject ) {
-		configs.push( getProjectConfig( rootPath, { skipLiveSnippets: true } ) );
+		configs.push( await getProjectConfig( rootPath, { skipLiveSnippets: true } ) );
 	} else {
 		const projectPaths = getMainConfig( rootPath ).projects;
-		projectPaths.forEach( projectPath => {
-			configs.push( getProjectConfig( upath.join( rootPath, projectPath ), { skipLiveSnippets: true } ) );
+		const promises = projectPaths.map( projectPath => {
+			return getProjectConfig( upath.join( rootPath, projectPath ), { skipLiveSnippets: true } );
 		} );
+		configs.push( ...await Promise.all( promises ) );
 	}
 
 	configs
@@ -32,6 +33,8 @@ module.exports = ( {
 			createSymbolicLink( config );
 		} );
 
+	return Promise.resolve();
+
 	function createSymbolicLink( config ) {
 		const destinationPath = upath.join( rootPath, 'build', 'docs', config.slug, 'latest' );
 

package/src/tasks/execute-hooks.js

@@ -6,6 +6,7 @@
 'use strict';
 
 const upath = require( 'upath' );
+const importModule = require( '../helpers/import-module' );
 
 /**
  * This function executes all hooks of the specified type for each config passed in the configs array.
@@ -22,42 +23,47 @@ const upath = require( 'upath' );
  * }
  *
  * @param {Array} configs Array of all the configurations that might contain hooks to execute.
- * @param {String} hookName Name of a hook to execute, either 'beforeHexo' or 'afterHexo'.
+ * @param {'beforeHexo'|'afterHexo'} hookName Name of a hook to execute.
  * @returns {Promise}
  */
-module.exports = function executeHooks( configs, hookName ) {
-	let promise = Promise.resolve();
+module.exports = async function executeHooks( configs, hookName ) {
+	try {
+		for ( const config of configs ) {
+			if ( !config.hooks || !config.hooks[ hookName ] ) {
+				continue;
+			}
 
-	for ( const config of configs ) {
-		if ( !config.hooks || !config.hooks[ hookName ] ) {
-			continue;
+			for ( const scriptPath of config.hooks[ hookName ] ) {
+				await processSingleHook( upath.dirname( config.__configPath ), scriptPath );
+			}
 		}
 
-		for ( const scriptPath of config.hooks[ hookName ] ) {
-			const callbackAbsolutePath = upath.join( upath.dirname( config.__configPath ), scriptPath );
-
-			promise = promise
-				.then( () => {
-					// The `callback` may be synchronous function. Let's wrap it in the promise chain.
-					return new Promise( resolve => {
-						const callback = require( callbackAbsolutePath );
-
-						return resolve( callback() );
-					} ).catch( error => {
-						// Store a path to the executed file.
-						error._filePath = scriptPath;
-
-						// Rejecting the promise allows catching it later.
-						return Promise.reject( error );
-					} );
-				} );
-		}
-	}
-
-	return promise.catch( error => {
+		return Promise.resolve();
+	} catch ( error ) {
 		console.error( `The "${ hookName }" hook pointing to the "${ error._filePath }" file ended with an error.`, error.message );
 
 		// Re-throwing the error as we want to break the build process.
 		throw error;
-	} );
+	}
 };
+
+/**
+ * @param {String} configPath
+ * @param {String} scriptPath
+ * @return {Promise}
+ */
+async function processSingleHook( configPath, scriptPath ) {
+	const callbackAbsolutePath = upath.join( configPath, scriptPath );
+
+	try {
+		const callback = await importModule( callbackAbsolutePath );
+
+		await callback();
+	} catch ( error ) {
+		// Store a path to the executed file.
+		error._filePath = scriptPath;
+
+		// Rejecting the promise allows catching it later.
+		return Promise.reject( error );
+	}
+}

package/src/tasks/get-project-config.js

@@ -8,6 +8,7 @@
 const upath = require( 'upath' );
 const fs = require( 'fs' );
 const glob = require( 'glob' );
+const importModule = require( '../helpers/import-module' );
 
 const cache = new Map();
 
@@ -17,9 +18,9 @@ const cache = new Map();
  * @param {String} rootPath
  * @param {Object} [options={}]
  * @param {Boolean} [options.skipLiveSnippets=false] If set to `true`, the `snippetAdapter` module will not be added to the configuration.
- * @returns {Object}
+ * @returns {Promise}
  */
-module.exports = ( rootPath, options = {} ) => {
+module.exports = async ( rootPath, options = {} ) => {
 	// Let's normalize the root path to fix mixed slashes and backslashes. Root path should contain only slashes.
 	rootPath = rootPath.split( /[\\/]/g ).join( '/' );
 
@@ -35,7 +36,7 @@ module.exports = ( rootPath, options = {} ) => {
 
 	// Get the `realImportPath()` function. It displays an import path of a class below the class title.
 	// See: https://ckeditor.com/docs/ckeditor5/latest/api/module_editor-classic_classiceditor-ClassicEditor.html.
-	loadScriptToConfig( config, {
+	await loadScriptToConfig( config, {
 		scriptKey: 'import-path',
 		configKey: 'getRealImportPath',
 		configPath,
@@ -47,7 +48,7 @@ module.exports = ( rootPath, options = {} ) => {
 	} );
 
 	// Load the `insertChangelog()` script that allows inserting a changelog to a guide.
-	loadScriptToConfig( config, {
+	await loadScriptToConfig( config, {
 		scriptKey: 'insert-changelog',
 		configKey: 'insertChangelog',
 		configPath,
@@ -58,7 +59,7 @@ module.exports = ( rootPath, options = {} ) => {
 
 	// Load the snippet adapter only if snippets will be built.
 	if ( !options.skipLiveSnippets ) {
-		loadScriptToConfig( config, {
+		await loadScriptToConfig( config, {
 			scriptKey: 'snippet-adapter',
 			configKey: 'snippetAdapter',
 			configPath,
@@ -146,7 +147,7 @@ function getConfigurationFile( configPath ) {
  * @param {String} options.configPath An absolute path to the configuration file. It is used to obtain a path of the function to load.
  * @param {Function} options.onError A callback will be executed if the function could not be load.
  */
-function loadScriptToConfig( config, options ) {
+async function loadScriptToConfig( config, options ) {
 	if ( !config.scripts ) {
 		return;
 	}
@@ -160,13 +161,13 @@ function loadScriptToConfig( config, options ) {
 
 	try {
 		// Tries to load the function from the current working directory.
-		config[ configKey ] = require( config.scripts[ scriptKey ] );
+		config[ configKey ] = await importModule( config.scripts[ scriptKey ] );
 	} catch ( err ) {
 		// If failed, let's resolve the path from the directory where the configuration file is located.
 		const fnPath = upath.join( upath.dirname( options.configPath ), config.scripts[ scriptKey ] );
 
 		try {
-			config[ configKey ] = require( fnPath );
+			config[ configKey ] = await importModule( fnPath );
 		} catch ( nestedErr ) {
 			// If still fails, let's call the callback and throw an error.
 			options.onError( err );