assertledger 1.4.0 → 1.5.0

package/integrations/bun/preload.mjs

@@ -14,11 +14,62 @@ if (!path.isAbsolute(root ?? "")) {
 const preloadPath = fileURLToPath(import.meta.url);
 const safeApply = Reflect.apply.bind(Reflect);
 const safeGet = Reflect.get.bind(Reflect);
+const ownDescriptor = Reflect.getOwnPropertyDescriptor.bind(Reflect);
+const prototypeOf = Reflect.getPrototypeOf.bind(Reflect);
+const stringReplace = String.prototype.replace;
+const stringSplit = String.prototype.split;
+const stringTrim = String.prototype.trim;
+const stringStartsWith = String.prototype.startsWith;
+const isErrorInstance = Object.prototype.isPrototypeOf.bind(Error.prototype);
+const ANSI_SGR = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "gu");
+const LINE_BREAK = /\r?\n/u;
+const fileKey = (file) =>
+  process.platform === "win32" ? path.resolve(file).toLowerCase() : path.resolve(file);
+
+// A designated selection runs one existing test ("run") or only loads its file ("load"). Without it
+// the preload keeps the candidate-file behavior: only assertSame failures can be owned.
+const designatedSelection = (() => {
+  const value = process.env.ASSERTLEDGER_BUN_DESIGNATED;
+  if (value === undefined) return undefined;
+  const parsed = JSON.parse(value);
+  if (parsed?.mode !== "run" && parsed?.mode !== "load") {
+    throw new Error("ASSERTLEDGER_BUN_PRELOAD_CONFIGURATION_INVALID");
+  }
+  return parsed;
+})();
+const designatedKeys = (
+  designatedSelection === undefined
+    ? []
+    : designatedSelection.mode === "run"
+      ? [designatedSelection.test]
+      : designatedSelection.tests
+).map((test) => JSON.stringify([fileKey(path.resolve(root, test.file)), ...test.path]));
+// The expected line may be copied from Bun's output, which prefixes "error:".
+const expectedFailure =
+  designatedSelection?.mode === "run" && typeof designatedSelection.expectedFailure === "string"
+    ? designatedSelection.expectedFailure
+        .replace(ANSI_SGR, "")
+        .split(LINE_BREAK)[0]
+        .trim()
+        .replace(/^error:\s*/u, "")
+    : null;
+
+/** The first line of a failure message without terminal colors, as Bun prints it after "error:". */
+function failureSignature(error) {
+  const descriptor = ownDescriptor(error, "message");
+  const message = typeof descriptor?.value === "string" ? descriptor.value : "";
+  const plain = safeApply(stringReplace, message, [ANSI_SGR, ""]);
+  return safeApply(stringTrim, safeApply(stringSplit, plain, [LINE_BREAK])[0] ?? "", []);
+}
+
 const rawAssertSame = assertionHelper.assertSame;
 const verifyIssuedError = assertionHelper.isAssertSameFailure;
 const issuedDuringTest = new WeakMap();
 const markIssuingTest = WeakMap.prototype.set.bind(issuedDuringTest);
 const issuingTest = WeakMap.prototype.get.bind(issuedDuringTest);
+const expectIssued = new WeakMap();
+const markExpectIssued = WeakMap.prototype.set.bind(expectIssued);
+const expectIssuingTest = WeakMap.prototype.get.bind(expectIssued);
 const activeTestExecution = new AsyncLocalStorage();
 const currentTestId = AsyncLocalStorage.prototype.getStore.bind(activeTestExecution);
 const runInTest = AsyncLocalStorage.prototype.run.bind(activeTestExecution);
@@ -31,6 +82,71 @@ function scopedAssertSame(...arguments_) {
     throw error;
   }
 }
