refactor(project): Add perf logging, cleanups

Author: RandomByte

packages/project/lib/build/BuildReader.js

@@ -1,12 +1,32 @@
 import AbstractReader from "@ui5/fs/AbstractReader";
 
+/**
+ * Reader for accessing build results of multiple projects
+ *
+ * Provides efficient resource access by delegating to appropriate project readers
+ * based on resource paths and namespaces. Supports namespace-based routing to
+ * minimize unnecessary project searches.
+ *
+ * @class
+ * @extends @ui5/fs/AbstractReader
+ */
 class BuildReader extends AbstractReader {
 	#projects;
 	#projectNames;
 	#namespaces = new Map();
 	#getReaderForProject;
 	#getReaderForProjects;
 
+	/**
+	 * Creates a new BuildReader instance
+	 *
+	 * @public
+	 * @param {string} name Name of the reader
+	 * @param {Array<@ui5/project/specifications/Project>} projects Array of projects to read from
+	 * @param {Function} getReaderForProject Function that returns a reader for a single project by name
+	 * @param {Function} getReaderForProjects Function that returns a combined reader for multiple project names
+	 * @throws {Error} If multiple projects share the same namespace
+	 */
 	constructor(name, projects, getReaderForProject, getReaderForProjects) {
 		super(name);
 		this.#projects = projects;
@@ -27,11 +47,31 @@ class BuildReader extends AbstractReader {
 		}
 	}
 
+	/**
+	 * Locates resources by glob pattern
+	 *
+	 * Retrieves a combined reader for all projects and delegates the glob search to it.
+	 *
+	 * @public
+	 * @param {...*} args Arguments to pass to the underlying reader's byGlob method
+	 * @returns {Promise<Array<@ui5/fs/Resource>>} Promise resolving to list of resources
+	 */
 	async byGlob(...args) {
 		const reader = await this.#getReaderForProjects(this.#projectNames);
 		return reader.byGlob(...args);
 	}
 
+	/**
+	 * Locates a resource by path
+	 *
+	 * Attempts to determine the appropriate project reader based on the resource path
+	 * and namespace. Falls back to searching all projects if the resource cannot be found.
+	 *
+	 * @public
+	 * @param {string} virPath Virtual path of the resource
+	 * @param {...*} args Additional arguments to pass to the underlying reader's byPath method
+	 * @returns {Promise<@ui5/fs/Resource|null>} Promise resolving to resource or null if not found
+	 */
 	async byPath(virPath, ...args) {
 		const reader = await this._getReaderForResource(virPath);
 		let res = await reader.byPath(virPath, ...args);
@@ -43,7 +83,16 @@ class BuildReader extends AbstractReader {
 		return res;
 	}
 
-
+	/**
+	 * Gets the appropriate reader for a resource at the given path
+	 *
+	 * Determines which project(s) might contain the resource based on namespace matching
+	 * and returns a reader for those projects. For single-project readers, returns that
+	 * project's reader directly.
+	 *
+	 * @param {string} virPath Virtual path of the resource
+	 * @returns {Promise<@ui5/fs/AbstractReader>} Promise resolving to appropriate reader
+	 */
 	async _getReaderForResource(virPath) {
 		let reader;
 		if (this.#projects.length === 1) {
@@ -65,9 +114,14 @@ class BuildReader extends AbstractReader {
 	}
 
 	/**
-	 * Determine which projects might contain the resource for the given path.
+	 * Determines which projects might contain the resource for the given path
+	 *
+	 * Analyzes the resource path to identify matching project namespaces. Only processes
+	 * paths starting with /resources/ or /test-resources/. Returns project names in order
+	 * from most specific to least specific namespace match.
 	 *
 	 * @param {string} virPath Virtual resource path
+	 * @returns {string[]} Array of project names that might contain the resource
 	 */
 	_getProjectsForResourcePath(virPath) {
 		if (!virPath.startsWith("/resources/") && !virPath.startsWith("/test-resources/")) {

packages/project/lib/build/BuildServer.js

@@ -3,6 +3,27 @@ import {createReaderCollectionPrioritized} from "@ui5/fs/resourceFactory";
 import BuildReader from "./BuildReader.js";
 import WatchHandler from "./helpers/WatchHandler.js";
 
+/**
+ * Development server that provides access to built project resources with automatic rebuilding
+ *
+ * BuildServer watches project sources for changes and automatically rebuilds affected projects
+ * on-demand. It provides readers for accessing built resources and emits events for build
+ * completion and source changes.
+ *
+ * The server maintains separate readers for:
+ * - All projects (root + dependencies)
+ * - Root project only
+ * - Dependencies only
+ *
+ * Projects are built lazily when their resources are first requested, and rebuilt automatically
+ * when source files change.
+ *
+ * @class
+ * @extends EventEmitter
+ * @fires BuildServer#buildFinished
+ * @fires BuildServer#sourcesChanged
+ * @fires BuildServer#error
+ */
 class BuildServer extends EventEmitter {
 	#graph;
 	#projectBuilder;
@@ -12,6 +33,18 @@ class BuildServer extends EventEmitter {
 	#dependenciesReader;
 	#projectReaders = new Map();
 
+	/**
+	 * Creates a new BuildServer instance
+	 *
+	 * Initializes readers for different project combinations, sets up file watching,
+	 * and optionally performs an initial build of specified dependencies.
+	 *
+	 * @public
+	 * @param {@ui5/project/graph/ProjectGraph} graph Project graph containing all projects
+	 * @param {@ui5/project/build/ProjectBuilder} projectBuilder Builder instance for executing builds
+	 * @param {string[]} initialBuildIncludedDependencies Project names to include in initial build
+	 * @param {string[]} initialBuildExcludedDependencies Project names to exclude from initial build
+	 */
 	constructor(graph, projectBuilder, initialBuildIncludedDependencies, initialBuildExcludedDependencies) {
 		super();
 		this.#graph = graph;
@@ -64,18 +97,57 @@ class BuildServer extends EventEmitter {
 		});
 	}
 
+	/**
+	 * Gets a reader for all projects (root and dependencies)
+	 *
+	 * Returns a reader that provides access to built resources from all projects in the graph.
+	 * Projects are built on-demand when their resources are requested.
+	 *
+	 * @public
+	 * @returns {BuildReader} Reader for all projects
+	 */
 	getReader() {
 		return this.#allReader;
 	}
 
+	/**
+	 * Gets a reader for the root project only
+	 *
+	 * Returns a reader that provides access to built resources from only the root project,
+	 * excluding all dependencies. The root project is built on-demand when its resources
+	 * are requested.
+	 *
+	 * @public
+	 * @returns {BuildReader} Reader for root project
+	 */
 	getRootReader() {
 		return this.#rootReader;
 	}
 
+	/**
+	 * Gets a reader for dependencies only (excluding root project)
+	 *
+	 * Returns a reader that provides access to built resources from all transitive
+	 * dependencies of the root project. Dependencies are built on-demand when their
+	 * resources are requested.
+	 *
+	 * @public
+	 * @returns {BuildReader} Reader for all dependencies
+	 */
 	getDependenciesReader() {
 		return this.#dependenciesReader;
 	}
 
+	/**
+	 * Gets a reader for a single project, building it if necessary
+	 *
+	 * Checks if the project has already been built and returns its reader from cache.
+	 * If not built, waits for any in-progress build, then triggers a build for the
+	 * requested project.
+	 *
+	 * @param {string} projectName Name of the project to get reader for
+	 * @returns {Promise<@ui5/fs/AbstractReader>} Reader for the built project
+	 */
 	async #getReaderForProject(projectName) {
 		if (this.#projectReaders.has(projectName)) {
 			return this.#projectReaders.get(projectName);
@@ -101,6 +173,16 @@ class BuildServer extends EventEmitter {
 		return this.#projectReaders.get(projectName);
 	}
 
+	/**
+	 * Gets a combined reader for multiple projects, building them if necessary
+	 *
+	 * Determines which projects need to be built, waits for any in-progress build,
+	 * then triggers a build for any missing projects. Returns a prioritized collection
+	 * reader combining all requested projects.
+	 *
+	 * @param {string[]} projectNames Array of project names to get readers for
+	 * @returns {Promise<@ui5/fs/ReaderCollection>} Combined reader for all requested projects
+	 */
 	async #getReaderForProjects(projectNames) {
 		let projectsRequiringBuild = [];
 		for (const projectName of projectNames) {
@@ -140,6 +222,15 @@ class BuildServer extends EventEmitter {
 		return this.#getReaderForCachedProjects(projectNames);
 	}
 
+	/**
+	 * Creates a combined reader for already-built projects
+	 *
+	 * Retrieves readers from the cache for the specified projects and combines them
+	 * into a prioritized reader collection.
+	 *
+	 * @param {string[]} projectNames Array of project names to combine
+	 * @returns {@ui5/fs/ReaderCollection} Combined reader for cached projects
+	 */
 	#getReaderForCachedProjects(projectNames) {
 		const readers = [];
 		for (const projectName of projectNames) {
@@ -181,6 +272,15 @@ class BuildServer extends EventEmitter {
 	// 	return this.#allProjectsReader;
 	// }
 
+	/**
+	 * Handles completion of a project build
+	 *
+	 * Caches readers for all built projects and emits the buildFinished event
+	 * with the list of project names that were built.
+	 *
+	 * @param {string[]} projectNames Array of project names that were built
+	 * @fires BuildServer#buildFinished
+	 */
 	#projectBuildFinished(projectNames) {
 		for (const projectName of projectNames) {
 			this.#projectReaders.set(projectName,
@@ -190,5 +290,32 @@ class BuildServer extends EventEmitter {
 	}
 }
 
+/**
+ * Build finished event
+ *
+ * Emitted when one or more projects have finished building.
+ *
+ * @event BuildServer#buildFinished
+ * @param {string[]} projectNames Array of project names that were built
+ */
+
+/**
+ * Sources changed event
+ *
+ * Emitted when source files have changed and affected projects have been invalidated.
+ *
+ * @event BuildServer#sourcesChanged
+ * @param {string[]} changedResourcePaths Array of changed resource paths
+ */
+
+/**
+ * Error event
+ *
+ * Emitted when an error occurs during watching or building.
+ *
+ * @event BuildServer#error
+ * @param {Error} error The error that occurred
+ */
+
 
 export default BuildServer;