Add generateApiIndex task

index.js

@@ -13,7 +13,9 @@ module.exports = {
 		flexChangesBundler: require("./lib/processors/bundlers/flexChangesBundler"),
 		manifestBundler: require("./lib/processors/bundlers/manifestBundler"),
 		moduleBundler: require("./lib/processors/bundlers/moduleBundler"),
+		apiIndexGenerator: require("./lib/processors/jsdoc/apiIndexGenerator"),
 		jsdocGenerator: require("./lib/processors/jsdoc/jsdocGenerator"),
+		sdkTransformer: require("./lib/processors/jsdoc/sdkTransformer"),
 		bootstrapHtmlTransformer: require("./lib/processors/bootstrapHtmlTransformer"),
 		debugFileCreator: require("./lib/processors/debugFileCreator"),
 		resourceCopier: require("./lib/processors/resourceCopier"),
@@ -36,8 +38,9 @@ module.exports = {
 		generateBundle: require("./lib/tasks/bundlers/generateBundle"),
 		buildThemes: require("./lib/tasks/buildThemes"),
 		createDebugFiles: require("./lib/tasks/createDebugFiles"),
-		generateJsdoc: require("./lib/tasks/jsdoc/generateJsdoc"),
 		executeJsdocSdkTransformation: require("./lib/tasks/jsdoc/executeJsdocSdkTransformation"),
+		generateApiIndex: require("./lib/tasks/jsdoc/generateApiIndex"),
+		generateJsdoc: require("./lib/tasks/jsdoc/generateJsdoc"),
 		generateVersionInfo: require("./lib/tasks/generateVersionInfo"),
 		replaceCopyright: require("./lib/tasks/replaceCopyright"),
 		replaceVersion: require("./lib/tasks/replaceVersion"),

lib/builder/builder.js

@@ -54,6 +54,7 @@ function composeTaskList({dev, selfContained, jsdoc, includedTasks, excludedTask
 	selectedTasks.transformBootstrapHtml = false;
 	selectedTasks.generateJsdoc = false;
 	selectedTasks.executeJsdocSdkTransformation = false;
+	selectedTasks.generateApiIndex = false;
 
 	if (selfContained) {
 		// No preloads, bundle only
@@ -67,6 +68,7 @@ function composeTaskList({dev, selfContained, jsdoc, includedTasks, excludedTask
 		// Include JSDoc tasks
 		selectedTasks.generateJsdoc = true;
 		selectedTasks.executeJsdocSdkTransformation = true;
+		selectedTasks.generateApiIndex = true;
 
 		// Exclude all tasks not relevant to JSDoc generation
 		selectedTasks.generateComponentPreload = false;
@@ -75,6 +77,8 @@ function composeTaskList({dev, selfContained, jsdoc, includedTasks, excludedTask
 		selectedTasks.buildThemes = false;
 		selectedTasks.createDebugFiles = false;
 		selectedTasks.uglify = false;
+		selectedTasks.generateFlexChangesBundle = false;
+		selectedTasks.generateManifestBundle = false;
 	}
 
 	// Only run essential tasks in development mode, it is not desired to run time consuming tasks during development.

lib/processors/jsdoc/apiIndexGenerator.js

@@ -0,0 +1,50 @@
+const resourceFactory = require("@ui5/fs").resourceFactory;
+const createIndex = require("./lib/create-api-index");
+
+/**
+ * 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.
+ * 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
+ * @param {Object} parameters Parameters
+ * @param {string} parameters.versionInfoFile Path to <code>sap-ui-version.json</code> resource
+ * @param {string} parameters.unpackedTestresourcesRoot Path to <code>/test-resources</code> root directory in the
+ *														given fs
+ * @param {string} parameters.targetFile Path to create the generated API index JSON resource for
+ * @param {string} parameters.targetFileDeprecated Path to create the generated API index "deprecated" JSON resource for
+ * @param {string} parameters.targetFileExperimental Path to create the generated API index "experimental" JSON
+ *														resource for
+ * @param {string} parameters.targetFileSince 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>,
+ * <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)
+ */
+const apiIndexGenerator = async function({
+	versionInfoFile, unpackedTestresourcesRoot, targetFile, targetFileDeprecated, targetFileExperimental,
+	targetFileSince, fs
+}) {
+	if (!versionInfoFile || !unpackedTestresourcesRoot || !targetFile || !targetFileDeprecated ||
+			!targetFileExperimental || !targetFileSince || !fs) {
+		throw new Error("[apiIndexGenerator]: One or more mandatory parameters not provided");
+	}
+
+	const resourceMap = await createIndex(versionInfoFile, unpackedTestresourcesRoot, targetFile,
+		targetFileDeprecated, targetFileExperimental, targetFileSince, {
+			fs,
+			returnOutputFiles: true
+		});
+
+	return Object.keys(resourceMap).map((resPath) => {
+		return resourceFactory.createResource({
+			path: resPath,
+			string: resourceMap[resPath]
+		});
+	});
+};
+
+module.exports = apiIndexGenerator;

lib/processors/jsdoc/lib/create-api-index.js

@@ -7,25 +7,41 @@
 
 "use strict";
 const path = require("path");
+const log = (function() {
+	try {
+		return require("@ui5/logger").getLogger("builder:processors:jsdoc:create-api-index");
+	} catch (error) {
+		/* eslint-disable no-console */
+		return {
+			info: function info(...msg) {
+				console.log("[INFO]", ...msg);
+			},
+			error: function error(...msg) {
+				console.error(...msg);
+			}
+		};
+		/* eslint-enable no-console */
+	}
+}());
 
 function process(versionInfoFile, unpackedTestresourcesRoot, targetFile, targetFileDeprecated, targetFileExperimental, targetFileSince, options) {
 	const fs = options && options.fs || require("fs");
 	const returnOutputFiles = options && !!options.returnOutputFiles;
 
-	console.log("[INFO] creating API index files");
-	console.log("[INFO]   sap-ui-version.json: " + versionInfoFile);
-	console.log("[INFO]   unpacked test-resources: " + unpackedTestresourcesRoot);
-	console.log("[INFO]   target file: " + targetFile);
-	console.log("[INFO]   target file deprecated: " + targetFileDeprecated);
-	console.log("[INFO]   target file experimental: " + targetFileExperimental);
-	console.log("[INFO]   target file since: " + targetFileSince);
+	log.info("creating API index files");
+	log.info("  sap-ui-version.json: " + versionInfoFile);
+	log.info("  unpacked test-resources: " + unpackedTestresourcesRoot);
+	log.info("  target file: " + targetFile);
+	log.info("  target file deprecated: " + targetFileDeprecated);
+	log.info("  target file experimental: " + targetFileExperimental);
+	log.info("  target file since: " + targetFileSince);
 	if (options && options.fs) {
-		console.log("[INFO] Using custom fs");
+		log.info("Using custom fs");
 	}
 	if (returnOutputFiles) {
-		console.log("[INFO] Returning output files instead of writing to fs.")
+		log.info("Returning output files instead of writing to fs.")
 	}
-	console.log("[INFO]");
+	log.info("");
 
 	// Deprecated, Experimental and Since collections
 	let oListCollection = {
@@ -422,7 +438,7 @@ function process(versionInfoFile, unpackedTestresourcesRoot, targetFile, targetF
 				}
 			})
 			.catch(err => {
-				console.error("**** failed to create API index for libraries:", err)
+				log.error("**** failed to create API index for libraries:", err)
 				throw err;
 			});
 

lib/processors/jsdoc/sdkTransformer.js

@@ -27,8 +27,8 @@ const sdkTransformer = async function({
 	}
 	const fakeTargetPath = "/ignore/this/path/resource/will/be/returned";
 	const apiJsonContent = await transformer(apiJsonPath, fakeTargetPath, dotLibraryPath, dependencyApiJsonPaths, {
-		customFs: fs,
-		returnOutputFile: true
+		fs,
+		returnOutputFiles: true
 	});
 	return [resourceFactory.createResource({
 		path: targetApiJsonPath,

lib/tasks/jsdoc/generateApiIndex.js

@@ -0,0 +1,49 @@
+const ui5Fs = require("@ui5/fs");
+const ReaderCollectionPrioritized = ui5Fs.ReaderCollectionPrioritized;
+const fsInterface = ui5Fs.fsInterface;
+const apiIndexGenerator = require("../../processors/jsdoc/apiIndexGenerator");
+
+/**
+ * Compiles an api-index.json resource from all available api.json resources as created by the
+ * [executeJsdocSdkTransformation]{@link module:@ui5/builder.tasks.executeJsdocSdkTransformation} task.
+ * The resulting api-index.json resource is mainly to be used in the SDK.
+ *
+ * @public
+ * @alias module:@ui5/builder.tasks.generateApiIndex
+ * @param {Object} parameters Parameters
+ * @param {module:@ui5/fs.DuplexCollection} parameters.workspace DuplexCollection to read and write files
+ * @param {module:@ui5/fs.AbstractReader} parameters.dependencies Reader or Collection to read dependency files
+ * @param {Object} parameters.options Options
+ * @param {string} parameters.options.projectName Project name
+ * @returns {Promise<undefined>} Promise resolving with <code>undefined</code> once data has been written
+ */
+module.exports = async function({workspace, dependencies, options}) {
+	if (!options || !options.projectName) {
+		throw new Error("[generateApiIndex]: One or more mandatory options not provided");
+	}
+	const combo = new ReaderCollectionPrioritized({
+		name: `generateApiIndex - workspace + dependencies: ${options.projectName}`,
+		readers: [workspace, dependencies]
+	});
+
+	const versionInfoFile = "/resources/sap-ui-version.json";
+	const unpackedTestresourcesRoot = "/test-resources";
+	const targetFile = "/docs/api/api-index.json";
+	const targetFileDeprecated = "/docs/api/api-index-deprecated.json";
+	const targetFileExperimental = "/docs/api/api-index-experimental.json";
+	const targetFileSince = "/docs/api/api-index-since.json";
+
+	const createdResources = await apiIndexGenerator({
+		versionInfoFile,
+		unpackedTestresourcesRoot,
+		targetFile,
+		targetFileDeprecated,
+		targetFileExperimental,
+		targetFileSince,
+		fs: fsInterface(combo),
+	});
+
+	await Promise.all(createdResources.map((resource) => {
+		return workspace.write(resource);
+	}));
+};

lib/tasks/taskRepository.js

@@ -2,8 +2,9 @@ const tasks = {
 	replaceCopyright: require("./replaceCopyright"),
 	replaceVersion: require("./replaceVersion"),
 	createDebugFiles: require("./createDebugFiles"),
-	generateJsdoc: require("./jsdoc/generateJsdoc"),
 	executeJsdocSdkTransformation: require("./jsdoc/executeJsdocSdkTransformation"),
+	generateApiIndex: require("./jsdoc/generateApiIndex"),
+	generateJsdoc: require("./jsdoc/generateJsdoc"),
 	uglify: require("./uglify"),
 	buildThemes: require("./buildThemes"),
 	transformBootstrapHtml: require("./transformBootstrapHtml"),

lib/types/application/ApplicationBuilder.js

@@ -13,7 +13,8 @@ const tasks = { // can't require index.js due to circular dependency
 	replaceCopyright: require("../../tasks/replaceCopyright"),
 	replaceVersion: require("../../tasks/replaceVersion"),
 	transformBootstrapHtml: require("../../tasks/transformBootstrapHtml"),
-	uglify: require("../../tasks/uglify")
+	uglify: require("../../tasks/uglify"),
+	generateApiIndex: require("../../tasks/jsdoc/generateApiIndex")
 };
 
 class ApplicationBuilder extends AbstractBuilder {
@@ -159,6 +160,16 @@ class ApplicationBuilder extends AbstractBuilder {
 				}
 			});
 		});
+
+		this.addTask("generateApiIndex", () => {
+			return tasks.generateApiIndex({
+				workspace: resourceCollections.workspace,
+				dependencies: resourceCollections.dependencies,
+				options: {
+					projectName: project.metadata.name
+				}
+			});
+		});
 	}
 }
 

test/lib/processors/jsdoc/sdkTransformer.js

@@ -41,8 +41,8 @@ test.serial("sdkTransformer", async (t) => {
 		"/some/path/y/api.json"
 	], "transform-apijson-for-sdk called with correct argument #4");
 	t.deepEqual(transformerStub.getCall(0).args[4], {
-		customFs: "custom fs",
-		returnOutputFile: true
+		fs: "custom fs",
+		returnOutputFiles: true
 	}, "transform-apijson-for-sdk called with correct argument #5");
 
 	t.deepEqual(createResourceStub.callCount, 1, "createResource called once");

test/lib/types/application/ApplicationBuilder.js

@@ -67,7 +67,8 @@ test("Instantiation", (t) => {
 		"generateBundle",
 		"createDebugFiles",
 		"uglify",
-		"generateVersionInfo"
+		"generateVersionInfo",
+		"generateApiIndex"
 	], "ApplicationBuilder is instantiated with standard tasks");
 });
 
@@ -87,7 +88,8 @@ test("Instantiation without component preload project configuration", (t) => {
 		"generateBundle",
 		"createDebugFiles",
 		"uglify",
-		"generateVersionInfo"
+		"generateVersionInfo",
+		"generateApiIndex"
 	], "ApplicationBuilder is still instantiated with standard tasks");
 });
 
@@ -107,7 +109,8 @@ test("Instantiation without project namespace", (t) => {
 		"generateBundle",
 		"createDebugFiles",
 		"uglify",
-		"generateVersionInfo"
+		"generateVersionInfo",
+		"generateApiIndex"
 	], "All standard tasks but generateComponentPreload will be executed");
 });
 
@@ -132,6 +135,7 @@ test("Instantiation with custom tasks", (t) => {
 		"createDebugFiles",
 		"uglify",
 		"replaceVersion--1",
-		"generateVersionInfo"
+		"generateVersionInfo",
+		"generateApiIndex"
 	], "ApplicationBuilder is still instantiated with standard tasks");
 });