@solhun/feedback-kit-core 0.1.0

package/src/adapters/adapters.test.ts

@@ -0,0 +1,730 @@
+// DP-255 어댑터 TC 검증.
+//
+// import 를 어댑터 파일이 아니라 **코어 공개 진입점(`../index.js`)** 에서 하는 이유:
+// 여기서 확인하려는 건 "파일 안의 함수가 맞게 도는가"보다 "호스트가 실제로 손에 쥐는
+// 표면이 맞는가"다. 배럴 배선이 빠지면 파일 단위 테스트는 통과하면서 소비자만 깨진다.
+
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  buildLassoEnvelope,
+  buildLinearIssue,
+  buildNotionPage,
+  buildTitle,
+  createLassoAdapter,
+  FeedbackQueue,
+  LASSO_DEFAULT_ENDPOINT,
+  renderReportBody,
+  TITLE_MAX_CHARS,
+} from "../index.js";
+import type {
+  FeedbackAdapter,
+  FeedbackReport,
+  FeedbackStorage,
+  LassoFetch,
+  LassoRequestInit,
+  LassoResponseLike,
+  QueueStatus,
+  SubmitOutcome,
+  SubmitResult,
+} from "../index.js";
+
+// ────────────────────────────────────────────────────────────────────────────
+// 공용 도구
+// ────────────────────────────────────────────────────────────────────────────
+
+const START_TIME = 1_700_000_000_000;
+let clockNow = START_TIME;
+const clock = (): number => clockNow;
+const advance = (ms: number): void => {
+  clockNow += ms;
+};
+
+const ENDPOINT = "https://ingest.example/api/feedback";
+
+let seq = 0;
+
+function makeReport(over: Partial<FeedbackReport> = {}): FeedbackReport {
+  seq += 1;
+  return {
+    clientSubmissionId: `sub-${seq}`,
+    kind: "report",
+    comment: `테스트 제보 ${seq}`,
+    priority: "unset",
+    screenshot: null,
+    pin: null,
+    element: null,
+    context: {
+      app: "test-app",
+      screen: "/home",
+      url: null,
+      sessionId: "session-1",
+      user: { id: "guest_1", email: null, isGuest: true },
+      source: { screenId: null, sourceFile: null },
+      platform: "unknown",
+      timezone: "Asia/Seoul",
+      clientTimestamp: new Date(clockNow).toISOString(),
+      native: null,
+      web: null,
+      diagnostics: null,
+      extra: {},
+    },
+    createdAt: new Date(clockNow).toISOString(),
+    ...over,
+  };
+}
+
+/**
+ * 담을 수 있는 값을 전부 채운 제보.
+ *
+ * TC3·TC4·TC5 가 전부 "대상이 못 받는 값이 어디로 가는가"를 묻기 때문에,
+ * 빈 컨텍스트로는 아무것도 증명되지 않는다(접을 게 없으면 접힘 규칙도 안 깨진다).
+ */
+function makeRichReport(over: Partial<FeedbackReport> = {}): FeedbackReport {
+  const base = makeReport({
+    kind: "annotation",
+    comment: "저장 버튼을 눌러도 아무 일이 없다",
+    priority: "high",
+    screenshot: { base64: "AAAA".repeat(64), contentType: "image/png" },
+    pin: { x: 0.5, y: 0.25 },
+    element: {
+      tag: "button",
+      id: "save",
+      className: "btn primary",
+      text: "저장",
+      boundingBox: { x: 10, y: 20, width: 80, height: 32 },
+      attributes: { "data-testid": "save-button" },
+    },
+  });
+  return {
+    ...base,
+    context: {
+      ...base.context,
+      url: "https://app.example/orders/1?token=abc",
+      platform: "native",
+      source: { screenId: "OrderDetail", sourceFile: "src/screens/Order.tsx", sourceLine: 42 },
+      native: {
+        screenPath: "src/screens/Order.tsx",
+        navPath: ["Root", "Orders", "OrderDetail"],
+        routeParams: { orderId: 1 },
+        appInfo: { version: "1.2.3", channel: "preview", updateId: "u-1", runtimeVersion: "1.0.0" },
+        device: { model: "iPhone 15", osName: "iOS", osVersion: "17.4", deviceType: "phone" },
+        display: { width: 393, height: 852, pixelRatio: 3, fontScale: 1 },
+      },
+      web: {
+        viewport: { width: 1280, height: 800, devicePixelRatio: 2 },
+        userAgent: "Mozilla/5.0 (test)",
+      },
+      diagnostics: {
+        network: [
+          {
+            method: "POST",
+            url: "https://api.example/orders?token=%5BREDACTED%5D",
+            status: 500,
+            durationMs: 812,
+            at: "2026-02-01T09:00:00.000Z",
+          },
+          {
+            method: "GET",
+            url: "https://api.example/me",
+            status: null,
+            durationMs: 30_000,
+            at: "2026-02-01T09:00:01.000Z",
+          },
+        ],
+        logs: [
+          { level: "error", message: "저장 실패: 500", at: "2026-02-01T09:00:02.000Z" },
+        ],
+      },
+      extra: { build: "ci-42" },
+    },
+    ...over,
+  };
+}
+
+function memoryStorage(): FeedbackStorage {
+  const map = new Map<string, string>();
+  return {
+    async get(key) {
+      return map.get(key) ?? null;
+    },
+    async set(key, value) {
+      map.set(key, value);
+    },
+    async remove(key) {
+      map.delete(key);
+    },
+  };
+}
+
+interface FetchStep {
+  status?: number;
+  /** 응답 본문 원문. JSON 이 아닐 수도 있다(프록시가 끼어든 상황 재현). */
+  body?: string;
+  headers?: Record<string, string>;
+  /** 값이 있으면 fetch 자체가 그 값을 던진다(네트워크 오류). */
+  throws?: unknown;
+  /** true 면 본문 읽기에서 실패한다(끊긴 스트림). */
+  textThrows?: boolean;
+}
+
+function fakeFetch(steps: FetchStep[] = []) {
+  const calls: Array<{ url: string; init: LassoRequestInit }> = [];
+  const plan = [...steps];
+  const impl: LassoFetch = async (url, init) => {
+    calls.push({ url, init });
+    const step = plan.shift() ?? {};
+    if (step.throws !== undefined) throw step.throws;
+    const status = step.status ?? 200;
+    const body = step.body ?? JSON.stringify({ ok: true, id: `srv-${calls.length}` });
+    const headers = new Map(Object.entries(step.headers ?? {}));
+    const res: LassoResponseLike = {
+      status,
+      headers: { get: (name) => headers.get(name) ?? null },
+      text: async () => {
+        if (step.textThrows === true) throw new Error("stream closed");
+        return body;
+      },
+    };
+    return res;
+  };
+  return { calls, impl };
+}
+
+/** 경고를 모으되 원문을 그대로 보관한다(누설 검사가 이 문자열을 훑는다). */
+function warnSink() {
+  const lines: string[] = [];
+  const warn = (message: string, ...rest: unknown[]): void => {
+    lines.push([message, ...rest].map((v) => String(v)).join(" "));
+  };
+  return { lines, warn };
+}
+
+beforeEach(() => {
+  clockNow = START_TIME;
+  seq = 0;
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC1 — 어댑터를 바꿔도 코어 동작이 같다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("TC1 어댑터를 바꿔도 코어 동작이 같다", () => {
+  /** 시나리오에서 어댑터가 낼 결과 순서. */
+  type Step = "ok" | "retryable" | "dead";
+
+  const OK_ID = "srv-ok-1";
+
+  interface Probe {
+    adapter: FeedbackAdapter;
+    /** 각 시도에 실린 멱등 키. 재시도가 같은 키를 쓰는지 본다. */
+    keys: () => string[];
+  }
+
+  /** 실제 라쏘런 어댑터 + 가짜 전송. 계획을 HTTP 응답으로 번역한다. */
+  function lassoProbe(plan: Step[]): Probe {
+    const steps: FetchStep[] = plan.map((step) => {
+      if (step === "ok") return { status: 200, body: JSON.stringify({ ok: true, id: OK_ID }) };
+      if (step === "retryable") return { status: 503 };
+      return { status: 400 };
+    });
+    const { calls, impl } = fakeFetch(steps);
+    const adapter = createLassoAdapter({
+      endpoint: ENDPOINT,
+      fetch: impl,
+      token: "fk_test_token",
+      warn: () => {},
+    });
+    return { adapter, keys: () => calls.map((c) => c.init.headers["Idempotency-Key"]) };
+  }
+
+  /** 코어가 요구하는 최소 계약만 만족하는 다른 어댑터(전송 없음). */
+  function inlineProbe(plan: Step[]): Probe {
+    const seen: string[] = [];
+    const rest = [...plan];
+    const adapter: FeedbackAdapter = {
+      async submit(report) {
+        seen.push(report.clientSubmissionId);
+        const step = rest.shift() ?? "ok";
+        if (step === "ok") return { ok: true, id: OK_ID, retryable: false, retryAfterMs: null };
+        return { ok: false, id: null, retryable: step === "retryable", retryAfterMs: null };
+      },
+    };
+    return { adapter, keys: () => seen };
+  }
+
+  interface Observed {
+    outcome: SubmitOutcome;
+    sizeAfterSubmit: number;
+    sizeAfterRetry: number;
+    status: QueueStatus;
+    keys: string[];
+  }
+
+  async function observe(probeFor: (plan: Step[]) => Probe, plan: Step[]): Promise<Observed> {
+    clockNow = START_TIME;
+    const { adapter, keys } = probeFor(plan);
+    const queue = new FeedbackQueue({
+      storage: memoryStorage(),
+      adapter,
+      now: clock,
+      flushIntervalMs: 0,
+    });
+    const outcome = await queue.submit(makeReport({ clientSubmissionId: "sub-fixed" }));
+    const sizeAfterSubmit = await queue.size();
+    advance(10 * 60 * 1000); // 백오프를 확실히 넘긴다
+    await queue.flush();
+    const sizeAfterRetry = await queue.size();
+    return { outcome, sizeAfterSubmit, sizeAfterRetry, status: queue.getStatus(), keys: keys() };
+  }
+
+  const PLANS: Array<[string, Step[]]> = [
+    ["첫 시도에 성공", ["ok"]],
+    ["한 번 실패 후 재시도 성공", ["retryable", "ok"]],
+    ["재시도 불가 실패", ["dead"]],
+  ];
+
+  it.each(PLANS)("%s — 라쏘런 어댑터와 최소 어댑터의 관측값이 같다", async (_name, plan) => {
+    const viaLasso = await observe(lassoProbe, plan);
+    const viaInline = await observe(inlineProbe, plan);
+    expect(viaLasso).toEqual(viaInline);
+  });
+
+  it("성공하면 큐에서 사라지고 서버 id 가 그대로 올라온다", async () => {
+    for (const probe of [lassoProbe, inlineProbe]) {
+      const seenResult = await observe(probe, ["ok"]);
+      expect(seenResult.outcome).toEqual({ delivered: true, id: OK_ID, queued: false });
+      expect(seenResult.sizeAfterSubmit).toBe(0);
+    }
+  });
+
+  it("재시도는 같은 멱등 키를 다시 쓴다(중복 적재 방지)", async () => {
+    for (const probe of [lassoProbe, inlineProbe]) {
+      const seenResult = await observe(probe, ["retryable", "ok"]);
+      expect(seenResult.outcome.queued).toBe(true);
+      expect(seenResult.sizeAfterSubmit).toBe(1);
+      expect(seenResult.sizeAfterRetry).toBe(0);
+      expect(seenResult.keys).toEqual(["sub-fixed", "sub-fixed"]);
+    }
+  });
+
+  it("재시도 불가 실패는 두 어댑터 모두 큐에 쌓지 않는다", async () => {
+    for (const probe of [lassoProbe, inlineProbe]) {
+      const seenResult = await observe(probe, ["dead"]);
+      expect(seenResult.outcome).toEqual({ delivered: false, id: null, queued: false });
+      expect(seenResult.sizeAfterSubmit).toBe(0);
+      expect(seenResult.status.lastError).toBe("non-retryable");
+    }
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC2 — 어댑터가 실패를 결과로 돌려준다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("TC2 어댑터가 실패를 결과로 돌려준다", () => {
+  function adapterWith(steps: FetchStep[], over: { token?: string | null } = {}) {
+    const { calls, impl } = fakeFetch(steps);
+    const sink = warnSink();
+    const adapter = createLassoAdapter({
+      endpoint: ENDPOINT,
+      fetch: impl,
+      token: over.token ?? null,
+      warn: sink.warn,
+    });
+    return { adapter, calls, warned: sink.lines };
+  }
+
+  const FAILURES: Array<[string, FetchStep, Partial<SubmitResult>]> = [
+    ["네트워크 예외", { throws: new TypeError("Failed to fetch") }, { retryable: true, retryAfterMs: null }],
+    [
+      "429 는 대기 시간을 함께 돌려준다",
+      { status: 429, headers: { "Retry-After": "30" } },
+      { retryable: true, retryAfterMs: 30_000, rateLimited: true },
+    ],
+    ["408", { status: 408 }, { retryable: true }],
+    ["425", { status: 425 }, { retryable: true }],
+    ["500", { status: 500 }, { retryable: true }],
+    ["502", { status: 502 }, { retryable: true }],
+    ["503", { status: 503 }, { retryable: true }],
+    ["504", { status: 504 }, { retryable: true }],
+    ["400", { status: 400 }, { retryable: false }],
+    ["401", { status: 401 }, { retryable: false }],
+    ["403", { status: 403 }, { retryable: false }],
+    ["413", { status: 413 }, { retryable: false }],
+    ["2xx 이지만 ok:false", { status: 200, body: '{"ok":false,"error":"invalid"}' }, { retryable: false }],
+    ["2xx 인데 본문이 JSON 이 아님", { status: 200, body: "<!doctype html><title>502</title>" }, { retryable: true }],
+    ["2xx 인데 본문을 못 읽음", { status: 200, textThrows: true }, { retryable: true }],
+  ];
+
+  it.each(FAILURES)("%s — 던지지 않고 실패를 결과로 돌려준다", async (_name, step, expected) => {
+    const { adapter } = adapterWith([step]);
+    const result = await adapter.submit(makeReport());
+    expect(result).toMatchObject({ ok: false, id: null, ...expected });
+  });
+
+  it("2xx + ok:true 면 성공과 서버 id 를 돌려준다", async () => {
+    const { adapter } = adapterWith([{ status: 200, body: '{"ok":true,"id":"srv-9"}' }]);
+    await expect(adapter.submit(makeReport())).resolves.toEqual({
+      ok: true,
+      id: "srv-9",
+      retryable: false,
+      retryAfterMs: null,
+    });
+  });
+
+  it("id 가 data 안에 있어도 찾아낸다", async () => {
+    const { adapter } = adapterWith([{ status: 200, body: '{"ok":true,"data":{"id":"nested-1"}}' }]);
+    const result = await adapter.submit(makeReport());
+    expect(result).toMatchObject({ ok: true, id: "nested-1" });
+  });
+
+  it("id 가 없어도 성공은 성공이다", async () => {
+    const { adapter } = adapterWith([{ status: 200, body: '{"ok":true}' }]);
+    expect(await adapter.submit(makeReport())).toMatchObject({ ok: true, id: null });
+  });
+
+  it("Retry-After 가 숫자가 아니면 무시한다(문자열을 그대로 믿지 않는다)", async () => {
+    const { adapter } = adapterWith([
+      { status: 429, headers: { "Retry-After": "Wed, 21 Oct 2026 07:28:00 GMT" } },
+    ]);
+    const result = await adapter.submit(makeReport());
+    expect(result).toMatchObject({ ok: false, retryable: true, rateLimited: true, retryAfterMs: null });
+  });
+
+  it("Error 가 아닌 값을 던져도 결과로 바꾼다", async () => {
+    const { adapter } = adapterWith([{ throws: "boom" }]);
+    expect(await adapter.submit(makeReport())).toMatchObject({ ok: false, retryable: true });
+  });
+
+  it("전송 수단이 아예 없으면 재시도 가능한 실패다(끊긴 게 아니라 아직 못 보낸 것)", async () => {
+    vi.stubGlobal("fetch", undefined);
+    const sink = warnSink();
+    const adapter = createLassoAdapter({ endpoint: ENDPOINT, warn: sink.warn });
+    expect(await adapter.submit(makeReport())).toMatchObject({ ok: false, retryable: true });
+    expect(sink.lines.length).toBeGreaterThan(0);
+  });
+
+  it("상대 endpoint 인데 오리진이 없으면 재시도하지 않는다(재시도해도 같은 결과다)", async () => {
+    const { impl, calls } = fakeFetch([]);
+    const sink = warnSink();
+    const adapter = createLassoAdapter({ fetch: impl, warn: sink.warn });
+    expect(await adapter.submit(makeReport())).toMatchObject({ ok: false, retryable: false });
+    expect(calls).toHaveLength(0); // 보내보지도 않는다
+    expect(sink.lines.join("\n")).toContain(LASSO_DEFAULT_ENDPOINT);
+  });
+
+  it("오리진이 있으면 상대 endpoint 를 절대 URL 로 만든다", async () => {
+    vi.stubGlobal("location", { origin: "https://app.example" });
+    const { impl, calls } = fakeFetch([{ status: 200, body: '{"ok":true,"id":"srv-1"}' }]);
+    const adapter = createLassoAdapter({ fetch: impl, warn: () => {} });
+    await adapter.submit(makeReport());
+    expect(calls[0]?.url).toBe(`https://app.example${LASSO_DEFAULT_ENDPOINT}`);
+  });
+
+  it("토큰이 있으면 Authorization 을, 없으면 아예 헤더를 안 붙인다", async () => {
+    const withToken = adapterWith([{ status: 200 }], { token: "fk_live_1" });
+    await withToken.adapter.submit(makeReport());
+    expect(withToken.calls[0]?.init.headers.Authorization).toBe("Bearer fk_live_1");
+    expect(withToken.calls[0]?.init.headers["Idempotency-Key"]).toBe("sub-1");
+
+    const withoutToken = adapterWith([{ status: 200 }]);
+    await withoutToken.adapter.submit(makeReport());
+    expect(withoutToken.calls[0]?.init.headers.Authorization).toBeUndefined();
+    expect(withoutToken.calls[0]?.init.headers["Idempotency-Key"]).toBe("sub-2");
+  });
+
+  // 이 검사가 TC2 의 진짜 목적이다. 실패를 "결과로" 돌려준다는 건 실패 사실을 어딘가에
+  // 뱉지 않는다는 뜻이기도 하다 — 진단 로그로 토큰·본문이 새면 실패 처리 자체가 사고다.
+  it("경고 어디에도 토큰·요청 본문·헤더 이름이 실리지 않는다", async () => {
+    const token = "fk_live_SECRET_TOKEN";
+    const secret = "비밀번호가 1234 라서 안 된다";
+    const warned: string[] = [];
+    for (const [, step] of FAILURES) {
+      const { adapter, warned: lines } = adapterWith([step], { token });
+      await adapter.submit(makeReport({ comment: secret }));
+      warned.push(...lines);
+    }
+    const joined = warned.join("\n");
+    expect(warned.length).toBeGreaterThan(0); // 아무 경고도 없으면 검사가 공허하다
+    expect(joined).not.toContain(token);
+    expect(joined).not.toContain(secret);
+    expect(joined).not.toContain("Authorization");
+    expect(joined).not.toContain("Bearer");
+  });
+
+  it("warn 이 던져도 전송 결과에는 영향이 없다", async () => {
+    const { impl } = fakeFetch([{ status: 500 }]);
+    const adapter = createLassoAdapter({
+      endpoint: ENDPOINT,
+      fetch: impl,
+      warn: () => {
+        throw new Error("콘솔이 막혔다");
+      },
+    });
+    expect(await adapter.submit(makeReport())).toMatchObject({ ok: false, retryable: true });
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC3 — 대상이 못 받는 필드는 본문에 접어 넣는다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("TC3 대상이 못 받는 필드는 본문에 접어 넣는다", () => {
+  const count = (haystack: string, needle: string): number => haystack.split(needle).length - 1;
+
+  it("제보 하나당 접힌 블록은 정확히 하나다", () => {
+    const body = renderReportBody(makeRichReport());
+    expect(count(body, "<details>")).toBe(1);
+    expect(count(body, "</details>")).toBe(1);
+    expect(count(body, "<summary>")).toBe(1);
+  });
+
+  it("사용자 코멘트는 블록 밖, 진단 값들은 블록 안에 있다", () => {
+    const report = makeRichReport();
+    const body = renderReportBody(report);
+    const open = body.indexOf("<details>");
+    const close = body.indexOf("</details>");
+
+    expect(body.indexOf(report.comment)).toBeLessThan(open);
+    for (const label of ["- 소스:", "- 요소:", "- 기기:", "- 진단 네트워크", "- 진단 로그", "- 핀:"]) {
+      const at = body.indexOf(label);
+      expect(at).toBeGreaterThan(open);
+      expect(at).toBeLessThan(close);
+    }
+  });
+
+  it("로그 본문에 </details> 가 들어 있어도 블록이 거기서 닫히지 않는다", () => {
+    const report = makeRichReport();
+    report.context.diagnostics = {
+      network: [],
+      logs: [
+        { level: "warn", message: "툴팁이 </details> 때문에 깨진다", at: "2026-02-01T09:00:00.000Z" },
+      ],
+    };
+    const body = renderReportBody(report);
+    expect(count(body, "</details>")).toBe(1);
+    expect(body).toContain("&lt;/details>");
+  });
+
+  it("여러 줄 로그가 접힌 블록의 줄 구조를 흐트러뜨리지 않는다", () => {
+    const report = makeRichReport();
+    report.context.diagnostics = {
+      network: [],
+      logs: [{ level: "error", message: "1행\n2행\n3행", at: "2026-02-01T09:00:00.000Z" }],
+    };
+    const body = renderReportBody(report);
+    expect(body).toContain("[error] 1행 2행 3행");
+    expect(body).not.toContain("1행\n2행");
+  });
+
+  it("'수집 안 함'과 '수집했는데 비어 있음'을 본문에서 구분한다", () => {
+    const notCollected = makeRichReport();
+    notCollected.context.diagnostics = null;
+    expect(renderReportBody(notCollected)).toContain("- 진단: 수집하지 않음");
+
+    const empty = makeRichReport();
+    empty.context.diagnostics = { network: [], logs: [] };
+    const body = renderReportBody(empty);
+    expect(body).toContain("- 진단 네트워크 (0건)");
+    expect(body).toContain("- 진단 로그 (0건)");
+    expect(body).not.toContain("수집하지 않음");
+  });
+
+  // 라쏘런은 headline 필드가 없고 comment 하나로 받는다(실호출로 확정한 계약).
+  // 지목 제보면 annotation.comment, 리포트 제출이면 report.comment 에 들어간다.
+  function lassoBody(envelope: ReturnType<typeof buildLassoEnvelope>): string {
+    return envelope.report?.comment ?? envelope.annotation?.comment ?? "";
+  }
+
+  it("라쏘런 봉투는 구조화 필드로 못 받는 값을 본문 안에 담아 보낸다", () => {
+    const report = makeRichReport();
+    const envelope = buildLassoEnvelope(report);
+    // 봉투에 진단·요소·기기 전용 필드는 없다. 없다고 값이 사라지면 안 된다.
+    for (const key of Object.keys(envelope)) {
+      expect(key).not.toMatch(/diagnostic|element|device|display|native/i);
+    }
+    for (const needle of ["- 진단 네트워크", "- 요소:", "- 기기:", "- 내비 스택:"]) {
+      expect(lassoBody(envelope)).toContain(needle);
+    }
+    expect(count(lassoBody(envelope), "</details>")).toBe(1);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC4 — 어댑터가 달라도 사람이 읽는 내용은 같다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("TC4 어댑터가 달라도 사람이 읽는 내용은 같다", () => {
+  const VARIANTS: Array<[string, () => FeedbackReport]> = [
+    ["최소 제보", () => makeReport()],
+    ["전부 채운 제보", () => makeRichReport()],
+    ["코멘트가 빈 제보", () => makeRichReport({ comment: "   " })],
+    ["코멘트가 아주 긴 제보", () => makeRichReport({ comment: "가".repeat(300) })],
+    [
+      "진단을 수집하지 않은 제보",
+      () => {
+        const r = makeRichReport();
+        r.context.diagnostics = null;
+        return r;
+      },
+    ],
+  ];
+
+  it.each(VARIANTS)("%s — 세 대상의 본문과 제목이 글자 단위로 같다", (_name, build) => {
+    const report = build();
+    const lasso = buildLassoEnvelope(report);
+    const linear = buildLinearIssue(report);
+    const notion = buildNotionPage(report);
+
+    const lassoText = lasso.report?.comment ?? lasso.annotation?.comment ?? "";
+    expect(new Set([lassoText, linear.description, notion.content]).size).toBe(1);
+    // 라쏘런은 제목 필드가 없다(comment 첫 줄이 목록에 뜬다) → 제목 비교 대상에서 뺀다.
+    expect(new Set([linear.title, notion.title]).size).toBe(1);
+    // 렌더러가 바뀌어도 세 대상이 함께 움직인다는 것까지 고정한다.
+    expect(linear.description).toBe(renderReportBody(report));
+    expect(notion.title).toBe(buildTitle(report));
+  });
+
+  it("제목은 코멘트 첫 줄에서 오고, 비면 화면 이름으로 대체된다", () => {
+    const report = makeRichReport({ comment: "첫 줄\n둘째 줄" });
+    expect(buildTitle(report)).toBe("첫 줄");
+
+    const blank = makeRichReport({ comment: "   " });
+    expect(buildTitle(blank)).toBe("요소 주석 — /home");
+  });
+
+  it("긴 제목은 잘리되 세 대상에서 똑같이 잘린다", () => {
+    const report = makeRichReport({ comment: "가".repeat(300) });
+    const title = buildTitle(report);
+    expect(title).toHaveLength(TITLE_MAX_CHARS);
+    expect(title.endsWith("…")).toBe(true);
+    expect(buildLinearIssue(report).title).toBe(title);
+    expect(buildNotionPage(report).title).toBe(title);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────────
+// TC5 — 코어가 특정 어댑터의 payload 형태를 참조하지 않는다
+// ────────────────────────────────────────────────────────────────────────────
+
+describe("TC5 코어가 특정 어댑터의 payload 형태를 참조하지 않는다", () => {
+  // 검사 대상은 `packages/core/src` **바로 아래**의 비테스트 .ts 파일이다.
+  // `adapters/` 하위는 일부러 뺀다 — 거기는 대상별 모양을 아는 게 일이다.
+  // 확인하는 건 "코어 본체가 특정 대상의 필드명을 알고 있는가"다.
+  const CORE_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+
+  function coreFiles(): string[] {
+    return readdirSync(CORE_DIR, { withFileTypes: true })
+      .filter((e) => e.isFile() && e.name.endsWith(".ts") && !e.name.endsWith(".test.ts"))
+      .map((e) => e.name);
+  }
+
+  function read(name: string): string {
+    return readFileSync(join(CORE_DIR, name), "utf8");
+  }
+
+  /** 중첩까지 훑어 객체의 키 이름을 모은다. */
+  function collectKeys(value: unknown, into = new Set<string>()): Set<string> {
+    if (Array.isArray(value)) {
+      for (const item of value) collectKeys(item, into);
+      return into;
+    }
+    if (value !== null && typeof value === "object") {
+      for (const [key, child] of Object.entries(value)) {
+        into.add(key);
+        collectKeys(child, into);
+      }
+    }
+    return into;
+  }
+
+  /** 실제로 전선에 실린 payload 를 붙잡는다(빌더 반환값이 아니라 직렬화된 본문). */
+  async function capturePayload(report: FeedbackReport): Promise<Record<string, unknown>> {
+    const { calls, impl } = fakeFetch([{ status: 200 }]);
+    const adapter = createLassoAdapter({ endpoint: ENDPOINT, fetch: impl, warn: () => {} });
+    await adapter.submit(report);
+    const raw = calls[0]?.init.body ?? "{}";
+    return JSON.parse(raw) as Record<string, unknown>;
+  }
+
+  it("검사기가 볼 파일을 실제로 찾았다", () => {
+    // 파일이 옮겨지면 아래 검사들이 '아무것도 못 찾아서' 조용히 통과할 수 있다.
+    const files = coreFiles();
+    expect(files.length).toBeGreaterThanOrEqual(10);
+    for (const must of ["queue.ts", "types.ts", "config.ts", "report.ts", "context.ts"]) {
+      expect(files).toContain(must);
+    }
+  });
+
+  /**
+   * 코어가 자기 도메인 이름으로 정당하게 쓰는 단어들(types.ts 의 필드명).
+   * 실제 라쏘런 계약은 url·timestamp·logs 처럼 **일반적인** 이름을 쓰므로,
+   * 이걸 빼지 않으면 "코어가 대상 필드명을 안다"가 아니라 "같은 단어를 쓴다"를
+   * 잡게 된다. 검사 대상은 대상에만 있는 이름이어야 한다.
+   */
+  function coreVocabulary(): Set<string> {
+    const names = new Set<string>();
+    const types = read("types.ts");
+    // 필드명 (`comment: string`)
+    for (const match of types.matchAll(/^\s*(\w+)\??:/gm)) names.add(match[1]);
+    // 유니온 리터럴 (`"report" | "annotation"`) — 이것도 코어가 아는 자기 어휘다.
+    for (const match of types.matchAll(/"(\w+)"/g)) names.add(match[1]);
+    return names;
+  }
+
+  it("라쏘런 봉투에만 있는 필드명이 코어 본체 어디에도 없다", async () => {
+    const report = makeRichReport();
+    const payload = await capturePayload(report);
+
+    // 금지어 목록을 손으로 적지 않는다 — payload 에서 제보 자체의 키와 코어 어휘를
+    // 뺀 나머지가 정의상 "라쏘런에만 있는 이름"이다. 봉투가 바뀌면 목록도 따라 바뀐다.
+    const known = new Set([...collectKeys(report), ...coreVocabulary()]);
+    const lassoOnly = [...collectKeys(payload)].filter((key) => !known.has(key));
+    expect(lassoOnly.length).toBeGreaterThan(2); // 목록이 비면 검사가 공허하다
+
+    const lassoSource = read(join("adapters", "lasso.ts"));
+    const coreSources = coreFiles().map((name) => [name, read(name)] as const);
+
+    for (const key of lassoOnly) {
+      const word = new RegExp(`\\b${key}\\b`);
+      expect(lassoSource, `${key} 는 어댑터에 있어야 한다`).toMatch(word);
+      for (const [name, text] of coreSources) {
+        expect(text, `${name} 이 라쏘런 필드명 ${key} 를 알고 있다`).not.toMatch(word);
+      }
+    }
+  });
+
+  it("멱등 키 헤더 이름도 어댑터에만 있다", () => {
+    expect(read(join("adapters", "lasso.ts"))).toContain("Idempotency-Key");
+    for (const name of coreFiles()) {
+      expect(read(name), `${name}`).not.toContain("Idempotency-Key");
+    }
+  });
+
+  it("코어 본체는 어댑터를 import 하지 않는다(공개 진입점의 재수출만 예외)", () => {
+    for (const name of coreFiles()) {
+      if (name === "index.ts") continue; // 배럴은 재수출이라 값을 쓰지 않는다
+      expect(read(name), `${name}`).not.toContain("adapters/");
+    }
+    // 예외인 index.ts 도 "재수출"이지 "사용"이 아니어야 한다.
+    const barrel = read("index.ts");
+    for (const line of barrel.split("\n")) {
+      if (line.includes("adapters/")) expect(line.startsWith("}") || line.includes("export")).toBe(true);
+    }
+  });
+
+  it("코어가 아는 것은 어댑터의 '이름'까지다(모양이 아니라)", () => {
+    // config.ts 는 adapter: "lasso" 같은 설정값을 다룬다 — 이건 알아도 된다.
+    // 알면 안 되는 건 그 대상이 payload 를 어떤 모양으로 받는지다.
+    expect(read("config.ts")).toContain("lasso");
+    expect(read("config.ts")).not.toContain("bodyMarkdown");
+  });
+});