feat(logger): Add module filtering, task-skip event

Allow filtering of log messages by module names using an environment
variable UI5_LOG_MODULES. Inspired by the 'debug' npm package.

**Examples:**

* `UI5_LOG_MODULES=specifications:*,graph:Module,Build ui5 build`
* `UI5_LOG_MODULES=graph:*,-graph:providers:* ui5 serve --verbose`

Add a new log event "task-skip".

Cherry-pick of SAP/ui5-logger#480
JIRA: CPOUI5FOUNDATION-1174

Author: RandomByte

packages/logger/lib/loggers/ProjectBuild.js

@@ -83,6 +83,24 @@ class ProjectBuild extends Logger {
 			this._log(level, `${this.#projectName}: Finished task ${taskName}`);
 		}
 	}
+
+	skipTask(taskName) {
+		if (!this.#tasksToRun || !this.#tasksToRun.includes(taskName)) {
+			throw new Error(`loggers/ProjectBuild#skipTask: Unknown task ${taskName}`);
+		}
+		const level = "info";
+		const hasListeners = this._emit(ProjectBuild.PROJECT_BUILD_STATUS_EVENT_NAME, {
+			level,
+			projectName: this.#projectName,
+			projectType: this.#projectType,
+			taskName,
+			status: "task-skip",
+		});
+
+		if (!hasListeners) {
+			this._log(level, `${this.#projectName}: Skipping task ${taskName}`);
+		}
+	}
 }
 
 export default ProjectBuild;

packages/logger/lib/writers/Console.js

