coverage-check 0.1.1 → 0.2.1

package/src/s3-suite-store.test.mts

@@ -0,0 +1,308 @@
+import { Readable } from "node:stream";
+import { describe, expect, it, vi } from "vitest";
+import { GetObjectCommand, ListObjectsV2Command, PutObjectCommand } from "@aws-sdk/client-s3";
+import { S3SuiteStore } from "./s3-suite-store.mts";
+
+function makeClient(sendImpl: (cmd: unknown) => Promise<unknown>) {
+  return { send: vi.fn(sendImpl) };
+}
+
+const BUCKET = "test-bucket";
+const PREFIX = "coverage";
+const LCOV = "SF:backend/foo.mts\nDA:1,1\nend_of_record\n";
+const POINTER = JSON.stringify({ sha: "abc123", timestamp: "2026-01-01T00:00:00.000Z" });
+
+function notFound() {
+  const err = new Error("NoSuchKey");
+  err.name = "NoSuchKey";
+  return Promise.reject(err);
+}
+
+describe("S3SuiteStore — list()", () => {
+  it("returns suite names from CommonPrefixes", async () => {
+    const client = makeClient(async () => ({
+      CommonPrefixes: [{ Prefix: `${PREFIX}/backend/` }, { Prefix: `${PREFIX}/frontend/` }],
+    }));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.list()).toEqual(["backend", "frontend"]);
+    expect(client.send).toHaveBeenCalledOnce();
+    const cmd = client.send.mock.calls[0][0];
+    expect(cmd).toBeInstanceOf(ListObjectsV2Command);
+  });
+
+  it("returns empty array when CommonPrefixes is absent", async () => {
+    const client = makeClient(async () => ({}));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.list()).toEqual([]);
+  });
+
+  it("works without a prefix", async () => {
+    const client = makeClient(async () => ({
+      CommonPrefixes: [{ Prefix: "backend/" }],
+    }));
+    const store = new S3SuiteStore({ bucket: BUCKET, client });
+    expect(await store.list()).toEqual(["backend"]);
+  });
+
+  it("filters out empty-string entries", async () => {
+    const client = makeClient(async () => ({
+      CommonPrefixes: [{ Prefix: undefined }, { Prefix: `${PREFIX}/web/` }],
+    }));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.list()).toEqual(["web"]);
+  });
+
+  it("paginates through all results when IsTruncated is true", async () => {
+    let callCount = 0;
+    const client = makeClient(async () => {
+      callCount++;
+      if (callCount === 1) {
+        return {
+          CommonPrefixes: [{ Prefix: `${PREFIX}/suite-a/` }],
+          IsTruncated: true,
+          NextContinuationToken: "token-xyz",
+        };
+      }
+      return { CommonPrefixes: [{ Prefix: `${PREFIX}/suite-b/` }], IsTruncated: false };
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.list()).toEqual(["suite-a", "suite-b"]);
+    expect(client.send).toHaveBeenCalledTimes(2);
+    const secondCmd = client.send.mock.calls[1][0] as ListObjectsV2Command;
+    expect(secondCmd.input.ContinuationToken).toBe("token-xyz");
+  });
+});
+
+describe("S3SuiteStore — get()", () => {
+  it("follows branch pointer to fetch lcov (Uint8Array body)", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return { Body: Buffer.from(LCOV) };
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const result = await store.get("backend", { branch: "main" });
+    expect(result!.toString()).toBe(LCOV);
+    expect(client.send).toHaveBeenCalledTimes(2);
+  });
+
+  it("defaults to main branch when no opts provided", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return { Body: Buffer.from(LCOV) };
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const result = await store.get("backend");
+    expect(result).not.toBeNull();
+  });
+
+  it("fetches by explicit sha without reading the pointer", async () => {
+    const client = makeClient(async (cmd) => {
+      if (cmd instanceof GetObjectCommand) return { Body: Buffer.from(LCOV) };
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const result = await store.get("backend", { sha: "abc123" });
+    expect(result!.toString()).toBe(LCOV);
+    expect(client.send).toHaveBeenCalledOnce();
+  });
+
+  it("returns null when branch pointer is not found", async () => {
+    const client = makeClient(async (cmd) => {
+      if (cmd instanceof GetObjectCommand) return notFound();
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.get("backend", { branch: "main" })).toBeNull();
+  });
+
+  it("returns null when lcov object is not found", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        const err = new Error("NotFound");
+        err.name = "NotFound";
+        return Promise.reject(err);
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    expect(await store.get("backend", { branch: "main" })).toBeNull();
+  });
+
+  it("rethrows unexpected errors from pointer fetch", async () => {
+    const client = makeClient(async () => Promise.reject(new Error("network error")));
+    const store = new S3SuiteStore({ bucket: BUCKET, client });
+    await expect(store.get("backend")).rejects.toThrow("network error");
+  });
+
+  it("rethrows unexpected errors from lcov fetch", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return Promise.reject(new Error("read error"));
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, client });
+    await expect(store.get("backend")).rejects.toThrow("read error");
+  });
+
+  it("handles a Readable body", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return { Body: Readable.from([Buffer.from(LCOV)]) };
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const result = await store.get("backend");
+    expect(result!.toString()).toBe(LCOV);
+  });
+
+  it("handles a Blob body", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return { Body: new Blob([LCOV]) };
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const result = await store.get("backend");
+    expect(result!.toString()).toBe(LCOV);
+  });
+
+  it("throws for an unexpected body type", async () => {
+    let callCount = 0;
+    const client = makeClient(async (cmd) => {
+      callCount++;
+      if (cmd instanceof GetObjectCommand) {
+        if (callCount === 1) return { Body: Buffer.from(POINTER) };
+        return { Body: 12345 }; // not Readable, Uint8Array, or Blob
+      }
+      return {};
+    });
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    await expect(store.get("backend")).rejects.toThrow("unexpected S3 response body type");
+  });
+});
+
+describe("S3SuiteStore — put()", () => {
+  it("sends two PutObjectCommands: lcov payload and branch pointer", async () => {
+    const client = makeClient(async () => ({}));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    await store.put("backend", Buffer.from(LCOV), { sha: "abc123", branch: "main" });
+
+    expect(client.send).toHaveBeenCalledTimes(2);
+    const cmds = client.send.mock.calls.map((c) => c[0]);
+    expect(cmds.every((c) => c instanceof PutObjectCommand)).toBe(true);
+
+    const keys = cmds.map((c) => (c as PutObjectCommand).input.Key);
+    expect(keys).toContain(`${PREFIX}/backend/sha/abc123/lcov.info`);
+    expect(keys).toContain(`${PREFIX}/backend/branch/main/latest.json`);
+  });
+
+  it("uses provided timestamp in pointer", async () => {
+    const client = makeClient(async () => ({}));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    const ts = "2026-05-01T00:00:00.000Z";
+    await store.put("backend", Buffer.from(LCOV), {
+      sha: "abc",
+      branch: "main",
+      timestamp: ts,
+    });
+
+    const pointerCmd = client.send.mock.calls
+      .map((c) => c[0] as PutObjectCommand)
+      .find((c) => c.input.Key?.endsWith("latest.json"))!;
+    const pointer = JSON.parse((pointerCmd.input.Body as Buffer).toString("utf8"));
+    expect(pointer.timestamp).toBe(ts);
+  });
+
+  it("generates a timestamp when none is provided", async () => {
+    const client = makeClient(async () => ({}));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: PREFIX, client });
+    await store.put("backend", Buffer.from(LCOV), { sha: "abc", branch: "main" });
+
+    const pointerCmd = client.send.mock.calls
+      .map((c) => c[0] as PutObjectCommand)
+      .find((c) => (c as PutObjectCommand).input.Key?.endsWith("latest.json"))!;
+    const pointer = JSON.parse((pointerCmd.input.Body as Buffer).toString("utf8"));
+    expect(typeof pointer.timestamp).toBe("string");
+    expect(pointer.timestamp.length).toBeGreaterThan(0);
+  });
+
+  it("works without a prefix", async () => {
+    const client = makeClient(async () => ({}));
+    const store = new S3SuiteStore({ bucket: BUCKET, client });
+    await store.put("backend", Buffer.from(LCOV), { sha: "abc", branch: "main" });
+
+    const keys = client.send.mock.calls.map((c) => (c[0] as PutObjectCommand).input.Key);
+    expect(keys).toContain("backend/sha/abc/lcov.info");
+    expect(keys).toContain("backend/branch/main/latest.json");
+  });
+});
+
+describe("S3SuiteStore — path traversal protection", () => {
+  const store = new S3SuiteStore({
+    bucket: BUCKET,
+    prefix: PREFIX,
+    client: makeClient(async () => ({})),
+  });
+  const invalid = ["", ".", "..", "a/b", "a\\b"];
+  for (const val of invalid) {
+    it(`get() rejects suite=${JSON.stringify(val)}`, async () => {
+      await expect(store.get(val)).rejects.toThrow("invalid suite");
+    });
+    it(`get() rejects branch=${JSON.stringify(val)}`, async () => {
+      await expect(store.get("backend", { branch: val })).rejects.toThrow("invalid branch");
+    });
+    it(`get() rejects sha=${JSON.stringify(val)}`, async () => {
+      await expect(store.get("backend", { sha: val })).rejects.toThrow("invalid sha");
+    });
+    it(`put() rejects suite=${JSON.stringify(val)}`, async () => {
+      await expect(store.put(val, Buffer.from(""), { sha: "abc", branch: "main" })).rejects.toThrow(
+        "invalid suite",
+      );
+    });
+    it(`put() rejects sha=${JSON.stringify(val)}`, async () => {
+      await expect(
+        store.put("backend", Buffer.from(""), { sha: val, branch: "main" }),
+      ).rejects.toThrow("invalid sha");
+    });
+    it(`put() rejects branch=${JSON.stringify(val)}`, async () => {
+      await expect(
+        store.put("backend", Buffer.from(""), { sha: "abc", branch: val }),
+      ).rejects.toThrow("invalid branch");
+    });
+  }
+});
+
+describe("S3SuiteStore — constructor prefix normalization", () => {
+  it("strips all trailing slashes from prefix", async () => {
+    const client = makeClient(async () => ({ CommonPrefixes: [] }));
+    const store = new S3SuiteStore({ bucket: BUCKET, prefix: "coverage///", client });
+    expect(await store.list()).toEqual([]);
+    const cmd = client.send.mock.calls[0][0] as InstanceType<typeof ListObjectsV2Command>;
+    expect(cmd.input.Prefix).toBe("coverage/");
+  });
+});

