Files
clean-architecture-frontend…/tests/recipes/optional-capability-contracts.test.ts
T
DongHyeonka e1a458081d refactor(recipes)!: runtime이 있는 port는 src port를 다시 내보낸다 (0929/05-03)
문제: `recipes/frontend-capabilities/`가 `src/application/ports/`와
같은 이름의 타입 34개를 따로 정의한다(`DurableObjectStorePort`,
`FilePickerPort`, `StorageDurabilityPort`, `TransferProgress`,
`PublicCacheInspection` 등). 7월 이후 runtime port가 바뀌어도(0929
05-01~05-14) recipe 복사본은 한 번도 따라오지 않았다. catalog는 이
복사본을 구현한 fake를 runtime의 fake로 안내해서, 그 fake로 쓴 테스트는
runtime에 없는 resume·quarantine을 전제했다.

고른 방법 (리뷰의 (c)):
- runtime이 있는 port와 그 표면의 타입은 recipe 정의를 지우고
  `src/application/ports`의 것을 같은 이름으로 다시 내보낸다. 옛 recipe
  port에만 쓰이던 `DurableObjectDataClass`, `DurableObjectIntegrity`,
  `DurableObjectRead`, `ObjectStoreRecoverySummary`도 지운다. src에 없는
  `DurableObjectId`·`ObjectGeneration` 브랜드와 `as*` 헬퍼는 남긴다(src
  port가 그대로 받는다).
- fake는 src port를 `implements`한다.
  - 파일 picker·content·preview·download fake와 storage durability fake:
    결과를 `BrowserDataResult`(`error`, 닫힌 코드, operation)로 바꿨다.
    `PROVIDER_UNAVAILABLE`은 src 코드 `UNAVAILABLE`이 된다.
  - `MemoryDurableObjectStore`: src OPFS port에 맞춰 다시 썼다. 생성자는
    scope·storagePolicy·maxObjectBytes를 받는다. 멈춘 put의 행은
    reconcile이 rollback만 한다(resume·quarantine 없음, runtime과 같다).
    LOGOUT·ACCOUNT_DELETION만 지원하고 나머지 reason은 `UNSUPPORTED`다.
  - 고칠 수 없는 fake: `MemoryStructuredOfflineStore`는
    `IndexedDbRepositoryPort`와 설계가 달라(배치 commit·idempotency 대
    CAS·lifecycle batch) catalog offline-indexeddb 행의 fake 칸에서 뺐다.
    recipe 전용 `StructuredOfflineStore`의 fake로는 남는다.
- recipe 전용 port 두 곳:
  - `PublicResponseCacheAdmin.inspect`는 runtime의 `PublicCacheInspection`
    모양으로 보고한다. `MemoryPublicResponseCache`가 그 모양을 만든다.
  - `FileTransferPort`(runtime 없음)의 progress는 `FileTransferProgress`로
    나눴다. `TransferProgress`라는 이름은 recipe barrel에서 src 타입으로
    계속 나간다. 일반 recipe인 `contracts.ts`가 선택형 runtime port를
    import하지 않게 하려는 것이다.
- 다시 갈라지지 않게 `optional-capability-contracts.test.ts`에 검사를
  더했다. recipes/가 src/application/ports/에 있는 이름으로 타입을
  정의하면 실패한다(다시 내보내기는 허용).
- runtime 제거 fixture(`test-browser-file-storage-runtime-removal.ts`)는
  이 runtime의 port를 다시 내보내는 recipe 두 파일과 그 테스트를 함께
  지우고, recipe barrel에서 두 export 줄을 먼저 뺀다.
버린 대안: 현상 유지(변경 누락 계속), 이름만 바꿔 `*Sketch`로 표시(중복
유지비가 남음), 두 벌을 비교하는 타입 테스트(두 벌을 계속 유지).

위험·한계:
- recipe에서 위 타입·fake를 쓰던 다운스트림은 컴파일 오류로 드러난다
  (조용히 깨지지 않는다). 같은 이름 타입의 모양, `MemoryDurableObjectStore`
  생성자·메서드, 파일 fake의 실패 결과(`failure` → `error`), 지운 타입
  4개가 바뀌었다. 두 제품 repo의 사용 여부는 확인하지 않았다.
- `MemoryDurableObjectStore`의 integrity digest는 runtime의 tree digest가
  아니다(주석에 적음). worker·Web Lock·authority·GC는 흉내내지 않는다.
- `test:browser-file-storage-removal`은 pnpm이 필요해 돌리지 못했다.
  barrel 줄 제거와 경로 추가는 코드로만 확인했다.

