@specific.dev/spectest 0.67.0 → 0.69.0

package/src/daemon.ts

@@ -90,6 +90,8 @@ import {
   sanitizeSegment,
 } from "./harness/volume-paths.js";
 import { pollUntilReady } from "./harness/ready-poll.js";
+import { runWrapperRules } from "./harness/wrapper-rules.js";
+import type { WrapperDiagnostic } from "./harness/wrapper-rules.js";
 import { APP_DIR, WORKSPACE, resolveProjectPath } from "./project-files.js";
 import {
   isTextualContentType,
@@ -5038,7 +5040,16 @@ async function pollCall<T>(
     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 as T;
         success = true;
         break;
@@ -6103,7 +6114,11 @@ async function evalCode(
 // 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;
 
@@ -6112,7 +6127,7 @@ interface TypecheckError {
   file: string;
   line: number;
   column: number;
-  /** `TS2345` etc. */
+  /** `TS2345` from the compiler, or a `SPECTEST….` rule code. */
   code: string;
   message: string;
 }
@@ -6124,6 +6139,19 @@ interface TypecheckReport {
   durationMs: number;
   /** Why the check was skipped / how it failed. */
   detail?: string;
+  /**
+   * Findings that FAIL the run, as opposed to `errors`, which only advise.
+   * A diagnostic qualifies only when it is true of the program that runs
+   * rather than of the declared types alone — see `harness/wrapper-rules.ts`
+   * for why no `tsc` code can be in here and why these can.
+   *
+   * The list is the rollout mechanism as well as the payload: an older SDK
+   * never sends the field, `#[serde(default)]` leaves it empty on the server,
+   * and the gate is inert for every project that has not moved to a version
+   * carrying it. The version a project runs is already its own choice
+   * (`sdk.rs` honours the declared lower bound), so the bump is the consent.
+   */
+  blocking?: TypecheckError[];
 }
 
 let TYPECHECK: Promise<TypecheckReport> | null = null;
@@ -6248,7 +6276,17 @@ async function runTypecheck(): Promise<TypecheckReport> {
     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 }: WrapperDiagnostic): TypecheckError => ({
+    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.
@@ -6261,7 +6299,50 @@ async function runTypecheck(): Promise<TypecheckReport> {
     }
     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: string): Promise<WrapperDiagnostic[]> {
+  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 as Error)?.message ?? err}`);
+    return [];
+  }
 }
 
 // ────────────────────────────────────────────────────────────────────────

package/src/harness/wrapper-rules.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from "bun:test";
+import {
+  classifyType,
+  equalityIsConstant,
+  equalityMessage,
+  isCarrierMember,
+  isNullishLiteral,
+  lineColumnAt,
+  snippet,
+  splitUnion,
+  startOfNode,
+  truthyMessage,
+} from "./wrapper-rules.js";
+
+describe("splitUnion", () => {
+  test("splits only at the top level", () => {
+    expect(splitUnion("Carrier<string> | undefined")).toEqual([
+      "Carrier<string>",
+      "undefined",
+    ]);
+    // A nested union must survive whole, or its member reads as a bare `A`.
+    expect(splitUnion("Carrier<A | B>")).toEqual(["Carrier<A | B>"]);
+    expect(splitUnion("Carrier<{ a: 1 | 2 }> | null")).toEqual([
+      "Carrier<{ a: 1 | 2 }>",
+      "null",
+    ]);
+    expect(splitUnion("Carrier<(a: 1 | 2) => void>")).toEqual([
+      "Carrier<(a: 1 | 2) => void>",
+    ]);
+    expect(splitUnion("number")).toEqual(["number"]);
+  });
+});
+
+describe("isCarrierMember", () => {
+  test("only the primitive carrier", () => {
+    expect(isCarrierMember("Carrier<boolean>")).toBe(true);
+    expect(isCarrierMember("Carrier<string>")).toBe(true);
+    // Object-shaped wrappers are objects with or without us, so a condition on
+    // one is not made constant by the wrapper.
+    expect(isCarrierMember("WrappedObject<Row>")).toBe(false);
+    expect(isCarrierMember("WrappedArray<Row>")).toBe(false);
+    expect(isCarrierMember("WrappedResponse")).toBe(false);
+    expect(isCarrierMember("boolean")).toBe(false);
+    // Not a generic reference — a value merely *named* Carrier is not one.
+    expect(isCarrierMember("Carrier")).toBe(false);
+  });
+});
+
+describe("classifyType", () => {
+  test("a bare carrier is constant", () => {
+    expect(classifyType("Carrier<boolean>")).toBe("carrier");
+    expect(classifyType("Carrier<number>")).toBe("carrier");
+  });
+
+  test("a nullish union is a presence test and must never be flagged", () => {
+    // `wrapChild` returns null/undefined RAW, so `if (row.opt)` correctly
+    // tells present from absent. This is the case that would break the rule.
+    expect(classifyType("Carrier<string> | undefined")).toBe("nullable-carrier");
+    expect(classifyType("Carrier<number> | null")).toBe("nullable-carrier");
+    expect(classifyType("Carrier<number> | null | undefined")).toBe("nullable-carrier");
+  });
+
+  test("anything the checker could not pin down reads as plain", () => {
+    for (const t of ["any", "unknown", "boolean", "number", "error", undefined, ""]) {
+      expect(classifyType(t)).toBe("plain");
+    }
+  });
+
+  test("an unrecognised mixed union does not block", () => {
+    expect(classifyType("Carrier<string> | number")).toBe("plain");
+    expect(classifyType("null | undefined")).toBe("plain");
+  });
+});
+
+describe("equalityIsConstant", () => {
+  test("exactly one carrier side is constant", () => {
+    expect(equalityIsConstant("Carrier<number>", "2")).toBe(true);
+    expect(equalityIsConstant("number", "Carrier<number>")).toBe(true);
+  });
+
+  test("two carriers compare identity — a different mistake, not proven", () => {
+    expect(equalityIsConstant("Carrier<number>", "Carrier<number>")).toBe(false);
+  });
+
+  test("a maybe-absent carrier is not proven either", () => {
+    expect(equalityIsConstant("Carrier<string> | undefined", "\"a\"")).toBe(false);
+  });
+
+  test("no carrier at all is not our business", () => {
+    expect(equalityIsConstant("number", "2")).toBe(false);
+  });
+
+  test("a nullish literal is never constant — that is the correct null check", () => {
+    // `wrapChild` returns a null/undefined leaf RAW, so `row.setting === null`
+    // answers correctly in both directions however the generic was declared.
+    expect(equalityIsConstant("Carrier<unknown>", "null", "row.setting", "null")).toBe(false);
+    expect(equalityIsConstant("Carrier<string>", "undefined", "row.x", "undefined")).toBe(false);
+    expect(equalityIsConstant("null", "Carrier<string>", "null", "row.x")).toBe(false);
+    // and a real literal on the other side still is
+    expect(equalityIsConstant("Carrier<number>", "2", "row.n", "2")).toBe(true);
+  });
+});
+
+describe("isNullishLiteral", () => {
+  test("the three spellings", () => {
+    expect(isNullishLiteral("null")).toBe(true);
+    expect(isNullishLiteral(" undefined ")).toBe(true);
+    expect(isNullishLiteral("void 0")).toBe(true);
+    expect(isNullishLiteral("nullish")).toBe(false);
+    expect(isNullishLiteral("row.nullable")).toBe(false);
+  });
+});
+
+describe("lineColumnAt", () => {
+  test("1-indexed, matching tsc", () => {
+    const text = "a\nbb\nccc";
+    expect(lineColumnAt(text, 0)).toEqual({ line: 1, column: 1 });
+    expect(lineColumnAt(text, 2)).toEqual({ line: 2, column: 1 });
+    expect(lineColumnAt(text, 3)).toEqual({ line: 2, column: 2 });
+    expect(lineColumnAt(text, 5)).toEqual({ line: 3, column: 1 });
+  });
+
+  test("out-of-range offsets clamp instead of throwing", () => {
+    expect(lineColumnAt("ab", -5)).toEqual({ line: 1, column: 1 });
+    expect(lineColumnAt("ab", 99)).toEqual({ line: 1, column: 3 });
+  });
+});
+
+describe("snippet", () => {
+  test("one line, bounded", () => {
+    expect(snippet("  row.written  ", 0, 15)).toBe("row.written");
+    expect(snippet("a\nb", 0, 3)).toBe("a");
+    const long = "x".repeat(200);
+    expect(snippet(long, 0, 200).length).toBe(58);
+  });
+});
+
+describe("messages", () => {
+  test("name the value, the type and the fix", () => {
+    const m = truthyMessage("row.written", "Carrier<boolean>");
+    expect(m).toContain("row.written");
+    expect(m).toContain("Carrier<boolean>");
+    expect(m).toContain(".unwrap()");
+    expect(m).toContain("always true");
+  });
+
+  test("a negated comparison is always true, not always false", () => {
+    expect(equalityMessage("m.rows", "Carrier<number>", false)).toContain("always false");
+    expect(equalityMessage("m.rows", "Carrier<number>", true)).toContain("always true");
+  });
+});
+
+describe("startOfNode", () => {
+  test("skips the leading trivia a node's pos includes", () => {
+    // `pos` is the end of the previous node, so it points at the whitespace.
+    expect(startOfNode("a;   b", 2)).toBe(5);
+    expect(startOfNode("a;\n  b", 2)).toBe(5);
+  });
+
+  test("skips comments, so a finding never points at the comment above it", () => {
+    const text = "a;\n// note\nb";
+    expect(startOfNode(text, 2)).toBe(text.indexOf("b"));
+    const block = "a;\n/* note */ b";
+    expect(startOfNode(block, 2)).toBe(block.indexOf("b"));
+  });
+
+  test("an unterminated comment stops at the end instead of looping", () => {
+    expect(startOfNode("a;\n/* open", 2)).toBe(10);
+  });
+});