package/src/step-summary.mts

@@ -0,0 +1,89 @@
+import { appendFileSync } from "node:fs";
+import type { LcovData } from "./types.mts";
+import type { CoverageCheckResult } from "./types.mts";
+
+export type SuiteSource = {
+  suite: string;
+  source: "fresh" | "store";
+  lcov: LcovData;
+};
+
+function suiteTotals(lcov: LcovData): { hit: number; total: number } {
+  let hit = 0;
+  let total = 0;
+  for (const lines of lcov.values()) {
+    for (const count of lines.values()) {
+      total++;
+      if (count > 0) hit++;
+    }
+  }
+  return { hit, total };
+}
+
+function pctStr(hit: number, total: number): string {
+  if (total === 0) return "—";
+  return `${((hit / total) * 100).toFixed(1)}% (${hit}/${total})`;
+}
+
+function escMd(s: string): string {
+  return s.replace(/\|/g, "\\|");
+}
+
+export function buildSummaryMarkdown(
+  suiteSources: SuiteSource[],
+  result: CoverageCheckResult,
+  runUrl: string,
+  branch = "main",
+): string {
+  const suiteRows = suiteSources
+    .map(({ suite, source, lcov }) => {
+      const { hit, total } = suiteTotals(lcov);
+      const sourceLabel = source === "fresh" ? "fresh" : `store (${escMd(branch)})`;
+      return `| \`${escMd(suite)}\` | ${sourceLabel} | ${pctStr(hit, total)} |`;
+    })
+    .join("\n");
+
+  const suiteTable = [
+    "| Suite | Source | Line coverage |",
+    "|---|---|---|",
+    suiteRows || "| — | — | — |",
+  ].join("\n");
+
+  const ruleRows = result.buckets
+    .map((b) => {
+      const status = b.passed ? "✅" : "❌";
+      const pct = b.coverable > 0 ? `${((b.hit / b.coverable) * 100).toFixed(1)}%` : "—";
+      return `| \`${escMd(b.rule)}\` | ${b.threshold}% | ${pct} | ${status} |`;
+    })
+    .join("\n");
+
+  const ruleTable = [
+    "| Rule | Threshold | Patch coverage | Status |",
+    "|---|---|---|---|",
+    ruleRows || "| — | — | — | — |",
+  ].join("\n");
+
+  const overall = result.passed ? "✅ passed" : "❌ failed";
+  const runLink = runUrl !== "N/A" ? `\n\n_[View run](${runUrl})_` : "";
+
+  return `## Coverage summary — ${overall}
+
+### Suite totals
+
+${suiteTable}
+
+### Patch coverage
+
+${ruleTable}${runLink}
+`;
+}
+
+export function writeSummary(
+  summaryFile: string,
+  suiteSources: SuiteSource[],
+  result: CoverageCheckResult,
+  runUrl: string,
+  branch?: string,
+): void {
+  appendFileSync(summaryFile, buildSummaryMarkdown(suiteSources, result, runUrl, branch), "utf8");
+}

