@specific.dev/spectest 0.66.0 → 0.68.0

package/dist/harness/wrapper-rules.js

@@ -0,0 +1,422 @@
+// Blocking typecheck rules: control flow that a provenance wrapper makes
+// constant.
+//
+// `sdk/src/inspect.ts` returns every primitive leaf of a recorded op as a
+// `Carrier` — an object holding the value, with coercion sinks so template
+// interpolation, arithmetic, `==` and `JSON.stringify` all behave. Two things
+// a carrier cannot rescue, because JavaScript exposes no hook for either:
+//
+//   if (row.written)      // an object is ALWAYS truthy, even around `false`
+//   measured.rows === 2   // an object is NEVER === a primitive
+//
+// Both are constant, and both are silent. The first is the more expensive: a
+// `ctx.poll` predicate that collapses a wrapped `false` to `true` reports
+// success on attempt 1 and the suite runs on against data that never arrived
+// (reported 2026-08-30). `tsc` catches the second as TS2367 and says nothing
+// about the first — a truthiness test on an object type is legal TypeScript.
+//
+// WHY THESE MAY BLOCK A RUN WHEN `tsc`'s OWN DIAGNOSTICS MAY NOT
+// ---------------------------------------------------------------
+// The typecheck report is advisory because a `tsc` verdict is about the
+// DECLARED TYPES, and those can disagree with the program that actually runs,
+// in both directions:
+//
+//   - the types go stale: the global `fetch` is patched at runtime to record
+//     but keeps its raw `Response` type, so correct code is flagged;
+//   - narrowing is unsound: TypeScript does not reset a narrowed `let` across
+//     a callback, so `phase === "end"` after `[1,2].forEach(() => phase = "end")`
+//     is reported as having no overlap when at runtime it matches.
+//
+// The second is why TS2367 cannot gate a run even though it is exactly the
+// diagnostic that would have caught the reported bug.
+//
+// These rules ask a different question — *is this value a `Carrier`* — which
+// is a fact about the runtime representation, not an inference. Wrapping is
+// unconditional (see inspect.ts), so a value typed `Carrier<T>` IS an object
+// when the line executes. Narrowing cannot turn a carrier into a number, so
+// there is no unsoundness to inherit.
+//
+// {@link CODE_EQUALITY} is true of the run outright. {@link CODE_TRUTHY} is a
+// convention on top of it — read its note for why that still earns a gate, and
+// for the line neither rule crosses.
+//
+// SOUNDNESS CONDITIONS, both load-bearing:
+//
+//   1. `strictNullChecks` must be on. With it off, an optional leaf
+//      (`row.opt?: Carrier<string>`) reports as `Carrier<string>` rather than
+//      `Carrier<string> | undefined`, and `if (row.opt)` — a legitimate
+//      presence test, since `wrapChild` returns nullish RAW — would be flagged
+//      as a bug. The driver refuses to run rather than guess.
+//   2. A union carrying `null`/`undefined` is never flagged, for the same
+//      reason: that condition distinguishes present from absent and is correct.
+//
+// The type is identified from its printed form rather than from its symbol:
+// one round trip instead of several, and the whole decision stays a pure
+// function over a string, which is what the tests below drive. A user type
+// that happens to be called `Carrier<T>` would also be flagged — and would
+// also be an object at runtime, so the finding stays true.
+/**
+ * A condition on a wrapped value — always true. **Blocking**, but on different
+ * grounds from {@link CODE_EQUALITY}, and the difference is worth knowing.
+ *
+ * This rule is NOT a proof. Two things can hide a runtime nullish from the
+ * compiler: a row generic that overstates a column
+ * (`client<{ names: string }>` over a `string_agg` that returns NULL) and
+ * TypeScript's deliberately unsound array indexing (`rows[0]` is typed
+ * non-optional even when the array is empty). A nullish leaf comes back RAW
+ * from `wrapChild`, so in those shapes `if (rows[0]?.names)` really does tell
+ * present from absent, and "always true" is false about it — measured against
+ * a real suite on 2026-08-30 (`journal-note.ts:200`).
+ *
+ * It blocks anyway, as a CONVENTION rather than a verdict: *unwrap before
+ * branching on a wrapped value*, the same discipline the docs already teach
+ * for `===`. What makes that acceptable is that the fix is safe in every case
+ * — `?.unwrap()` short-circuits, so it never throws and never changes code
+ * that was already correct; it only removes the accident. And the accident is
+ * the worst failure this SDK has: a `ctx.poll` predicate that collapses a
+ * wrapped `false` to `true` passes on attempt 1, the suite runs on against
+ * data that never arrived, and neither the compiler nor the runtime says a
+ * word (reported 2026-08-30).
+ *
+ * The line this does not cross: a rule may demand more of the user's own code,
+ * but it may never fail a run over OUR stale types (the patched global
+ * `fetch`) or over the compiler's own bad inference (TS2367 across a
+ * callback). Those cost the user a fix they cannot make.
+ */
+export const CODE_TRUTHY = "SPECTEST2001";
+/**
+ * `===`/`!==` between a wrapped value and a plain one — always false/true.
+ * **Blocking.** Sound even when a row generic understates nullability: if the
+ * leaf is a carrier the comparison is false because an object never equals a
+ * primitive, and if it is raw nullish it is false because nullish does not
+ * equal the literal either. A nullish literal on the other side is excluded —
+ * see {@link equalityIsConstant}.
+ */
+export const CODE_EQUALITY = "SPECTEST2002";
+/**
+ * Split a printed type on its TOP-LEVEL `|`, leaving nested unions alone
+ * (`Carrier<A | B> | undefined` → [`Carrier<A | B>`, `undefined`]). Depth is
+ * tracked across every bracket kind because a printed type can hold object
+ * literals (`{ a: 1 | 2 }`), tuples and parenthesised function types.
+ */
+export function splitUnion(text) {
+    const parts = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i += 1) {
+        const c = text[i];
+        if (c === "<" || c === "(" || c === "[" || c === "{")
+            depth += 1;
+        else if (c === ">" || c === ")" || c === "]" || c === "}")
+            depth -= 1;
+        else if (c === "|" && depth === 0) {
+            parts.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    parts.push(text.slice(start).trim());
+    return parts.filter((p) => p.length > 0);
+}
+/** One union member that is the primitive carrier. Object/array/response
+ *  wrappers are deliberately NOT included: they are objects whether or not we
+ *  wrap them, so a condition on one is not made constant by the wrapper. */
+export function isCarrierMember(member) {
+    return /^Carrier<[\s\S]*>$/.test(member.trim());
+}
+/**
+ * Classify a printed type for the rules. `unknown`/`any`/an error type read as
+ * `plain`: the checker could not say what the value is, and a rule that blocks
+ * a run must not guess.
+ */
+export function classifyType(text) {
+    if (!text)
+        return "plain";
+    const members = splitUnion(text);
+    const nullish = members.filter((m) => m === "null" || m === "undefined");
+    const rest = members.filter((m) => m !== "null" && m !== "undefined");
+    if (rest.length === 0)
+        return "plain";
+    // A union mixing a carrier with a non-nullish plain type is not a shape the
+    // SDK produces. Blocking a run needs certainty, so an unrecognised shape
+    // reads as plain rather than as a finding.
+    if (!rest.every((m) => isCarrierMember(m)))
+        return "plain";
+    return nullish.length > 0 ? "nullable-carrier" : "carrier";
+}
+/** Source text that denotes a nullish literal. */
+export function isNullishLiteral(exprText) {
+    const t = exprText.trim();
+    return t === "null" || t === "undefined" || /^void\s+0$/.test(t);
+}
+/**
+ * Verdict for a strict `===`/`!==`. Blocking only when exactly one side is a
+ * definite carrier: two carriers compare object identity, which is a different
+ * mistake and not one this rule can prove constant.
+ *
+ * A comparison against a NULLISH LITERAL is never constant, whatever the type
+ * says. `wrapChild` hands a `null`/`undefined` leaf back RAW, so
+ * `row.setting === null` is the correct way to ask whether a column is null —
+ * and it answers correctly in both directions. The declared type cannot show
+ * this, because a row generic is the caller's own assertion
+ * (`client<{ setting: unknown }>`) and routinely understates nullability.
+ * Found in a real suite on 2026-08-30 (`document-export-settings.ts:64`),
+ * where flagging it would have blocked a passing test.
+ */
+export function equalityIsConstant(left, right, leftExpr = "", rightExpr = "") {
+    if (isNullishLiteral(leftExpr) || isNullishLiteral(rightExpr))
+        return false;
+    const l = classifyType(left);
+    const r = classifyType(right);
+    return (l === "carrier") !== (r === "carrier");
+}
+/**
+ * The real start of a node. A TypeScript node's `pos` is the end of the
+ * PREVIOUS node, so it includes the leading whitespace and comments; `tsc`
+ * reports the first meaningful character. Without this every column is a few
+ * places to the left and a finding above a comment points at the comment.
+ */
+export function startOfNode(text, pos) {
+    let i = Math.max(0, Math.min(pos, text.length));
+    while (i < text.length) {
+        const c = text[i];
+        if (c === " " || c === "\t" || c === "\r" || c === "\n") {
+            i += 1;
+        }
+        else if (c === "/" && text[i + 1] === "/") {
+            const nl = text.indexOf("\n", i);
+            i = nl === -1 ? text.length : nl + 1;
+        }
+        else if (c === "/" && text[i + 1] === "*") {
+            const close = text.indexOf("*/", i + 2);
+            i = close === -1 ? text.length : close + 2;
+        }
+        else {
+            break;
+        }
+    }
+    return i;
+}
+/** 1-indexed line/column for a character offset, matching `tsc` output. */
+export function lineColumnAt(text, pos) {
+    const clamped = Math.max(0, Math.min(pos, text.length));
+    let line = 1;
+    let lineStart = 0;
+    for (let i = 0; i < clamped; i += 1) {
+        if (text.charCodeAt(i) === 10) {
+            line += 1;
+            lineStart = i + 1;
+        }
+    }
+    return { line, column: clamped - lineStart + 1 };
+}
+/** Trim a source snippet for a message: one line, bounded. */
+export function snippet(text, pos, end) {
+    const raw = text.slice(Math.max(0, pos), Math.max(0, end)).trim();
+    const oneLine = raw.split("\n")[0]?.trim() ?? "";
+    return oneLine.length > 60 ? `${oneLine.slice(0, 57)}…` : oneLine;
+}
+export function truthyMessage(expr, typeText) {
+    const subject = expr ? `\`${expr}\`` : "This value";
+    return (`${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+        `runtime, so this condition is always true. A wrapped \`false\`, \`0\` or ` +
+        `\`""\` reads as truthy. Call \`.unwrap()\` before testing it.`);
+}
+export function equalityMessage(expr, typeText, negated) {
+    const subject = expr ? `\`${expr}\`` : "This value";
+    const verdict = negated ? "always true" : "always false";
+    return (`${subject} is \`${typeText}\` — a provenance wrapper, which is an object at ` +
+        `runtime and can never be strictly equal to a plain value, so this ` +
+        `comparison is ${verdict}. Call \`.unwrap()\` first, or assert with ` +
+        `\`expect(...)\`, which unwraps for you.`);
+}
+/** `TypeFlags.Object | TypeFlags.Union` — the only shapes a carrier can wear.
+ *  Filtering on the flags the batch call already returned keeps the printed
+ *  name (one round trip each) off every ordinary `boolean` condition. */
+const OBJECT_OR_UNION = (1 << 19) | (1 << 20);
+const SYNTAX = {
+    If: "IfStatement",
+    While: "WhileStatement",
+    DoWhile: "DoStatement",
+    For: "ForStatement",
+    Conditional: "ConditionalExpression",
+    Prefix: "PrefixUnaryExpression",
+    Binary: "BinaryExpression",
+};
+/**
+ * Collect the positions worth asking about in one file. Kept separate from the
+ * checker so the walk can be reasoned about (and extended) on its own.
+ */
+export function collectCandidates(statements, kindName, walk) {
+    const all = [];
+    const push = (n) => {
+        all.push(n);
+        walk(n, push);
+    };
+    for (const s of statements)
+        push(s);
+    const out = [];
+    for (const n of all) {
+        const k = kindName(n);
+        if (k === SYNTAX.If || k === SYNTAX.While || k === SYNTAX.DoWhile) {
+            const e = n.expression;
+            if (e)
+                out.push({ node: e, kind: "truthy" });
+        }
+        else if (k === SYNTAX.For || k === SYNTAX.Conditional) {
+            const e = n.condition;
+            if (e)
+                out.push({ node: e, kind: "truthy" });
+        }
+        else if (k === SYNTAX.Prefix) {
+            // `!x` — TypeScript's own always-truthy check misses this shape, which
+            // is why the rule cannot lean on TS2774.
+            if (kindName({ kind: n.operator }) === "ExclamationToken") {
+                const e = n.operand;
+                if (e)
+                    out.push({ node: e, kind: "truthy" });
+            }
+        }
+        else if (k === SYNTAX.Binary) {
+            const op = kindName({ kind: n.operatorToken?.kind });
+            const left = n.left;
+            const right = n.right;
+            if (!left || !right)
+                continue;
+            if (op === "AmpersandAmpersandToken" || op === "BarBarToken") {
+                out.push({ node: left, kind: "truthy" });
+            }
+            else if (op === "EqualsEqualsEqualsToken") {
+                out.push({ node: left, kind: "equality", other: right, negated: false });
+            }
+            else if (op === "ExclamationEqualsEqualsToken") {
+                out.push({ node: left, kind: "equality", other: right, negated: true });
+            }
+        }
+    }
+    return out;
+}
+export async function runWrapperRules(opts) {
+    const started = Date.now();
+    const done = (r) => ({
+        ...r,
+        durationMs: Date.now() - started,
+    });
+    let api;
+    try {
+        const base = opts.join(opts.typescriptDir, "dist");
+        const apiMod = (await import(opts.join(base, "api", "async", "api.js")));
+        const utils = (await import(opts.join(base, "ast", "utils.js")));
+        const visitor = (await import(opts.join(base, "ast", "visitor.js")));
+        const inst = new apiMod.API({ cwd: opts.dirname(opts.configFile) });
+        api = inst;
+        const snapshot = await inst.updateSnapshot({ openProjects: [opts.configFile] });
+        const project = (await snapshot.getProjects())[0];
+        if (!project)
+            return done({ status: "failed", diagnostics: [], detail: "no project" });
+        // Soundness condition 1 — see the header. Without strictNullChecks an
+        // optional carrier loses its `| undefined` and every presence test in the
+        // suite becomes a finding, so refuse rather than guess.
+        // `compilerOptions` is the file's raw options, not the resolved ones, so
+        // the `strict` family has to be folded by hand: an explicit
+        // `strictNullChecks` wins, otherwise `strict` supplies it.
+        const strictNullChecks = project.compilerOptions.strictNullChecks ??
+            project.compilerOptions.strict ??
+            false;
+        if (strictNullChecks !== true) {
+            return done({
+                status: "skipped",
+                diagnostics: [],
+                detail: "strictNullChecks is off; a wrapped optional cannot be told from a wrapped value",
+            });
+        }
+        const kindName = (n) => typeof n?.kind === "number" ? utils.formatSyntaxKind(n.kind) : "";
+        const walk = (n, visit) => {
+            try {
+                visitor.visitEachChild(n, (c) => {
+                    visit(c);
+                    return c;
+                }, undefined);
+            }
+            catch {
+                /* a node shape the walker cannot descend — its children are skipped */
+            }
+        };
+        const names = await project.program.getSourceFileNames();
+        const files = names.filter((f) => f.startsWith(`${opts.appDir}/`) && !f.includes("/node_modules/") && !f.endsWith(".d.ts"));
+        const diagnostics = [];
+        for (const file of files) {
+            const sf = await project.program.getSourceFile(file);
+            if (!sf)
+                continue;
+            const candidates = collectCandidates(sf.statements, kindName, walk);
+            if (candidates.length === 0)
+                continue;
+            // One batched checker call per file, then a printed name only for the
+            // types that could be a wrapper at all.
+            const nodes = candidates.flatMap((c) => (c.other ? [c.node, c.other] : [c.node]));
+            const types = await project.checker.getTypeAtLocation(nodes);
+            const printed = new Map();
+            for (let i = 0; i < nodes.length; i += 1) {
+                const t = types[i];
+                if (t && (t.flags & OBJECT_OR_UNION) !== 0) {
+                    printed.set(i, await project.checker.typeToString(t));
+                }
+            }
+            const text = await opts.readFile(file);
+            const rel = opts.relative(opts.appDir, file);
+            let idx = 0;
+            for (const c of candidates) {
+                const leftText = printed.get(idx);
+                idx += 1;
+                const rightText = c.other ? printed.get(idx) : undefined;
+                if (c.other)
+                    idx += 1;
+                const start = startOfNode(text, c.node.pos);
+                const where = lineColumnAt(text, start);
+                const expr = snippet(text, start, c.node.end);
+                if (c.kind === "truthy") {
+                    if (classifyType(leftText) !== "carrier")
+                        continue;
+                    diagnostics.push({
+                        file: rel,
+                        ...where,
+                        code: CODE_TRUTHY,
+                        message: truthyMessage(expr, leftText),
+                        blocking: true,
+                    });
+                    continue;
+                }
+                const otherStart = startOfNode(text, c.other.pos);
+                const otherExpr = snippet(text, otherStart, c.other.end);
+                if (!equalityIsConstant(leftText, rightText, expr, otherExpr))
+                    continue;
+                const carrierIsLeft = classifyType(leftText) === "carrier";
+                const node = carrierIsLeft ? c.node : c.other;
+                const at = carrierIsLeft ? start : otherStart;
+                diagnostics.push({
+                    file: rel,
+                    ...lineColumnAt(text, at),
+                    code: CODE_EQUALITY,
+                    message: equalityMessage(snippet(text, at, node.end), (carrierIsLeft ? leftText : rightText), c.negated === true),
+                    blocking: true,
+                });
+            }
+        }
+        return done({ status: "ok", diagnostics });
+    }
+    catch (err) {
+        return done({
+            status: "failed",
+            diagnostics: [],
+            detail: err?.message ?? String(err),
+        });
+    }
+    finally {
+        try {
+            api?.close();
+        }
+        catch {
+            /* the session is already gone */
+        }
+    }
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { McpHttpError, McpRpcError, McpAuthDeniedError, type Mcp, type McpOption
 import type { Mcp, McpOptions } from "./mcp.js";
 export type { Locator, GetByRoleOptions, GetByTextOptions, FilterOptions, ClickOptions, BoundingBox, FilePayload, InputFiles, } from "./locator.js";
 import type { Locator } from "./locator.js";
+import { type TextMatchOptions } from "./text-match.js";
 export type { UrlPattern } from "./url-match.js";
 import type { UrlPattern } from "./url-match.js";
 export type { Mobile, MobileApp } from "./mobile.js";
@@ -34,7 +35,8 @@ export type { InterceptHandler, InterceptNext, InterceptedRequest };
  */
 export interface Interception {
     hostname: string;
-    /** The normalised mount path (`"/"` when none was given). */
+    /** The normalised mount path parsed off the target (`"/"` when the
+     *  target was a bare hostname). */
     path: string;
     /** How many requests the interceptor has seen. Provenance-wrapped, so an
      *  `expect(outage.calls)` nests under the intercept step; `.unwrap()` for
@@ -381,12 +383,23 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * make your **own** backend misbehave for one test: force a 500 from an
      * API route, add latency, fail twice then pass, or just count calls.
      *
+     * `target` is the hostname, optionally with a mount path:
+     * `"app.test"` claims every request to that host, `"app.test/api/sync"`
+     * claims that path and everything below it (like `app.use(path, fn)`).
+     *
+     * `description` is what the environment now **does**, in the present
+     * tense — it is the step's whole title in the timeline and in the CLI's
+     * failure detail, so it is what tells a reader why the page under test
+     * went to its error state. Write the effect, not the act of intercepting
+     * (the step is already labelled INTERCEPT) and not the test's goal:
+     * `"the sync endpoint returns 503"`, not `"intercept sync"`, `"mock the
+     * API"` or `"test error handling"`. The handler's own source is shown
+     * under it, so the description carries the intent, never the mechanism.
+     *
      * Hono/Koa-style middleware: `(req, next)` where `next()` returns the real upstream's
      * response (a proxied service, or a fake). Return a `Response` to answer
      * yourself, `next()` to pass through, or change what `next()` returned.
-     * An optional mount `path` limits it to that path and everything below
-     * (`"/functions/v1/sync"`), like `app.use(path, fn)`. Interceptors run in
-     * registration order.
+     * Interceptors run in registration order.
      *
      * Only traffic that reaches the daemon can be intercepted: the browser,
      * `ctx.fetch`, and any container that calls the hostname — so the service
@@ -400,16 +413,18 @@ export interface SpectestContext<S extends ServicesMap = ServicesMap, F extends
      * `remove()`. Every request it sees is recorded under the intercept step.
      *
      * ```ts
-     * const outage = ctx.intercept("api.test", "/functions/v1/sync", () =>
-     *   new Response("boom", { status: 500 }));
+     * const outage = ctx.intercept(
+     *   "api.test/functions/v1/sync",
+     *   "the sync function returns 500",
+     *   () => new Response("boom", { status: 500 }),
+     * );
      * await page.getByRole("button", { name: "Sync" }).click();
      * await expect(page.getByText("Retry")).toBeVisible();
      * expect(outage.calls).toBe(1);
      * outage.remove();                           // the retry now reaches the real function
      * ```
      */
-    intercept(hostname: string, handler: InterceptHandler): Interception;
-    intercept(hostname: string, path: string, handler: InterceptHandler): Interception;
+    intercept(target: string, description: string, handler: InterceptHandler): Interception;
     /**
      * Mint a leaf certificate from the in-VM root CA and return the PEMs.
      *
@@ -1672,6 +1687,14 @@ interface Matchers {
 export interface Expectation extends Matchers {
     not: Matchers;
 }
+/** Options for the text matchers — playwright's set, same names, same
+ *  meanings. */
+export interface TextMatcherOptions extends TextMatchOptions {
+    timeout?: number;
+    /** Read `innerText` (what the page renders — hidden elements dropped,
+     *  `text-transform` applied) instead of `textContent`. */
+    useInnerText?: boolean;
+}
 /**
  * Auto-retrying web-first assertions for a {@link Locator} — Playwright's
  * `expect(locator)` matchers. Each polls the element until it passes or a
@@ -1687,14 +1710,27 @@ export interface LocatorMatchers {
     toBeHidden(opts?: {
         timeout?: number;
     }): Promise<void>;
-    /** The element's (trimmed) text equals `expected` (or matches a RegExp). */
-    toHaveText(expected: string | RegExp, opts?: {
-        timeout?: number;
-    }): Promise<void>;
-    /** The element's text contains `expected`. */
-    toContainText(expected: string, opts?: {
-        timeout?: number;
-    }): Promise<void>;
+    /**
+     * The element's text equals `expected`, or matches it when it is a RegExp.
+     *
+     * **Whitespace is normalized on both sides**, exactly as playwright does
+     * it: the text is trimmed and every run of whitespace becomes one space.
+     * So a typed space matches the no-break space (U+00A0) that
+     * `Intl.NumberFormat` puts between thousands, and a value wrapped across
+     * two lines in the markup matches the one-line string you wrote.
+     *
+     * Pass an **array** to assert over every element the locator matches, in
+     * order; the counts must then agree.
+     */
+    toHaveText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
+    /**
+     * The element's text contains `expected` — a substring, or a RegExp tested
+     * against the text. Whitespace is normalized as in {@link toHaveText}.
+     *
+     * An **array** asserts that the matched elements contain these texts in
+     * order; unlike `toHaveText` extra elements between them are allowed.
+     */
+    toContainText(expected: string | RegExp | Array<string | RegExp>, opts?: TextMatcherOptions): Promise<void>;
     /** The input's value equals `expected` (or matches a RegExp). */
     toHaveValue(expected: string | RegExp, opts?: {
         timeout?: number;