test+script: address cr round 5 — actionable diagnostics

cr round 5 (Approved, non-blocking) findings I acted on:

- Completeness test: replace vitest's default set-diff with a
  custom remediation message. On drift, it names the offending
  method AND tells the contributor what to do: "add to
  SDK_PUBLIC_METHODS + add a case" OR "add to INTERNAL_HELPERS
  if not user-facing." Saves a future-dev the five minutes of
  figuring out where to update on first encounter.
- Regen script: verify origin remote is qurl-service. Prevents
  the silent-foot-gun where someone with an unrelated repo at
  ../qurl-service that happens to contain api/openapi.yaml
  (or a fork) snapshots from the wrong source. The header SHA
  would otherwise be from the fork, not upstream.

Skipped per cr's explicit guidance:
  - #2 (throw-vs-expect) — cr: "probably the right tradeoff"
  - #3 (second-page cursor) — cr: "no coverage gap … consistent
    with the CONTRIBUTING.md scope note"
  - #5 (mockOk in test-helpers) — cr: "not worth churning for"

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Author: justin-layerv

scripts/update-openapi-snapshot.sh

@@ -22,6 +22,18 @@ if [ ! -d "$QURL_SERVICE_DIR/.git" ]; then
   exit 2
 fi
 
+# Verify the remote actually points at qurl-service. Without this, someone
+# with an unrelated repo at ../qurl-service that happens to contain
+# api/openapi.yaml could silently snapshot from the wrong source — the
+# header SHA would be from their fork, not upstream.
+REMOTE_URL=$(git -C "$QURL_SERVICE_DIR" remote get-url origin 2>/dev/null || echo "")
+if ! printf '%s' "$REMOTE_URL" | grep -q -E '[:/]qurl-service(\.git)?$'; then
+  echo "error: $QURL_SERVICE_DIR origin remote does not look like qurl-service:" >&2
+  echo "       $REMOTE_URL" >&2
+  echo "       expected a URL ending in :qurl-service or /qurl-service(.git)" >&2
+  exit 2
+fi
+
 # Refresh remote refs so `origin/main` (the default) points at the current
 # upstream tip, not whatever was last fetched locally. Without this, a
 # stale checkout would silently pin the snapshot to an old SHA. Harmless

src/contract.test.ts

@@ -183,7 +183,27 @@ describe("OpenAPI contract", () => {
       const desc = Object.getOwnPropertyDescriptor(QURLClient.prototype, name);
       return typeof desc?.value === "function";
     });
-    expect(new Set(prototypeMethods)).toEqual(SDK_PUBLIC_METHODS);
+    const actual = new Set(prototypeMethods);
+    const missingFromSet = [...actual].filter((m) => !SDK_PUBLIC_METHODS.has(m));
+    const missingFromPrototype = [...SDK_PUBLIC_METHODS].filter((m) => !actual.has(m));
+    // Custom remediation message — vitest's default `toEqual` diff on Sets
+    // doesn't explain *what to do*. If this fires, the contributor needs
+    // to either add the method to SDK_PUBLIC_METHODS + write a contract
+    // case, or move it to INTERNAL_HELPERS if it's not a public API call.
+    if (missingFromSet.length || missingFromPrototype.length) {
+      throw new Error(
+        `Contract set drift:\n` +
+          (missingFromSet.length
+            ? `  New public method(s) on QURLClient.prototype: ${missingFromSet.join(", ")}\n` +
+              `    → add to SDK_PUBLIC_METHODS and add an it("…") case, ` +
+              `OR add to INTERNAL_HELPERS if not a user-facing API call.\n`
+            : "") +
+          (missingFromPrototype.length
+            ? `  Listed in SDK_PUBLIC_METHODS but missing from prototype: ${missingFromPrototype.join(", ")}\n` +
+              `    → either the method was removed/renamed in client.ts, or the name here is wrong.\n`
+            : ""),
+      );
+    }
   });
 
   // Each SDK public method → one call → captured (verb, url) must match