package/src/step-summary.test.mts

@@ -0,0 +1,189 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildSummaryMarkdown, writeSummary } from "./step-summary.mts";
+import type { SuiteSource } from "./step-summary.mts";
+import type { CoverageCheckResult } from "./types.mts";
+
+const passResult: CoverageCheckResult = {
+  passed: true,
+  buckets: [{ rule: "backend/**", threshold: 90, coverable: 10, hit: 10, passed: true, files: [] }],
+  informational: [],
+};
+
+const failResult: CoverageCheckResult = {
+  passed: false,
+  buckets: [{ rule: "backend/**", threshold: 90, coverable: 10, hit: 8, passed: false, files: [] }],
+  informational: [],
+};
+
+const freshSource: SuiteSource = {
+  suite: "backend",
+  source: "fresh",
+  lcov: new Map([
+    [
+      "backend/foo.mts",
+      new Map([
+        [1, 1],
+        [2, 0],
+        [3, 1],
+      ]),
+    ],
+  ]),
+};
+
+const storeSource: SuiteSource = {
+  suite: "frontend",
+  source: "store",
+  lcov: new Map([
+    [
+      "web/app.tsx",
+      new Map([
+        [10, 1],
+        [11, 1],
+      ]),
+    ],
+  ]),
+};
+
+describe("buildSummaryMarkdown", () => {
+  it("shows passed status in heading", () => {
+    const md = buildSummaryMarkdown([freshSource], passResult, "https://example.com/run/1");
+    expect(md).toContain("✅ passed");
+  });
+
+  it("shows failed status in heading", () => {
+    const md = buildSummaryMarkdown([freshSource], failResult, "https://example.com/run/1");
+    expect(md).toContain("❌ failed");
+  });
+
+  it("lists suite names with source labels", () => {
+    const md = buildSummaryMarkdown(
+      [freshSource, storeSource],
+      passResult,
+      "https://example.com/run/1",
+    );
+    expect(md).toContain("`backend`");
+    expect(md).toContain("fresh");
+    expect(md).toContain("`frontend`");
+    expect(md).toContain("store (main)");
+  });
+
+  it("uses the provided branch name in store source label", () => {
+    const md = buildSummaryMarkdown(
+      [storeSource],
+      passResult,
+      "https://example.com/run/1",
+      "feature/my-branch",
+    );
+    expect(md).toContain("store (feature/my-branch)");
+  });
+
+  it("shows line coverage percentage for suite", () => {
+    const md = buildSummaryMarkdown([freshSource], passResult, "https://example.com/run/1");
+    // 2/3 lines covered = 66.7%
+    expect(md).toContain("66.7%");
+  });
+
+  it("shows — for empty lcov data", () => {
+    const emptySource: SuiteSource = { suite: "empty", source: "fresh", lcov: new Map() };
+    const md = buildSummaryMarkdown([emptySource], passResult, "https://example.com/run/1");
+    expect(md).toContain("—");
+  });
+
+  it("shows rule thresholds and pass/fail status", () => {
+    const md = buildSummaryMarkdown([freshSource], passResult, "https://example.com/run/1");
+    expect(md).toContain("backend/**");
+    expect(md).toContain("90%");
+    expect(md).toContain("✅");
+  });
+
+  it("shows ❌ for failing rule", () => {
+    const md = buildSummaryMarkdown([freshSource], failResult, "https://example.com/run/1");
+    expect(md).toContain("❌");
+  });
+
+  it("shows — in rule table when bucket has no coverable lines", () => {
+    const noCoverableResult: CoverageCheckResult = {
+      passed: false,
+      buckets: [
+        { rule: "backend/**", threshold: 90, coverable: 0, hit: 0, passed: false, files: [] },
+      ],
+      informational: [],
+    };
+    const md = buildSummaryMarkdown([], noCoverableResult, "N/A");
+    expect(md).toContain("—");
+  });
+
+  it("renders empty-suite placeholder row when no sources provided", () => {
+    const md = buildSummaryMarkdown([], passResult, "N/A");
+    expect(md).toContain("| — | — | — |");
+  });
+
+  it("renders empty-rule placeholder row when no buckets provided", () => {
+    const emptyResult: CoverageCheckResult = { passed: true, buckets: [], informational: [] };
+    const md = buildSummaryMarkdown([], emptyResult, "N/A");
+    expect(md).toContain("| — | — | — | — |");
+  });
+
+  it("includes run link when runUrl is a valid URL", () => {
+    const md = buildSummaryMarkdown([], passResult, "https://example.com/run/42");
+    expect(md).toContain("https://example.com/run/42");
+    expect(md).toContain("[View run]");
+  });
+
+  it("omits run link when runUrl is N/A", () => {
+    const md = buildSummaryMarkdown([], passResult, "N/A");
+    expect(md).not.toContain("[View run]");
+    expect(md).not.toContain("N/A");
+  });
+
+  it("escapes pipe characters in suite names, branch names, and rule names", () => {
+    const pipeSource: SuiteSource = {
+      suite: "back|end",
+      source: "store",
+      lcov: new Map(),
+    };
+    const pipeResult: CoverageCheckResult = {
+      passed: true,
+      buckets: [
+        { rule: "back|end/**", threshold: 90, coverable: 10, hit: 10, passed: true, files: [] },
+      ],
+      informational: [],
+    };
+    const md = buildSummaryMarkdown([pipeSource], pipeResult, "N/A", "feat|branch");
+    expect(md).toContain("back\\|end");
+    expect(md).toContain("feat\\|branch");
+  });
+});
+
+describe("writeSummary", () => {
+  let tmpDir: string;
+  let summaryFile: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "step-summary-"));
+    summaryFile = join(tmpDir, "summary.md");
+    writeFileSync(summaryFile, "");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appends summary markdown to the summary file", () => {
+    writeSummary(summaryFile, [freshSource], passResult, "https://example.com");
+    const content = readFileSync(summaryFile, "utf8");
+    expect(content).toContain("Coverage summary");
+    expect(content).toContain("backend");
+  });
+
+  it("appends to existing content", () => {
+    writeFileSync(summaryFile, "# Prior content\n");
+    writeSummary(summaryFile, [], passResult, "N/A");
+    const content = readFileSync(summaryFile, "utf8");
+    expect(content).toContain("# Prior content");
+    expect(content).toContain("Coverage summary");
+  });
+});

