Add ProjectGraph tests

Author: RandomByte

lib/Module.js

@@ -28,18 +28,18 @@ class Module {
 	 *						or an absolute File System path to the project configuration file.
 	 * @param {object} [parameters.configuration]
 	 * 						Configuration object to use. If supplied, no ui5.yaml will be read
-	 * @param {@ui5/extension.extensions.ShimCollection} [parameters.shimCollection]
+	 * @param {@ui5/project.graph.ShimCollection} [parameters.shimCollection]
 	 *						Collection of shims that might be relevant for this module
 	 */
 	constructor({id, version, modulePath, configPath = defaultConfigPath, configuration, shimCollection}) {
 		if (!id) {
-			throw new Error(`Could not create Module: Missing or empty id parameter`);
+			throw new Error(`Could not create Module: Missing or empty parameter 'id'`);
 		}
 		if (!version) {
-			throw new Error(`Could not create Module: Missing or empty version parameter`);
+			throw new Error(`Could not create Module: Missing or empty parameter 'version'`);
 		}
 		if (!modulePath) {
-			throw new Error(`Could not create Module: Missing or empty modulePath parameter`);
+			throw new Error(`Could not create Module: Missing or empty parameter 'modulePath'`);
 		}
 
 		this._id = id;

lib/graph/ProjectGraph.js

@@ -1,17 +1,21 @@
 const log = require("@ui5/logger").getLogger("graph:ProjectGraph");
 /**
-* A rooted, directed graph representing a UI5 project that should be worked with and all its dependencies
-*/
+ * A rooted, directed graph representing a UI5 project and all its dependencies
+ *
+ * @public
+ * @memberof module:@ui5/project.graph
+ */
 class ProjectGraph {
 	/**
+	 * @public
 	 * @param {object} parameters Parameters
 	 * @param {string} parameters.rootProjectName Root project name
-	 * @param {Array.<module:@ui5/project.Extension>} parameters.extensions
+	 * @param {Array.<module:@ui5/project.specification.Extension>} parameters.extensions
 	 * 													Final list of extensions to be used in this project tree
 	 */
 	constructor({rootProjectName, extensions = []}) {
 		if (!rootProjectName) {
-			throw new Error(`Could not create ProjectGraph: One or more required parameters are missing`);
+			throw new Error(`Could not create ProjectGraph: Missing or empty parameter 'rootProjectName'`);
 		}
 		this._rootProjectName = rootProjectName;
 		this._extensions = Object.freeze(extensions);
@@ -34,22 +38,30 @@ class ProjectGraph {
 			if (ignoreDuplicates) {
 				return;
 			}
-			throw new Error(`Could not add duplicate project '${projectName}' to project tree`);
+			throw new Error(
+				`Failed to add project ${projectName} to the graph: A project with that name has already been added`);
+		}
+		if (!isNaN(projectName)) {
+			// Reject integer-like project names. They would take precedence when traversing object keys which
+			// could lead to unexpected behavior. We don't really expect anyone to use such names anyways
+			throw new Error(
+				`Failed to add project ${projectName} to graph: Project name must not be integer-like`);
 		}
 		this._projects[projectName] = project;
-		this._adjList[projectName] = [];
+		this._adjList[projectName] = {};
 	}
 
 	getProject(projectName) {
 		return this._projects[projectName];
 	}
 
 	/**
-	* Declare a dependency from one project in the graph to another
-	*
-	* @param {string} fromProjectName Name of the depending project
-	* @param {string} toProjectName Name of project on which the other depends
-	*/
+	 * Declare a dependency from one project in the graph to another
+	 *
+	 * @public
+	 * @param {string} fromProjectName Name of the depending project
+	 * @param {string} toProjectName Name of project on which the other depends
+	 */
 	declareDependency(fromProjectName, toProjectName/* , optional*/) {
 		if (!this._projects[fromProjectName]) {
 			throw new Error(
@@ -69,18 +81,49 @@ class ProjectGraph {
 		}
 	}
 
+
 	/**
-	* Visit every project in the graph that can be reached by the given entry project exactly once.
-	* The entry project defaults to the root project.
-	* In case a cycle is detected, an error is thrown
-	*
-	* @param {Function} callback
-	*/
-	async traverseBreadthFirst(callback) {
-		// TODO: Add parameter to define point of entry, defaulting to root
+	 * Callback for graph traversal operations
+	 *
+	 * @public
+	 * @async
+	 * @callback module:@ui5/project.graph.ProjectGraph~traversalCallback
+	 * @param {object} parameters Parameters passed to the callback
+	 * @param {module:@ui5/project.specifications.Project} parameters.project The project that is currently visited
+	 * @param {module:@ui5/project.graph.ProjectGraph~getDependencies} parameters.getDependencies
+	 * 				Function to access the dependencies of the project that is currently visited.
+	 * @returns {Promise} Must return a promise on which the graph traversal will wait
+	 */
+
+	/**
+	 * Helper function available in the
+	 * traversalCallback]{@link module:@ui5/project.graph.ProjectGraph~traversalCallback} to access the
+	 * dependencies of the corresponding project in the current graph.
+	 * <br><br>
+	 * Note that transitive dependencies can't be accessed this way. Projects should rather add a direct
+	 * dependency to projects they need access to.
+	 *
+	 * @public
+	 * @function module:@ui5/project.graph.ProjectGraph~getDependencies
+	 * @returns {Array.<module:@ui5/project.specifications.Project>} Direct dependencies of the visited project
+	 */
+
+	/**
+	 * Visit every project in the graph that can be reached by the given entry project exactly once.
+	 * The entry project defaults to the root project.
+	 * In case a cycle is detected, an error is thrown
+	 *
+	 * @public
+	 * @param {module:@ui5/project.graph.ProjectGraph~traversalCallback} callback Will be called
+	 * @param {string} [startName] Name of the project to start the traversal at. Defaults to the graph's root project
+	 */
+	async traverseBreadthFirst(callback, startName = this._rootProjectName) {
+		if (!this.getProject(startName)) {
+			throw new Error(`Failed to start graph traversal: Could not find project ${startName} in graph`);
+		}
 
 		const queue = [{
-			projectNames: [this._rootProjectName],
+			projectNames: [startName],
 			predecessors: []
 		}];
 
@@ -114,7 +157,7 @@ class ProjectGraph {
 					await callback({
 						project: this.getProject(projectName),
 						getDependencies: () => {
-							return dependencies.map(($) => this.getProject($.projectName));
+							return dependencies.map(($) => this.getProject($));
 						}
 					});
 				})();
@@ -123,15 +166,18 @@ class ProjectGraph {
 	}
 
 	/**
-	* Visit every project in the graph that can be reached by the given entry project exactly once.
-	* The entry project defaults to the root project.
-	* In case a cycle is detected, an error is thrown
-	*
-	* @param {Function} callback
-	*/
-	async traverseDepthFirst(callback) {
-		// TODO: Add parameter to define point of entry, defaulting to root
-		return this._traverseDepthFirst(this._rootProjectName, {}, [], callback);
+	 * Visit every project in the graph that can be reached by the given entry project exactly once.
+	 * The entry project defaults to the root project.
+	 * In case a cycle is detected, an error is thrown
+	 *
+	 * @param {module:@ui5/project.graph.ProjectGraph~traversalCallback} callback Will be called
+	 * @param {string} [startName] Name of the project to start the traversal at. Defaults to the graph's root project
+	 */
+	async traverseDepthFirst(callback, startName = this._rootProjectName) {
+		if (!this.getProject(startName)) {
+			throw new Error(`Failed to start graph traversal: Could not find project ${startName} in graph`);
+		}
+		return this._traverseDepthFirst(startName, {}, [], callback);
 	}
 
 	async _traverseDepthFirst(projectName, visited, predecessors, callback) {
@@ -156,7 +202,7 @@ class ProjectGraph {
 			await callback({
 				project: this.getProject(projectName),
 				getDependencies: () => {
-					return dependencies.map(($) => this.getProject($.projectName));
+					return dependencies.map(($) => this.getProject($));
 				}
 			});
 		})();

lib/specifications/AbstractSpecification.js

@@ -14,12 +14,20 @@ class AbstractSpecification {
 		if (new.target === AbstractSpecification) {
 			throw new TypeError("Class 'AbstractSpecification' is abstract");
 		}
-		if (!id || !version || !modulePath || !configuration) {
-			throw new Error(`Could not create Project: One or more required parameters are missing`);
+		if (!id) {
+			throw new Error(`Could not create specification: Missing or empty parameter 'id'`);
+		}
+		if (!version) {
+			throw new Error(`Could not create specification: Missing or empty parameter 'version'`);
+		}
+		if (!modulePath) {
+			throw new Error(`Could not create specification: Missing or empty parameter 'modulePath'`);
+		}
+		if (!configuration) {
+			throw new Error(`Could not create specification: Missing or empty parameter 'configuration'`);
 		}
-
 		if (!(configuration instanceof Configuration)) {
-			throw new Error(`Could not create project: 'configuration' must be an instance of ` +
+			throw new Error(`Could not create specification: 'configuration' must be an instance of ` +
 				`@ui5/project.specifications.Configuration`);
 		}