@ui5/builder 3.0.0-alpha.9 → 3.0.0-beta.2

package/lib/lbt/utils/parseUtils.js

@@ -1,15 +1,13 @@
-"use strict";
 
-const espree = require("espree");
-const {Syntax, VisitorKeys} = espree;
+import {parse} from "espree";
 
 const hasOwn = Function.prototype.call.bind(Object.prototype.hasOwnProperty);
 
-function parseJS(code, userOptions = {}) {
+export function parseJS(code, userOptions = {}) {
 	// allowed options and their defaults
 	const options = {
 		comment: false,
-		ecmaVersion: 2021, // NOTE: Adopt JSModuleAnalyzer.js to allow new Syntax when upgrading to newer ECMA versions
+		ecmaVersion: 2022, // NOTE: Adopt JSModuleAnalyzer.js to allow new Syntax when upgrading to newer ECMA versions
 		range: false,
 		sourceType: "script",
 	};
@@ -22,11 +20,7 @@ function parseJS(code, userOptions = {}) {
 		options[name] = value;
 	}
 
-	return espree.parse(code, options);
+	return parse(code, options);
 }
 
-module.exports = {
-	parseJS,
-	Syntax,
-	VisitorKeys
-};
+export {Syntax, VisitorKeys} from "espree";

package/lib/processors/bootstrapHtmlTransformer.js

@@ -1,17 +1,25 @@
-const log = require("@ui5/logger").getLogger("builder:processors:bootstrapHtmlTransformer");
-const cheerio = require("cheerio");
+import logger from "@ui5/logger";
+const log = logger.getLogger("builder:processors:bootstrapHtmlTransformer");
+import cheerio from "cheerio";
+
+/**
+ * @module @ui5/builder/processors/bootstrapHtmlTransformer
+ */
 
 /**
  * Transforms the UI5 bootstrap of a HTML resource files.
  *
- * @module builder/processors/bootstrapHtmlTransformer
+ * @public
+ * @function default
+ * @static
+ *
  * @param {object} parameters Parameters
- * @param {module:@ui5/fs.Resource[]} parameters.resources List of resources to be processed
+ * @param {@ui5/fs/Resource[]} parameters.resources List of resources to be processed
  * @param {object} parameters.options Options
  * @param {string} parameters.options.src Bootstrap "src" that should be used
- * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with the cloned resources
+ * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving with the cloned resources
  */
-module.exports = function({resources, options: {src}}) {
+export default function({resources, options: {src}}) {
 	async function processResource(resource) {
 		const content = await resource.getString();
 		const $ = cheerio.load(content);
@@ -30,4 +38,4 @@ module.exports = function({resources, options: {src}}) {
 	}
 
 	return Promise.all(resources.map(processResource));
-};
+}

package/lib/processors/bundlers/flexChangesBundler.js

@@ -1,20 +1,28 @@
-const log = require("@ui5/logger").getLogger("builder:processors:bundlers:flexChangesBundler");
-const resourceFactory = require("@ui5/fs").resourceFactory;
+import logger from "@ui5/logger";
+const log = logger.getLogger("builder:processors:bundlers:flexChangesBundler");
+import {createResource} from "@ui5/fs/resourceFactory";
+
+/**
+ * @public
+ * @module @ui5/builder/processors/bundlers/flexChangesBundler
+ */
 
 /**
  * Bundles all supplied changes.
  *
  * @public
- * @alias module:@ui5/builder.processors.flexChangesBundler
+ * @function default
+ * @static
+ *
  * @param {object} parameters Parameters
- * @param {module:@ui5/fs.Resource[]} parameters.resources List of resources to be processed
+ * @param {@ui5/fs/Resource[]} parameters.resources List of resources to be processed
  * @param {object} parameters.options Options
  * @param {string} parameters.options.pathPrefix Prefix for bundle path
  * @param {string} parameters.options.hasFlexBundleVersion true if minUI5Version >= 1.73 than
  *															create flexibility-bundle.json
- * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with flex changes bundle resources
+ * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving with flex changes bundle resources
  */
-module.exports = function({resources, options: {pathPrefix, hasFlexBundleVersion}}) {
+export default function({resources, options: {pathPrefix, hasFlexBundleVersion}}) {
 	let bundleName = "changes-bundle.json";
 
 	function sortByTimeStamp(a, b) {
@@ -101,11 +109,11 @@ module.exports = function({resources, options: {pathPrefix, hasFlexBundleVersion
 		const result = [];
 		if (nNumberOfChanges > 0) {
 			changesContent = sortAndStringifyInFlexFormat(changesContent);
-			result.push(resourceFactory.createResource({
+			result.push(createResource({
 				path: `${pathPrefix}/changes/${bundleName}`,
 				string: changesContent
 			}));
 		}
 		return result;
 	});
-};
+}

package/lib/processors/bundlers/moduleBundler.js

@@ -1,7 +1,13 @@
-const BundleBuilder = require("../../lbt/bundle/Builder");
-const LocatorResourcePool = require("../../lbt/resources/LocatorResourcePool");
-const EvoResource = require("@ui5/fs").Resource;
-const log = require("@ui5/logger").getLogger("builder:processors:bundlers:moduleBundler");
+import BundleBuilder from "../../lbt/bundle/Builder.js";
+import LocatorResourcePool from "../../lbt/resources/LocatorResourcePool.js";
+import EvoResource from "@ui5/fs/Resource";
+import logger from "@ui5/logger";
+const log = logger.getLogger("builder:processors:bundlers:moduleBundler");
+
+/**
+ * @public
+ * @module @ui5/builder/processors/bundlers/moduleBundler
+ */
 
 /**
  * A ModuleBundleDefinitionSection specifies the embedding mode (either 'provided', 'raw', 'preload', 'require'
@@ -80,7 +86,7 @@ const log = require("@ui5/logger").getLogger("builder:processors:bundlers:module
  * @property {string} name The module bundle name
  * @property {string[]} [defaultFileTypes=[".js", ".control.xml", ".fragment.html", ".fragment.json", ".fragment.xml", ".view.html", ".view.json", ".view.xml"]]
  *   List of default file types to be included in the bundle
- * @property {ModuleBundleDefinitionSection[]} sections List of module bundle definition sections.
+ * @property {module:@ui5/builder/processors/bundlers/moduleBundler~ModuleBundleDefinitionSection[]} sections List of module bundle definition sections.
  */
 /* eslint-enable max-len */
 
@@ -106,27 +112,32 @@ const log = require("@ui5/logger").getLogger("builder:processors:bundlers:module
  *
  * @public
  * @typedef {object} ModuleBundlerResult
- * @property {module:@ui5/fs.Resource} bundle Bundle resource
- * @property {module:@ui5/fs.Resource} sourceMap Source Map
- * @memberof module:@ui5/builder.processors
+ * @property {@ui5/fs/Resource} bundle Bundle resource
+ * @property {@ui5/fs/Resource} sourceMap Source Map
  */
 
+/* eslint-disable max-len */
 /**
  * Legacy module bundler.
  *
  * @public
- * @alias module:@ui5/builder.processors.moduleBundler
+ * @function default
+ * @static
+ *
  * @param {object} parameters Parameters
- * @param {module:@ui5/fs.Resource[]} parameters.resources Resources
+ * @param {@ui5/fs/Resource[]} parameters.resources Resources
  * @param {object} parameters.options Options
  * @param {object} [parameters.options.moduleNameMapping]
  				Optional mapping of resource paths to module name in order to overwrite the default determination
- * @param {ModuleBundleDefinition} parameters.options.bundleDefinition Module bundle definition
- * @param {ModuleBundleOptions} [parameters.options.bundleOptions] Module bundle options
- * @returns {Promise<module:@ui5/builder.processors.ModuleBundlerResult[]>}
+ * @param {module:@ui5/builder/processors/bundlers/moduleBundler~ModuleBundleDefinition} parameters.options.bundleDefinition Module
+				bundle definition
+ * @param {module:@ui5/builder/processors/bundlers/moduleBundler~ModuleBundleOptions} [parameters.options.bundleOptions] Module
+				bundle options
+ * @returns {Promise<module:@ui5/builder/processors/bundlers/moduleBundler~ModuleBundlerResult[]>}
  * Promise resolving with module bundle resources
  */
-module.exports = function({resources, options: {bundleDefinition, bundleOptions, moduleNameMapping}}) {
+/* eslint-enable max-len */
+export default function({resources, options: {bundleDefinition, bundleOptions, moduleNameMapping}}) {
 	// Apply defaults without modifying the passed object
 	bundleOptions = Object.assign({}, {
 		optimize: true,
@@ -177,4 +188,4 @@ module.exports = function({resources, options: {bundleDefinition, bundleOptions,
 				}
 			}));
 		});
-};
+}

package/lib/processors/jsdoc/apiIndexGenerator.js

@@ -1,14 +1,21 @@
-const resourceFactory = require("@ui5/fs").resourceFactory;
-const createIndex = require("./lib/createIndexFiles");
+import {createResource} from "@ui5/fs/resourceFactory";
+import createIndex from "./lib/createIndexFiles.cjs";
+
+/**
+ * @public
+ * @module @ui5/builder/processors/jsdoc/apiIndexGenerator
+ */
 
 /**
  * Compiles API index resources from all <code>api.json</code> resources available in the given test resources directory
- * as created by the [sdkTransformer]{@link module:@ui5/builder.processors.sdkTransformer} processor.
+ * as created by the [sdkTransformer]{@link @ui5/builder/processors/sdkTransformer} processor.
  * The resulting index resources (e.g. <code>api-index.json</code>,  <code>api-index-deprecated.json</code>,
  * <code>api-index-experimental.json</code> and <code>api-index-since.json</code>) are mainly to be used in the SDK.
  *
  * @public
- * @alias module:@ui5/builder.processors.apiIndexGenerator
+ * @function default
+ * @static
+ *
  * @param {object} parameters Parameters
  * @param {string} parameters.versionInfoPath Path to <code>sap-ui-version.json</code> resource
  * @param {string} parameters.testResourcesRootPath Path to <code>/test-resources</code> root directory in the
@@ -19,9 +26,9 @@ const createIndex = require("./lib/createIndexFiles");
  * @param {string} parameters.targetApiIndexExperimentalPath Path to create the generated API index "experimental" JSON
  *																resource for
  * @param {string} parameters.targetApiIndexSincePath Path to create the generated API index "since" JSON resource for
- * @param {fs|module:@ui5/fs.fsInterface} parameters.fs Node fs or
- * 				custom [fs interface]{@link module:resources/module:@ui5/fs.fsInterface} to use
- * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with created resources <code>api-index.json</code>,
+ * @param {fs|module:@ui5/fs/fsInterface} parameters.fs Node fs or
+ * 				custom [fs interface]{@link module:@ui5/fs/fsInterface} to use
+ * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving with created resources <code>api-index.json</code>,
  * <code>api-index-deprecated.json</code>, <code>api-index-experimental.json</code> and
  * <code>api-index-since.json</code> (names depend on the supplied paths)
  */
@@ -41,11 +48,11 @@ const apiIndexGenerator = async function({
 		});
 
 	return Object.keys(resourceMap).map((resPath) => {
-		return resourceFactory.createResource({
+		return createResource({
 			path: resPath,
 			string: resourceMap[resPath]
 		});
 	});
 };
 
-module.exports = apiIndexGenerator;
+export default apiIndexGenerator;

package/lib/processors/jsdoc/jsdocGenerator.js

@@ -1,15 +1,27 @@
-const spawn = require("child_process").spawn;
-const fs = require("graceful-fs");
-const path = require("path");
-const {promisify} = require("util");
+import {spawn} from "node:child_process";
+import fs from "graceful-fs";
+import path from "node:path";
+import {promisify} from "node:util";
 const writeFile = promisify(fs.writeFile);
-const {resourceFactory} = require("@ui5/fs");
+import {createAdapter} from "@ui5/fs/resourceFactory";
+import {createRequire} from "node:module";
+import {fileURLToPath} from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+/**
+ * @public
+ * @module @ui5/builder/processors/jsdoc/jsdocGenerator
+ */
 
 /**
  * JSDoc generator
  *
  * @public
- * @alias module:@ui5/builder.processors.jsdocGenerator
+ * @function default
+ * @static
+ *
  * @param {object} parameters Parameters
  * @param {string} parameters.sourcePath Path of the source files to be processed
  * @param {string} parameters.targetPath Path to write any output files
@@ -19,9 +31,9 @@ const {resourceFactory} = require("@ui5/fs");
  * @param {string} parameters.options.namespace Namespace to build (e.g. <code>some/project/name</code>)
  * @param {string} parameters.options.version Project version
  * @param {Array} [parameters.options.variants=["apijson"]] JSDoc variants to be built
- * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with newly created resources
+ * @returns {Promise<@ui5/fs/Resource[]>} Promise resolving with newly created resources
  */
-const jsdocGenerator = async function(
+export default async function jsdocGenerator(
 	{sourcePath, targetPath, tmpPath, options: {projectName, namespace, version, variants}} = {}
 ) {
 	if (!sourcePath || !targetPath || !tmpPath || !projectName || !namespace || !version) {
@@ -48,7 +60,7 @@ const jsdocGenerator = async function(
 		configPath
 	});
 
-	const fsTarget = resourceFactory.createAdapter({
+	const fsTarget = createAdapter({
 		fsBasePath: targetPath,
 		virBasePath: "/"
 	});
@@ -58,7 +70,7 @@ const jsdocGenerator = async function(
 		fsTarget.byPath(`/test-resources/${namespace}/designtime/api.json`)
 		// fsTarget.byPath(`/libraries/${options.projectName}.js`)
 	]).then((res) => res.filter(($)=>$));
-};
+}
 
 
 /**
@@ -82,8 +94,11 @@ async function generateJsdocConfig({targetPath, tmpPath, namespace, projectName,
 
 	// Resolve path to this script to get the path to the JSDoc extensions folder
 	const jsdocPath = path.normalize(__dirname);
-	const pluginPath = path.join(jsdocPath, "lib", "ui5", "plugin.js").replace(backslashRegex, "\\\\");
-	const templatePath = path.join(jsdocPath, "lib", "ui5", "template").replace(backslashRegex, "\\\\");
+	const pluginPath = path.join(jsdocPath, "lib", "ui5", "plugin.cjs").replace(backslashRegex, "\\\\");
+	// Using export via package.json to allow loading the CJS template.
+	// jsdoc appends /publish to the provided path but doesn't allow to
+	// add the .cjs extension, so loading won't work otherwise.
+	const templatePath = "@ui5/builder/internal/jsdoc/template";
 	const destinationPath = path.normalize(tmpPath).replace(backslashRegex, "\\\\");
 	const jsapiFilePath = path.join(targetPath, "libraries", projectName + ".js").replace(backslashRegex, "\\\\");
 	const apiJsonFolderPath = path.join(tmpPath, "dependency-apis").replace(backslashRegex, "\\\\");
@@ -155,21 +170,18 @@ async function buildJsdoc({sourcePath, configPath}) {
 		"--verbose",
 		sourcePath
 	];
-	return new Promise((resolve, reject) => {
+	const exitCode = await new Promise((resolve /* , reject */) => {
 		const child = spawn("node", args, {
-			stdio: ["ignore", "ignore", process.stderr]
-		});
-		child.on("close", function(code) {
-			if (code === 0 || code === 1) {
-				resolve();
-			} else {
-				reject(new Error(`JSDoc child process closed with code ${code}`));
-			}
+			stdio: ["ignore", "ignore", "inherit"]
 		});
+		child.on("close", resolve);
 	});
+
+	if (exitCode !== 0) {
+		throw new Error(`JSDoc reported an error, check the log for issues (exit code: ${exitCode})`);
+	}
 }
 
-module.exports = jsdocGenerator;
-module.exports._generateJsdocConfig = generateJsdocConfig;
-module.exports._writeJsdocConfig = writeJsdocConfig;
-module.exports._buildJsdoc = buildJsdoc;
+jsdocGenerator._generateJsdocConfig = generateJsdocConfig;
+jsdocGenerator._writeJsdocConfig = writeJsdocConfig;
+jsdocGenerator._buildJsdoc = buildJsdoc;

package/lib/processors/jsdoc/lib/{transformApiJson.js → transformApiJson.cjs}

@@ -25,6 +25,11 @@ const log = (function() {
 	}
 }());
 
+function replaceLastPathSegment(p, replacement) {
+	// Note: path.join also correctly normalizes any POSIX paths on Windows
+	return path.join(path.dirname(p), replacement);
+}
+
 /*
  * Transforms the api.json as created by the JSDoc build into a pre-processed api.json file suitable for the SDK.
  *
@@ -698,7 +703,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 							oMethod.returnValue.types.forEach(oType => {
 
 								// Link Enabled
-								if (!isBuiltInType(oType.value)) {
+								if (!isBuiltInType(oType.value) && possibleUI5Symbol(oType.value)) {
 									oType.href = "api/" + oType.value.replace("[]", "");
 									oType.linkEnabled = true;
 								}
@@ -981,6 +986,58 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 			// Normalize path to resolve relative path
 			sPath = path.normalize(sPath);
 
+			const {sources} = options;
+			let {librarySrcDir, libraryTestDir} = options;
+
+			if (Array.isArray(sources) && typeof librarySrcDir === "string" && typeof libraryTestDir === "string") {
+
+				// Using path.join to normalize POSIX paths to Windows paths on Windows
+				librarySrcDir = path.join(librarySrcDir);
+				libraryTestDir = path.join(libraryTestDir);
+
+				/**
+				 * Calculate prefix to check
+				 *
+				 * Example 1:
+				 * - sSource: /path/to/project/src
+				 * - sLibrarySrcDir: src
+				 *
+				 * Prefix: /path/to/project/test-resources
+				 *
+				 * Example 2:
+				 * - sSource: /path/to/project/src/main/js
+				 * - sLibrarySrcDir: src/main/js
+				 *
+				 * Prefix: /path/to/project/src/main/test-resources
+				 */
+				const librarySrcDirWithTestResources = replaceLastPathSegment(librarySrcDir, "test-resources");
+
+				for (const sourcePath of sources) {
+					/**
+					 * Replace prefix with file system path
+					 *
+					 * Example 1:
+					 * - sPath: /path/to/project/test-resources/sap/test/demokit/docuindex.json
+					 *
+					 * New sPath: /path/to/project/test/sap/test/demokit/docuindex.json
+					 *
+					 * Example 2:
+					 * - sPath: /path/to/project/src/main/test-resources/sap/test/demokit/docuindex.json
+					 *
+					 * New sPath: /path/to/project/src/main/test/sap/test/demokit/docuindex.json
+					 */
+					if (!sourcePath.endsWith(librarySrcDir)) {
+						continue;
+					}
+					const libraryDir = sourcePath.substring(0, sourcePath.lastIndexOf(librarySrcDir) - 1);
+					const prefix = path.join(libraryDir, librarySrcDirWithTestResources);
+					if (sPath.startsWith(prefix)) {
+						sPath = path.join(libraryDir, libraryTestDir, sPath.substring(prefix.length));
+						break;
+					}
+				}
+			}
+
 			fs.readFile(sPath, 'utf8', (oError, oFileData) => {
 				if (!oError) {
 					oFileData = JSON.parse(oFileData);
@@ -991,7 +1048,7 @@ function transformer(sInputFile, sOutputFile, sLibraryFile, vDependencyAPIFiles,
 						});
 					}
 				}
-				// We aways resolve as this data is not mandatory
+				// We always resolve as this data is not mandatory
 				oResolve(oChainObject);
 			});