package/src/store-factory.mts

@@ -0,0 +1,23 @@
+import { FileSystemSuiteStore } from "./suite-store.mts";
+import { S3SuiteStore } from "./s3-suite-store.mts";
+import type { SuiteStore } from "./suite-store.mts";
+
+/** Parse "bucket/prefix" or "bucket" into S3SuiteStore constructor args. */
+export function parseS3Spec(spec: string): { bucket: string; prefix?: string } {
+  const slash = spec.indexOf("/");
+  const bucket = slash === -1 ? spec : spec.slice(0, slash);
+  if (!bucket) throw new Error(`invalid S3 spec ${JSON.stringify(spec)}: bucket must not be empty`);
+  if (slash === -1) return { bucket };
+  const prefix = spec.slice(slash + 1).replace(/^\/+|\/+$/g, "");
+  return prefix ? { bucket, prefix } : { bucket };
+}
+
+/** Build a SuiteStore from CLI flag values. Returns null if neither is set. */
+export function makeStore(opts: { fs?: string | null; s3?: string | null }): SuiteStore | null {
+  if (opts.s3 != null) {
+    const { bucket, prefix } = parseS3Spec(opts.s3);
+    return new S3SuiteStore({ bucket, prefix });
+  }
+  if (opts.fs != null) return new FileSystemSuiteStore(opts.fs);
+  return null;
+}