+
+// Only a built-in matcher, present before any test file can extend expect, can issue an owned
+// failure, and only when its message has Bun's matcher form. Usage errors and custom matchers stay
+// ordinary errors.
+const nativeExpect = bunTest.expect;
+const builtInMatchers = new Set();
+const matcherChains = new Set(["not", "resolves", "rejects"]);
+const matcherPrototype =
+  designatedSelection === undefined ? null : prototypeOf(nativeExpect(undefined));
+for (const name of matcherPrototype === null ? [] : Reflect.ownKeys(matcherPrototype)) {
+  const descriptor = ownDescriptor(matcherPrototype, name);
+  if (typeof name === "string" && name !== "constructor" && typeof descriptor?.value === "function")
+    builtInMatchers.add(name);
+}
+const hasBuiltInMatcher = Set.prototype.has.bind(builtInMatchers);
+const isMatcherChain = Set.prototype.has.bind(matcherChains);
+function markMatcherFailure(error, id) {
+  if (id === undefined || !isErrorInstance(error)) return;
+  const signature = failureSignature(error);
+  if (safeApply(stringStartsWith, signature, ["expect("]))
+    markExpectIssued(error, { id, signature });
+}
+function scopedMatchers(matchers) {
+  return new Proxy(matchers, {
+    get(target, property) {
+      const value = safeGet(target, property, target);
+      if (typeof property === "string" && isMatcherChain(property)) return scopedMatchers(value);
+      if (typeof value !== "function") return value;
+      if (typeof property !== "string" || !hasBuiltInMatcher(property)) return value.bind(target);
+      return (...arguments_) => {
+        const id = currentTestId();
+        try {
+          const result = safeApply(value, target, arguments_);
+          return result && typeof result.then === "function"
+            ? Promise.resolve(result).catch((error) => {
+                markMatcherFailure(error, id);
+                throw error;
+              })
+            : result;
+        } catch (error) {
+          markMatcherFailure(error, id);
+          throw error;
+        }
+      };
+    },
+  });
+}
+const scopedExpect = new Proxy(nativeExpect, {
+  apply(target, thisArg, arguments_) {
+    return scopedMatchers(safeApply(target, thisArg, arguments_));
+  },
+  get(target, property) {
+    const value = safeGet(target, property, target);
+    return typeof value === "function" ? value.bind(target) : value;
+  },
+});
+
+/** Whether a designated test's failure is an owned assertion with the expected first line. */
+function designatedFailureOwned(error, id) {
+  const assertSameOwned = verifyIssuedError(error) && issuingTest(error) === id;
+  const expectOwned = expectIssuingTest(error)?.id === id;
+  if (!assertSameOwned && !expectOwned) return false;
+  return expectedFailure === null || failureSignature(error) === expectedFailure;
+}
+
 const stringify = JSON.stringify.bind(JSON);
 const evidenceKey = Buffer.alloc(32);
 let received = 0;
@@ -71,7 +187,19 @@ function registrationFile() {
   throw new Error("ASSERTLEDGER_BUN_REGISTRATION_FILE_UNAVAILABLE");
 }
 
