@specific.dev/spectest 0.26.0 → 0.27.0

package/dist/inspect.js

@@ -0,0 +1,429 @@
+// Provenance wrappers for op return values.
+//
+// When a tracked op (fetch, db query, browser.evaluate) records its
+// event, it wraps its return value via `wrap(value, sourceSeq)`. The
+// wrapper carries an `OP_TAG` describing which op produced it and the
+// access path within that op's payload. When the wrapped value reaches
+// `expect()`, the matcher reads the tag and attaches `sourceSeq` + `path`
+// to its AssertionEvent so the UI can nest the assertion under its
+// originating op.
+//
+// Two shapes of wrapper:
+//   - Objects/arrays: lazy `Proxy`. Reading a property returns a fresh
+//     wrapped child with the path extended. Structural shape stays raw:
+//     an array's `length` is a real number (provenance belongs on the
+//     data, not the container's size — `rows.length === 1` must work).
+//   - Primitives: a small `Carrier` object holding the value and tag.
+//     Coercion sinks (`valueOf`/`toString`/`toJSON`/`Symbol.toPrimitive`)
+//     recover the raw primitive, so template interpolation, arithmetic,
+//     loose equality, and `JSON.stringify` all behave. The one remaining
+//     sharp edge is strict `===` against a primitive (always false — an
+//     object can never `===` a number); `.unwrap()` first, and the
+//     `Carrier<T>` typing makes that a compile-time error in TS.
+//
+// Cannot tag: `null` / `undefined` (no place to attach a symbol) and
+// functions (we don't currently need to). Those pass through as-is — but a
+// nullish *leaf read* off a proxy is recorded in the pending-nullish register
+// below so `expect()` can still recover its provenance (see `adoptNullishTag`).
+//
+// Escape: every wrapper exposes `.unwrap()` returning the fully raw value (it
+// walks every wrapper layer, so one call always reaches raw). That is the
+// public escape hatch; there is no `unwrap(x)` free function — a spectest op
+// result is always wrapped (see below), so the value always has `.unwrap()`.
+// (`readRaw` is the internal, never-throws primitive `.unwrap()` and `expect()`
+// are built on; it isn't part of the public surface.)
+//
+// Wrapping is UNCONDITIONAL: a spectest op (fetch/exec/terminal/poll/db/
+// browser.evaluate) always returns a wrapped value, in every context — a test,
+// a `ctx.poll` predicate, `setup`, `eval`, a fake handler. Whether the op also
+// recorded a timeline *event* is a separate decision (the recorder may be
+// absent, paused, or have truncated the event): when there is no event the
+// wrapper simply carries no provenance (`sourceSeq: undefined`), so `expect()`
+// can't nest it under an op — but the wrapper SHAPE (`.unwrap()`, coercion
+// sinks, the proxy) is always present. That keeps `Wrapped`/`WrappedResponse`/
+// `Carrier<T>` honest at runtime everywhere, instead of silently collapsing to
+// a raw value wherever recording happened to be off.
+// Registered in the GLOBAL symbol registry (`Symbol.for`), not module-private
+// (`Symbol`), so a value tagged by ONE copy of this module unwraps correctly in
+// ANOTHER. This matters whenever two copies of the SDK load in the same runtime:
+// the in-VM daemon runs the baked SDK at /opt/spectest/sdk and mints the
+// provenance carriers (ctx.fetch / ctx.browser / db results), while a user's
+// test file resolving `@specific.dev/spectest` to a registry-pinned copy gets
+// its `expect`. With module-private symbols the two `UNWRAP`s differed, so
+// `expect`'s auto-unwrap silently no-op'd and wrapped assertions failed
+// nonsensically (`expect("Hello Spec").toContain("Hello")` -> false). The
+// control plane also repoints the dep at the baked copy so normally only one
+// copy loads; this is defense-in-depth for the cases where it can't (and only
+// takes full effect once both copies ship this `Symbol.for`).
+export const OP_TAG = Symbol.for("spectest.opTag");
+export const UNWRAP = Symbol.for("spectest.unwrap");
+/** Read the tag if present; returns undefined for raw values. */
+export function readTag(x) {
+    if (x === null || x === undefined)
+        return undefined;
+    if (typeof x !== "object" && typeof x !== "function")
+        return undefined;
+    return x[OP_TAG];
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Pending nullish-leaf register
+//
+// Reading a `null`/`undefined` leaf off a wrapped object (`dep.status.readyReplicas`
+// on a failed deployment) hands back a raw nullish value with no tag — a symbol
+// can't ride on `null`/`undefined`, and minting a stand-in object would break
+// every `=== null` / `if (!x)` in real code (see `wrap`). So the natural
+// `expect(dep.status.readyReplicas).toBeFalsy()` used to lose its provenance and
+// render as a disconnected top-level assertion, even though `field(...)` could
+// recover it manually.
+//
+// To make the natural form work too, the proxy *notes* every nullish leaf read
+// here (source op + access path). `expect()` consults the register when it
+// receives an untagged nullish value via `adoptNullishTag`, matching the most
+// recent note. The note is single-consume, freshest-wins, and invalidated by
+// any subsequent recorded op (the recorder calls `clearPendingNullish`), so the
+// window for misattribution is one untagged nullish read immediately followed by
+// an `expect` of an unrelated nullish literal with no op in between — narrow,
+// and the worst case points at a contextually-adjacent field rather than losing
+// the link entirely. The note never reaches program control flow: it is read
+// only inside `expect()`, which `readRaw`s back to the real nullish value.
+// ───────────────────────────────────────────────────────────────────────────
+let pendingNullish;
+function noteNullishLeaf(value, sourceSeq, path) {
+    pendingNullish = { value, tag: { sourceSeq, path: [...path] } };
+}
+/** Forget any pending nullish-leaf note. Called by the recorder whenever a new
+ *  op is recorded, so a note can't outlive the read that produced it. */
+export function clearPendingNullish() {
+    pendingNullish = undefined;
+}
+/**
+ * If `value` is an untagged `null`/`undefined` that matches the most recent
+ * nullish-leaf read, mint a tagged {@link makeCarrier} holder for it (the same
+ * stand-in `field`/`retag` use) and clear the note; otherwise return `value`
+ * unchanged. The holder is safe because it goes straight to `expect()`, which
+ * `readRaw`s it before matching — it never escapes into control flow.
+ */
+export function adoptNullishTag(value) {
+    if (value !== null && value !== undefined)
+        return value;
+    const p = pendingNullish;
+    if (!p || !Object.is(p.value, value))
+        return value;
+    pendingNullish = undefined;
+    return makeCarrier(value, p.tag.sourceSeq, p.tag.path);
+}
+/** If x is wrapped, return the raw value; otherwise return x. */
+export function readRaw(x) {
+    // Walks the chain — a value can carry more than one wrapper at once
+    // (e.g. a polled k8s pod is wrapped by the component's `withTagging`
+    // with the HTTP seq, then by `ctx.poll`'s `wrap(...)` with the wait
+    // seq). A single-step unwrap would still hand callers a proxy.
+    let cur = x;
+    while (cur !== null && cur !== undefined) {
+        const t = typeof cur;
+        if (t !== "object" && t !== "function")
+            return cur;
+        // Presence check, NOT `next === undefined`: a carrier minted by `field`
+        // may wrap `undefined` itself (`[UNWRAP] = undefined`). Testing the value
+        // would mistake that for "no wrapper" and hand the carrier object back, so
+        // a `toBeFalsy()` would see a truthy object.
+        if (!(UNWRAP in cur))
+            return cur;
+        const next = cur[UNWRAP];
+        if (next === cur)
+            return cur;
+        cur = next;
+    }
+    return cur;
+}
+/**
+ * Wrap a value so reads through it carry an `OpTag`. Recursion is lazy:
+ * a property read on an object Proxy wraps its child on demand.
+ */
+export function wrap(raw, sourceSeq, path = []) {
+    if (raw === null || raw === undefined)
+        return raw;
+    const t = typeof raw;
+    if (t === "object") {
+        return wrapObject(raw, sourceSeq, path);
+    }
+    if (t === "function")
+        return raw;
+    // primitive
+    return makeCarrier(raw, sourceSeq, path);
+}
+/**
+ * Like {@link wrap}, but for values read *through* a wrapped container, where a
+ * `null`/`undefined` leaf must still leave a provenance trail. `wrap` passes
+ * nullish through raw (a symbol can't ride on it); here we additionally
+ * {@link noteNullishLeaf note} the read so `expect()` can adopt the tag via
+ * {@link adoptNullishTag}. The returned value is identical to `wrap`'s — raw
+ * nullish or a proxy/carrier — so control flow is unaffected.
+ */
+function wrapChild(value, sourceSeq, path) {
+    if (value === null || value === undefined) {
+        noteNullishLeaf(value, sourceSeq, path);
+        return value;
+    }
+    return wrap(value, sourceSeq, path);
+}
+// Array methods whose return value derives from the array's contents.
+// We re-wrap their results so assertions on `arr.find(...)` etc. still
+// fold under the originating op. Predicates still see raw items (the
+// method runs on the raw target), so `===` comparisons keep working.
+const ARRAY_TAGGED_METHODS = new Set([
+    "find",
+    "findLast",
+    "at",
+    "map",
+    "filter",
+    "slice",
+    "flat",
+    "flatMap",
+    "concat",
+    "includes",
+    "indexOf",
+    "lastIndexOf",
+    "findIndex",
+    "findLastIndex",
+    "some",
+    "every",
+]);
+function wrapObject(raw, sourceSeq, path) {
+    const tag = { sourceSeq, path };
+    const isArray = Array.isArray(raw);
+    const handler = {
+        get(target, prop, receiver) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            if (prop === "unwrap") {
+                // Only intercept when the underlying object doesn't already have
+                // its own `unwrap` — otherwise we'd shadow a legitimate property.
+                // `readRaw` (not a bare `target`) so a value carrying more than one
+                // wrapper — e.g. a `ctx.poll` result whose inner value was already
+                // tagged by a component's `withTagging` — unwraps all the way to raw
+                // in one call, not just one layer.
+                if (!(prop in target)) {
+                    return () => readRaw(target);
+                }
+            }
+            // `.transform(label, fn)` — same shape/guard as `unwrap`: only intercept
+            // when the underlying object has no own `transform`, so a real data field
+            // named `transform` is never shadowed.
+            if (prop === "transform" && !(prop in target)) {
+                return makeTransform(readRaw(target), sourceSeq, path);
+            }
+            // Hide thenable-ness from `await`. We must never accidentally
+            // implement `then`, or `await fetch(...)` would resolve to the
+            // wrong thing if we ever wrapped a Promise (we don't, but be safe).
+            if (prop === "then" && !(prop in target))
+                return undefined;
+            const value = Reflect.get(target, prop, receiver);
+            if (typeof prop === "symbol") {
+                // Symbols (iterator, toPrimitive, etc.) — pass through bound.
+                return typeof value === "function"
+                    ? value.bind(target)
+                    : value;
+            }
+            // Container shape stays raw: `rows.length === 1` must be a plain
+            // number comparison, not carrier-vs-number (silently false).
+            // Provenance for "how many" assertions still works — `expect`
+            // accepts raw values, it just won't nest under the op.
+            if (isArray && prop === "length")
+                return value;
+            const childPath = path.concat(String(prop));
+            if (typeof value === "function") {
+                if (isArray && ARRAY_TAGGED_METHODS.has(prop)) {
+                    const method = value;
+                    const taggedPath = path.concat(`<${prop}>`);
+                    return (...args) => {
+                        const result = method.apply(target, args);
+                        return wrapChild(result, sourceSeq, taggedPath);
+                    };
+                }
+                // Other methods stay bound to the raw target; their return
+                // values aren't wrapped here — call sites that need
+                // promise-returning methods (e.g. Response.json()) install a
+                // bespoke wrapper.
+                return value.bind(target);
+            }
+            return wrapChild(value, sourceSeq, childPath);
+        },
+        has(target, prop) {
+            if (prop === OP_TAG || prop === UNWRAP)
+                return true;
+            return Reflect.has(target, prop);
+        },
+        // Block writes; wrappers are read-only views.
+        set() {
+            return false;
+        },
+        deleteProperty() {
+            return false;
+        },
+    };
+    return new Proxy(raw, handler);
+}
+// The `.transform(label, fn)` method every wrapper (carrier + object/array
+// proxy) carries — the value-level analogue of `.unwrap()`. It runs the raw
+// value through `fn` and re-`wrap`s the result with `path` extended by a
+// `<label>` derived-step marker, so the decoded value keeps the source op's
+// provenance (`sourceSeq`) and stays navigable: a later `expect(...)` on it, or
+// on a subfield, still nests under the originating op (`secret.data.config.<json>.tier`).
+// `label` is a plain word; the `<…>` brackets are added here so they never leak
+// into the call site (the same convention array methods use, `<find>`/`<map>`).
+// A throw in `fn` (a non-string value, malformed base64/JSON) is rethrown
+// prefixed with `<label>:`, failing the test at the bad value.
+function makeTransform(raw, sourceSeq, path) {
+    return (label, fn) => {
+        const nextPath = [...path, `<${label}>`];
+        let result;
+        try {
+            result = fn(raw);
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new Error(`<${label}>: ${detail}`);
+        }
+        return wrap(result, sourceSeq, nextPath);
+    };
+}
+function makeCarrier(raw, sourceSeq, path) {
+    const tag = { sourceSeq, path };
+    return {
+        [OP_TAG]: tag,
+        [UNWRAP]: raw,
+        unwrap: () => raw,
+        transform: makeTransform(raw, sourceSeq, path),
+        // Coercion sinks recover the raw primitive instead of inheriting
+        // Object.prototype's defaults ("[object Object]" / NaN / {}). A
+        // carrier interpolated into a string, fed to arithmetic, `==`, or
+        // `JSON.stringify` now behaves like its value — silent wrongness
+        // (a bogus "[object Object]" namespace in a kubectl command) was
+        // the most expensive failure mode this wrapper ever produced.
+        valueOf: () => raw,
+        toString: () => String(raw),
+        toJSON: () => raw,
+        [Symbol.toPrimitive]: () => raw,
+    };
+}
+// ───────────────────────────────────────────────────────────────────────────
+// Provenance-preserving field selection
+//
+// The proxy/carrier only carries the OpTag across *property reads* (and a
+// whitelist of array methods), and it can't carry it across `null`/`undefined`
+// at all — those are primitives with nowhere to hang a symbol, and `wrap`
+// passes them through raw. So `expect(row.deleted_at).toBe(null)` reaches
+// `expect()` as a bare `null` with no tag and renders as a disconnected
+// top-level row. `field` recovers the link by tagging from the *container*.
+// (A decoded value loses its tag the same way, through the decode; the
+// `.transform(label, fn)` method every wrapper carries (see `makeTransform`)
+// recovers it — it runs the still-tagged value through `fn` and re-`wrap`s the
+// result with the source path extended by a `<label>` marker.)
+// ───────────────────────────────────────────────────────────────────────────
+/**
+ * Re-tag a value against an existing source op. Uses the normal `wrap` for
+ * non-nullish results (object → proxy, primitive → carrier) but a
+ * {@link makeCarrier} *holder* for `null`/`undefined` — those can't hold a
+ * symbol, and `wrap` deliberately passes them through raw. The holder is an
+ * object masquerading as null/undefined, which is ONLY safe because it never
+ * escapes into program control flow: it goes straight to `expect()`, which
+ * `readRaw`s it back to the real value before matching.
+ */
+function retag(raw, sourceSeq, path) {
+    return raw === null || raw === undefined
+        ? makeCarrier(raw, sourceSeq, path)
+        : wrap(raw, sourceSeq, path);
+}
+/**
+ * Provenance-preserving, null-safe field selector — for asserting on a leaf
+ * that is `null`/`undefined`. Reading such a leaf off a wrapped object hands
+ * back a raw `null`/`undefined` (a symbol tag can't ride on those, and minting
+ * a stand-in object would break every `=== null` / `if (!x)` in real code), so
+ * the raw value alone loses its link to the originating op. `field` reads the
+ * tag from the *container* and navigates the raw value, returning a tagged
+ * handle even when the leaf is nullish — safe because the handle only ever
+ * feeds `expect()`. Pass it straight to `expect(...)`; works with every matcher.
+ *
+ * Mostly redundant now: the plain `expect(dep.status.readyReplicas).toBeFalsy()`
+ * form recovers provenance on its own — the proxy notes each nullish leaf read
+ * and `expect` adopts the note (see {@link adoptNullishTag}). Reach for `field`
+ * when the nullish read and the `expect` are separated by another recorded op
+ * (which clears the note), or to make the navigation explicit.
+ *
+ * ```ts
+ * expect(field(created, "branched_from_environment_id")).toBe(null);
+ * expect(field(dep, "status", "readyReplicas")).toBeFalsy();
+ * ```
+ */
+export function field(value, ...path) {
+    const tag = readTag(value);
+    let cur = readRaw(value);
+    for (const key of path) {
+        if (cur === null || cur === undefined) {
+            cur = undefined;
+            break;
+        }
+        cur = cur[key];
+    }
+    if (!tag)
+        return cur;
+    return retag(cur, tag.sourceSeq, [...tag.path, ...path.map(String)]);
+}
+/**
+ * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
+ * `statusText` / `url` / `redirected` / `type` return carriers tagged
+ * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
+ * resolved value wrapped under `path: ["body"]`. Everything else passes
+ * through bound to the real Response.
+ */
+export function wrapResponse(res, sourceSeq) {
+    const tag = { sourceSeq, path: [] };
+    const carrierProps = new Set([
+        "status",
+        "ok",
+        "statusText",
+        "url",
+        "redirected",
+        "type",
+    ]);
+    const bodyMethods = new Set(["json", "text"]);
+    const handler = {
+        get(target, prop) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            // Full recursive unwrap (see the note in `wrapObject`).
+            if (prop === "unwrap")
+                return () => readRaw(target);
+            if (prop === "then")
+                return undefined;
+            if (typeof prop === "string" && carrierProps.has(prop)) {
+                const value = target[prop];
+                return wrap(value, sourceSeq, [prop]);
+            }
+            if (typeof prop === "string" && bodyMethods.has(prop)) {
+                const fn = target[prop];
+                if (typeof fn !== "function")
+                    return fn;
+                return async (...args) => {
+                    const value = await fn.apply(target, args);
+                    return wrap(value, sourceSeq, ["body"]);
+                };
+            }
+            const value = target[prop];
+            return typeof value === "function"
+                ? value.bind(target)
+                : value;
+        },
+        has(target, prop) {
+            if (prop === OP_TAG || prop === UNWRAP)
+                return true;
+            return Reflect.has(target, prop);
+        },
+    };
+    return new Proxy(res, handler);
+}