refactor(project, server): Improve error handling and recovery

packages/logger/lib/loggers/Serve.js

@@ -3,7 +3,7 @@ import Logger from "./Logger.js";
 
 /**
  * Logger for emitting status events on the lifecycle of a UI5 development server
- * (idle / stale / building / build-done / error).
+ * (idle / stale / settling / building / build-done / error).
  * <br><br>
  * Emits <code>ui5.log</code> and <code>ui5.serve-status</code> events on the
  * [<code>process</code>]{@link https://nodejs.org/api/process.html} object, which can be handled
@@ -46,6 +46,14 @@ class Serve extends Logger {
 			`Sources changed in: ${changedProjects.join(", ")}`);
 	}
 
+	settling(pendingProjects) {
+		if (!pendingProjects || !Array.isArray(pendingProjects)) {
+			throw new Error("loggers/Serve#settling: Missing or incorrect pendingProjects parameter");
+		}
+		this.#emitStatus("serve-settling", {pendingProjects},
+			`Waiting for changes to settle in: ${pendingProjects.join(", ")}`);
+	}
+
 	validating(validatingProjects) {
 		if (!validatingProjects || !Array.isArray(validatingProjects)) {
 			throw new Error(

packages/logger/lib/writers/InteractiveConsole.js

@@ -354,13 +354,16 @@ class InteractiveConsole {
 			this.#buildState.changedProjects = evt.changedProjects || [];
 			this.#transitionTo(STATES.STALE);
 			break;
+		case "serve-settling":
+			this.#buildState.pendingProjects = evt.pendingProjects || [];
+			this.#transitionTo(STATES.SETTLING);
+			break;
 		case "serve-building":
 			beginBuild(this.#buildState, this.#buildState.projectOrder);
 			this.#transitionTo(STATES.BUILDING);
 			break;
 		case "serve-validating":
 			this.#buildState.validatingProjects = evt.validatingProjects || [];
-			this.#buildState.spinFrame = 0;
 			this.#transitionTo(STATES.VALIDATING);
 			break;
 		case "serve-build-done":

packages/logger/lib/writers/interactiveConsole/render.js

@@ -150,6 +150,11 @@ function renderStatusLine(state) {
 	case STATES.STALE:
 		return `${label}${chalk.yellow(figures.circle)} ${chalk.yellow(pad("stale"))} ` +
 			`${chalk.dim("· files changed, rebuild on next request")}`;
+	case STATES.SETTLING: {
+		const frame = SPINNER_FRAMES[state.spinFrame % SPINNER_FRAMES.length];
+		return `${label}${chalk.yellow(frame)} ${chalk.yellow(pad("settling"))} ` +
+			`${chalk.dim("· waiting for changes to settle")}`;
+	}
 	case STATES.VALIDATING: {
 		const frame = SPINNER_FRAMES[state.spinFrame % SPINNER_FRAMES.length];
 		const parts = [

packages/logger/lib/writers/interactiveConsole/state/build.js

@@ -6,6 +6,7 @@ export const STATES = Object.freeze({
 	STARTING: "starting", // pre-populated placeholder before the first real state arrives
 	READY: "ready",
 	STALE: "stale",
+	SETTLING: "settling", // changes seen, rebuild deferred until they quiesce
 	BUILDING: "building",
 	VALIDATING: "validating",
 	ERROR: "error",
@@ -14,7 +15,7 @@ export const STATES = Object.freeze({
 // States that animate a spinner. Consulted by both the tick scheduler in the
 // interactive console writer and the status-line renderer, so a state either
 // spins in both places or in neither.
-export const SPINNING_STATES = new Set([STATES.BUILDING, STATES.VALIDATING]);
+export const SPINNING_STATES = new Set([STATES.SETTLING, STATES.BUILDING, STATES.VALIDATING]);
 
 export function createBuildState() {
 	return {
@@ -31,6 +32,9 @@ export function createBuildState() {
 		// Names of projects collected via `serve-validating` payloads — used to
 		// label the validating state if/when the renderer wants to.
 		validatingProjects: [],
+		// Names of projects collected via `serve-settling` payloads — used to
+		// label the settling state if/when the renderer wants to.
+		pendingProjects: [],
 		// Frame counter for the spinner (incremented by the tick loop).
 		spinFrame: 0,
 		// Most recent error captured by `serve-error`.

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

@@ -56,6 +56,26 @@ test.serial("stale: Missing parameter", (t) => {
 	}, "Threw with expected error message");
 });
 
+test.serial("settling emits serve-settling", (t) => {
+	const {serveLogger, statusHandler} = t.context;
+	serveLogger.settling(["project.a", "project.b"]);
+	t.is(statusHandler.callCount, 1, "One serve-status event emitted");
+	t.deepEqual(statusHandler.getCall(0).args[0], {
+		level: "info",
+		status: "serve-settling",
+		pendingProjects: ["project.a", "project.b"],
+	}, "Status event has expected payload");
+});
+
+test.serial("settling: Missing parameter", (t) => {
+	const {serveLogger} = t.context;
+	t.throws(() => {
+		serveLogger.settling();
+	}, {
+		message: "loggers/Serve#settling: Missing or incorrect pendingProjects parameter",
+	}, "Threw with expected error message");
+});
+
 test.serial("validating emits serve-validating", (t) => {
 	const {serveLogger, statusHandler} = t.context;
 	serveLogger.validating(["library.a", "library.b"]);
@@ -161,6 +181,18 @@ test.serial("No event listener: validating", (t) => {
 	t.is(logHandler.callCount, 0, "No log event emitted");
 });
 
+test.serial("No event listener: settling", (t) => {
+	const {serveLogger, statusHandler, logHandler, logStub} = t.context;
+	process.off(ServeLogger.SERVE_STATUS_EVENT_NAME, statusHandler);
+	serveLogger.settling(["project.a", "project.b"]);
+	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],
+		"Waiting for changes to settle in: project.a, project.b",
+		"Logged expected message");
+	t.is(logHandler.callCount, 0, "No log event emitted");
+});
+
 test.serial("No event listener: building", (t) => {
 	const {serveLogger, statusHandler, logHandler, logStub} = t.context;
 	process.off(ServeLogger.SERVE_STATUS_EVENT_NAME, statusHandler);

packages/logger/test/lib/writers/InteractiveConsole.js

@@ -535,6 +535,24 @@ test.serial("serve-status: serve-stale without a payload falls back to an empty
 	writer.disable();
 });
 
+test.serial("serve-status: serve-settling records pendingProjects and transitions to SETTLING", (t) => {
+	const {writer, stderr} = createWriter();
+	process.emit("ui5.serve-status", {status: "serve-settling", pendingProjects: ["my.app"]});
+	const state = writer._getStateForTest().build;
+	t.is(state.state, STATES.SETTLING);
+	t.deepEqual(state.pendingProjects, ["my.app"]);
+	const tail = stripAnsi(stderr.writes.slice(-5).join(""));
+	t.regex(tail, /settling/);
+	writer.disable();
+});
+
+test.serial("serve-status: serve-settling without a payload falls back to an empty list", (t) => {
+	const {writer} = createWriter();
+	process.emit("ui5.serve-status", {status: "serve-settling"});
+	t.deepEqual(writer._getStateForTest().build.pendingProjects, []);
+	writer.disable();
+});
+
 test.serial("serve-status: serve-validating records projects and transitions to VALIDATING", (t) => {
 	const {writer, stderr} = createWriter();
 	process.emit("ui5.serve-status", {

packages/logger/test/lib/writers/interactiveConsole/render.js

@@ -253,6 +253,13 @@ test("renderBuildRegion: stale state includes 'files changed' hint", (t) => {
 	t.regex(plain, /Status\s+.+?\s+stale\s+·\s+files changed/);
 });
 
+test("renderBuildRegion: settling state includes 'waiting for changes to settle' hint", (t) => {
+	const state = createBuildState();
+	transitionTo(state, STATES.SETTLING);
+	const plain = renderBuildRegion(state).map(stripAnsi).join("\n");
+	t.regex(plain, /Status\s+.+?\s+settling\s+·\s+waiting for changes to settle/);
+});
+
 test("renderBuildRegion: validating state includes 'checking dependency caches' hint", (t) => {
 	const state = createBuildState();
 	transitionTo(state, STATES.VALIDATING);