Files
tech-log-frontend/tests/features/tech-log/contract-operation-coverage.test.ts
T
DongHyeonkaandClaude Opus 5 0d4d1e5c0c feat: sitemap 을 공개 계약에 올린다
서버가 공개 프리픽스 아래에 내는 것은 전부 계약에 있어야 한다 —
PublicContractDriftTest 가 양방향으로 본다. 봉투를 쓰지 않는 자리는 media 가
선례이고, sitemap 도 같다: XML 이고 읽는 것은 브라우저가 아니라 크롤러다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PTnWufiY9ATv57egkKKVAV
2026-09-09 15:46:32 +09:00

84 lines
4.3 KiB
TypeScript

import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { test } from "vitest";
import { TECH_LOG_MANAGEMENT_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-management-contract-contribution.ts";
import { TECH_LOG_PUBLIC_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-public-contract-contribution.ts";
/**
* 계약에 있는 연산은 전부 기여 목록에 등록되어 있어야 한다.
*
* <p>등록하지 않은 연산은 타입에는 멀쩡히 보이는데 부를 수가 없다. 그래서 화면은 그 연산이
* 없는 줄 모르고 옆 연산을 부르거나(개념 삭제가 질문 삭제를 불러 "질문을 찾을 수 없습니다"
* 가 떴다), 아무것도 못 부른 채로 조용히 빈 화면이 됐다(`getPublicConcept`). 손으로 나열한
* 목록에 새 종류를 빠뜨리는 일이 이 저장소에서만 다섯 번 넘게 났고, 매번 다섯 개의 검사를
* 다 통과했다.
*
* <p>그래서 목록을 손으로 관리하지 않고 계약 문서에서 읽어 대조한다. 새 연산을 계약에 더하고
* 등록을 잊으면 여기서 멈춘다.
*/
function contractOperationIds(path: string): string[] {
const text = readFileSync(path, "utf8");
return [...text.matchAll(/^\s+operationId:\s*(\S+)\s*$/gmu)].map((match) => match[1]!);
}
/**
* 봉투를 쓰지 않고 바이트를 그대로 돌려주는 연산. `<img src>` 가 직접 가리키므로 HTTP 기여
* 목록을 지나지 않는다 — 등록을 잊은 것이 아니라 지날 이유가 없다.
*
* <p>`getPublicSitemap` 도 같은 자리다. XML 을 돌려주고, 그것을 읽는 것은 브라우저 코드가
* 아니라 크롤러다.
*/
const NOT_A_JSON_OPERATION = new Set(["getPublicMedia", "getPublicSitemap"]);
test("공개 계약의 모든 연산이 기여 목록에 등록되어 있다", () => {
const declared = contractOperationIds(
"src/features/tech-log/contracts/public/public-api.openapi.yaml",
);
assert.ok(declared.length > 0, "계약에서 연산을 하나도 읽지 못했다 — 정규식이 낡았다");
const registered = new Set(
TECH_LOG_PUBLIC_CONTRIBUTION.http.map((entry) => entry.contract.operationId),
);
const missing = declared.filter(
(operationId) => !registered.has(operationId) && !NOT_A_JSON_OPERATION.has(operationId),
);
assert.deepEqual(missing, [], `등록되지 않은 연산: ${missing.join(", ")}`);
});
/**
* 관리 계약은 다르다. Studio 는 종류마다 갈린 옛 연산 대신 작업본 하나(`/studio/documents/…`)로
* 문서를 다루므로, 계약에 있으나 화면이 부르지 않는 연산이 정상적으로 많다. 그래서 전수 대조는
* 뜻이 없고, 대신 **한 종류만 빠진 자리**를 본다 — 실제로 깨진 것이 늘 그 모양이었다.
*
* <p>주소에서 종류를 지우면 같은 일을 하는 연산들이 한 가족으로 모인다. 가족 하나가 세 종류만
* 갖고 있으면 나머지 한 종류의 화면은 조용히 옆 종류의 API 를 부르거나 아무것도 못 부른다.
*/
const KIND_SEGMENTS = ["cases", "references", "questions", "concepts"] as const;
test("문서 종류별 관리 연산에 빠진 종류가 없다", () => {
const families = new Map<string, Set<string>>();
for (const entry of TECH_LOG_MANAGEMENT_CONTRIBUTION.http) {
const { method, pathTemplate } = entry.contract;
for (const kind of KIND_SEGMENTS) {
if (!pathTemplate.includes(`/${kind}`)) continue;
const family = `${method} ${pathTemplate.replace(`/${kind}`, "/{kind}")}`;
const kinds = families.get(family) ?? new Set<string>();
kinds.add(kind);
families.set(family, kinds);
}
}
assert.ok(families.size > 0, "종류별 연산을 하나도 찾지 못했다 — 주소 규칙이 바뀌었다");
const holes: string[] = [];
for (const [family, kinds] of families) {
// 한 종류만 있는 가족은 그 종류에만 있는 일이다(예: 질문의 해결). 구멍은 여럿 중 빠진 것이다.
if (kinds.size === 1) continue;
const missing = KIND_SEGMENTS.filter((kind) => !kinds.has(kind));
if (missing.length > 0) holes.push(`${family} ← ${missing.join(", ")} 없음`);
}
assert.deepEqual(holes, [], `종류가 빠진 연산 가족:\n${holes.join("\n")}`);
});