feat: port release-v2 experience improvements from #6582 (audited subset) (#6609)

packages/integrations/src/base/response-contract.spec.ts

@@ -0,0 +1,43 @@
+import { describe, expect, test } from "vitest";
+import { z } from "zod/v4";
+
+import { simulateResponseContractAsync } from "./response-contract";
+
+const parser = async (response: { json: () => Promise<unknown> }) =>
+  z.object({ count: z.number() }).parse(await response.json());
+
+describe("simulateResponseContractAsync", () => {
+  test("runs valid, mapped, and rejected payload fixtures", async () => {
+    const results = await simulateResponseContractAsync(
+      parser,
+      [
+        { name: "valid response", payload: { count: 2 }, expected: { total: 2 } },
+        { name: "invalid response", payload: { count: "two" }, rejects: true },
+      ],
+      (value) => ({ total: value.count }),
+    );
+
+    expect(results).toEqual([
+      { name: "valid response", passed: true, message: undefined },
+      { name: "invalid response", passed: true, message: undefined },
+    ]);
+  });
+
+  test("treats a fixture without expected or rejects as a successful parse assertion", async () => {
+    const results = await simulateResponseContractAsync(parser, [{ name: "parses only", payload: { count: 5 } }]);
+
+    expect(results).toEqual([{ name: "parses only", passed: true, message: undefined }]);
+  });
+
+  test("reports actionable mismatches without throwing away later fixtures", async () => {
+    const results = await simulateResponseContractAsync(parser, [
+      { name: "wrong output", payload: { count: 2 }, expected: { count: 3 } },
+      { name: "unexpected success", payload: { count: 4 }, rejects: true },
+    ]);
+
+    expect(results).toEqual([
+      { name: "wrong output", passed: false, message: "Parsed output did not match expected." },
+      { name: "unexpected success", passed: false, message: "Expected parser rejection, but parsing succeeded." },
+    ]);
+  });
+});

packages/integrations/src/base/response-contract.ts

@@ -0,0 +1,51 @@
+export type ResponseContractParser<TResult> = (response: { json: () => Promise<unknown> }) => Promise<TResult>;
+
+export interface ResponseContractFixture<TResult> {
+  name: string;
+  payload: unknown;
+  expected?: TResult;
+  rejects?: true;
+}
+
+/**
+ * Runs JSON-like fixtures through the same parser used by an integration.
+ * This keeps contribution fixtures transport-free and deterministic while
+ * still exercising schema validation and response mapping.
+ */
+export const simulateResponseContractAsync = async <TParsed, TResult = TParsed>(
+  parser: ResponseContractParser<TParsed>,
+  fixtures: readonly ResponseContractFixture<TResult>[],
+  map: (parsed: TParsed) => TResult = (parsed) => parsed as unknown as TResult,
+) => {
+  const results: { name: string; passed: boolean; message?: string }[] = [];
+
+  for (const fixture of fixtures) {
+    try {
+      const parsed = await parser({ json: () => Promise.resolve(structuredClone(fixture.payload)) });
+      if (fixture.rejects) {
+        results.push({
+          name: fixture.name,
+          passed: false,
+          message: "Expected parser rejection, but parsing succeeded.",
+        });
+        continue;
+      }
+      const actual = map(parsed);
+      const passed = "expected" in fixture ? isDeepStrictEqual(actual, fixture.expected) : true;
+      results.push({
+        name: fixture.name,
+        passed,
+        message: passed ? undefined : "Parsed output did not match expected.",
+      });
+    } catch (error) {
+      results.push({
+        name: fixture.name,
+        passed: fixture.rejects === true,
+        message: fixture.rejects ? undefined : error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  return results;
+};
+import { isDeepStrictEqual } from "node:util";

packages/integrations/src/index.ts

@@ -102,3 +102,5 @@ export { downloadClientItemSchema } from "./interfaces/downloads/download-client
 
 // Helpers
 export { createIntegrationAsync } from "./base/creator";
+export { simulateResponseContractAsync } from "./base/response-contract";
+export type { ResponseContractFixture, ResponseContractParser } from "./base/response-contract";