package/src/store-factory.test.mts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import { parseS3Spec, makeStore } from "./store-factory.mts";
+import { FileSystemSuiteStore } from "./suite-store.mts";
+import { S3SuiteStore } from "./s3-suite-store.mts";
+
+describe("parseS3Spec", () => {
+  it("returns bucket-only when no slash present", () => {
+    expect(parseS3Spec("my-bucket")).toEqual({ bucket: "my-bucket" });
+  });
+
+  it("splits on first slash into bucket and prefix", () => {
+    expect(parseS3Spec("my-bucket/my/deep/prefix")).toEqual({
+      bucket: "my-bucket",
+      prefix: "my/deep/prefix",
+    });
+  });
+
+  it("handles a single-segment prefix", () => {
+    expect(parseS3Spec("bucket/prefix")).toEqual({ bucket: "bucket", prefix: "prefix" });
+  });
+
+  it("throws when spec starts with a slash (empty bucket)", () => {
+    expect(() => parseS3Spec("/prefix")).toThrow("bucket must not be empty");
+  });
+
+  it("throws when spec is empty", () => {
+    expect(() => parseS3Spec("")).toThrow("bucket must not be empty");
+  });
+
+  it("omits prefix when trailing slash yields empty prefix", () => {
+    expect(parseS3Spec("bucket/")).toEqual({ bucket: "bucket" });
+  });
+
+  it("normalizes double slashes in prefix", () => {
+    expect(parseS3Spec("bucket//foo")).toEqual({ bucket: "bucket", prefix: "foo" });
+  });
+});
+
+describe("makeStore", () => {
+  it("returns null when neither fs nor s3 is provided", () => {
+    expect(makeStore({ fs: null, s3: null })).toBeNull();
+  });
+
+  it("returns null when both are undefined", () => {
+    expect(makeStore({})).toBeNull();
+  });
+
+  it("returns a FileSystemSuiteStore for an fs path", () => {
+    expect(makeStore({ fs: "/tmp/store" })).toBeInstanceOf(FileSystemSuiteStore);
+  });
+
+  it("returns an S3SuiteStore for an s3 spec", () => {
+    expect(makeStore({ s3: "my-bucket" })).toBeInstanceOf(S3SuiteStore);
+  });
+
+  it("returns an S3SuiteStore for an s3 spec with prefix", () => {
+    expect(makeStore({ s3: "my-bucket/prefix" })).toBeInstanceOf(S3SuiteStore);
+  });
+
+  it("prefers s3 over fs when both are provided", () => {
+    expect(makeStore({ fs: "/tmp/store", s3: "my-bucket" })).toBeInstanceOf(S3SuiteStore);
+  });
+
+  it("throws when s3 spec is an empty string (not silently treated as absent)", () => {
+    expect(() => makeStore({ s3: "" })).toThrow("bucket must not be empty");
+  });
+});