improve jsdoc and reuse types

add tests for versionInfoGenerator with new parameters
* libraryManifest
* embeddedManifests

Author: tobiasso85

lib/processors/versionInfoGenerator.js

@@ -19,7 +19,7 @@ function getTimestamp() {
 /**
  * Manifest libraries as defined in the manifest.json file
  *
- * @typedef {object<string, object>} ManifestLibraries
+ * @typedef {object<string, {lazy: boolean}>} ManifestLibraries
  *
  * sample:
  * <pre>
@@ -37,10 +37,10 @@ function getTimestamp() {
  *
  * @typedef {object} ManifestInfo
  *
- * @property {string} id The library name
- * @property {string} embeddedBy the library this component is embedded in
- * @property {string[]} embeds the embedded component names
- * @property {ManifestLibraries} libs the dependencies
+ * @property {string} id The library name, e.g. "lib.x"
+ * @property {string} embeddedBy the library this component is embedded in, e.g. "lib.x"
+ * @property {string[]} embeds the embedded component names, e.g. ["lib.x.sub"]
+ * @property {ManifestLibraries} libs the dependencies, e.g. {"sap.chart":{"lazy": true}, "sap.f":{}}
  */
 
 
@@ -85,6 +85,7 @@ const processManifest = async (manifestResource) => {
 };
 
 /**
+ * Checks if a component (componentPath) is bundled with the library (embeddedBy)
  *
  * @param {string} embeddedBy e.g. "../"
  * @param {string} componentPath e.g. "lib/x/sub"
@@ -126,7 +127,7 @@ const isBundledWithLibrary = (embeddedBy, componentPath, libraryPathPrefix) => {
 };
 
 /**
- * Retrieves the manifest path
+ * Retrieves the manifest path of a subcomponent
  *
  * @param {string} filePath path to the manifest, e.g. "lib/x/manifest.json"
  * @param {string} subPath relative sub path, e.g. "sub"
@@ -137,31 +138,37 @@ const getManifestPath = (filePath, subPath) => {
 	return posixPath.resolve(folderPathOfManifest + "/manifest.json");
 };
 
-
+/**
+ * Represents dependency information for a library.
+ * Dependencies can be resolved recursively using <code>#resolve</code>
+ * and are stored then in <code>libsResolved</code>
+ */
 class DependencyInfo {
 	/**
 	 *
-	 * @param {object} libs
-	 * @param {string} name
+	 * @param {ManifestLibraries} libs
+	 * @param {string} name library name, e.g. "lib.x"
 	 */
 	constructor(libs, name) {
 		this.libs = libs;
 		this.name = name;
 
 		/**
-		 * contains as key the lirbary name and as value the lazy property
+		 * contains as key the library name and as value an object with an optional lazy property
 		 *
-		 * @type {object}
+		 * @type {ManifestLibraries}
 		 */
 		this.libsResolved = Object.create(null);
 		this.wasResolved = false;
 	}
 
 	/**
+	 * Add library to libsResolved and if already present
+	 * merge lazy property
 	 *
-	 * @param {string} libName
+	 * @param {string} libName library name, e.g. "lib.x"
 	 * @param {boolean} lazy
-	 * @returns {{lazy: boolean}}
+	 * @returns {{lazy: boolean}} the added library
 	 */
 	addResolvedLibDependency(libName, lazy) {
 		let alreadyResolved = this.libsResolved[libName];
@@ -219,7 +226,7 @@ class DependencyInfo {
  * Sorts the keys of a given object
  *
  * @param {object} obj the object
- * @returns {{}}
+ * @returns {{}} the object with sorted keys
  */
 const sortObjectKeys = (obj) => {
 	const sortedObject = {};
@@ -232,9 +239,10 @@ const sortObjectKeys = (obj) => {
 };
 
 /**
+ * Builds the manifestHints object from the dependencyInfo
  *
  * @param {DependencyInfo} dependencyInfo
- * @returns {object} manifestHints
+ * @returns {{dependencies: {libs: ManifestLibraries}}} manifestHints
  */
 const getManifestHints = (dependencyInfo) => {
 	if (dependencyInfo && Object.keys(dependencyInfo.libsResolved).length) {
@@ -307,6 +315,13 @@ class ArtifactInfo {
 	}
 }
 
+/**
+ * Processes the manifest and creates a ManifestInfo and an ArtifactInfo.
+ *
+ * @param {module:@ui5/fs.Resource} libraryManifest
+ * @param {string} [name] library name, if not provided using the ManifestInfo's id
+ * @returns {Promise<{manifestInfo: ManifestInfo, libraryArtifactInfo: ArtifactInfo}>}
+ */
 async function processManifestAndGetArtifactInfo(libraryManifest, name) {
 	const manifestInfo = await processManifest(libraryManifest);
 	name = name || manifestInfo.id;
@@ -340,21 +355,23 @@ const processLibraryInfo = async (libraryInfo) => {
 		return getManifestPath(libraryInfo.libraryManifest.getPath(), embed);
 	});
 	// e.g. manifest resource with lib/x/sub/manifest.json
-	const relevantManifests = libraryInfo.manifestResources.filter((manifestResource) => {
+	let embeddedManifests = libraryInfo.embeddedManifests || [];
+	embeddedManifests = embeddedManifests.filter((manifestResource) => {
 		return embeddedPaths.includes(manifestResource.getPath());
 	});
 
 	// get all embedded manifests
-	const embeddedManifestPromises = relevantManifests.map(async (relevantManifest) => {
+	const embeddedManifestPromises = embeddedManifests.map(async (embeddedManifest) => {
 		const {manifestInfo: embeddedManifestInfo, libraryArtifactInfo: embeddedArtifactInfo} =
-			await processManifestAndGetArtifactInfo(relevantManifest);
+			await processManifestAndGetArtifactInfo(embeddedManifest);
 
 		const componentName = embeddedManifestInfo.id;
 
-		const fullManifestPath = posixPath.dirname(relevantManifest.getPath());
-		const libraryPathPrefix = posixPath.dirname(libraryInfo.libraryManifest.getPath());
+		const embeddedManifestDirName = posixPath.dirname(embeddedManifest.getPath());
+		const libraryManifestDirName = posixPath.dirname(libraryInfo.libraryManifest.getPath());
 
-		if (isBundledWithLibrary(embeddedManifestInfo.embeddedBy, fullManifestPath, libraryPathPrefix + "/")) {
+		if (isBundledWithLibrary(embeddedManifestInfo.embeddedBy, embeddedManifestDirName,
+			libraryManifestDirName + "/")) {
 			bundledComponents.add(componentName);
 		}
 		return embeddedArtifactInfo;
@@ -376,7 +393,7 @@ const processLibraryInfo = async (libraryInfo) => {
  * @property {string} version The library version, e.g. "1.0.0"
  * @property {module:@ui5/fs.Resource} libraryManifest library manifest resource,
  *  e.g. resource with path "lib/x/manifest.json"
- * @property {module:@ui5/fs.Resource[]} manifestResources list of embedded manifest resources,
+ * @property {module:@ui5/fs.Resource[]} embeddedManifests list of embedded manifest resources,
  *  e.g. resource with path "lib/x/sub/manifest.json"
  */
 
@@ -395,7 +412,7 @@ const processLibraryInfo = async (libraryInfo) => {
  *      name: "lib.x",
  *      version: "1.0.0",
  *      libraryManifest: module:@ui5/fs.Resource,
- *      manifestResources: module:@ui5/fs.Resource[]
+ *      embeddedManifests: module:@ui5/fs.Resource[]
  *   }
  * </pre>
  * @returns {Promise<module:@ui5/fs.Resource[]>} Promise resolving with an array containing the versionInfo resource
@@ -416,7 +433,7 @@ module.exports = async function({options}) {
 	const dependencyInfoMap = new Map();
 
 
-	// gather all manifestHints
+	// process library infos
 	const librariesPromises = options.libraryInfos.map((libraryInfo) => {
 		return processLibraryInfo(libraryInfo);
 	});

lib/tasks/generateVersionInfo.js

@@ -30,7 +30,7 @@ module.exports = async ({workspace, dependencies, options: {rootProject, pattern
 				manifestResources.filter((manifestResource) => manifestResource !== libraryManifest);
 			return {
 				libraryManifest,
-				manifestResources: embeddedManifests,
+				embeddedManifests,
 				name: dotLibResource._project.metadata.name,
 				version: dotLibResource._project.version
 			};