@specific.dev/spectest 0.67.0 → 0.69.0

package/dist/browser.js

@@ -1406,7 +1406,7 @@ function buildBackend(holder, recorder, buildOpts) {
             }, { wrap: true });
         },
         async waitForFunction(description, fn, arg, options = {}) {
-            const timeoutMs = options.timeout ?? 5_000;
+            const timeoutMs = options.timeout ?? DEFAULT_ACTION_TIMEOUT_MS;
             const intervalMs = options.polling ?? 100;
             const src = typeof fn === "string" ? fn : fn.toString();
             const t = truncateUtf8(src);

package/dist/daemon.js

@@ -39,6 +39,7 @@ import { summarizeBuildKit } from "./harness/buildkit-progress.js";
 import { LOG_DELTA_MAX_BYTES, capMiddle, streamDelta } from "./harness/log-delta.js";
 import { resolveHostPath as resolveVolumeHostPath, sanitizeSegment, } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { runWrapperRules } from "./harness/wrapper-rules.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import { isTextualContentType, looksBinary, omittedBody, parseContentLength, } from "./harness/http-body.js";
 import { encodeRegistry } from "./harness/names-registry.js";
@@ -4133,7 +4134,16 @@ async function pollCall(description, fn, opts) {
         lastIterStartIdx = recorderEventCount();
         try {
             const v = await fn();
-            if (v !== null && v !== undefined && v !== false) {
+            // Decide on the RAW value. A predicate that hands back a wrapped leaf
+            // (`rows[0].written` off an instrumented query) returns a `Carrier`,
+            // and a carrier around `false` is an object — truthy, and `!== false`.
+            // Without this a poll accepted a condition that was never met and the
+            // test ran on against stale data, which is worse than a timeout: there
+            // is no failure to read (reported 2026-08-30, run_0cjtx0dbzjs5yq6vwefkk,
+            // where `written: false` passed the wait on attempt 1 in 3 ms).
+            // `value` keeps the WRAPPED form so the return still carries provenance.
+            const ready = readRaw(v);
+            if (ready !== null && ready !== undefined && ready !== false) {
                 value = v;
                 success = true;
                 break;
@@ -5061,7 +5071,11 @@ async function evalCode(code, secrets) {
 // its own `typescript` in spectest/package.json wins. A project tsconfig.json
 // wins over the generated one the same way.
 // ────────────────────────────────────────────────────────────────────────
-const TYPECHECK_DIR = "/opt/spectest/typecheck";
+/** Where the baked compiler lives. Overridable so the typecheck — and the
+ *  blocking rules, which always use THIS copy rather than the project's own —
+ *  can be driven outside a VM (same convention as
+ *  `SPECTEST_COVERAGE_TOOLS_DIR`). */
+const TYPECHECK_DIR = process.env.SPECTEST_TYPECHECK_DIR ?? "/opt/spectest/typecheck";
 /** Cap on errors shipped in the report; `totalErrors` carries the true count. */
 const TYPECHECK_ERROR_CAP = 50;
 let TYPECHECK = null;
@@ -5176,7 +5190,17 @@ async function runTypecheck() {
         return { status: "failed", errors: [], totalErrors: 0, durationMs, detail: "typecheck timed out" };
     }
     const { errors, total, suppressed } = parseTscOutput(res.stdout + res.stderr);
-    if (errors.length === 0) {
+    const wrapper = await runWrapperRulesReport(config);
+    const strip = ({ file, line, column, code, message }) => ({
+        file,
+        line,
+        column,
+        code,
+        message,
+    });
+    const blocking = wrapper.filter((d) => d.blocking).map(strip);
+    const advisory = wrapper.filter((d) => !d.blocking).map(strip);
+    if (errors.length === 0 && wrapper.length === 0) {
         // Exit 0 → clean. Non-zero with no *user-file* diagnostics is either
         // all-suppressed (still ok from the user's perspective) or a compiler
         // crash (config not found, OOM) — surface the latter.
@@ -5189,7 +5213,51 @@ async function runTypecheck() {
         }
         return { status: "ok", errors: [], totalErrors: 0, durationMs };
     }
-    return { status: "errors", errors, totalErrors: total, durationMs };
+    // The wrapper findings ride the same list the CLI and the dashboard already
+    // render; `blocking` is a second view of the ones that also fail the run, so
+    // nothing has to learn a new shape to show them. Blocking leads, because
+    // `errors` is capped and the entries that stopped the run must never be the
+    // ones the cap drops.
+    const all = [...blocking, ...advisory, ...errors];
+    return {
+        status: "errors",
+        errors: all.slice(0, TYPECHECK_ERROR_CAP),
+        totalErrors: total + wrapper.length,
+        durationMs,
+        ...(blocking.length > 0 ? { blocking } : {}),
+    };
+}
+/**
+ * The blocking rules, run against the BAKED compiler whatever the project
+ * pins. Best-effort in every direction: an install that predates the API, a
+ * config the rules cannot open, or a throw from `typescript/unstable/*` all
+ * yield no findings, so a run proceeds exactly as it does today. Only a
+ * definite finding can stop one.
+ */
+async function runWrapperRulesReport(config) {
+    const typescriptDir = path.join(TYPECHECK_DIR, "node_modules", "typescript");
+    if (!existsSync(path.join(typescriptDir, "dist", "api", "async", "api.js")))
+        return [];
+    try {
+        const run = await runWrapperRules({
+            typescriptDir,
+            configFile: config,
+            appDir: APP_DIR,
+            readFile: (f) => fs.readFile(f, "utf8"),
+            relative: path.relative,
+            join: path.join,
+            dirname: path.dirname,
+        });
+        if (run.status !== "ok") {
+            console.warn(`[typecheck] wrapper rules ${run.status}: ${run.detail ?? "no detail"}`);
+            return [];
+        }
+        return run.diagnostics;
+    }
+    catch (err) {
+        console.warn(`[typecheck] wrapper rules threw: ${err?.message ?? err}`);
+        return [];
+    }
 }
 /** Run `job` under a mutual-exclusion slot, refusing if one is held. */
 async function exclusive(state, slot, busy, job) {

package/dist/harness/wrapper-rules.d.ts

@@ -0,0 +1,149 @@
+/** A finding, shaped like the `TypecheckError` the report already carries. */
+export interface WrapperDiagnostic {
+    /** Path relative to the app dir, matching the advisory diagnostics. */
+    file: string;
+    line: number;
+    column: number;
+    code: string;
+    message: string;
+    /**
+     * Whether this finding may fail the run. Only a rule that is true of the
+     * RUN, not merely of the declared types, may block — see the header and the
+     * note on {@link CODE_TRUTHY}.
+     */
+    blocking: boolean;
+}
+/**
+ * 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 declare 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 declare 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 declare function splitUnion(text: string): string[];
+/** 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 declare function isCarrierMember(member: string): boolean;
+export type TypeVerdict = 
+/** Every member is a carrier and none is nullish — constant at runtime. */
+"carrier"
+/** A carrier that may also be absent — a real presence test, leave alone. */
+ | "nullable-carrier"
+/** Not a wrapper. */
+ | "plain";
+/**
+ * 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 declare function classifyType(text: string | undefined): TypeVerdict;
+/** Source text that denotes a nullish literal. */
+export declare function isNullishLiteral(exprText: string): boolean;
+/**
+ * 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 declare function equalityIsConstant(left: string | undefined, right: string | undefined, leftExpr?: string, rightExpr?: string): boolean;
+/**
+ * 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 declare function startOfNode(text: string, pos: number): number;
+/** 1-indexed line/column for a character offset, matching `tsc` output. */
+export declare function lineColumnAt(text: string, pos: number): {
+    line: number;
+    column: number;
+};
+/** Trim a source snippet for a message: one line, bounded. */
+export declare function snippet(text: string, pos: number, end: number): string;
+export declare function truthyMessage(expr: string, typeText: string): string;
+export declare function equalityMessage(expr: string, typeText: string, negated: boolean): string;
+/** Minimal shape of the bits of the TS 7 API this uses. */
+interface TsNode {
+    kind: number;
+    pos: number;
+    end: number;
+    [k: string]: unknown;
+}
+export interface WrapperRuleRun {
+    status: "ok" | "skipped" | "failed";
+    diagnostics: WrapperDiagnostic[];
+    detail?: string;
+    durationMs: number;
+}
+/** Candidate positions, and what each one means if the operand is a carrier. */
+interface Candidate {
+    node: TsNode;
+    kind: "truthy" | "equality";
+    /** For an equality, the other side, whose type decides with this one. */
+    other?: TsNode;
+    negated?: boolean;
+}
+/**
+ * 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 declare function collectCandidates(statements: readonly TsNode[], kindName: (n: TsNode) => string, walk: (n: TsNode, visit: (c: TsNode) => void) => void): Candidate[];
+export declare function runWrapperRules(opts: {
+    /** Directory of the baked `typescript` package. */
+    typescriptDir: string;
+    /** Absolute path of the tsconfig to open. */
+    configFile: string;
+    /** Only files under here produce diagnostics. */
+    appDir: string;
+    readFile: (p: string) => Promise<string>;
+    relative: (from: string, to: string) => string;
+    join: (...parts: string[]) => string;
+    dirname: (p: string) => string;
+}): Promise<WrapperRuleRun>;
+export {};