@solhun/feedback-kit-core 0.1.0

package/src/queue.ts

@@ -0,0 +1,546 @@
+// 영속 제출 큐 — 저장소(FeedbackStorage)에 제보를 쌓고, 어댑터로 비운다.
+//
+// 이 모듈이 지키는 약속(DP-252 전송 보장):
+// 1. 제보는 **전송 전에** 큐에 들어간다. 큐에서 빠지는 유일한 조건은 어댑터가
+//    `ok=true`(= HTTP 2xx **그리고** 본문 ok)를 돌려준 것이다.
+// 2. 재시도는 항상 **같은 `clientSubmissionId`** 로 나간다. 서버가 이 값을 멱등 키로
+//    쓰므로 몇 번을 재시도해도 서버에 제보는 1건만 남는다.
+// 3. 보관 한도는 **최대 50건 / 최대 7일**. 넘치면 오래된 것부터 버리고 개발자 콘솔에
+//    경고한다(사용자에게는 노출하지 않는다).
+// 4. 저장소 한도에 걸리면 **스크린샷만 떼어내고 제보 본문은 보관**한다. 스크린샷은
+//    다시 만들 수 있지만 사용자가 쓴 글은 다시 만들 수 없다.
+// 5. 백오프는 5초에서 시작해 2배씩, **상한 5분**. 단 429(요청 한도 초과)는 이 상한의
+//    예외로 **최소 10분** 뒤에 다시 시도한다.
+// 6. 대기 중인 제보가 여러 건이면 **한 건씩 순서대로** 보낸다(서버 부하와 순서 보존).
+//
+// 재시도 트리거는 3가지다: 마운트(start) / 네트워크 복귀(`online` 이벤트 · 앱 포그라운드
+// 복귀 시 호스트가 `retryNow()` 호출) / 사용자의 [다시 보내기](`retryNow()`).
+//
+// 인스턴스 독립: 큐는 주입받은 storage 인스턴스에만 의존한다. 저장소 구현
+// (localStorage/AsyncStorage/메모리)이 바뀌어도 동작은 동일하다(인터페이스만 안다).
+//
+// 코어는 글로벌을 globalThis 로만 참조한다(document/window/RN 모듈 직접 접근 금지).
+
+import type {
+  FeedbackAdapter,
+  FeedbackReport,
+  FeedbackStorage,
+  SubmitResult,
+} from "./types.js";
+
+const QUEUE_KEY = "feedback-kit:queue";
+
+/** 대기 큐 최대 길이. 넘치면 오래된 것부터 버린다. */
+export const MAX_QUEUE_ITEMS = 50;
+
+/** 대기 큐 최대 보관 기간(ms). 7일. */
+export const MAX_QUEUE_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** 백오프 시작 간격(ms). */
+export const BACKOFF_BASE_MS = 5 * 1000;
+
+/** 백오프 상한(ms). 429 는 이 상한의 예외다. */
+export const BACKOFF_MAX_MS = 5 * 60 * 1000;
+
+/** 429 를 받았을 때의 최소 대기(ms). 상한 5분을 넘겨 잡는다. */
+export const RATE_LIMIT_MIN_DELAY_MS = 10 * 60 * 1000;
+
+/** 저장된 큐 항목. JSON 직렬화 가능한 값으로만 구성한다. */
+interface QueuedReport {
+  /** 조립된 전체 제보. */
+  report: FeedbackReport;
+  /** 지금까지 시도한 횟수. */
+  attempts: number;
+  /** 다음 전송 시도 에포크(ms). null = 즉시. */
+  nextAttemptAt: number | null;
+  /** 큐에 들어온 시각(에포크 ms). 7일 보관 한도의 기준. */
+  enqueuedAt: number;
+  /** 마지막 실패가 429 였는지. true 면 수동 재시도로도 대기를 앞당기지 않는다. */
+  rateLimited?: boolean;
+  /** 저장소 한도 때문에 스크린샷을 떼어냈는지(진단용). */
+  screenshotDropped?: boolean;
+}
+
+/** UI 가 구독하는 전송 상태. */
+export interface QueueStatus {
+  /** idle=대기 중 제보 없음, sending=전송 중, pending=대기 중(연결되면 자동 전송). */
+  state: "idle" | "sending" | "pending";
+  /** 대기 중인 제보 수. */
+  pending: number;
+  /** 마지막 실패 요약(사용자 노출용 아님, 개발자 진단용). 성공/초기엔 null. */
+  lastError: string | null;
+}
+
+/** `submit()` 한 건의 결과. */
+export interface SubmitOutcome {
+  /** 서버가 수락(2xx + ok=true)했는가. */
+  delivered: boolean;
+  /** 서버가 부여한 id(표시용). 수락 전이면 null. */
+  id: string | null;
+  /** 아직 큐에 남아 있는가(=나중에 자동 재전송). */
+  queued: boolean;
+}
+
+export type QueueStatusListener = (status: QueueStatus) => void;
+
+export interface FeedbackQueueOpts {
+  storage: FeedbackStorage;
+  adapter: FeedbackAdapter;
+  /** 주기적 flush 간격(ms). 기본 30000. 0/음수면 주기 flush 를 끈다. */
+  flushIntervalMs?: number;
+  /** 시각 주입(테스트용). */
+  now?: () => number;
+  /** 백오프 계산 주입(테스트용). */
+  backoff?: (
+    attempts: number,
+    retryAfterMs: number | null,
+    rateLimited: boolean
+  ) => number;
+  /**
+   * 개발자 콘솔 경고 싱크. 기본은 `console.warn`.
+   * 진단 버퍼가 콘솔을 패치한 환경에서는 원본 콘솔(`DiagnosticsCollector.originalConsole.warn`)을
+   * 넘겨 위젯 자신의 경고가 다시 수집되는 되먹임을 막는다.
+   */
+  warn?: (...a: unknown[]) => void;
+}
+
+/**
+ * 지수 백오프 계산.
+ * - 429(rateLimited)면 상한 예외: `max(10분, 서버 권장)`.
+ * - 서버가 `retryAfterMs` 를 줬으면 그것을 쓰되 5분으로 자른다.
+ * - 아니면 5초 * 2^(attempts-1), 상한 5분.
+ *
+ * attempts=10 이면 5s*2^9 = 2560s 지만 상한에 걸려 정확히 5분이다(연속 실패해도 간격이
+ * 5분을 넘지 않는다).
+ */
+export function defaultBackoff(
+  attempts: number,
+  retryAfterMs: number | null,
+  rateLimited = false
+): number {
+  const serverHint =
+    typeof retryAfterMs === "number" && retryAfterMs >= 0 ? retryAfterMs : null;
+
+  if (rateLimited) {
+    return Math.max(RATE_LIMIT_MIN_DELAY_MS, serverHint ?? 0);
+  }
+  if (serverHint !== null) {
+    return Math.min(serverHint, BACKOFF_MAX_MS);
+  }
+  const v = BACKOFF_BASE_MS * Math.pow(2, Math.max(0, attempts - 1));
+  return Math.min(v, BACKOFF_MAX_MS);
+}
+
+export class FeedbackQueue {
+  private storage: FeedbackStorage;
+  private adapter: FeedbackAdapter;
+  private flushIntervalMs: number;
+  private now: () => number;
+  private backoff: (a: number, r: number | null, rl: boolean) => number;
+  private warn: (...a: unknown[]) => void;
+
+  /**
+   * 저장소 접근 직렬화 체인.
+   *
+   * 왜 필요한가: `load → 수정 → save` 사이에 다른 경로가 끼어들면 그 사이 쓰기가 통째로
+   * 사라진다(flush 가 [A]를 읽는 동안 enqueue 가 [A,B]를 저장 → flush 가 []를 저장 →
+   * B 유실). 단순한 `flushing` 불리언은 재진입을 "무시"할 뿐이라 이 경합을 못 막고,
+   * 무시된 flush 를 기다리던 `submit()` 이 자기 전송을 await 할 수도 없다.
+   */
+  private chain: Promise<unknown> = Promise.resolve();
+  /** 아직 시작하지 않은 flush 요청(있으면 재사용해서 타이머 연타를 합친다). */
+  private queuedFlush: Promise<void> | null = null;
+
+  private timer: unknown | null = null;
+  private onlineHandler: (() => void) | null = null;
+
+  private pending = 0;
+  private sending = false;
+  private lastError: string | null = null;
+  private listeners = new Set<QueueStatusListener>();
+
+  /** 제출 단위 결과 캐시. `submit()` 이 자기 건의 결말을 알아내는 데 쓴다. */
+  private outcomes = new Map<string, { delivered: boolean; id: string | null }>();
+
+  constructor(opts: FeedbackQueueOpts) {
+    this.storage = opts.storage;
+    this.adapter = opts.adapter;
+    this.flushIntervalMs = opts.flushIntervalMs ?? 30000;
+    this.now = opts.now ?? (() => Date.now());
+    this.backoff = opts.backoff ?? defaultBackoff;
+    this.warn = opts.warn ?? defaultWarn;
+  }
+
+  // ── 공개 API ──────────────────────────────────────────────
+
+  /**
+   * 제보를 큐에 넣고 전송을 시도한 뒤, 그 한 건의 결말을 돌려준다.
+   * 실패해도 예외를 던지지 않는다 — 제보는 큐에 남고 `queued: true` 로 알린다.
+   */
+  async submit(report: FeedbackReport): Promise<SubmitOutcome> {
+    this.outcomes.delete(report.clientSubmissionId);
+    await this.serialize(() => this.enqueueInner(report));
+    await this.flush();
+    const outcome = this.outcomes.get(report.clientSubmissionId);
+    if (outcome) {
+      return { delivered: outcome.delivered, id: outcome.id, queued: false };
+    }
+    return { delivered: false, id: null, queued: true };
+  }
+
+  /** 큐에 제보를 추가하고, 전송을 백그라운드로 시도한다. */
+  async enqueue(report: FeedbackReport): Promise<void> {
+    await this.serialize(() => this.enqueueInner(report));
+    void this.flush();
+  }
+
+  /**
+   * 만기된 큐 항목들을 한 건씩 순서대로 전송한다.
+   * 이미 진행 중이면 그 뒤에 한 번만 예약해 붙는다(타이머 연타로 flush 가 쌓이지 않는다).
+   */
+  flush(): Promise<void> {
+    if (this.queuedFlush) return this.queuedFlush;
+    const p = this.serialize(async () => {
+      this.queuedFlush = null;
+      await this.doFlush();
+    });
+    this.queuedFlush = p;
+    return p;
+  }
+
+  /**
+   * 지금 즉시 재시도한다. 네트워크 복귀·앱 포그라운드 복귀·[다시 보내기] 용.
+   * 백오프 대기를 앞당기되, **429 로 묶인 항목은 앞당기지 않는다**(서버가 명시한 한도라
+   * 무시하면 다시 429 만 받는다).
+   */
+  async retryNow(): Promise<void> {
+    await this.serialize(async () => {
+      const queue = await this.load();
+      let changed = false;
+      for (const item of queue) {
+        if (item.rateLimited === true) continue;
+        if (item.nextAttemptAt !== null) {
+          item.nextAttemptAt = null;
+          changed = true;
+        }
+      }
+      if (changed) await this.persist(queue);
+    });
+    await this.flush();
+  }
+
+  /** 현재 큐 길이(대기 중 제보 수). 검증/진단용. */
+  async size(): Promise<number> {
+    const queue = await this.serialize(() => this.load());
+    this.setPending(queue.length);
+    return queue.length;
+  }
+
+  /** 현재 전송 상태 스냅샷. */
+  getStatus(): QueueStatus {
+    return {
+      state: this.sending ? "sending" : this.pending > 0 ? "pending" : "idle",
+      pending: this.pending,
+      lastError: this.lastError,
+    };
+  }
+
+  /** 특정 clientSubmissionId의 마지막 확정 결말. 큐에 있거나 아직 시도 전이면 null이다. */
+  getOutcome(
+    clientSubmissionId: string
+  ): Pick<SubmitOutcome, "delivered" | "id"> | null {
+    return this.outcomes.get(clientSubmissionId) ?? null;
+  }
+
+  /** 전송 상태 구독. 반환값을 호출하면 해지된다. 구독 즉시 현재 상태를 1회 통지한다. */
+  subscribe(listener: QueueStatusListener): () => void {
+    this.listeners.add(listener);
+    try {
+      listener(this.getStatus());
+    } catch {
+      /* 구독자 예외가 큐를 멈추게 하지 않는다. */
+    }
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /**
+   * 마운트 시 호출. 만기 항목 정리 + 즉시 재시도 + 주기 flush + `online` 재시도를 건다.
+   * 앱(RN)에는 `online` 이벤트가 없으므로, 호스트가 포그라운드 복귀 시 `retryNow()` 를
+   * 직접 부른다(코어는 플랫폼 API 를 모른다).
+   */
+  start(): void {
+    this.stop();
+
+    const g = globalThis as {
+      addEventListener?: (t: string, h: () => void) => void;
+      setInterval?: (h: () => void, ms: number) => unknown;
+    };
+
+    if (typeof g.addEventListener === "function") {
+      const handler = (): void => {
+        void this.retryNow();
+      };
+      g.addEventListener("online", handler);
+      this.onlineHandler = handler;
+    }
+
+    if (this.flushIntervalMs > 0 && typeof g.setInterval === "function") {
+      this.timer = g.setInterval(() => {
+        void this.flush();
+      }, this.flushIntervalMs);
+    }
+
+    void this.retryNow();
+  }
+
+  /** 타이머와 이벤트 구독을 해제한다. 큐 내용은 그대로 남는다. */
+  stop(): void {
+    const g = globalThis as {
+      removeEventListener?: (t: string, h: () => void) => void;
+      clearInterval?: (t: unknown) => void;
+    };
+    if (this.timer !== null) {
+      if (typeof g.clearInterval === "function") g.clearInterval(this.timer);
+      this.timer = null;
+    }
+    if (this.onlineHandler !== null) {
+      if (typeof g.removeEventListener === "function") {
+        g.removeEventListener("online", this.onlineHandler);
+      }
+      this.onlineHandler = null;
+    }
+  }
+
+  // ── 내부: 적재 / 전송 ─────────────────────────────────────
+
+  private async enqueueInner(report: FeedbackReport): Promise<void> {
+    const queue = this.purgeExpired(await this.load());
+    queue.push({
+      report,
+      attempts: 0,
+      nextAttemptAt: null,
+      enqueuedAt: this.now(),
+    });
+
+    // 보관 한도(50건) — 오래된 것부터 버리고 개발자 콘솔에 경고한다.
+    while (queue.length > MAX_QUEUE_ITEMS) {
+      const dropped = queue.shift();
+      this.warn(
+        `feedback-kit: 대기 큐가 ${MAX_QUEUE_ITEMS}건을 넘어 가장 오래된 제보를 버렸다`,
+        dropped?.report.clientSubmissionId
+      );
+    }
+
+    await this.persist(queue);
+  }
+
+  private async doFlush(): Promise<void> {
+    let queue = await this.load();
+
+    const kept = this.purgeExpired(queue);
+    if (kept.length !== queue.length) {
+      queue = kept;
+      await this.persist(queue);
+    }
+    this.setPending(queue.length);
+    if (queue.length === 0) {
+      this.emit();
+      return;
+    }
+
+    const now = this.now();
+    const due = queue.filter(
+      (item) => item.nextAttemptAt === null || now >= item.nextAttemptAt
+    );
+    if (due.length === 0) {
+      this.emit();
+      return;
+    }
+
+    this.sending = true;
+    this.emit();
+    try {
+      // 한 건씩 순서대로. 앞 건이 끝나야 다음 건을 보낸다.
+      for (const item of due) {
+        if (queue.indexOf(item) === -1) continue; // 저장 한도로 밀려나 사라진 항목.
+
+        const result = await this.submitOne(item.report);
+        const at = this.now();
+        const index = queue.indexOf(item);
+
+        if (result.ok) {
+          if (index !== -1) queue.splice(index, 1);
+          this.recordOutcome(item.report.clientSubmissionId, true, result.id);
+          this.lastError = null;
+        } else if (!result.retryable) {
+          // 영구 실패(예: 스키마 거부) — 재시도해도 결과가 같으므로 데드레터.
+          if (index !== -1) queue.splice(index, 1);
+          this.recordOutcome(item.report.clientSubmissionId, false, null);
+          this.lastError = "non-retryable";
+          this.warn(
+            "feedback-kit: 재시도 불가 실패로 제보를 버렸다",
+            item.report.clientSubmissionId
+          );
+        } else {
+          // 일시적 실패 — 같은 clientSubmissionId 로 나중에 다시 보낸다.
+          item.attempts += 1;
+          item.rateLimited = result.rateLimited === true;
+          item.nextAttemptAt =
+            at + this.backoff(item.attempts, result.retryAfterMs, item.rateLimited);
+          this.lastError = item.rateLimited ? "rate-limited" : "retryable";
+        }
+
+        await this.persist(queue);
+        this.setPending(queue.length);
+        this.emit();
+      }
+    } finally {
+      this.sending = false;
+      this.emit();
+    }
+  }
+
+  /** 어댑터 호출. 어댑터가 예외를 던져도 결과값으로 흡수한다(전송 보장 우선). */
+  private async submitOne(report: FeedbackReport): Promise<SubmitResult> {
+    try {
+      return await this.adapter.submit(report);
+    } catch (err) {
+      this.warn("feedback-kit: 어댑터가 예외를 던졌다(일시 실패로 처리)", err);
+      return { ok: false, id: null, retryable: true, retryAfterMs: null };
+    }
+  }
+
+  // ── 내부: 저장소 ──────────────────────────────────────────
+
+  private async load(): Promise<QueuedReport[]> {
+    let raw: string | null = null;
+    try {
+      raw = await this.storage.get(QUEUE_KEY);
+    } catch (err) {
+      this.warn("feedback-kit: 큐를 읽지 못했다", err);
+      return [];
+    }
+    if (!raw) return [];
+    try {
+      const parsed: unknown = JSON.parse(raw);
+      if (!Array.isArray(parsed)) return [];
+      return parsed.filter(isQueuedReport).map(normalizeEntry(this.now()));
+    } catch {
+      // 손상된 큐는 빈 것으로 취급(복구 불가).
+      this.warn("feedback-kit: 큐가 손상돼 초기화했다");
+      return [];
+    }
+  }
+
+  /**
+   * 큐를 저장한다. 저장소 한도(쿼터)에 걸리면 **스크린샷부터** 떼어내고, 그래도 안 되면
+   * 가장 오래된 제보를 버린다. 사용자가 쓴 글이 스크린샷보다 우선이다.
+   * 인자로 받은 배열을 제자리에서 수정한다(호출부가 들고 있는 항목 참조는 유지된다).
+   */
+  private async persist(queue: QueuedReport[]): Promise<void> {
+    for (;;) {
+      try {
+        await this.storage.set(QUEUE_KEY, JSON.stringify(queue));
+        this.setPending(queue.length);
+        return;
+      } catch (err) {
+        if (queue.length === 0) {
+          this.warn("feedback-kit: 큐를 저장하지 못했다", err);
+          return;
+        }
+        const shotIndex = queue.findIndex(
+          (item) => item.report.screenshot !== null
+        );
+        if (shotIndex !== -1) {
+          const entry = queue[shotIndex] as QueuedReport;
+          // 원본 report 객체를 건드리지 않고 새 객체로 교체한다(호출자 소유물 보호).
+          entry.report = { ...entry.report, screenshot: null };
+          entry.screenshotDropped = true;
+          this.warn(
+            "feedback-kit: 저장 한도를 넘어 스크린샷을 떼어내고 제보만 보관한다",
+            entry.report.clientSubmissionId
+          );
+          continue;
+        }
+        const evicted = queue.shift();
+        this.warn(
+          "feedback-kit: 저장 한도를 넘어 가장 오래된 제보를 버렸다",
+          evicted?.report.clientSubmissionId
+        );
+      }
+    }
+  }
+
+  /** 7일이 지난 항목을 걸러낸다. 만기 항목은 전송을 시도하지 않는다. */
+  private purgeExpired(queue: QueuedReport[]): QueuedReport[] {
+    const now = this.now();
+    const kept = queue.filter((item) => now - item.enqueuedAt <= MAX_QUEUE_AGE_MS);
+    if (kept.length !== queue.length) {
+      this.warn(
+        `feedback-kit: 보관 기간(7일)이 지난 제보 ${queue.length - kept.length}건을 정리했다`
+      );
+    }
+    return kept;
+  }
+
+  // ── 내부: 상태 통지 ───────────────────────────────────────
+
+  private recordOutcome(id: string, delivered: boolean, serverId: string | null): void {
+    // 무한 증가를 막는다. 오래된 것부터 버린다(결말은 UI 가 즉시 읽고 버리는 값).
+    if (this.outcomes.size >= 100) {
+      const oldest = this.outcomes.keys().next();
+      if (!oldest.done) this.outcomes.delete(oldest.value);
+    }
+    this.outcomes.set(id, { delivered, id: serverId });
+  }
+
+  private setPending(n: number): void {
+    if (this.pending === n) return;
+    this.pending = n;
+  }
+
+  private emit(): void {
+    if (this.listeners.size === 0) return;
+    const status = this.getStatus();
+    for (const listener of this.listeners) {
+      try {
+        listener(status);
+      } catch {
+        /* 구독자 예외가 큐를 멈추게 하지 않는다. */
+      }
+    }
+  }
+
+  private serialize<T>(fn: () => Promise<T>): Promise<T> {
+    const next = this.chain.then(fn, fn);
+    this.chain = next.catch(() => undefined);
+    return next;
+  }
+}
+
+// ── 모듈 내부 헬퍼 ──────────────────────────────────────────
+
+function defaultWarn(...a: unknown[]): void {
+  const g = globalThis as { console?: { warn?: (...a: unknown[]) => void } };
+  g.console?.warn?.(...a);
+}
+
+function isQueuedReport(v: unknown): v is QueuedReport {
+  if (typeof v !== "object" || v === null) return false;
+  const report = (v as { report?: unknown }).report;
+  if (typeof report !== "object" || report === null) return false;
+  return typeof (report as { clientSubmissionId?: unknown }).clientSubmissionId === "string";
+}
+
+/** 이전 버전이 저장한 항목에도 견디도록 필드를 보정한다. */
+function normalizeEntry(now: number): (v: QueuedReport) => QueuedReport {
+  return (v) => ({
+    ...v,
+    attempts: typeof v.attempts === "number" && v.attempts >= 0 ? v.attempts : 0,
+    nextAttemptAt: typeof v.nextAttemptAt === "number" ? v.nextAttemptAt : null,
+    // enqueuedAt 이 없던 시절의 항목은 "방금 들어온 것"으로 봐서 즉시 버리지 않는다.
+    enqueuedAt: typeof v.enqueuedAt === "number" ? v.enqueuedAt : now,
+  });
+}

package/src/report.ts

@@ -0,0 +1,58 @@
+// 제보 조립 — 호스트가 준 부분 데이터로 FeedbackReport(전체 계약)를 만든다.
+//
+// 핵심 규칙:
+// - 호스트는 kind/comment/priority/screenshot/pin/element 만 넘긴다.
+//   clientSubmissionId / createdAt / context 는 코어가 여기서 채운다.
+// - context(사용자·화면·기기·진단) 조립은 context.ts 가 담당한다. 여기서는 쓰기만 한다.
+// - getUser는 prop(함수). 제출 시점에 호출한다. 캐싱하지 않는다 → 로그인/로그아웃으로
+//   반환값이 바뀌어도 제출 순간의 최신 신원이 들어간다.
+
+import type { BuildContextOpts } from "./context.js";
+import { buildContext } from "./context.js";
+import type {
+  ElementInfo,
+  FeedbackKind,
+  FeedbackPin,
+  FeedbackPriority,
+  FeedbackReport,
+  FeedbackScreenshot,
+} from "./types.js";
+import { uuidv4 } from "./uuid.js";
+
+/** 호스트가 submit() 호출 시 넘기는 부분 데이터. 계약의 나머지는 코어가 채운다. */
+export interface ReportParts {
+  kind: FeedbackKind;
+  comment: string;
+  priority: FeedbackPriority;
+  screenshot: FeedbackScreenshot | null;
+  pin: FeedbackPin | null;
+  element: ElementInfo | null;
+}
+
+/** 제보 조립 옵션. 컨텍스트 조립 옵션과 동일하다(제보 쪽에 추가 입력이 없다). */
+export type BuildReportOpts = BuildContextOpts;
+
+/**
+ * 부분 데이터 + 옵션으로 FeedbackReport 하나를 만든다.
+ * clientSubmissionId(UUID)와 createdAt(ISO)은 매 호출마다 새로 생성.
+ */
+export async function buildReport(
+  parts: ReportParts,
+  opts: BuildReportOpts
+): Promise<FeedbackReport> {
+  const now = opts.now ?? ((): number => Date.now());
+  const iso = opts.iso ?? ((n: number): string => new Date(n).toISOString());
+  const context = await buildContext(opts);
+
+  return {
+    clientSubmissionId: uuidv4(),
+    kind: parts.kind,
+    comment: parts.comment,
+    priority: parts.priority,
+    screenshot: parts.screenshot,
+    pin: parts.pin,
+    element: parts.element,
+    context,
+    createdAt: iso(now()),
+  };
+}

package/src/ring-buffer.test.ts

@@ -0,0 +1,62 @@
+// 링버퍼 자체의 밀어내기 규칙(DP-253 TC4 의 단위 근거).
+//
+// 여기서는 "상한을 넘으면 오래된 것부터 밀려나고, 남는 건 최근 것"만 본다.
+// 실제 수집기(네트워크 30 / 로그 50)에 대한 검증은 diagnostics.test.ts 에 있다.
+
+import { describe, expect, it } from "vitest";
+
+import { RingBuffer } from "./ring-buffer.js";
+
+describe("RingBuffer", () => {
+  it("상한 이하에서는 넣은 순서 그대로 보관한다", () => {
+    const buf = new RingBuffer<number>(3);
+    buf.push(1);
+    buf.push(2);
+
+    expect(buf.size).toBe(2);
+    expect(buf.toArray()).toEqual([1, 2]);
+  });
+
+  it("상한을 넘으면 오래된 것부터 밀려나고 최근 것만 남는다", () => {
+    const buf = new RingBuffer<number>(3);
+    for (let i = 1; i <= 10; i += 1) buf.push(i);
+
+    expect(buf.size).toBe(3);
+    // 1~7 은 밀려나고 마지막 3건만 남는다.
+    expect(buf.toArray()).toEqual([8, 9, 10]);
+  });
+
+  it("toArray 는 사본이라 이후 push 가 이미 낸 스냅샷을 바꾸지 않는다", () => {
+    const buf = new RingBuffer<string>(2);
+    buf.push("a");
+    const snapshot = buf.toArray();
+
+    buf.push("b");
+    buf.push("c");
+
+    expect(snapshot).toEqual(["a"]);
+    expect(buf.toArray()).toEqual(["b", "c"]);
+  });
+
+  it("clear 는 내용을 비우되 용량은 유지한다", () => {
+    const buf = new RingBuffer<number>(2);
+    buf.push(1);
+    buf.clear();
+
+    expect(buf.size).toBe(0);
+    expect(buf.toArray()).toEqual([]);
+
+    buf.push(9);
+    expect(buf.toArray()).toEqual([9]);
+    expect(buf.capacity).toBe(2);
+  });
+
+  it("용량이 0 이하/비정상이면 아무것도 담지 않는다(메모리 사고 방지)", () => {
+    for (const bad of [0, -5, Number.NaN]) {
+      const buf = new RingBuffer<number>(bad);
+      buf.push(1);
+      expect(buf.capacity).toBe(0);
+      expect(buf.toArray()).toEqual([]);
+    }
+  });
+});