@@ -21,6 +21,7 @@ class Console {
 	#progressBarContainer;
 	#progressBar;
 	#progressProjectWeight;
+	#moduleFilter;
 
 	constructor() {
 		this._handleLogEvent = this.#handleLogEvent.bind(this);
@@ -31,6 +32,65 @@ class Console {
 		this._handleStop = this.disable.bind(this);
 	}
 
+	#initFiters() {
+		const modulesPatterns = process.env.UI5_LOG_MODULES;
+		if (!modulesPatterns) {
+			this.#moduleFilter = null;
+			return;
+		}
+		const enabledModules = [];
+		const enabledNamespaces = [];
+		const disabledModules = [];
+		const disabledNamespaces = [];
+		// Example of modulePattern: "module1,module2:submodule:subsubmodule,module3:*:-module3:submodule"
+		modulesPatterns.split(",").forEach((modulePattern) => {
+			const pattern = modulePattern.trim();
+			if (pattern.startsWith("-")) {
+				if (pattern.endsWith(":*")) {
+					disabledNamespaces.push(pattern.substring(1, pattern.length - 2));
+				} else {
+					disabledModules.push(pattern.substring(1));
+				}
+			} else {
+				if (pattern.endsWith(":*")) {
+					enabledNamespaces.push(pattern.substring(0, pattern.length - 2));
+				} else {
+					enabledModules.push(pattern);
+				}
+			}
+		});
+
+		this.#moduleFilter = {
+			enabledModules,
+			enabledNamespaces,
+			disabledModules,
+			disabledNamespaces,
+		};
+	}
+
+	#filterModule(moduleName) {
+		if (!this.#moduleFilter) {
+			return true;
+		}
+		if (this.#moduleFilter.disabledModules.includes(moduleName)) {
+			return false;
+		}
+		if (this.#moduleFilter.enabledModules.includes(moduleName)) {
+			return true;
+		}
+		const moduleParts = moduleName.split(":");
+		for (let i = moduleParts.length - 1; i > 0; i--) {
+			const namespace = moduleParts.slice(0, i).join(":");
+			if (this.#moduleFilter.disabledNamespaces.includes(namespace)) {
+				return false;
+			}
+			if (this.#moduleFilter.enabledNamespaces.includes(namespace)) {
+				return true;
+			}
+		}
+		return false;
+	}
+
 	/**
 	 * Attaches all event listeners and starts writing to output stream
 	 *
@@ -137,7 +197,9 @@ class Console {
 	}
 
 	#handleLogEvent({level, message, moduleName}) {
-		this.#writeMessage(level, `${chalk.blue(moduleName)} ${message}`);
+		if (this.#filterModule(moduleName)) {
+			this.#writeMessage(level, `${chalk.blue(moduleName)} ${message}`);
+		}
 	}
 
 	#handleBuildMetadataEvent({projectsToBuild}) {
@@ -328,6 +390,27 @@ class Console {
 			taskMetadata.executionEnded = true;
 			message = `${chalk.green(figures.tick)} Finished task ${chalk.bold(taskName)}`;
 
+			// Update progress bar (if used)
+			this._getProgressBar()?.increment(1);
+			break;
+		case "task-skip":
+			if (taskMetadata.executionSkipped) {
+				throw new Error(`writers/Console: ` +
+					`Unexpected duplicate task-skip event for project ${projectName}, task ${taskName}`);
+			}
+			if (taskMetadata.executionStarted) {
+				throw new Error(`writers/Console: ` +
+					`Unexpected task-skip event for project ${projectName}, task ${taskName}. ` +
+					`Task execution already started`);
+			}
+			if (taskMetadata.executionEnded) {
+				throw new Error(`writers/Console: ` +
+					`Unexpected task-skip event for project ${projectName}, task ${taskName}. ` +
+					`Task execution already ended`);
+			}
+			taskMetadata.executionEnded = true;
+			message = `${chalk.green(figures.tick)} Skipping task ${chalk.bold(taskName)}`;
+
 			// Update progress bar (if used)
 			this._getProgressBar()?.increment(1);
 			break;

packages/logger/test/lib/loggers/ProjectBuild.js

@@ -228,3 +228,58 @@ test.serial("End task: Unknown task", (t) => {
 	}, "Threw with expected error message");
 });
 
+test.serial("Skip task", (t) => {
+	const {projectBuildLogger, logHandler, metadataHandler, statusHandler, logStub} = t.context;
+	projectBuildLogger.setTasks(["task.a"]);
+
+	projectBuildLogger.skipTask("task.a");
+
+	t.is(statusHandler.callCount, 1, "One build-status event emitted");
+	t.deepEqual(statusHandler.getCall(0).args[0], {
+		level: "info",
+		projectName: "projectName",
+		projectType: "projectType",
+		status: "task-skip",
+		taskName: "task.a",
+	}, "Metadata event has expected payload");
+
+	t.is(logHandler.callCount, 0, "No log event emitted");
+	t.is(metadataHandler.callCount, 1, "One build-metadata event emitted");
+	t.is(logStub.callCount, 0, "_log was never called");
+});
+
+test.serial("No event listener: Skip task", (t) => {
+	const {projectBuildLogger, logHandler, metadataHandler, statusHandler, logStub} = t.context;
+	process.off(ProjectBuildLogger.PROJECT_BUILD_STATUS_EVENT_NAME, statusHandler);
+	projectBuildLogger.setTasks(["task.a"]);
+
+	projectBuildLogger.skipTask("task.a");
+	t.is(logStub.callCount, 1, "_log got called once");
+	t.is(logStub.getCall(0).args[0], "info", "Logged with expected log-level");
+	t.is(logStub.getCall(0).args[1],
+		"projectName: Skipping task task.a",
+		"Logged expected message");
+
+	t.is(logHandler.callCount, 0, "No log event emitted");
+	t.is(metadataHandler.callCount, 1, "One build-metadata event emitted");
+});
+
+test.serial("Skip task: Unknown task", (t) => {
+	const {projectBuildLogger} = t.context;
+
+	// Throws because no projects are set
+	t.throws(() => {
+		projectBuildLogger.skipTask("task.x");
+	}, {
+		message: `loggers/ProjectBuild#skipTask: Unknown task task.x`
+	}, "Threw with expected error message");
+
+	projectBuildLogger.setTasks(["task.a"]);
+	// Throws because given project is unknown
+	t.throws(() => {
+		projectBuildLogger.skipTask("task.x");
+	}, {
+		message: `loggers/ProjectBuild#skipTask: Unknown task task.x`
+	}, "Threw with expected error message");
+});
+