-function wrapRegistration(native, cache) {
+// Describe names enclosing the registration in progress. A templated (`each`) or non-string name
+// can never match a designated path.
+const describeStack = [];
+const UNNAMED = Symbol("unnamed");
+
+function designatedIndex(file, name) {
+  if (designatedSelection === undefined || describeStack.includes(UNNAMED) || name === UNNAMED) {
+    return -1;
+  }
+  return designatedKeys.indexOf(JSON.stringify([fileKey(file), ...describeStack, name]));
+}
+
+function wrapRegistration(native, cache, templated = false) {
   if (cache.has(native)) return cache.get(native);
   const wrapper = new Proxy(native, {
     apply(target, thisArg, arguments_) {
@@ -80,14 +208,25 @@ function wrapRegistration(native, cache) {
       );
       if (callbackIndex < 0) {
         const result = safeApply(target, thisArg, arguments_);
-        return typeof result === "function" ? wrapRegistration(result, cache) : result;
+        return typeof result === "function" ? wrapRegistration(result, cache, templated) : result;
       }
       const callback = arguments_[callbackIndex];
       const file = registrationFile();
+      const name = !templated && typeof arguments_[0] === "string" ? arguments_[0] : UNNAMED;
+      const designated = designatedIndex(file, name);
+      if (designatedSelection?.mode === "load") {
+        // Loading registers nothing: the file and every module it imports are evaluated only.
+        record({ kind: "registered", file, designated });
+        return undefined;
+      }
       const wrappedArguments = [...arguments_];
       wrappedArguments[callbackIndex] = function (...callbackArguments) {
         const id = randomUUID();
-        record({ kind: "found", id, file });
+        record(
+          designatedSelection === undefined
+            ? { kind: "found", id, file }
+            : { kind: "found", id, file, designated: designated >= 0 },
+        );
         return runInTest(id, () => {
           const passed = (value) => {
             record({ kind: "end", id, status: "pass" });
@@ -98,7 +237,10 @@ function wrapRegistration(native, cache) {
               kind: "end",
               id,
               status: "fail",
-              owned: verifyIssuedError(error) && issuingTest(error) === id,
+              owned:
+                designatedSelection === undefined
+                  ? verifyIssuedError(error) && issuingTest(error) === id
+                  : designated >= 0 && designatedFailureOwned(error, id),
             });
             throw error;
           };
@@ -117,7 +259,42 @@ function wrapRegistration(native, cache) {
     get(target, property, receiver) {
       const value = safeGet(target, property, receiver);
       return typeof value === "function" && property !== "constructor"
-        ? wrapRegistration(value.bind(target), cache)
+        ? wrapRegistration(value.bind(target), cache, templated || property === "each")
+        : value;
+    },
+  });
+  cache.set(native, wrapper);
+  return wrapper;
+}
+
+function wrapDescribe(native, cache, templated = false) {
+  if (cache.has(native)) return cache.get(native);
+  const wrapper = new Proxy(native, {
+    apply(target, thisArg, arguments_) {
+      const callbackIndex = arguments_.findIndex(
+        (value, index) => typeof value === "function" && (index > 0 || arguments_.length === 1),
+      );
+      if (callbackIndex < 0) {
+        const result = safeApply(target, thisArg, arguments_);
+        return typeof result === "function" ? wrapDescribe(result, cache, templated) : result;
+      }
+      const callback = arguments_[callbackIndex];
+      const name = !templated && typeof arguments_[0] === "string" ? arguments_[0] : UNNAMED;
+      const wrappedArguments = [...arguments_];
+      wrappedArguments[callbackIndex] = function (...callbackArguments) {
+        describeStack.push(name);
+        try {
+          return safeApply(callback, this, callbackArguments);
+        } finally {
+          describeStack.pop();
+        }
+      };
+      return safeApply(target, thisArg, wrappedArguments);
+    },
+    get(target, property, receiver) {
+      const value = safeGet(target, property, receiver);
+      return typeof value === "function" && property !== "constructor"
+        ? wrapDescribe(value.bind(target), cache, templated || property === "each")
         : value;
     },
   });
@@ -150,6 +327,7 @@ function wrapHook(nativeHook) {
 const cache = new WeakMap();
 const wrappedTest = wrapRegistration(bunTest.test, cache);
 const wrappedIt = wrapRegistration(bunTest.it, cache);
+const describeCache = new WeakMap();
 bunTest.mock.module("bun:test", () => ({
   ...bunTest,
   test: wrappedTest,
@@ -158,6 +336,9 @@ bunTest.mock.module("bun:test", () => ({
   afterAll: wrapHook(bunTest.afterAll),
   beforeEach: wrapHook(bunTest.beforeEach),
   afterEach: wrapHook(bunTest.afterEach),
+  ...(designatedSelection === undefined
+    ? {}
+    : { describe: wrapDescribe(bunTest.describe, describeCache), expect: scopedExpect }),
 }));
 bunTest.mock.module("assertledger/bun", () => ({
   ...assertionHelper,

package/integrations/bun-native/README.md

@@ -0,0 +1,86 @@
+# Native Bun collection profile 1.0.0
+
+This profile is separate from the frozen helper-only Bun adapter. It requires
+Bun 1.4.2, revision 744846f844374847c902b5e7fd59b4342a51ef99.
+The outer Node process runs the driver with argument arrays and a bounded process
+tree; the driver loads the signed-pipe preload and checks complete JUnit evidence.
+
+The outer Node driver exits 0 whenever it emits a complete report, including
+reports of assertion failures or operational inner Bun failures. The report's
+`exitCode` retains the inner Bun exit code and its `outcome` retains the semantic
+classification. Driver exceptions, nonzero or missing outer exit codes, signals,
+process errors, timeouts and truncated output invalidate collection regardless
+of a previously emitted report. This separates transport completion from test
+outcome, including on Windows where forced termination may appear as exit 1
+without a signal. This internal native profile contract does not change the
+frozen helper adapter protocols.
+
+The internal native report now always includes `assertionFailureFiles`: the
+sorted, unique relative test-file paths owning issued assertions that failed.
+These paths come from controlled test-registration IDs and failure events, never
+from error stacks or helper locations. An attributed `ASSERTION_FAILURE` report
+requires a nonempty subset of `testFiles`; passing and operational reports carry
+an empty array. Counts, declared files, attribution and inner exit status must
+agree with the outcome. Consumers must use these actual failure owners when
+evaluating a required suite, so a failure in another collected file cannot credit
+a passing suite. This is an additive migration of the unreleased native profile;
+old native reports without this field are refused. Frozen v1-v4 helper reports
+and their schema versions are unchanged.
+
+The collector translates driver filesystem keys back to the declared test-file
+names before returning `testFiles` and `assertionFailureFiles`. These outward
+facts use sorted, unique POSIX relative paths and preserve declared case, such as
+`Nested/Example.test.ts`, on every host. Aliased declarations that normalize to
+the same filesystem key, or observations without an unambiguous declared name,
+invalidate collection. Internal driver path normalization remains host-specific.
+
+The qualified forms are TypeScript tests importing `bun:test`, `test`, `it`,
+`describe`, async functions, helper-module imports, `test.each`, native `expect`
+matchers and `not`/`resolves`/`rejects` chains. The qualified matcher names are
+`toBe`, `toEqual`, `toStrictEqual`, `toHaveProperty`, and `toThrow`; each has
+executable reference, target and neutral witnesses. Comparison operands and
+arguments must be primitive values or recursively passive plain objects/arrays:
+accessors, functions, proxies, custom prototypes and custom coercions are refused
+before matcher issuance. `toHaveProperty` accepts a simple dotted identifier path
+and an optional passive expected value. `toThrow` accepts a function and an optional
+string expectation, or a rejected native Promise with a plain Error. Callback
+errors are tracked separately from errors issued by the native matcher; active
+returned/thrown values invalidate collection. All other matcher names, asymmetric
+matchers and static expect helpers are explicitly unqualified.
+A matcher failure is attributed through the issuing test's
+async-local identity and an error WeakMap. Test errors are never classified from
+their message or JUnit failure text. Cross-test rethrows, hooks, collection errors,
+timeouts, skipped or missing tests, unmatched events and report inconsistency
+cannot establish a detection. Rejected inputs under `resolves`, TypeError and
+RangeError remain operational failures. Custom matchers (`expect.extend`) are
+explicitly unqualified.
+
+Both the outer process timeout and Bun's per-test timeout are operational failures.
+JUnit `TimeoutError` observations invalidate collection even when a synchronous
+callback finishes before the outer budget and throws an owned matcher error after
+its per-test deadline. This observation matches the existing v4 Bun driver's
+timeout handling; its private JUnit parser is not imported as a new dependency.
+
+The Node compatibility forms `node:test` default/named registrations with callback
+contexts (`t.after`), generated parameterized registrations, helper imports and
+`node:assert/strict` `ok`, `equal` and `strictEqual` assertions are qualified under
+the pinned Bun revision, with reference/target/neutral witnesses for each name.
+Their operands and optional message must be passive. All other assertion names,
+including callback-bearing `throws` and `rejects`, are explicitly unqualified.
+Native Node AssertionError is attributed only when issued by the wrapped assertion
+function in the current test. Manually constructed errors and failing after hooks
+remain operational failures.
+Snapshots, mocks, global-only registrations, callback-style completion, browser
+tests, and other runtime versions need additional qualification witnesses.
+Successful collection is an observation, not a campaign admission or readiness
+claim.
+
+Every declared test file must start at least one test; an empty or missing file
+beside an otherwise passing suite invalidates collection. Successful facts include
+the sorted relative paths of files that actually started tests (`testFiles`).
+The collector exposes binary, driver and preload identities. The consuming
+campaign must bind test/helper/configuration input digests and all world identities.
+The pipe MAC detects accidental or unsophisticated report substitution; this is
+trusted-local, unsandboxed execution. It is not an OS boundary or an authentication
+of a hostile producer. Candidates can execute arbitrary code in that process.
+Replay does not reexecute the tests or authenticate their producer.