@specific.dev/spectest 0.66.0 → 0.68.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,
@@ -100,6 +102,7 @@ import {
 import { encodeRegistry } from "./harness/names-registry.js";
 import {
   InterceptRegistry,
+  parseTarget,
   runChain,
   type Interceptor,
 } from "./harness/intercept.js";
@@ -174,6 +177,7 @@ import {
   startRecording,
   stopRecording,
   truncateUtf8,
+  type StepBlock,
   type TestEvent,
   type OmittedBody,
 } from "./recorder.js";
@@ -2796,16 +2800,22 @@ function ingressClaimsHostname(hostname: string): boolean {
   return false;
 }
 
-/** Record one request an interceptor saw, nested under its `intercept` step. */
+/** Record one request an interceptor saw, nested under its `intercept` step.
+ *
+ * A forced 503 is the step doing exactly what its description says, so it is
+ * **not** marked failed — reddening the outcome the test asked for trains the
+ * reader to ignore the colour. Only a handler that threw is marked, because
+ * that 500 is a bug in the middleware rather than the outage it stands for. */
 function recordInterceptedRequest(
   it: Interceptor,
-  rec: { method: string; path: string; status: number; answeredBy: string },
+  rec: { method: string; path: string; status: number; answeredBy: string; threw?: boolean },
   durationMs: number,
 ): void {
   const parentSeq = INTERCEPT_STEP_SEQ.get(it.id);
   if (parentSeq === undefined || !isRecording()) return;
-  const by =
-    rec.answeredBy === "handler"
+  const by = rec.threw
+    ? "the interceptor threw — 500 from spectest, not from your handler"
+    : rec.answeredBy === "handler"
       ? "answered by the interceptor"
       : rec.answeredBy === "modified"
         ? "upstream answer replaced by the interceptor"
@@ -2814,22 +2824,42 @@ function recordInterceptedRequest(
     kind: "intercept-request",
     parentSeq,
     title: `${rec.method} ${rec.path} → ${rec.status}`,
-    status: rec.status >= 500 && rec.answeredBy !== "upstream" ? "failed" : "passed",
+    status: rec.threw ? "failed" : "passed",
+    // Method, path and status are already the title; the one thing the row
+    // cannot say for itself is who produced that status.
     blocks: [
-      {
-        type: "kv",
-        rows: [
-          { label: "Host", value: it.hostname },
-          { label: "Request", value: `${rec.method} ${rec.path}` },
-          { label: "Status", value: String(rec.status) },
-          { label: "Answered", value: by },
-        ],
-      },
+      { type: "kv", rows: [{ label: "Answered", value: by, error: rec.threw === true }] },
     ],
     durationMs,
   });
 }
 