검증:
- RED: 새 검사를 수정 전 recipe 소스로 돌리면 실패한다.
  `expected [ 'LocalFileRef', …(33) ] to deeply equal []` (34개).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes
  tests/contract` 180 files 2,548건 통과. `tsc` app·recipes·test·node
  통과, 바꾼 파일 eslint 통과, `check-registries` PASS(재승인 불필요),
  `verify-documentation-readiness` PASS_SCOPED.
  `check-optional-recipes`(source)는 0929/05-01의 offline-indexeddb 예산
  초과(37,327 > 36,900)만 실패하고 catalog·source 검사는 통과했다.
  이 커밋은 그 번들 크기를 바꾸지 않는다(recipes/는 sourceRoots 밖).

BREAKING CHANGE: recipes/frontend-capabilities의 browser-file·OPFS·
storage durability·public cache 타입 중 src/application/ports와 이름이
같은 것은 이제 그 src 타입이다. file·durability·OPFS fake는 src port를
구현하고 BrowserDataResult를 돌려준다(`result.failure.code` →
`result.error.code`). `MemoryDurableObjectStore`는 `{ scope, storagePolicy,
maxObjectBytes }`로 만든다. `FileTransferPort`의 progress 타입은
`FileTransferProgress`다. `DurableObjectDataClass`·`DurableObjectIntegrity`
·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 없어졌다.
Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-03
2026-11-03 01:23:05 +09:00

325 lines
9.9 KiB
TypeScript

import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import { describe, expect, it } from "vitest";
import {
FakeBrowserPermissionAdapter,
FakeClientWorkflowAdapter,
FakeFeatureFlagAdapter,
FakeFileTransferAdapter,
FakeGeneratedApiAdapter,
FakeLargeDataUiAdapter,
FakeMultiTabAdapter,
FakeRealtimeAdapter,
FakeServiceWorkerUpdateAdapter,
FakeWorkerTaskAdapter,
MemoryOfflineRepository,
RecordingAnalyticsAdapter,
createUnavailableAdapters,
} from "../../recipes/frontend-capabilities/index.ts";
describe("optional capability recipes", () => {
it("requires realtime cleanup and rejects duplicate or out-of-order events", async () => {
const adapter = new FakeRealtimeAdapter<{ value: string }>();
const received: string[] = [];
const subscription = await adapter.subscribe({
channel: "orders",
onEvent(result) {
received.push(result.ok ? result.value.payload.value : result.failure.code);
},
});
expect(subscription.ok).toBe(true);
adapter.emit("orders", {
id: "event-2",
sequence: 2,
occurredAt: "2026-07-26T00:00:00.000Z",
payload: { value: "new" },
});
adapter.emit("orders", {
id: "event-1",
sequence: 1,
occurredAt: "2026-07-26T00:00:00.000Z",
payload: { value: "old" },
});
expect(received).toEqual(["new", "STALE_RESULT"]);
if (subscription.ok) subscription.value.unsubscribe();
expect(adapter.activeSubscriptionCount).toBe(0);
});
it("models offline schema migration and closed-repository fallback", async () => {
const repository = new MemoryOfflineRepository<{ id: string; name: string }>();
expect(await repository.open({ schemaVersion: 1 })).toEqual({
ok: true,
value: undefined,
});
await repository.put({ id: "one", name: "offline" });
expect(await repository.migrate({ from: 1, to: 2 })).toEqual({
ok: true,
value: undefined,
});
expect(await repository.get("one")).toEqual({
ok: true,
value: { id: "one", name: "offline" },
});
repository.close();
expect((await repository.get("one")).ok).toBe(false);
});
it("covers service-worker stale update and explicit unregister", async () => {
const adapter = new FakeServiceWorkerUpdateAdapter("v1", "v2");
expect((await adapter.inspect()).ok).toBe(true);
expect((await adapter.activate("stale")).ok).toBe(false);
expect(await adapter.activate("v2")).toEqual({ ok: true, value: undefined });
expect(await adapter.unregister()).toEqual({ ok: true, value: undefined });
});
it("covers file validation, progress and AbortSignal cancellation", async () => {
const adapter = new FakeFileTransferAdapter(10, new Set(["text/plain"]));
const progress: number[] = [];
const controller = new AbortController();
const uploaded = await adapter.upload({
file: {
name: "safe.txt",
size: 4,
type: "text/plain",
content: {
byteLength: 4,
chunks: (async function* () {
yield new TextEncoder().encode("safe");
})(),
},
},
signal: controller.signal,
onProgress(value) {
progress.push(value.transferredBytes);
},
});
expect(uploaded.ok).toBe(true);
expect(progress).toEqual([4]);
controller.abort();
const cancelled = await adapter.download({
resourceId: "one",
signal: controller.signal,
onProgress() {},
});
expect(cancelled).toMatchObject({
ok: false,
failure: { code: "ABORTED" },
});
});
it("keeps generated API and feature flag vendors behind typed facades", async () => {
const api = new FakeGeneratedApiAdapter("2026-07", {
list: () => [{ id: "one" }],
});
expect(
await api.execute<Array<{ id: string }>>({
operationId: "list",
contractVersion: "2026-07",
}),
).toEqual({ ok: true, value: [{ id: "one" }] });
expect(
(
await api.execute({
operationId: "list",
contractVersion: "old",
})
).ok,
).toBe(false);
const flags = new FakeFeatureFlagAdapter<{ checkout: boolean }>({
checkout: true,
});
expect(
await flags.evaluate({
key: "checkout",
fallback: false,
maxAgeMs: 1_000,
}),
).toEqual({ ok: true, value: true });
});
it("discards cancelled worker results and de-duplicates multi-tab events", async () => {
const worker = new FakeWorkerTaskAdapter<number, number>((value) => value * 2);
const controller = new AbortController();
worker.cancel("cancelled");
expect(
(
await worker.run({
taskId: "cancelled",
generation: 1,
payload: 2,
signal: controller.signal,
})
).ok,
).toBe(false);
const tabs = new FakeMultiTabAdapter<{ refreshed: boolean }>();
const observed: string[] = [];
const cleanup = tabs.subscribe({
sourceId: "tab-b",
onEvent(result) {
if (result.ok) observed.push(result.value.eventId);
},
});
expect(
tabs.publish({
eventId: "one",
sourceId: "tab-a",
version: 1,
payload: { refreshed: true },
}).ok,
).toBe(true);
expect(
tabs.publish({
eventId: "one",
sourceId: "tab-a",
version: 1,
payload: { refreshed: true },
}).ok,
).toBe(false);
expect(observed).toEqual(["one"]);
cleanup();
tabs.close();
});
it("separates browser permission, local workflow and large-data behavior", async () => {
const permissions = new FakeBrowserPermissionAdapter({
notification: "denied",
});
expect(
await permissions.request({ capability: "notification" }),
).toEqual({ ok: true, value: "denied" });
expect(
(
await permissions.request({
capability: "clipboard-read",
})
).ok,
).toBe(false);
const workflow = new FakeClientWorkflowAdapter(
{ step: 0 },
(state, event: "next") => ({
step: event === "next" ? state.step + 1 : state.step,
}),
);
workflow.dispatch("next");
expect(workflow.snapshot()).toEqual({ step: 1 });
workflow.reset();
expect(workflow.snapshot()).toEqual({ step: 0 });
const data = new FakeLargeDataUiAdapter<{ id: string; name: string }>();
data.replace([{ id: "one", name: "row" }], 2);
expect(data.window({ offset: 0, limit: 1, generation: 1 }).ok).toBe(false);
expect(data.window({ offset: 0, limit: 1, generation: 2 })).toEqual({
ok: true,
value: [{ id: "one", name: "row" }],
});
});
it("enforces analytics consent, redaction and bounded queues", () => {
const adapter = new RecordingAnalyticsAdapter(1);
expect(
adapter.record({
kind: "analytics",
eventId: "page-viewed",
consent: "denied",
attributes: {},
}).ok,
).toBe(false);
expect(
adapter.record({
kind: "error",
eventId: "render-failed",
consent: "not-required",
attributes: { routeId: "HOME", authToken: "must-not-survive" },
}).ok,
).toBe(true);
expect(adapter.records[0]?.attributes).toEqual({ routeId: "HOME" });
expect(
adapter.record({
kind: "error",
eventId: "second",
consent: "not-required",
attributes: {},
}).ok,
).toBe(false);
});
it("provides fail-closed unavailable adapters for every capability", async () => {
const adapters = createUnavailableAdapters();
const controller = new AbortController();
const results = await Promise.all([
adapters.realtime.heartbeat(),
adapters.offline.open({ schemaVersion: 1 }),
adapters.serviceWorker.unregister(),
adapters.fileTransfer.download({
resourceId: "one",
signal: controller.signal,
onProgress() {},
}),
adapters.generatedApi.execute({
operationId: "one",
contractVersion: "one",
}),
adapters.featureFlag.evaluate({
key: "one",
fallback: false,
maxAgeMs: 0,
}),
adapters.worker.run({
taskId: "one",
generation: 1,
payload: null,
signal: controller.signal,
}),
adapters.browserPermission.request({ capability: "notification" }),
adapters.analytics.flush(),
]);
expect(results.every((result) => !result.ok)).toBe(true);
expect(adapters.multiTab.publish({
eventId: "one",
sourceId: "one",
version: 1,
payload: null,
}).ok).toBe(false);
expect(adapters.clientWorkflow.dispatch(null).ok).toBe(false);
expect(
adapters.largeDataUi.window({ offset: 0, limit: 1, generation: 1 }).ok,
).toBe(false);
});
// [0929] 05-03. A recipe that defines its own type under the name of an
// application port drifts from it: the recipe copies of the browser-file
// and OPFS ports missed every runtime change for months. A recipe may
// re-export a port, never define a second one with the same name.
it("defines no type under the name of an application port", async () => {
const definedNames = async (root: string): Promise<Set<string>> => {
const names = new Set<string>();
const entries = await readdir(root, {
recursive: true,
withFileTypes: true,
});
for (const entry of entries) {
if (!entry.isFile() || !entry.name.endsWith(".ts")) continue;
const source = await readFile(
path.join(entry.parentPath, entry.name),
"utf8",
);
for (const match of source.matchAll(
/^export (?:declare |async )?(?:interface|type|class|enum|function|const) ([A-Za-z0-9_]+)/gmu,
)) {
names.add(match[1]!);
}
}
return names;
};
const portNames = await definedNames("src/application/ports");
const recipeNames = await definedNames("recipes");
expect([...recipeNames].filter((name) => portNames.has(name))).toEqual([]);
});
});