[INTERNAL] TypeScript: Add typings to BuildContext, Specification, Pr…

…ojectGraph

src/build/helpers/BuildContext.ts

@@ -1,12 +1,25 @@
+import ProjectGraph from "../../graph/ProjectGraph.js";
 import ProjectBuildContext from "./ProjectBuildContext.js";
 import OutputStyleEnum from "./ProjectBuilderOutputStyle.js";
 
+interface BuildConfig {
+	selfContained: boolean;
+	cssVariables: boolean;
+	jsdoc: boolean;
+	createBuildManifest: boolean;
+	outputStyle: typeof OutputStyleEnum;
+	includedTasks: string[];
+	excludedTasks: string[];
+}
+
 /**
  * Context of a build process
  *
  */
 class BuildContext {
-	constructor(graph, taskRepository, { // buildConfig
+    _graph: ProjectGraph;
+    _buildConfig: BuildConfig;
+	constructor(graph: ProjectGraph, taskRepository: typeof import("@ui5/builder/internal/taskRepository"), { // buildConfig
 		selfContained = false,
 		cssVariables = false,
 		jsdoc = false,

src/build/helpers/TaskUtil.ts

@@ -1,3 +1,4 @@
+import {ResourceInterface} from "@ui5/fs/Resource";
 import {
 	createReaderCollection,
 	createReaderCollectionPrioritized,
@@ -16,7 +17,6 @@ import {
  * The set of available functions on that interface depends on the specification
  * version defined for the extension.
  *
- * @alias @ui5/project/build/helpers/TaskUtil
  * @hideconstructor
  */
 class TaskUtil {
@@ -47,7 +47,9 @@ class TaskUtil {
 	 * @param parameters
 	 * @param parameters.projectBuildContext ProjectBuildContext
 	 */
-	constructor({projectBuildContext}: object) {
+	STANDARD_TAGS: object;
+
+	constructor({projectBuildContext}) {
 		this._projectBuildContext = projectBuildContext;
 		/**
 		 */
@@ -79,7 +81,7 @@ class TaskUtil {
 	 * 	[STANDARD_TAGS]{@link @ui5/project/build/helpers/TaskUtil#STANDARD_TAGS} are allowed
 	 * @param [value] Tag value. Must be primitive
 	 */
-	public setTag(resource, tag: string, value?: string | boolean | integer) {
+	public setTag(resource: ResourceInterface, tag: string, value?: string | boolean | number) {
 		if (typeof resource === "string") {
 			throw new Error("Deprecated parameter: " +
 				"Since UI5 Tooling 3.0, #setTag requires a resource instance. Strings are no longer accepted");
@@ -101,7 +103,7 @@ class TaskUtil {
 	 * @returns Tag value for the given resource.
 	 * 										<code>undefined</code> if no value is available
 	 */
-	public getTag(resource, tag: string) {
+	public getTag(resource: ResourceInterface, tag: string) {
 		if (typeof resource === "string") {
 			throw new Error("Deprecated parameter: " +
 				"Since UI5 Tooling 3.0, #getTag requires a resource instance. Strings are no longer accepted");
@@ -121,7 +123,7 @@ class TaskUtil {
 	 * @param resource Resource-instance the tag should be cleared for
 	 * @param tag Tag
 	 */
-	public clearTag(resource, tag: string) {
+	public clearTag(resource: ResourceInterface, tag: string) {
 		if (typeof resource === "string") {
 			throw new Error("Deprecated parameter: " +
 				"Since UI5 Tooling 3.0, #clearTag requires a resource instance. Strings are no longer accepted");

src/build/helpers/createBuildManifest.ts

@@ -30,7 +30,7 @@ function getSortedTags(project) {
  * @param buildConfig
  * @param taskRepository
  */
-export default async function (project, buildConfig, taskRepository) {
+export default async function (project, buildConfig, taskRepository: typeof import("@ui5/builder/internal/taskRepository")) {
 	if (!project) {
 		throw new Error(`Missing parameter 'project'`);
 	}

src/graph/ProjectGraph.ts

@@ -1,15 +1,32 @@
 import OutputStyleEnum from "../build/helpers/ProjectBuilderOutputStyle.js";
 import {getLogger} from "@ui5/logger";
+import type Project from "../specifications/Project.js";
+import type Extension from "../specifications/Extension.js";
+import type Specification from "../specifications/Specification.js";
+import type * as T_taskRepository from "@ui5/builder/internal/taskRepository";
 const log = getLogger("graph:ProjectGraph");
 
+type TraversalCallback = (arg: {project: Project; dependencies: string[]}) => Promise<undefined>;
+type VisitedNodes = Record<string, Promise<undefined> | undefined>;
+
 /**
  * A rooted, directed graph representing a UI5 project, its dependencies and available extensions.
  * <br><br>
  * While it allows defining cyclic dependencies, both traversal functions will throw an error if they encounter cycles.
  *
- * @alias @ui5/project/graph/ProjectGraph
  */
 class ProjectGraph {
+	_rootProjectName: string;
+
+	_projects: Map<string, Project>;
+	_adjList: Map<string, Set<string>>;
+	_optAdjList: Map<string, Set<string>>;
+	_extensions: Map<string, Extension>;
+
+	_sealed: boolean;
+	_hasUnresolvedOptionalDependencies: boolean;
+	_taskRepository: typeof T_taskRepository | null;
+
 	/**
 	 * @param parameters Parameters
 	 * @param parameters.rootProjectName Root project name
@@ -38,7 +55,7 @@ class ProjectGraph {
 	 *
 	 * @returns Root project
 	 */
-	public getRoot() {
+	public getRoot(): Specification {
 		const rootProject = this._projects.get(this._rootProjectName);
 		if (!rootProject) {
 			throw new Error(`Unable to find root project with name ${this._rootProjectName} in project graph`);
@@ -51,15 +68,15 @@ class ProjectGraph {
 	 *
 	 * @param project Project which should be added to the graph
 	 */
-	public addProject(project) {
+	public addProject(project: Project) {
 		this._checkSealed();
 		const projectName = project.getName();
 		if (this._projects.has(projectName)) {
 			throw new Error(
 				`Failed to add project ${projectName} to graph: A project with that name has already been added. ` +
 				`This might be caused by multiple modules containing projects with the same name`);
 		}
-		if (!isNaN(projectName)) {
+		if (!isNaN(projectName as unknown as number)) {
 			// 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(
@@ -114,7 +131,7 @@ class ProjectGraph {
 	 *
 	 * @param extension Extension which should be available in the graph
 	 */
-	public addExtension(extension) {
+	public addExtension(extension: Extension) {
 		this._checkSealed();
 		const extensionName = extension.getName();
 		if (this._extensions.has(extensionName)) {
@@ -123,7 +140,7 @@ class ProjectGraph {
 				`An extension with that name has already been added. ` +
 				`This might be caused by multiple modules containing extensions with the same name`);
 		}
-		if (!isNaN(extensionName)) {
+		if (!isNaN(extensionName as unknown as number)) {
 			// Reject integer-like extension names. They would take precedence when traversing object keys which
 			// might lead to unexpected behavior in the future. We don't really expect anyone to use such names anyways
 			throw new Error(
@@ -171,9 +188,12 @@ class ProjectGraph {
 			log.verbose(`Declaring dependency: ${fromProjectName} depends on ${toProjectName}`);
 			this._declareDependency(this._adjList, fromProjectName, toProjectName);
 		} catch (err) {
-			throw new Error(
-				`Failed to declare dependency from project ${fromProjectName} to ${toProjectName}: ` +
-				err.message);
+			if (err instanceof Error) {
+				throw new Error(
+					`Failed to declare dependency from project ${fromProjectName} to ${toProjectName}: ` +
+					err.message);
+			}
+			throw err;
 		}
 	}
 
@@ -190,9 +210,12 @@ class ProjectGraph {
 			this._declareDependency(this._optAdjList, fromProjectName, toProjectName);
 			this._hasUnresolvedOptionalDependencies = true;
 		} catch (err) {
-			throw new Error(
-				`Failed to declare optional dependency from project ${fromProjectName} to ${toProjectName}: ` +
-				err.message);
+			if (err instanceof Error) {
+				throw new Error(
+					`Failed to declare optional dependency from project ${fromProjectName} to ${toProjectName}: ` +
+					err.message);
+			}
+			throw err;
 		}
 	}
 
@@ -203,7 +226,7 @@ class ProjectGraph {
 	 * @param fromProjectName Name of the depending project
 	 * @param toProjectName Name of project on which the other depends
 	 */
-	_declareDependency(map: object, fromProjectName: string, toProjectName: string) {
+	_declareDependency(map: typeof this._adjList, fromProjectName: string, toProjectName: string) {
 		if (!this._projects.has(fromProjectName)) {
 			throw new Error(
 				`Unable to find depending project with name ${fromProjectName} in project graph`);
@@ -216,7 +239,7 @@ class ProjectGraph {
 			throw new Error(
 				`A project can't depend on itself`);
 		}
-		const adjacencies = map.get(fromProjectName);
+		const adjacencies = map.get(fromProjectName)!;
 		if (adjacencies.has(toProjectName)) {
 			log.warn(`Dependency has already been declared: ${fromProjectName} depends on ${toProjectName}`);
 		} else {
@@ -254,8 +277,8 @@ class ProjectGraph {
 				`Unable to find project in project graph`);
 		}
 
-		const processDependency = (depName) => {
-			const adjacencies = this._adjList.get(depName);
+		const processDependency = (depName: string) => {
+			const adjacencies = this._adjList.get(depName)!;
 			adjacencies.forEach((depName) => {
 				if (!dependencies.has(depName)) {
 					dependencies.add(depName);
@@ -287,7 +310,7 @@ class ProjectGraph {
 		if (adjacencies.has(toProjectName)) {
 			return false;
 		}
-		const optAdjacencies = this._optAdjList.get(fromProjectName);
+		const optAdjacencies = this._optAdjList.get(fromProjectName)!;
 		if (optAdjacencies.has(toProjectName)) {
 			return true;
 		}
@@ -340,26 +363,26 @@ class ProjectGraph {
 		}
 	}
 
-	public async traverseBreadthFirst(startName?: string, callback) {
+	public async traverseBreadthFirst(startName?: string, callback?: TraversalCallback) {
 		if (!callback) {
 			// Default optional first parameter
-			callback = startName;
+			callback = startName as unknown as TraversalCallback;
 			startName = this._rootProjectName;
 		}
 
-		if (!this.getProject(startName)) {
+		if (!this.getProject(startName!)) {
 			throw new Error(`Failed to start graph traversal: Could not find project ${startName} in project graph`);
 		}
 
 		const queue = [{
-			projectNames: [startName],
-			ancestors: [],
+			projectNames: [startName] as string[],
+			ancestors: [] as string[],
 		}];
 
-		const visited = Object.create(null);
+		const visited = Object.create(null) as VisitedNodes;
 
 		while (queue.length) {
-			const {projectNames, ancestors} = queue.shift(); // Get and remove first entry from queue
+			const {projectNames, ancestors} = queue.shift()!; // Get and remove first entry from queue
 
 			await Promise.all(projectNames.map(async (projectName) => {
 				this._checkCycle(ancestors, projectName);
@@ -386,20 +409,22 @@ class ProjectGraph {
 		}
 	}
 
-	public async traverseDepthFirst(startName?: string, callback) {
+	public async traverseDepthFirst(startName?: string, callback?: TraversalCallback) {
 		if (!callback) {
 			// Default optional first parameter
-			callback = startName;
+			callback = startName as unknown as TraversalCallback;
 			startName = this._rootProjectName;
 		}
 
-		if (!this.getProject(startName)) {
+		if (!this.getProject(startName!)) {
 			throw new Error(`Failed to start graph traversal: Could not find project ${startName} in project graph`);
 		}
-		return this._traverseDepthFirst(startName, Object.create(null), [], callback);
+		return this._traverseDepthFirst(startName!, Object.create(null) as VisitedNodes, [], callback);
 	}
 
-	async _traverseDepthFirst(projectName, visited, ancestors, callback) {
+	async _traverseDepthFirst(
+		projectName: string, visited: VisitedNodes, ancestors: string[], callback: TraversalCallback
+	) {
 		this._checkCycle(ancestors, projectName);
 
 		if (visited[projectName]) {
@@ -425,7 +450,7 @@ class ProjectGraph {
 	 *
 	 * @param projectGraph Project Graph to merge into this one
 	 */
-	public join(projectGraph) {
+	public join(projectGraph: ProjectGraph) {
 		try {
 			this._checkSealed();
 			if (!projectGraph.isSealed()) {
@@ -450,7 +475,7 @@ class ProjectGraph {
 	}
 
 	// Only to be used by @ui5/builder tests to inject its version of the taskRepository
-	setTaskRepository(taskRepository) {
+	setTaskRepository(taskRepository: typeof T_taskRepository) {
 		this._taskRepository = taskRepository;
 	}
 
@@ -459,9 +484,12 @@ class ProjectGraph {
 			try {
 				this._taskRepository = await import("@ui5/builder/internal/taskRepository");
 			} catch (err) {
-				throw new Error(
-					`Failed to load task repository. Missing dependency to '@ui5/builder'? ` +
-					`Error: ${err.message}`);
+				if (err instanceof Error) {
+					throw new Error(
+						`Failed to load task repository. Missing dependency to '@ui5/builder'? ` +
+						`Error: ${err.message}`);
+				}
+				throw err;
 			}
 		}
 		return this._taskRepository;
@@ -530,7 +558,7 @@ class ProjectGraph {
 		}
 	}
 
-	_checkCycle(ancestors, projectName) {
+	_checkCycle(ancestors: string[], projectName: string) {
 		if (ancestors.includes(projectName)) {
 			// "Back-edge" detected. Neither BFS nor DFS searches should continue
 			// Mark first and last occurrence in chain with an asterisk and throw an error detailing the
@@ -543,12 +571,7 @@ class ProjectGraph {
 	// TODO: introduce function to check for dangling nodes/consistency in general?
 }
 
-/**
- *
- * @param target
- * @param source
- */
-function mergeMap(target, source) {
+function mergeMap(target: Map<string, string | Set<string>>, source: Map<string, string | Set<string>>) {
 	for (const [key, value] of source) {
 		if (target.has(key)) {
 			throw new Error(`Failed to merge map: Key '${key}' already present in target set`);

src/specifications/Project.ts

@@ -4,7 +4,6 @@ import ResourceTagCollection from "@ui5/fs/internal/ResourceTagCollection";
 /**
  * Project
  *
- * @alias @ui5/project/specifications/Project
  * @hideconstructor
  */
 class Project extends Specification {