Move fail to core-utils (#23955)

## Description

Now that assert tagging can support `fail`, and that's confirmed to be
working in tree, it makes sense to broaden the availability of this
utility function.

## Breaking Changes

This will impact the call stack for asserts by adding "fail" to the top,
and the call stacks of "fail" by adding "assert" to the top.
Since such errors are mostly aggregated by their assert tag, and not
their stack, this shouldn't be a big deal, but it could have some
impact.

## Reviewer Guidance

The review process is outlined on [this wiki
page](https://github.com/microsoft/FluidFramework/wiki/PR-Guidelines#guidelines).

Author: CraigMacomber

packages/common/core-utils/src/assert.ts

@@ -31,12 +31,31 @@
  */
 export function assert(condition: boolean, message: string | number): asserts condition {
 	if (!condition) {
-		throw new Error(
-			typeof message === "number" ? `0x${message.toString(16).padStart(3, "0")}` : message,
-		);
+		fail(message);
 	}
 }
 
+/**
+ * Throw an error with a constant message.
+ * @remarks
+ * Works like {@link assert}, but errors unconditionally instead of taking in a condition.
+ *
+ * Unlike `assert`, this `fail` is not "tagged" by the assert tagging too by default.
+ * Use a `assertTagging.config.mjs` file to enable this and any other assert tagging customizations as needed.
+ *
+ * Returns `never` so it can be used inline as part of an expression, or as a return value.
+ * @example
+ * ```ts
+ *  const x: number = numbersMap.get("foo") ?? fail("foo missing from map");
+ * ```
+ * @internal
+ */
+export function fail(message: string | number): never {
+	throw new Error(
+		typeof message === "number" ? `0x${message.toString(16).padStart(3, "0")}` : message,
+	);
+}
+
 /**
  * Asserts that can be conditionally enabled in debug/development builds but will be optimized out of production builds.
  *

packages/common/core-utils/src/index.ts

@@ -5,6 +5,7 @@
 
 export {
 	assert,
+	fail,
 	debugAssert,
 	configureDebugAsserts,
 	nonProductionConditionalsIncluded,

packages/dds/tree/src/util/utils.ts

@@ -47,18 +47,8 @@ export function asMutable<T>(readonly: T): Mutable<T> {
 
 export const clone = structuredClone;
 
-/**
- * Throw an error with a constant message.
- * @remarks
- * Works like {@link @fluidframework/core-utils/internal#assert}.
- */
-export function fail(message: string | number): never {
-	// Declaring this here aliased to a different name avoids the assert tagging objecting to the usages of `assert` below.
-	// Since users of `fail` do the assert message tagging instead, suppressing tagging errors here makes sense.
-	const assertNoTag: (condition: boolean, message: string | number) => asserts condition =
-		assert;
-	assertNoTag(false, message);
-}
+// TODO: update usages of this to use @fluidframework/core-utils/internal directly.
+export { fail } from "@fluidframework/core-utils/internal";
 
 /**
  * Checks whether or not the given object is a `readonly` array.

packages/test/stochastic-test-utils/src/minification.ts

@@ -206,18 +206,7 @@ export class FuzzTestMinimizer<TOperation extends BaseOperation> {
 				return false;
 			}
 
-			const stackLines = error.stack.split("\n").map((s) => s.trim());
-
-			const stackTop = stackLines.findIndex((s) => s.startsWith("at"));
-
-			const message = stackLines[stackTop].startsWith("at assert ")
-				? // Reproduce based on the final two lines+col of the error if it is an assert error
-					// This ensures the same assert is triggered by the minified test
-					stackLines
-						.slice(stackTop, stackTop + 2)
-						.join("\n")
-				: // Otherwise the final line is sufficient
-					stackLines[stackTop];
+			const message = extractMessage(error.stack);
 
 			if (this.initialError === undefined) {
 				this.initialError = { message, op: lastOp };
@@ -230,3 +219,25 @@ export class FuzzTestMinimizer<TOperation extends BaseOperation> {
 		}
 	}
 }
+
+/**
+ * Collect relevant top portion of the stack.
+ * Include enough lines that the error doesn't look the same as too many other errors,
+ * but few enough that the stack doesn't include details not relevant to the error.
+ */
+export function extractMessage(stack: string): string {
+	const stackLines = stack.split("\n").map((s) => s.trim());
+
+	const stackTop = stackLines.findIndex((s) => s.startsWith("at"));
+
+	const linesToKeep: string[] = [];
+	for (const line of stackLines.slice(stackTop)) {
+		linesToKeep.push(line);
+		// Heuristically continue including lines if stack line matches this pattern:
+		if (!line.match(/^at (assert|fail) /)) {
+			break;
+		}
+	}
+
+	return linesToKeep.join("\n");
+}

packages/test/stochastic-test-utils/src/test/minification.spec.ts

@@ -0,0 +1,91 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { strict as assert } from "assert";
+
+import { assert as coreAssert, fail } from "@fluidframework/core-utils/internal";
+
+import { extractMessage } from "../minification.js";
+
+function requireLines(s: string, count = 1): void {
+	assert.equal(s.split("\n").length, count, `Expected ${count} lines in:\n${s}`);
+}
+
+describe("Minification", () => {
+	describe("extractMessage", () => {
+		it("non assert", () => {
+			function namedFunction() {
+				return new Error("message");
+			}
+			const e = namedFunction();
+			assert(e.stack !== undefined);
+			const message = extractMessage(e.stack);
+			requireLines(message);
+			assert.match(message, /^at namedFunction .*minification\.spec\.ts/);
+		});
+
+		it("node assert", () => {
+			function namedFunction(): Error {
+				try {
+					assert(false);
+				} catch (err: unknown) {
+					return err as Error;
+				}
+			}
+			const e = namedFunction();
+			assert(e.stack !== undefined);
+			const message = extractMessage(e.stack);
+			requireLines(message);
+			assert.match(message, /^at namedFunction .*minification\.spec\.ts/);
+		});
+
+		it("core assert", () => {
+			function namedFunction(): Error {
+				try {
+					coreAssert(false, "message");
+				} catch (err: unknown) {
+					return err as Error;
+				}
+			}
+			const e = namedFunction();
+			assert(e.stack !== undefined);
+			const message = extractMessage(e.stack);
+			requireLines(message, 3);
+			assert.match(message, /\nat namedFunction .*minification\.spec\.ts/);
+		});
+
+		it("node fail", () => {
+			function namedFunction(): Error {
+				try {
+					assert.fail();
+				} catch (err: unknown) {
+					return err as Error;
+				}
+			}
+			const e = namedFunction();
+			assert(e.stack !== undefined);
+			const message = extractMessage(e.stack);
+			// Interestingly assert.fail() doesn't include itself in the stack.
+			requireLines(message);
+			assert.match(message, /^at namedFunction .*minification\.spec\.ts/);
+		});
+
+		it("core fail", () => {
+			function namedFunction(): Error {
+				try {
+					fail("message");
+				} catch (err: unknown) {
+					return err as Error;
+				}
+			}
+			const e = namedFunction();
+			assert(e.stack !== undefined);
+			const message = extractMessage(e.stack);
+			requireLines(message, 2);
+			assert.match(message, /^at fail/);
+			assert.match(message, /\nat namedFunction .*minification\.spec\.ts/);
+		});
+	});
+});