+/** The handler's own source, which is what the interceptor actually does.
+ *
+ * Free and impossible to let rot: Bun runs the project's TypeScript
+ * directly, so `toString()` is the text the author wrote. It is the step's
+ * body, under the description — a mechanism the reader can check against
+ * the intent the description claims. A handler long enough to be a wall of
+ * code folds into a disclosure instead of pushing the requests off screen.
+ */
+function handlerBlocks(handler: InterceptHandler): StepBlock[] {
+  let src: string;
+  try {
+    src = String(handler);
+  } catch {
+    return [];
+  }
+  const code: StepBlock = { type: "code", lang: "ts", label: "Handler", code: src };
+  return src.split("\n").length > HANDLER_FOLD_LINES
+    ? [{ type: "details", summary: "Handler", blocks: [code] }]
+    : [code];
+}
+
+/** Past this many lines the handler source is folded away. Chosen so the
+ *  shapes this feature is for — a one-line forced status, a short
+ *  fail-twice-then-pass — always show, and only a real program hides. */
+const HANDLER_FOLD_LINES = 15;
+
 /**
  * Put middleware in front of a hostname the ingress serves — the
  * implementation behind `ctx.intercept`.
@@ -2838,19 +2868,25 @@ function recordInterceptedRequest(
  * the daemon (DNS does not point here), so the interceptor could only be
  * silent — and silence is the failure mode this whole layer is designed
  * against. The message names the two ways to get a route.
+ *
+ * The `description` is required because it is the step's whole title in the
+ * timeline and in the CLI's failure detail: it is what tells a reader why
+ * the UI under test went to its error state. The handler source says how;
+ * only the author can say what it means.
  */
 function registerInterceptor(
-  hostname: string,
-  pathOrHandler: string | InterceptHandler,
-  maybeHandler?: InterceptHandler,
+  target: string,
+  description: string,
+  handler: InterceptHandler,
 ): Interception {
-  const path = typeof pathOrHandler === "string" ? pathOrHandler : undefined;
-  const handler = typeof pathOrHandler === "function" ? pathOrHandler : maybeHandler;
-  if (typeof hostname !== "string" || hostname.length === 0) {
-    throw new Error("ctx.intercept: a hostname is required");
+  const { hostname: host, path } = parseTarget(target);
+  if (typeof description !== "string" || description.trim() === "") {
+    throw new Error(
+      `ctx.intercept(${JSON.stringify(target)}): a description is required — what the ` +
+        `environment now does, as the timeline reads it, e.g. "the sync endpoint returns 503".`,
+    );
   }
-  const host = hostname.toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "");
-  if (!handler) {
+  if (typeof handler !== "function") {
     throw new Error("ctx.intercept: a handler (req, next) => Response is required");
   }
   if (!ingressClaimsHostname(host)) {
@@ -2863,20 +2899,42 @@ function registerInterceptor(
   }
   const resv = reserveEvent();
   const it = INTERCEPTORS.register(host, path, handler);
+  const where = `${host}${it.path === "/" ? "" : it.path}`;
   const seq = recordStep(
     {
       kind: "intercept",
-      title: `intercept ${host}${it.path === "/" ? "" : it.path}`,
+      // The description alone. The pill already says INTERCEPT, and the
+      // target is in the panel — a row that repeats both spends its width
+      // on what the reader can already see and none of it on the one thing
+      // only the author knows.
+      title: description.trim(),
       blocks: [
+        ...handlerBlocks(handler),
         {
-          type: "kv",
-          rows: [
-            { label: "Host", value: host },
-            { label: "Path", value: it.path === "/" ? "/ (every path)" : `${it.path} and below` },
+          // The target IS the summary line, so the closed disclosure still
+          // says where the interceptor sits — a generic "Target" label
+          // would spend the one visible line saying nothing.
+          type: "details",
+          summary: where,
+          blocks: [
+            {
+              type: "kv",
+              rows: [
+                {
+                  label: "Matches",
+                  value: it.path === "/" ? "every path on this host" : `${it.path} and below`,
+                },
+                {
+                  label: "Until",
+                  value: it.scope === undefined ? "remove()" : "the end of this test",
+                },
+              ],
+            },
           ],
         },
       ],
-      durationMs: 0,
+      // No duration: this is a marker for the moment the interceptor went
+      // up, and "(0 ms)" reads as a step that did nothing.
     },
     resv,
   );
@@ -4982,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;
@@ -6047,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;
 
@@ -6056,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;
 }
@@ -6068,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;
@@ -6192,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.
@@ -6205,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/intercept.test.ts

@@ -3,6 +3,7 @@ import {
   InterceptRegistry,
   hostnameMatches,
   normalizeMount,
+  parseTarget,
   pathMounts,
   runChain,
   type Interceptor,
@@ -39,6 +40,41 @@ describe("normalizeMount", () => {
   });
 });
 
+describe("parseTarget", () => {
+  test("a bare hostname mounts at the root", () => {
+    expect(parseTarget("app.test")).toEqual({ hostname: "app.test", path: "/" });
+  });
+  test("a path rides the target", () => {
+    expect(parseTarget("app.test/api/sync")).toEqual({
+      hostname: "app.test",
+      path: "/api/sync",
+    });
+    expect(parseTarget("app.test/api/")).toEqual({ hostname: "app.test", path: "/api" });
+    expect(parseTarget("app.test/")).toEqual({ hostname: "app.test", path: "/" });
+  });
+  test("a scheme and case are tolerated", () => {
+    expect(parseTarget("https://App.Test/API")).toEqual({
+      hostname: "app.test",
+      path: "/api",
+    });
+  });
+  test("a wildcard host keeps its pattern", () => {
+    expect(parseTarget("*.example.com/v1")).toEqual({
+      hostname: "*.example.com",
+      path: "/v1",
+    });
+  });
+  test("rejects a target that is only a path, or none at all", () => {
+    expect(() => parseTarget("/api")).toThrow(/names no hostname/);
+    expect(() => parseTarget("")).toThrow(/target hostname is required/);
+    expect(() => parseTarget("   ")).toThrow(/target hostname is required/);
+  });
+  test("rejects a query or fragment", () => {
+    expect(() => parseTarget("app.test/api?x=1")).toThrow(/mount prefix/);
+    expect(() => parseTarget("app.test?x=1")).toThrow(/query or fragment/);
+  });
+});
+
 describe("hostnameMatches", () => {
   test("exact and wildcard", () => {
     expect(hostnameMatches("api.test", "api.test")).toBe(true);

package/src/harness/intercept.ts

@@ -56,6 +56,12 @@ export interface InterceptedRequest {
    *  upstream via `next()` untouched (`upstream`), or the upstream's answer
    *  replaced by the interceptor after `next()` (`modified`). */
   answeredBy: "handler" | "upstream" | "modified";
+  /** The handler threw (or returned something that is not a `Response`), so
+   *  the 500 below is a bug in the test's own middleware rather than the
+   *  outage it was asked to produce. The distinction cannot be recovered
+   *  from the status: a deliberate 500 and a crashed handler are the same
+   *  number, and only this tells the timeline which one to mark as wrong. */
+  threw?: boolean;
 }
 
 export interface Interceptor {
@@ -71,6 +77,39 @@ export interface Interceptor {
   requests: InterceptedRequest[];
 }
 
+/**
+ * Split an intercept target — `app.test`, `app.test/api/sync`,
+ * `*.example.com/v1` — into the hostname and the mount path.
+ *
+ * The path rides the target rather than a second argument because that is
+ * what it is: part of what the interceptor claims, not a separate knob. It
+ * also keeps the signature down to one string, so the description that
+ * follows can never be mistaken for a path.
+ *
+ * A scheme is tolerated (`https://app.test/api`) since that is how the same
+ * address is written everywhere else.
+ */
+export function parseTarget(target: string): { hostname: string; path: string } {
+  if (typeof target !== "string" || target.trim() === "") {
+    throw new Error("intercept: a target hostname is required, e.g. \"app.test\" or \"app.test/api\"");
+  }
+  const bare = target.trim().toLowerCase().replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+  const slash = bare.indexOf("/");
+  const hostname = slash === -1 ? bare : bare.slice(0, slash);
+  const rest = slash === -1 ? undefined : bare.slice(slash);
+  if (hostname === "") {
+    throw new Error(
+      `intercept: target ${JSON.stringify(target)} names no hostname — write it as "app.test/api", not "/api"`,
+    );
+  }
+  if (hostname.includes("?") || hostname.includes("#")) {
+    throw new Error(
+      `intercept: target ${JSON.stringify(target)} cannot carry a query or fragment`,
+    );
+  }
+  return { hostname, path: normalizeMount(rest) };
+}
+
 /** Mount semantics (`app.use(path, fn)`): `/api` matches `/api`, `/api/`, `/api/x`, and
  *  never `/apix`. `/` matches everything. Query strings do not take part. */
 export function pathMounts(mount: string, pathname: string): boolean {
@@ -222,6 +261,7 @@ export async function runChain(
       );
       record.answeredBy = "handler";
       record.status = 500;
+      record.threw = true;
       it.calls++;
       it.requests.push(record);
       observe?.(it, record, Date.now() - started);

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);
+  });
+});