refactor: v4 편집기가 걷어낸 화면의 잔해를 지운다

즉시 미리보기(`InstantPreview`)와 동작 원리 띠(`MechanismMap`)는 파일로만 남아 있었다.
아무 화면도 부르지 않는데 규칙과 검사는 그대로여서, 고칠 때마다 살아 있는 코드처럼 따라왔다.

함께 죽어 있던 것들:
- `createAssetCatalogResolver` — 즉시 미리보기만 쓰던 픽셀 해석기
- `mergeAssetCatalog` 와 편집기의 자료 목록 — 그 목록을 읽던 화면이 없어졌다
  (`DocumentEditor` 는 이미 `assets: _assets` 로 받아만 두고 있었다)
- 분할 편집기·미리보기 모드·예전 검증 패널의 CSS 규칙

검사는 지우지 않고 살아 있는 쪽으로 옮겼다. 자료 열쇠 합의 검사는 이제 목 어댑터의 투영과
공개 화면이 실제로 쓰는 해석기를 맞대고 본다 — READY 검사를 빼 보면 144개 조합 중 16개가
어긋난다.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-16 17:44:09 +09:00
co-authored by Claude Opus 5
parent d1c6ad5891
commit 7dda6c7923
17 changed files with 83 additions and 858 deletions
+3 -126
View File
@@ -10,14 +10,12 @@ import {
AssetPicker,
buildEvidenceDirective,
} from "../../../src/features/tech-log/presentation/studio/components/asset-picker.tsx";
import { mergeAssetCatalog } from "../../../src/features/tech-log/domain/content-format/asset-evidence-catalog.ts";
import {
AssetUploadDialog,
stateForError,
stateForUploaded,
} from "../../../src/features/tech-log/presentation/studio/components/asset-upload-dialog.tsx";
import { DocumentEditorScreen } from "../../../src/features/tech-log/presentation/studio/components/document-editor-screen.tsx";
import { InstantPreview } from "../../../src/features/tech-log/presentation/studio/components/instant-preview.tsx";
import { StudioProvider } from "../../../src/features/tech-log/presentation/studio/studio-provider.tsx";
import { createTechLogFeatureInstalledInput } from "../../../src/features/tech-log/adapters/create-tech-log-feature-input.ts";
import { createMockStudioGateway } from "../../../src/features/tech-log/adapters/mock/mock-studio-gateway.ts";
@@ -153,21 +151,6 @@ test("does not offer a QUARANTINED asset for insertion", async () => {
expect(screen.queryByRole("button", { name: /unsafe/ })).not.toBeInTheDocument();
});
test("reports the loaded Asset list once listAssets resolves", async () => {
const loaded: readonly Asset[][] = [];
render(
<AssetPicker
gateway={gatewayOf([READY, QUARANTINED])}
onInsert={() => {}}
onAssetsObserved={(assets) => (loaded as Asset[][]).push([...assets])}
/>,
);
await screen.findByRole("button", { name: /fetch-strategy-boundary/ });
assert.equal(loaded.length, 1);
assert.equal(loaded[0]!.length, 2);
});
// --- upload outcome/error classification: pure functions, tested apart from the dialog ---
test("stateForUploaded maps a READY asset to the READY outcome", () => {
@@ -463,7 +446,6 @@ test("inserts evidence after the active document block without leaving the writi
assert.ok(authored.indexOf("## 책임 경계") < authored.indexOf(expectedDirective), authored);
assert.ok(authored.indexOf(expectedDirective) < authored.indexOf("정책과 명령을 분리합니다."), authored);
expect(screen.getByLabelText("2번째 자료")).toHaveValue(expectedDirective);
expect(screen.queryByRole("region", { name: "즉시 미리보기" })).not.toBeInTheDocument();
});
// --- Fix round 1 ---
@@ -1077,7 +1059,7 @@ test("EVIDENCE_NOT_FOUND is reachable through validateWorkingCopy directly: the
// collapses "can this key be rendered" and "which Asset does it render" into
// one exported decision, `findResolvableAsset`, and puts every caller
// (validation's gate, validation's decorative lookup, the mock projection's
// gate and resolver, InstantPreview's gate, resolver, and pixel resolver) on
// gate and resolver) on
// it. The tests below are the shapes that broke the round-3 pair.
// `MockStudioDependencies.assets` is keyed by whatever the caller chooses --
@@ -1253,30 +1235,8 @@ function caseDraft(bodyMarkdown: string) {
} as never;
}
function renderInstantPreview(bodyMarkdown: string, assets: readonly Asset[]) {
render(
<MemoryRouter>
<StudioProvider
createManagementGateway={createManagementGatewayStub} createGateway={() => createMockStudioGateway()}>
<InstantPreview draft={caseDraft(bodyMarkdown)} catalog={PREVIEW_CATALOG} assets={assets} />
</StudioProvider>
</MemoryRouter>,
);
}
// Round 3 loosened InstantPreview's gate back to the merged catalog, arguing
// the un-loaded-asset case would otherwise blank the preview. It blanks
// either way -- an un-loaded Asset contributes no catalog row either. All the
// looseness bought was keys the fetched EVIDENCE catalog carries: those
// rendered a caption with an empty gap and no message while validation said
// EVIDENCE_UNSUPPORTED. Every caller is now on the same expression, so the
// preview refuses exactly what validation refuses -- and says so.
test("Instant Preview refuses a key only the document catalog carries, exactly as mock validation does", () => {
const body = ':::evidence key="resolution-evidence" alt="근거" caption="근거" zoom="false"\n:::';
renderInstantPreview(body, []);
const alert = screen.getByRole("alert");
assert.match(alert.textContent ?? "", /resolution-evidence/);
test("검증은 문서 목록에만 있는 자료 열쇠를 받지 않는다", () => {
const body = ':::evidence key="resolution-evidence" alt="근거" caption="근거" zoom="false"';
const report = validateWorkingCopy(
{ ...(caseDraft(body) as object), id: "88888888-8888-4888-8888-888888888882", version: 1, updatedAt: "2026-08-14T00:00:00.000Z" } as never,
@@ -1295,36 +1255,6 @@ test("Instant Preview refuses a key only the document catalog carries, exactly a
);
});
// The pixels come from `createAssetCatalogResolver` (a last-wins `Map`) while
// the block descriptor came from `resolveAssetDescriptor` (a first-wins
// `find`) -- a fourth expression in the same path, disagreeing with the third
// whenever two READY Assets share a key.
test("Instant Preview renders the same asset the gate and the descriptor picked when two assets share a key", () => {
const older = assetFixture({
id: "dddddddd-dddd-4ddd-8ddd-ddddddddddd1",
assetKey: "dup-pixels",
publicPath: "/media/dup-pixels-older.svg",
updatedAt: "2026-08-14T00:00:00.000Z",
});
const newer = assetFixture({
id: "dddddddd-dddd-4ddd-8ddd-ddddddddddd2",
assetKey: "dup-pixels",
publicPath: "/media/dup-pixels-newer.svg",
updatedAt: "2026-08-14T00:00:01.000Z",
});
renderInstantPreview(
':::evidence key="dup-pixels" alt="중복 키 그림" caption="근거" zoom="false"\n:::',
[newer, older],
);
expect(screen.queryByRole("alert")).not.toBeInTheDocument();
assert.equal(
screen.getByAltText("중복 키 그림").getAttribute("src"),
"/media/dup-pixels-newer.svg",
);
});
// The idempotency ledger must not freeze an *uncharacterized* internal
// failure: the port reports it as retryable, so a same-key retry has to
// actually re-run the work instead of replaying the cached 500.
@@ -1704,29 +1634,6 @@ test("a QUARANTINED asset the server wrongly returns for a query is still not of
expect(screen.queryByRole("button", { name: /unsafe-diagram/ })).not.toBeInTheDocument();
});
test("the Picker reports search results too, so the catalog grows with every query", async () => {
const user = userEvent.setup();
const observed: Asset[][] = [];
const { gateway } = searchableGateway([PICKER_A, PICKER_B]);
render(
<AssetPicker
gateway={gateway}
onInsert={() => {}}
onAssetsObserved={(assets) => observed.push([...assets])}
/>,
);
await screen.findByRole("button", { name: /inserted-diagram/ });
await user.type(screen.getByLabelText("Asset 검색"), "other");
await user.click(screen.getByRole("button", { name: "검색" }));
await waitFor(() => assert.equal(observed.length, 2));
assert.deepEqual(
observed[1]!.map((asset) => asset.assetKey),
["other-diagram"],
);
});
test("a slow earlier Picker search never overwrites the newer query's results", async () => {
const user = userEvent.setup();
const pending: Array<{ settle: (page: unknown) => void }> = [];
@@ -1822,36 +1729,6 @@ test("a Picker search never drops an already-inserted asset from the authored do
assert.ok(markdownSource().value.includes('key="inserted-diagram"'));
assert.ok((screen.getByLabelText(/번째 자료/) as HTMLTextAreaElement).value.includes('key="inserted-diagram"'));
expect(screen.queryByRole("region", { name: "즉시 미리보기" })).not.toBeInTheDocument();
});
test("mergeAssetCatalog keeps every previously known asset and lets a fresher copy win", () => {
const known = assetFixture({ id: "50505050-5050-4050-8050-505050505051", assetKey: "known" });
const staleCopy = assetFixture({
id: "50505050-5050-4050-8050-505050505052",
assetKey: "replaced",
publicPath: "/media/replaced-old.svg",
updatedAt: "2026-08-14T00:00:00.000Z",
});
const freshCopy = { ...staleCopy, publicPath: "/media/replaced-new.svg", version: 2 };
const arrival = assetFixture({ id: "50505050-5050-4050-8050-505050505053", assetKey: "arrival" });
const merged = mergeAssetCatalog([known, staleCopy], [freshCopy, arrival]);
assert.deepEqual(
[...merged].map((asset) => asset.assetKey).sort(),
["arrival", "known", "replaced"],
);
assert.equal(
merged.find((asset) => asset.id === staleCopy.id)?.publicPath,
"/media/replaced-new.svg",
);
});
test("mergeAssetCatalog can only grow: an empty arrival keeps everything", () => {
const known = assetFixture({ id: "60606060-6060-4060-8060-606060606061", assetKey: "kept" });
assert.deepEqual(mergeAssetCatalog([known], []).map((asset) => asset.id), [known.id]);
});
// --- Alignment follow-up, item 3: alt text must not outlive its file ---
@@ -1,12 +1,17 @@
import assert from "node:assert/strict";
import { test } from "vitest";
import { findResolvableAsset } from "../../../src/features/tech-log/domain/content-format/asset-evidence-catalog.ts";
import {
createAssetCatalogResolver,
createResolvedAssetResolver,
MISSING_EVIDENCE_ASSET,
} from "../../../src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts";
/** 서버가 블록에 붙여 보내는 서술자. 화면이 그림을 그릴 때 읽는 것은 이것뿐이다. */
function figure(asset: Record<string, unknown>) {
return [{ type: "EVIDENCE_FIGURE", key: String(asset["assetKey"]), asset }] as never;
}
const READY = {
id: "11111111-1111-4111-8111-111111111111",
assetKey: "boundary",
@@ -26,32 +31,31 @@ const READY = {
updatedAt: "2026-08-14T01:00:00.000Z",
} as never;
test("resolves a backend asset key to its public path", () => {
const resolve = createAssetCatalogResolver([READY]);
const asset = resolve("boundary");
test("고를 수 있는 자료를 열쇠로 찾는다", () => {
const found = findResolvableAsset([READY], "boundary");
assert.equal(asset.src, "/media/boundary.svg");
assert.equal(asset.width, 1080);
assert.equal(asset.height, 420);
assert.equal(found?.publicPath, "/media/boundary.svg");
assert.equal(found?.width, 1080);
assert.equal(found?.height, 420);
});
test("falls back to the static registry for the legacy hardcoded key", () => {
const resolve = createAssetCatalogResolver([]);
const resolve = createResolvedAssetResolver([]);
const asset = resolve("fetch-strategy-boundary");
assert.equal(asset.src, "/media/fetch-strategy-boundary.svg");
});
test("returns the placeholder instead of throwing on an unknown key", () => {
const resolve = createAssetCatalogResolver([]);
const resolve = createResolvedAssetResolver([]);
assert.deepEqual(resolve("does-not-exist"), MISSING_EVIDENCE_ASSET);
});
test("never resolves a QUARANTINED asset", () => {
const resolve = createAssetCatalogResolver([
{ ...(READY as object), managementStatus: "QUARANTINED" } as never,
]);
assert.deepEqual(resolve("boundary"), MISSING_EVIDENCE_ASSET);
test("격리된 자료는 고르지 않는다", () => {
assert.equal(
findResolvableAsset([{ ...(READY as object), managementStatus: "QUARANTINED" } as never], "boundary"),
undefined,
);
});
test("resolves from the server render model blocks", () => {
@@ -75,12 +79,12 @@ test("resolves from the server render model blocks", () => {
assert.equal(resolve("boundary").width, 800);
});
test("a READY asset wins over a QUARANTINED asset sharing the same key", () => {
const resolve = createAssetCatalogResolver([
{ ...(READY as object), managementStatus: "QUARANTINED" } as never,
READY,
]);
assert.equal(resolve("boundary").src, "/media/boundary.svg");
test("같은 열쇠를 가진 격리 자료보다 쓸 수 있는 자료가 이긴다", () => {
const found = findResolvableAsset(
[{ ...(READY as object), managementStatus: "QUARANTINED" } as never, READY],
"boundary",
);
assert.equal(found?.publicPath, "/media/boundary.svg");
});
test("keeps the legacy key's hand-authored labels when a server block resolves it via descriptor (today's real Preview/Snapshot path)", () => {
@@ -109,15 +113,17 @@ test("keeps the legacy key's hand-authored labels when a server block resolves i
});
test("a colliding backend descriptor's publicPath wins over the legacy src, but the legacy labels still win", () => {
const resolve = createAssetCatalogResolver([
{
...(READY as object),
const resolve = createResolvedAssetResolver(
figure({
assetId: "11111111-1111-4111-8111-111111111111",
assetKey: "fetch-strategy-boundary",
mediaType: "image/svg+xml",
publicPath: "/media/should-win.svg",
width: 999,
height: 111,
} as never,
]);
decorative: false,
}),
);
const asset = resolve("fetch-strategy-boundary");
assert.equal(asset.src, "/media/should-win.svg");
@@ -11,14 +11,12 @@
// Against fix round 3's code this reported 53 of 144 combinations disagreeing.
//
// The callers covered are the mock adapter's projection gate and descriptor
// resolver, `validateWorkingCopy`, the shared pixel resolver, and -- added in
// the final fix wave -- `instant-preview.tsx`'s own gate and descriptor
// resolver. The last pair is byte-parallel to the adapter's (they live in
// different layers: `presentation/` may not import `adapters/`), and is the
// pair three earlier fix rounds regressed. Its one sanctioned divergence is
// the legacy static key's `assetId`, which the assertions below pin rather
// than ignore. Mutating either half of that pair reports 96 and 64 of 144
// combinations disagreeing respectively.
// resolver, `validateWorkingCopy`, and the pixel resolver every public screen
// renders through (`createResolvedAssetResolver`, reading the descriptor the
// projection attached to the block). The editor's own instant preview used to
// be a fourth caller carrying a byte-parallel copy of the same decision; the
// v4 editor dropped that surface, so the copy is gone and the pair it could
// disagree with no longer exists.
import assert from "node:assert/strict";
import { test } from "vitest";
@@ -27,11 +25,10 @@ import type { Asset } from "../../../src/features/tech-log/contracts/studio/cont
import { projectWorkingCopy } from "../../../src/features/tech-log/adapters/mock/project-public-render-model.ts";
import { validateWorkingCopy } from "../../../src/features/tech-log/adapters/mock/validate-working-copy.ts";
import { isSupportedEvidenceKey } from "../../../src/features/tech-log/adapters/static/evidence-assets.ts";
import { createAssetCatalogResolver } from "../../../src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts";
import {
instantPreviewEvidenceKeyGate,
resolveInstantPreviewAssetDescriptor,
} from "../../../src/features/tech-log/presentation/studio/components/instant-preview.tsx";
bodyBlocksOf,
createResolvedAssetResolver,
} from "../../../src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts";
import { ContentFormatError } from "../../../src/features/tech-log/domain/content-format/parse-case-content.ts";
const LEGACY = "fetch-strategy-boundary";
@@ -162,7 +159,9 @@ function project(key: string, alt: string, assets: readonly Asset[]) {
bodyBlocks: Array<{ type: string; asset?: Descriptor }>;
};
const figure = model.bodyBlocks.find((block) => block.type === "EVIDENCE_FIGURE");
return { accepted: true as const, descriptor: figure!.asset! };
// 화면이 실제로 그림을 그릴 때 읽는 것은 블록에 붙은 서술자다. 같은 모델에서 뽑아야
// "서술자와 픽셀이 한 자료인가" 를 묻는 의미가 있다.
return { accepted: true as const, descriptor: figure!.asset!, blocks: bodyBlocksOf(model) };
} catch (error) {
return { accepted: false as const, error };
}
@@ -194,22 +193,13 @@ test("gate, projection resolver, pixel resolver and validation never disagree",
const projected = project(key, "a", assets);
const report = validate(key, "a", assets);
const unsupported = report.issues.some((issue) => issue.code === "EVIDENCE_UNSUPPORTED");
const pixels = createAssetCatalogResolver(assets)(key);
const pixels = projected.accepted
? createResolvedAssetResolver(projected.blocks)(key)
: null;
// 1. Validation and the preview projection accept exactly the same keys.
check(!unsupported === projected.accepted, `${where}: validation and projection disagree`);
// 1b. Instant Preview's gate is a fourth caller of the same decision,
// living in `presentation/` (which may not import `adapters/`) and
// therefore carrying its own copy of the legacy-key predicate. It
// must accept exactly the same keys, in either array order.
const previewAccepts = instantPreviewEvidenceKeyGate(assets)(key);
check(previewAccepts === projected.accepted, `${where}: Instant Preview gate and the projection disagree`);
check(
instantPreviewEvidenceKeyGate([...assets].reverse())(key) === previewAccepts,
`${where}: order-dependent Instant Preview gate`,
);
if (!projected.accepted) {
check(projected.error instanceof ContentFormatError, `${where}: expected a gate rejection, got ${String(projected.error)}`);
check(
@@ -224,7 +214,7 @@ test("gate, projection resolver, pixel resolver and validation never disagree",
check(projected.descriptor.publicPath !== "", `${where}: accepted a key that renders as an empty publicPath`);
// 3. The block descriptor and the pixels are the same asset.
check(pixels.src === projected.descriptor.publicPath, `${where}: descriptor (${projected.descriptor.publicPath}) and pixels (${pixels.src}) disagree`);
check(pixels!.src === projected.descriptor.publicPath, `${where}: descriptor (${projected.descriptor.publicPath}) and pixels (${pixels!.src}) disagree`);
// 4. The descriptor names an asset that really is in the list and really
// is renderable (or the legacy static asset, which is in no list).
@@ -246,52 +236,18 @@ test("gate, projection resolver, pixel resolver and validation never disagree",
`${where}: order-dependent descriptor (${projected.descriptor.publicPath} vs ${reProjected.descriptor.publicPath})`,
);
}
check(createAssetCatalogResolver(reversed)(key).src === pixels.src, `${where}: order-dependent pixels`);
if (reProjected.accepted) {
check(
createResolvedAssetResolver(reProjected.blocks)(key).src === pixels!.src,
`${where}: order-dependent pixels`,
);
}
// 6. The alt rule is judged against the asset that actually renders.
const emptyAlt = validate(key, "", assets);
const altRequired = emptyAlt.issues.some((issue) => issue.code === "EVIDENCE_ALT_REQUIRED");
check(altRequired === !projected.descriptor.decorative, `${where}: alt rule judged a different asset than the one rendered`);
// 7. Instant Preview's own pair agrees with the mock adapter's. The two
// are byte-parallel expressions in different layers (`presentation/`
// may not import `adapters/`), and the pair regressed in three
// separate fix rounds, so the agreement is asserted rather than
// assumed. The single sanctioned divergence is the legacy static
// key's `assetId`: with no Asset backing it, Instant Preview returns
// a fixed literal where the adapter derives one from the static
// registry. Everything else -- acceptance, path, dimensions,
// mediaType, decorative -- must match exactly, and the divergence is
// pinned so a future change cannot widen it unnoticed.
const previewDescriptor = resolveInstantPreviewAssetDescriptor(assets)(key);
const { assetId: previewAssetId, ...previewRest } = previewDescriptor;
const { assetId: mockAssetId, ...mockRest } = projected.descriptor as unknown as
Record<string, unknown> & { assetId: string };
check(
JSON.stringify(previewRest) === JSON.stringify(mockRest),
`${where}: Instant Preview descriptor differs from the adapter's beyond assetId (${JSON.stringify(previewRest)} vs ${JSON.stringify(mockRest)})`,
);
check(
/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/.test(previewAssetId),
`${where}: Instant Preview assetId is not a stable UUID (${previewAssetId})`,
);
check(
(previewAssetId === mockAssetId) === Boolean(assets.some((candidate) => candidate.assetKey === key && candidate.id === mockAssetId)),
`${where}: assetId agreement is not confined to the legacy fallback`,
);
// 8. Instant Preview's descriptor and the pixels it renders are one asset.
check(
pixels.src === previewDescriptor.publicPath,
`${where}: Instant Preview descriptor (${previewDescriptor.publicPath}) and pixels (${pixels.src}) disagree`,
);
// 9. Order independence holds for Instant Preview's resolver too.
check(
JSON.stringify(resolveInstantPreviewAssetDescriptor([...assets].reverse())(key)) ===
JSON.stringify(previewDescriptor),
`${where}: order-dependent Instant Preview descriptor`,
);
}
}
assert.ok(checked >= 100, `only ${checked} combinations checked`);
@@ -42,7 +42,6 @@ const SETTLED = new Set([
".home-path-records li",
".investigation-records li",
// 흐름의 마디는 한 모양뿐이다 — 각 li 안에 링크 하나.
".mechanism-map a",
".studio-warning-check span",
]);