fix(contracts): 짝 백엔드 답 표를 pin한 백엔드 표의 사본과 대조한다
문제: 짝 백엔드 답 표 JSON(backend-idempotency-answers.json)이 pin한
백엔드 http-contract.md와 같은지 아무 검사도 보지 않는다.
backend-contract-pin.test.ts는 pin과 답 표 두 파일만 읽고, drift
스크립트는 pin과 HEAD 사이에 문서 글자가 바뀌었는지만 본다. 그래서
답 표 status 오타나 옮기지 않은 행(§4 RATE_LIMIT_*)은 어디서도 걸리지
않는다. drift 스크립트는 옆 checkout이 없으면 "skipped"로 rc=0이고
(worktree에서 늘 그렇다), 매뉴얼에는 스크립트가 없다.
고른 방법: 게이트가 백엔드 checkout 없이 볼 수 있게, 백엔드 §2·§4 표의
`|` 줄을 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json
에 옮겼다. 읽는 함수는 scripts/lib/backend-contract-excerpt.ts 하나다.
- test:unit(backend-contract-pin.test.ts): 답 표의 행마다 사본의 같은 절에
같은 code·status 행이 있는지, 사본의 행마다 답 표에 있거나 pin의
`notCopied`에 이유와 함께 있는지 본다. `notCopied`에는 RATE_LIMIT_* 둘을
적었다(리뷰가 지적한 sectionsCompared §4의 실제 범위).
- check:backend-contract-drift(게이트 밖): pin 커밋의 문서에서 같은 표를
읽어 사본과 글자 단위로 비교하고, 답 표도 그 표와 비교하고, pin 뒤
HEAD에서 바뀐 사본 표 행을 찍는다. checkout이 없거나 pin 커밋·문서가
없으면 rc=2("not compared")로 끝난다. 기본 경로는 main checkout 옆이라
linked worktree에서도 같은 백엔드를 찾는다. `--write-excerpt`는 pin을
올릴 때 사본을 pin 커밋에서 다시 옮긴다.
- 매뉴얼 01 Envelope 단계와 계약 문서 4.1에 언제 무엇을 돌리는지 적었다.
버린 대안: 백엔드 문서의 digest만 pin에 두는 것. 게이트는 digest로 답
표를 확인할 수 없다. 계약 패키지(리뷰 안 D)는 배포 경로가 아직 없다.
위험·한계: 사본과 백엔드 문서의 일치는 여전히 백엔드 checkout이 있을
때만 drift 스크립트가 본다. 게이트는 답 표와 사본의 일치만 본다. 사본을
손으로 같이 고치면 게이트는 통과한다(drift 스크립트가 잡는다). 답 표의
refusedBeforeWrite·sameKeyResend는 백엔드 문장(클라이언트 행동)을 사람이
읽은 값이라 기계로 대조하지 않는다. 그 문장이 바뀌면 사본 diff와 drift
출력에 보인다. 백엔드 표 형식(머리글 `error.code`·`코드`·`status`)이
바뀌면 파서도 고친다. pin의 comparedOn을 사본을 옮긴 날로 올렸다.
검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts
drift 테스트는 가짜 백엔드 git repo로 D6g(pin 뒤 status 변경), 답 표
status 오타, 사본 오타, 옮기지도 적지도 않은 행, checkout 없음,
--write-excerpt를 돈다.
Refs: 1105/07-01
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
"entries": [
|
||||
{
|
||||
"script": "check:backend-contract-drift",
|
||||
"reason": "1103/12-06. Compares the paired backend checkout next to this repository with the commit config/contracts/backend-contract-pin.json pins. CI checks out this repository alone, so a gate has no backend to read; with no checkout the script reports skipped. The gated half of the pin is tests/unit/backend-contract-pin.test.ts (test:unit), which holds the Envelope table to the copied backend answer table. Run this before moving the pin."
|
||||
"reason": "1103/12-06, 1105/07-01. Compares the paired backend checkout (--backend, or beside the main checkout) with config/contracts/backend-contract-pin.json: the copied table excerpt and the answer table against the pinned document, and the document between the pin and the backend's HEAD. CI checks out this repository alone, so a gate has no backend to read; with no checkout the script exits 2 (not compared), never 0. The gated half is tests/unit/backend-contract-pin.test.ts (test:unit), which holds the Envelope table to the answer table and the answer table to the excerpt. Run this after pulling the backend and before moving the pin (docs/manual/01-add-a-feature.md)."
|
||||
},
|
||||
{
|
||||
"script": "check:feature-index",
|
||||
|
||||
@@ -12,8 +12,21 @@
|
||||
"readers": ["src/adapters/http/backend-envelope.ts"]
|
||||
},
|
||||
"tables": {
|
||||
"idempotencyAnswers": "config/contracts/backend-idempotency-answers.json"
|
||||
"idempotencyAnswers": "config/contracts/backend-idempotency-answers.json",
|
||||
"backendExcerpt": "config/contracts/backend-http-contract-excerpt.json"
|
||||
},
|
||||
"notCopied": [
|
||||
{
|
||||
"section": "4",
|
||||
"code": "RATE_LIMIT_UNAVAILABLE",
|
||||
"reason": "A rate-limit answer the Envelope table does not read: an unlisted 503 code goes to the feature's classifier, which the scaffold makes MAYBE_APPLIED. Copy it with a frontend verdict when one is needed."
|
||||
},
|
||||
{
|
||||
"section": "4",
|
||||
"code": "RATE_LIMIT_INCOMPATIBLE",
|
||||
"reason": "A rate-limit provider misconfiguration, not an answer to one request; it goes to the feature's classifier like RATE_LIMIT_UNAVAILABLE."
|
||||
}
|
||||
],
|
||||
"owner": "frontend-platform",
|
||||
"comparedOn": "2026-11-04"
|
||||
"comparedOn": "2026-11-05"
|
||||
}
|
||||
|
||||
@@ -0,0 +1,37 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"source": {
|
||||
"repository": "clean-architecture-backend-template",
|
||||
"commit": "45d2a478b800586f1d84151723629a560265d58e",
|
||||
"document": "docs/web/http-contract.md"
|
||||
},
|
||||
"sections": {
|
||||
"2": [
|
||||
[
|
||||
"| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |",
|
||||
"| --- | --- | --- | --- | --- | --- |",
|
||||
"| 재생(replay): 같은 키·같은 본문, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | — | 없음 | 첫 요청의 결과로 받아들인다. `meta`의 id는 이번 요청의 것이다 |",
|
||||
"| 처리 중(in-flight): 같은 키, 첫 요청이 아직 실행 중(Redis 저장소. PostgreSQL 저장소는 409 대신 첫 요청이 끝날 때까지 기다린다 — 아래 \"첫 시도가 lease보다 오래 걸릴 때\") | 409 | `IDEMPOTENT_IN_FLIGHT` | `true` | `2` | 결과 불명. **같은 `Idempotency-Key`로** `Retry-After` 뒤 재전송한다. **새 키 금지** |",
|
||||
"| 본문 불일치(mismatch): 같은 키·다른 본문 | 422 | `IDEMPOTENT_REQUEST_MISMATCH` | `false` | 없음 | 클라이언트 버그. 다시 보내지 않는다. 새 작업이면 새 키를 만든다 |",
|
||||
"| 키 누락·형식 오류 | 400 | `IDEMPOTENCY_KEY_INVALID` (`details.reason` = `MISSING`/`MALFORMED`) | `false` | 없음 | 문법에 맞는 키를 붙여 다시 보낸다 |"
|
||||
],
|
||||
[
|
||||
"| 경우 | status | `error.code` | `retryable` | `Retry-After` | 클라이언트 행동 |",
|
||||
"| --- | --- | --- | --- | --- | --- |",
|
||||
"| 작업 실행 전(claim·시작 단계) 멱등성 저장소 응답 없음. 또는 claim의 processing lease가 작업 시작 전에 끝나 저장소가 시작을 거절함 | 503 | `IDEMPOTENCY_UNAVAILABLE` | `true` | 없음 | 작업은 실행되지 않았다. 같은 키로 나중에 다시 보낸다(다음 요청이 그 claim을 넘겨받아 실행한다) |",
|
||||
"| 작업 실행 뒤 결과 기록(complete 단계) 중 저장소 응답 없음 — **결과 불명** | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | `true` | 없음 | \"적용되지 않았다\"고 알리지 않는다. **같은 키로** 나중에 다시 보낸다. 새 키 금지 |",
|
||||
"| 이전 시도의 효과를 증명할 수 없음 | 500 | `IDEMPOTENCY_RECOVERY_REQUIRED` | `false` | 없음 | 자동 재시도하지 않는다. 같은 키 재전송은 안전하다 — 서버는 효과가 있었을 수 있는 작업을 다시 돌리지 않고, 첫 시도가 늦게 끝났으면 그 결과를 재생하며, 효과 없이 끝났으면 실행하고, 아니면 다시 500이다. 결과는 업무 데이터로 확인하고, 효과가 없다고 확인된 뒤에만 운영 절차(`docs/runbooks/idempotency-unavailable.md`)에 따라 새 키로 다시 보낸다 |"
|
||||
]
|
||||
],
|
||||
"4": [
|
||||
[
|
||||
"| 코드 | status | category | `retryable` | `Retry-After` | 언제 |",
|
||||
"| --- | --- | --- | --- | --- | --- |",
|
||||
"| `REQUEST_TIMEOUT` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 없음 | 비동기 요청(`Callable`·`DeferredResult`·스트리밍)이 시간 안에 끝나지 않았다. GraphQL도 같은 이름을 쓰지만 그쪽 `category`는 GraphQL 전용 어휘 `TIMEOUT`이다(`src/adapter/inbound/graphql/README.md`) |",
|
||||
"| `IDEMPOTENCY_KEY_INVALID` | 400 | `VALIDATION` | `false` | 없음 | 2절 |",
|
||||
"| `RATE_LIMIT_UNAVAILABLE` | 503 | `TRANSIENT_DEPENDENCY` | `true` | 있음 | rate-limit 저장소 응답 없음(`docs/web/runbook.md`) |",
|
||||
"| `RATE_LIMIT_INCOMPATIBLE` | 503 | `INTERNAL` | `false` | 없음 | rate-limit 제공자가 계약과 맞지 않음 |"
|
||||
]
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -172,9 +172,18 @@ Envelope의 모양과 키 존재 규칙은 짝 백엔드 템플릿 문서가 정
|
||||
재전송 열로 옮겨 두었다. `tests/unit/backend-contract-pin.test.ts`가 그 표와
|
||||
`backend-envelope.ts`의 판정을 양방향으로 대조한다. 값이 null인 필드는 키째
|
||||
생략한다. 백엔드 기준 커밋을 올리면 pin, 답 표 JSON, 6.1절 표를 같은 변경에서
|
||||
다시 확인한다. 형제 디렉터리에 백엔드 checkout이 있으면
|
||||
`corepack pnpm check:backend-contract-drift`가 pin 뒤 `http-contract.md`가
|
||||
바뀌었는지 알려 준다(게이트 밖).
|
||||
다시 확인한다.
|
||||
- 백엔드 §2·§4 표의 행은 pin 커밋 그대로
|
||||
`config/contracts/backend-http-contract-excerpt.json`에 옮겨 두었다. 같은 테스트가
|
||||
답 표의 code·status를 이 사본과 대조한다. 사본에만 있는 행은 답 표에 옮기거나 pin의
|
||||
`notCopied`에 이유와 함께 적는다(지금은 §4의 `RATE_LIMIT_*` 둘). pin의
|
||||
`sectionsCompared`에 §4가 있어도 답 표가 옮긴 §4 행은 `REQUEST_TIMEOUT` 하나다.
|
||||
`IDEMPOTENCY_KEY_INVALID`는 §2 행으로 옮겼다.
|
||||
- 사본이 백엔드 문서와 같은지는 `corepack pnpm check:backend-contract-drift --backend <백엔드 checkout>`이
|
||||
본다(게이트 밖. CI는 이 repo만 checkout한다). pin 커밋의 표와 사본·답 표를
|
||||
비교하고, pin 뒤 백엔드 HEAD에서 바뀐 표 행을 알린다. 1은 어긋남, 2는 비교하지
|
||||
못함(통과가 아니다)이다. 짝 백엔드를 새로 받을 때마다 돌린다. pin을 올릴 때는
|
||||
`--write-excerpt`가 사본을 pin 커밋에서 다시 옮긴다.
|
||||
- 프론트에서 Envelope를 읽는 곳: `src/adapters/http/backend-envelope.ts`(스키마와
|
||||
해석). V3 실행기는 descriptor가 `responseEnvelope: "ENVELOPE_V1"`일 때 쓴다.
|
||||
`create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능은 선언하지 않고
|
||||
|
||||
@@ -220,6 +220,9 @@ FE-REG-API 행은 descriptor에서 자동으로 만든다(`src/contracts/api-ope
|
||||
- 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다.
|
||||
- problem 스키마(`<base>-schemas.ts`의 `<base>ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다.
|
||||
- 400·409·422와 백엔드가 정한 5xx 넷이 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다.
|
||||
- 기준 표는 백엔드 커밋 하나에 묶여 있다(`config/contracts/backend-contract-pin.json`). 백엔드 표의 행은 `config/contracts/backend-http-contract-excerpt.json`에 그대로 옮겨 두었고, `test:unit`이 답 표(`config/contracts/backend-idempotency-answers.json`)를 그 사본과 대조한다.
|
||||
- **짝 백엔드를 새로 받을 때마다** `corepack pnpm check:backend-contract-drift --backend <백엔드 checkout>`을 돌린다. 게이트 밖이라 CI는 돌리지 않는다. 1이면 pin 뒤 백엔드 표가 바뀌었거나 사본·답 표가 pin과 다르다. 출력이 그 행을 말한다. 2는 비교하지 못했다는 뜻이고 통과가 아니다(checkout이 없거나 pin 커밋이 없다).
|
||||
- pin을 올릴 때: pin의 `backend.commit`과 답 표의 `source.commit`을 바꾸고 같은 명령에 `--write-excerpt`를 붙여 사본을 다시 옮긴다. 그다음 답 표와 [백엔드 계약 6.1절](../architecture/backend-api-and-server-state-contract.md) 표를 명령이 통과할 때까지 고친다. 옮기지 않는 행은 pin의 `notCopied`에 이유와 함께 적는다.
|
||||
- 업무 규칙 거절(`<FEATURE>_INVALID`, `*_ALREADY_EXISTS` 등)은 표에 없어 결과 불명이 된다. 그 엔드포인트가 쓰기 전에만 내는 code면 `commandEffect.refusedBeforeWrite`에 적는다. 적어야 사용자가 값을 고쳐 다시 저장할 수 있다(02 결정표 4절).
|
||||
- `mapProblem`이 없거나 `undefined`를 돌려주면 백엔드 code·필드 오류·status별 kind로 읽는다(`src/adapters/http/backend-envelope.ts`).
|
||||
- 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다.
|
||||
|
||||
@@ -1,82 +1,169 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { existsSync, readFileSync } from "node:fs";
|
||||
import { existsSync, readFileSync, writeFileSync } from "node:fs";
|
||||
import path from "node:path";
|
||||
|
||||
import {
|
||||
answerTableProblems,
|
||||
excerptAnswerRows,
|
||||
excerptDifferences,
|
||||
readExcerptSections,
|
||||
type ExcerptSections,
|
||||
type NotCopiedRow,
|
||||
} from "./lib/backend-contract-excerpt.ts";
|
||||
|
||||
/**
|
||||
* 1103/12-06. Local only, outside every gate: CI checks this repository out
|
||||
* alone. Tells whether the paired backend checkout next to this one has moved
|
||||
* past the commit `config/contracts/backend-contract-pin.json` pins, and
|
||||
* whether the contract document changed since.
|
||||
* 1103/12-06, 1105/07-01. Local only, outside every gate: CI checks this
|
||||
* repository out alone. With the paired backend checkout it checks that
|
||||
*
|
||||
* corepack pnpm check:backend-contract-drift [--backend <dir>]
|
||||
* 1. the table excerpt (`tables.backendExcerpt`) is word for word the
|
||||
* backend document's tables at the pinned commit,
|
||||
* 2. the answer table JSON matches that excerpt (test:unit checks this too),
|
||||
* 3. the document has not changed between the pin and the backend's HEAD.
|
||||
*
|
||||
* Exit 0: no checkout to compare, the pinned commit itself, or a later commit
|
||||
* whose contract document is unchanged. Exit 1: the document changed after
|
||||
* the pin. Recheck the frontend contract 6.1 table, the copied answer table
|
||||
* and the pin in one change. Exit 2: the checkout cannot be compared.
|
||||
* corepack pnpm check:backend-contract-drift [--backend <dir>] [--write-excerpt]
|
||||
*
|
||||
* `--write-excerpt` copies the excerpt from the pinned commit first: run it
|
||||
* after moving the pin, then fix the answer table until this passes.
|
||||
*
|
||||
* Exit 0: all three hold. Exit 1: one does not; the output names the rows.
|
||||
* Recheck the frontend contract 6.1 table, the answer table, the excerpt and
|
||||
* the pin in one change. Exit 2: nothing was compared (no checkout, or the
|
||||
* pinned commit or document is missing), which is not a pass.
|
||||
*
|
||||
* Without `--backend` the checkout is looked for beside the main checkout of
|
||||
* this repository, so a linked worktree (`.claude/worktrees/<name>`) finds
|
||||
* the same one.
|
||||
*/
|
||||
|
||||
type Pin = Readonly<{
|
||||
backend: Readonly<{ repository: string; commit: string; document: string }>;
|
||||
tables: Readonly<{ idempotencyAnswers: string; backendExcerpt: string }>;
|
||||
notCopied: readonly NotCopiedRow[];
|
||||
}>;
|
||||
|
||||
type Answers = Readonly<{
|
||||
answers: readonly Readonly<{ section: string; code: string; status: number }>[];
|
||||
}>;
|
||||
|
||||
type Excerpt = Readonly<{
|
||||
schemaVersion: 1;
|
||||
source: Readonly<{ repository: string; commit: string; document: string }>;
|
||||
sections: ExcerptSections;
|
||||
}>;
|
||||
|
||||
const PIN_PATH = "config/contracts/backend-contract-pin.json";
|
||||
|
||||
function backendDirectory(pin: Pin): string {
|
||||
const flag = process.argv.indexOf("--backend");
|
||||
const given = flag >= 0 ? process.argv[flag + 1] : undefined;
|
||||
return given
|
||||
? path.resolve(given)
|
||||
: path.resolve("..", pin.backend.repository);
|
||||
}
|
||||
|
||||
function git(directory: string, ...args: string[]) {
|
||||
return spawnSync("git", ["-C", directory, ...args], { encoding: "utf8" });
|
||||
}
|
||||
|
||||
function backendDirectory(pin: Pin): string {
|
||||
const flag = process.argv.indexOf("--backend");
|
||||
const given = flag >= 0 ? process.argv[flag + 1] : undefined;
|
||||
if (given) return path.resolve(given);
|
||||
const common = spawnSync(
|
||||
"git",
|
||||
["rev-parse", "--path-format=absolute", "--git-common-dir"],
|
||||
{ encoding: "utf8" },
|
||||
);
|
||||
const mainCheckout =
|
||||
common.status === 0 && common.stdout.trim() !== ""
|
||||
? path.dirname(common.stdout.trim())
|
||||
: process.cwd();
|
||||
return path.resolve(mainCheckout, "..", pin.backend.repository);
|
||||
}
|
||||
|
||||
function readJson<T>(file: string): T {
|
||||
return JSON.parse(readFileSync(file, "utf8")) as T;
|
||||
}
|
||||
|
||||
function cannotCompare(message: string): void {
|
||||
console.error(`Backend contract drift: not compared. ${message}`);
|
||||
process.exitCode = 2;
|
||||
}
|
||||
|
||||
function main(): void {
|
||||
const pin = JSON.parse(readFileSync(PIN_PATH, "utf8")) as Pin;
|
||||
const pin = readJson<Pin>(PIN_PATH);
|
||||
const directory = backendDirectory(pin);
|
||||
const { commit, document } = pin.backend;
|
||||
if (!existsSync(path.join(directory, ".git"))) {
|
||||
console.log(
|
||||
`Backend contract drift: skipped, no ${pin.backend.repository} checkout at ${directory} (pass --backend <dir>)`,
|
||||
cannotCompare(
|
||||
`No ${pin.backend.repository} checkout at ${directory}; pass --backend <dir>. test:unit holds the answer table to ${pin.tables.backendExcerpt}, and only this script holds that copy to the backend.`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
const head = git(directory, "rev-parse", "HEAD");
|
||||
if (head.status !== 0 || git(directory, "cat-file", "-e", `${commit}^{commit}`).status !== 0) {
|
||||
console.error(
|
||||
`Backend contract drift: cannot compare ${directory} with the pinned ${commit.slice(0, 12)}; fetch the backend history first`,
|
||||
cannotCompare(
|
||||
`${directory} does not have the pinned ${commit.slice(0, 12)}; fetch the backend history first.`,
|
||||
);
|
||||
process.exitCode = 2;
|
||||
return;
|
||||
}
|
||||
const headCommit = head.stdout.trim();
|
||||
if (headCommit === commit) {
|
||||
console.log(`Backend contract drift: ${directory} is at the pinned ${commit.slice(0, 12)}`);
|
||||
const pinned = git(directory, "show", `${commit}:${document}`);
|
||||
if (pinned.status !== 0) {
|
||||
cannotCompare(`${document} is not in the pinned ${commit.slice(0, 12)}.`);
|
||||
return;
|
||||
}
|
||||
const changed = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", document);
|
||||
const tableLines = changed.stdout
|
||||
.split("\n")
|
||||
.filter((line) => /^[+-]\|/u.test(line));
|
||||
if (changed.stdout.trim() === "") {
|
||||
const sectionNames = Object.keys(readJson<Excerpt>(pin.tables.backendExcerpt).sections);
|
||||
const pinnedSections = readExcerptSections(pinned.stdout, sectionNames);
|
||||
if (process.argv.includes("--write-excerpt")) {
|
||||
const written: Excerpt = {
|
||||
schemaVersion: 1,
|
||||
source: { repository: pin.backend.repository, commit, document },
|
||||
sections: pinnedSections,
|
||||
};
|
||||
writeFileSync(pin.tables.backendExcerpt, `${JSON.stringify(written, null, 2)}\n`);
|
||||
console.log(
|
||||
`Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} unchanged`,
|
||||
`Backend contract drift: wrote ${pin.tables.backendExcerpt} from ${commit.slice(0, 12)} §${sectionNames.join(", §")}`,
|
||||
);
|
||||
}
|
||||
const excerpt = readJson<Excerpt>(pin.tables.backendExcerpt);
|
||||
const failures: string[] = [];
|
||||
|
||||
const source = excerpt.source;
|
||||
if (source.repository !== pin.backend.repository || source.commit !== commit || source.document !== document) {
|
||||
failures.push(`${pin.tables.backendExcerpt} names ${source.commit.slice(0, 12)}, the pin ${commit.slice(0, 12)}`);
|
||||
}
|
||||
for (const line of excerptDifferences(excerpt.sections, pinnedSections)) {
|
||||
failures.push(`excerpt differs from the pinned document: ${line}`);
|
||||
}
|
||||
const answers = readJson<Answers>(pin.tables.idempotencyAnswers).answers;
|
||||
for (const problem of answerTableProblems(answers, pin.notCopied, excerptAnswerRows(pinnedSections))) {
|
||||
failures.push(`answer table: ${problem}`);
|
||||
}
|
||||
|
||||
const headCommit = head.stdout.trim();
|
||||
if (headCommit !== commit) {
|
||||
const changed = git(directory, "diff", "--unified=0", `${commit}..HEAD`, "--", document);
|
||||
if (changed.stdout.trim() !== "") {
|
||||
failures.push(
|
||||
`${document} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}`,
|
||||
);
|
||||
const current = git(directory, "show", `HEAD:${document}`);
|
||||
const tableChanges =
|
||||
current.status === 0
|
||||
? excerptDifferences(pinnedSections, readExcerptSections(current.stdout, sectionNames))
|
||||
: [];
|
||||
for (const line of tableChanges) failures.push(` copied table at HEAD: ${line}`);
|
||||
if (tableChanges.length === 0) {
|
||||
failures.push(" (no copied table row changed; read the other changes with git diff)");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if (failures.length === 0) {
|
||||
console.log(
|
||||
headCommit === commit
|
||||
? `Backend contract drift: ${directory} is at the pinned ${commit.slice(0, 12)}; the excerpt and the answer table match it`
|
||||
: `Backend contract drift: HEAD ${headCommit.slice(0, 12)} is past the pin ${commit.slice(0, 12)}, ${document} unchanged; the excerpt and the answer table match it`,
|
||||
);
|
||||
return;
|
||||
}
|
||||
console.error("Backend contract drift:");
|
||||
for (const failure of failures) console.error(` ${failure}`);
|
||||
console.error(
|
||||
`Backend contract drift: ${document} changed between the pin ${commit.slice(0, 12)} and HEAD ${headCommit.slice(0, 12)}.`,
|
||||
`Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, ${pin.tables.idempotencyAnswers}, ${pin.tables.backendExcerpt} and ${PIN_PATH} together.`,
|
||||
);
|
||||
console.error(
|
||||
`Recheck docs/architecture/backend-api-and-server-state-contract.md 6.1, config/contracts/backend-idempotency-answers.json and ${PIN_PATH} together.`,
|
||||
);
|
||||
for (const line of tableLines) console.error(` ${line}`);
|
||||
if (tableLines.length === 0) {
|
||||
console.error(" (no table rows changed; read the prose changes with git diff)");
|
||||
}
|
||||
process.exitCode = 1;
|
||||
}
|
||||
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
/**
|
||||
* 1105/07-01. The paired backend's `http-contract.md` tables the frontend
|
||||
* copies at the pinned commit (`config/contracts/backend-http-contract-excerpt.json`),
|
||||
* read the same way from the backend document and from the copy.
|
||||
*
|
||||
* - `tests/unit/backend-contract-pin.test.ts` (test:unit) holds the answer
|
||||
* table JSON to the copy. It needs no backend checkout.
|
||||
* - `scripts/check-backend-contract-drift.ts` (local, outside the gates) holds
|
||||
* the copy to the backend document at the pin and reports what changed at
|
||||
* the backend's HEAD.
|
||||
*/
|
||||
|
||||
/** Section number (`"2"` for `## 2. ...`) → its tables, each the `|` lines in order. */
|
||||
export type ExcerptSections = Readonly<Record<string, readonly (readonly string[])[]>>;
|
||||
|
||||
export type ContractAnswerRow = Readonly<{
|
||||
section: string;
|
||||
code: string;
|
||||
status: number;
|
||||
}>;
|
||||
|
||||
export type NotCopiedRow = Readonly<{
|
||||
section: string;
|
||||
code: string;
|
||||
reason: string;
|
||||
}>;
|
||||
|
||||
const SECTION_HEADING = /^## (\d+)\.\s/u;
|
||||
const ANY_SECTION_HEADING = /^## /u;
|
||||
const CODE_HEADERS = new Set(["error.code", "코드"]);
|
||||
const STATUS_HEADER = "status";
|
||||
const CODE_CELL = /^`([A-Z][A-Z0-9_]*)`/u;
|
||||
const STATUS_CELL = /^\d{3}$/u;
|
||||
const SEPARATOR_ROW = /^\|(?:\s*:?-+:?\s*\|)+\s*$/u;
|
||||
|
||||
/**
|
||||
* The tables of the `## N.` sections named: every run of lines that start
|
||||
* with `|`, kept as written. A `###` heading stays inside its section.
|
||||
*/
|
||||
export function readExcerptSections(
|
||||
markdown: string,
|
||||
sections: readonly string[],
|
||||
): ExcerptSections {
|
||||
const tables: Record<string, string[][]> = {};
|
||||
let section: string | undefined;
|
||||
let table: string[] | undefined;
|
||||
for (const line of markdown.split(/\r?\n/u)) {
|
||||
if (ANY_SECTION_HEADING.test(line)) {
|
||||
section = SECTION_HEADING.exec(line)?.[1];
|
||||
table = undefined;
|
||||
continue;
|
||||
}
|
||||
if (section === undefined || !sections.includes(section) || !line.startsWith("|")) {
|
||||
table = undefined;
|
||||
continue;
|
||||
}
|
||||
if (table === undefined) {
|
||||
table = [];
|
||||
(tables[section] ??= []).push(table);
|
||||
}
|
||||
table.push(line);
|
||||
}
|
||||
return Object.freeze(
|
||||
Object.fromEntries(
|
||||
sections.map((name) => [
|
||||
name,
|
||||
Object.freeze((tables[name] ?? []).map((rows) => Object.freeze([...rows]))),
|
||||
]),
|
||||
),
|
||||
);
|
||||
}
|
||||
|
||||
function cells(line: string): string[] {
|
||||
return line
|
||||
.replace(/^\|/u, "")
|
||||
.replace(/\|\s*$/u, "")
|
||||
.split("|")
|
||||
.map((cell) => cell.trim());
|
||||
}
|
||||
|
||||
/**
|
||||
* The rows that answer with one error code and one status: the code column
|
||||
* is headed `error.code` or `코드`, the status column `status`. A row without
|
||||
* a code (§2's replay) or without one three-digit status is not an answer.
|
||||
*/
|
||||
export function excerptAnswerRows(sections: ExcerptSections): readonly ContractAnswerRow[] {
|
||||
const rows: ContractAnswerRow[] = [];
|
||||
for (const [section, tables] of Object.entries(sections)) {
|
||||
for (const table of tables) {
|
||||
const [header = "", ...body] = table;
|
||||
const headings = cells(header).map((cell) => cell.replaceAll("`", ""));
|
||||
const codeColumn = headings.findIndex((cell) => CODE_HEADERS.has(cell));
|
||||
const statusColumn = headings.indexOf(STATUS_HEADER);
|
||||
if (codeColumn < 0 || statusColumn < 0) continue;
|
||||
for (const line of body) {
|
||||
if (SEPARATOR_ROW.test(line)) continue;
|
||||
const row = cells(line);
|
||||
const code = CODE_CELL.exec(row[codeColumn] ?? "")?.[1];
|
||||
const status = row[statusColumn] ?? "";
|
||||
if (code !== undefined && STATUS_CELL.test(status)) {
|
||||
rows.push(Object.freeze({ section, code, status: Number(status) }));
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return Object.freeze(rows);
|
||||
}
|
||||
|
||||
/**
|
||||
* What the copied answer table gets wrong against the excerpt: an answer the
|
||||
* named section does not have, an excerpt row neither copied nor listed as
|
||||
* not copied, and a not-copied entry the excerpt does not have. An answer
|
||||
* covers an excerpt row of any section with the same code and status (§4
|
||||
* repeats §2's `IDEMPOTENCY_KEY_INVALID`).
|
||||
*/
|
||||
export function answerTableProblems(
|
||||
answers: readonly ContractAnswerRow[],
|
||||
notCopied: readonly NotCopiedRow[],
|
||||
excerpt: readonly ContractAnswerRow[],
|
||||
): readonly string[] {
|
||||
const problems: string[] = [];
|
||||
for (const answer of answers) {
|
||||
const inSection = excerpt.some(
|
||||
(row) =>
|
||||
row.section === answer.section &&
|
||||
row.code === answer.code &&
|
||||
row.status === answer.status,
|
||||
);
|
||||
if (!inSection) {
|
||||
problems.push(
|
||||
`answer ${answer.status} ${answer.code} is not a row of the pinned document's §${answer.section}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
for (const row of excerpt) {
|
||||
const copied = answers.some(
|
||||
(answer) => answer.code === row.code && answer.status === row.status,
|
||||
);
|
||||
const skipped = notCopied.some(
|
||||
(entry) => entry.section === row.section && entry.code === row.code,
|
||||
);
|
||||
if (copied && skipped) {
|
||||
problems.push(
|
||||
`§${row.section} ${row.status} ${row.code} is both copied and listed in notCopied`,
|
||||
);
|
||||
} else if (!copied && !skipped) {
|
||||
problems.push(
|
||||
`§${row.section} ${row.status} ${row.code} is neither in the answer table nor in the pin's notCopied`,
|
||||
);
|
||||
}
|
||||
}
|
||||
for (const entry of notCopied) {
|
||||
if (!excerpt.some((row) => row.section === entry.section && row.code === entry.code)) {
|
||||
problems.push(
|
||||
`notCopied ${entry.code} is not a row of the pinned document's §${entry.section}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze(problems);
|
||||
}
|
||||
|
||||
/**
|
||||
* The lines one excerpt has and the other does not, per section: `-` only
|
||||
* in `expected`, `+` only in `actual`. Empty when they are the same.
|
||||
*/
|
||||
export function excerptDifferences(
|
||||
expected: ExcerptSections,
|
||||
actual: ExcerptSections,
|
||||
): readonly string[] {
|
||||
const differences: string[] = [];
|
||||
const names = [...new Set([...Object.keys(expected), ...Object.keys(actual)])].sort();
|
||||
for (const name of names) {
|
||||
const before = (expected[name] ?? []).flat();
|
||||
const after = (actual[name] ?? []).flat();
|
||||
const sameTables =
|
||||
JSON.stringify(expected[name] ?? []) === JSON.stringify(actual[name] ?? []);
|
||||
if (sameTables) continue;
|
||||
const removed = before.filter((line) => !after.includes(line));
|
||||
const added = after.filter((line) => !before.includes(line));
|
||||
for (const line of removed) differences.push(`§${name} -${line}`);
|
||||
for (const line of added) differences.push(`§${name} +${line}`);
|
||||
if (removed.length === 0 && added.length === 0) {
|
||||
differences.push(`§${name} the same rows, split into tables or ordered differently`);
|
||||
}
|
||||
}
|
||||
return Object.freeze(differences);
|
||||
}
|
||||
@@ -0,0 +1,267 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
|
||||
import { afterEach, describe, expect, it } from "vitest";
|
||||
|
||||
/**
|
||||
* 1105/07-01. `check:backend-contract-drift` on a fake paired backend: a git
|
||||
* repository with a small `docs/web/http-contract.md`, and a frontend root
|
||||
* with the pin, the answer table and the table excerpt. The script compared
|
||||
* only the document between the pin and HEAD, so an answer table or an
|
||||
* excerpt that disagreed with the pinned document passed, and no checkout
|
||||
* passed as "skipped".
|
||||
*/
|
||||
|
||||
type Answer = Readonly<{ section: string; code: string; status: number }>;
|
||||
type Sections = Readonly<Record<string, readonly (readonly string[])[]>>;
|
||||
|
||||
const T2A = [
|
||||
"| 경우 | status | `error.code` | 클라이언트 행동 |",
|
||||
"| --- | --- | --- | --- |",
|
||||
"| 재생: 같은 키, 첫 요청 완료 | 첫 요청과 같은 성공 status | — (성공 Envelope) | 받아들인다 |",
|
||||
"| 처리 중 | 409 | `IDEMPOTENT_IN_FLIGHT` | 같은 키로 다시 보낸다 |",
|
||||
];
|
||||
const T2B = [
|
||||
"| 경우 | status | `error.code` | 클라이언트 행동 |",
|
||||
"| --- | --- | --- | --- |",
|
||||
"| 결과 불명 | 503 | `IDEMPOTENCY_COMPLETION_UNKNOWN` | 같은 키로 나중에 |",
|
||||
];
|
||||
const T4 = [
|
||||
"| 코드 | status | 언제 |",
|
||||
"| --- | --- | --- |",
|
||||
"| `REQUEST_TIMEOUT` | 503 | 시간 안에 끝나지 않았다 |",
|
||||
"| `RATE_LIMIT_UNAVAILABLE` | 503 | rate-limit 저장소 응답 없음 |",
|
||||
];
|
||||
const SECTIONS: Sections = { "2": [T2A, T2B], "4": [T4] };
|
||||
const ANSWERS: readonly Answer[] = [
|
||||
{ section: "2", code: "IDEMPOTENT_IN_FLIGHT", status: 409 },
|
||||
{ section: "2", code: "IDEMPOTENCY_COMPLETION_UNKNOWN", status: 503 },
|
||||
{ section: "4", code: "REQUEST_TIMEOUT", status: 503 },
|
||||
];
|
||||
const NOT_COPIED = [
|
||||
{ section: "4", code: "RATE_LIMIT_UNAVAILABLE", reason: "fixture" },
|
||||
];
|
||||
|
||||
function contractDocument(sections: Sections): string {
|
||||
return [
|
||||
"# HTTP wire 계약",
|
||||
"",
|
||||
"## 1. Envelope",
|
||||
"",
|
||||
"| 응답 | 키 |",
|
||||
"| --- | --- |",
|
||||
"| 성공 | `data` |",
|
||||
"",
|
||||
"## 2. 멱등성 응답",
|
||||
"",
|
||||
...(sections["2"]?.[0] ?? []),
|
||||
"",
|
||||
"### 저장소가 응답하지 않을 때",
|
||||
"",
|
||||
...(sections["2"]?.[1] ?? []),
|
||||
"",
|
||||
"## 4. web 전용 오류 코드",
|
||||
"",
|
||||
...(sections["4"]?.[0] ?? []),
|
||||
"",
|
||||
"## 5. 바꿀 때",
|
||||
"",
|
||||
"- 표를 고치면 짝 프론트에 알린다.",
|
||||
"",
|
||||
].join("\n");
|
||||
}
|
||||
|
||||
const directories: string[] = [];
|
||||
afterEach(async () => {
|
||||
await Promise.all(
|
||||
directories.splice(0).map((directory) => rm(directory, { recursive: true, force: true })),
|
||||
);
|
||||
});
|
||||
|
||||
function git(cwd: string, ...args: string[]): string {
|
||||
const result = spawnSync("git", args, {
|
||||
cwd,
|
||||
encoding: "utf8",
|
||||
env: {
|
||||
...process.env,
|
||||
GIT_AUTHOR_NAME: "drift-fixture",
|
||||
GIT_AUTHOR_EMAIL: "drift-fixture@localhost",
|
||||
GIT_COMMITTER_NAME: "drift-fixture",
|
||||
GIT_COMMITTER_EMAIL: "drift-fixture@localhost",
|
||||
},
|
||||
});
|
||||
if (result.error || result.status !== 0) {
|
||||
throw new Error(`fixture git ${args[0]} failed: ${result.stderr || result.error?.message}`);
|
||||
}
|
||||
return result.stdout.trim();
|
||||
}
|
||||
|
||||
async function commitDocument(backend: string, text: string, message: string): Promise<string> {
|
||||
await mkdir(path.join(backend, "docs/web"), { recursive: true });
|
||||
await writeFile(path.join(backend, "docs/web/http-contract.md"), text);
|
||||
git(backend, "add", "--all");
|
||||
git(backend, "commit", "--quiet", "--no-gpg-sign", "--no-verify", "-m", message);
|
||||
return git(backend, "rev-parse", "HEAD");
|
||||
}
|
||||
|
||||
async function drift(
|
||||
options: Readonly<{
|
||||
answers?: readonly Answer[];
|
||||
excerpt?: Sections;
|
||||
notCopied?: typeof NOT_COPIED;
|
||||
/** The document of a backend commit after the pin. */
|
||||
head?: string;
|
||||
/** Where the script looks for the backend instead of the fake one. */
|
||||
backend?: string;
|
||||
flags?: readonly string[];
|
||||
}> = {},
|
||||
) {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "drift-frontend-"));
|
||||
const backend = await mkdtemp(path.join(tmpdir(), "drift-backend-"));
|
||||
directories.push(root, backend);
|
||||
git(backend, "init", "--quiet", "--initial-branch=fixture");
|
||||
const commit = await commitDocument(backend, contractDocument(SECTIONS), "pinned");
|
||||
if (options.head !== undefined) await commitDocument(backend, options.head, "after the pin");
|
||||
|
||||
const source = {
|
||||
repository: "clean-architecture-backend-template",
|
||||
commit,
|
||||
document: "docs/web/http-contract.md",
|
||||
};
|
||||
const write = async (file: string, value: unknown) => {
|
||||
await mkdir(path.dirname(path.join(root, file)), { recursive: true });
|
||||
await writeFile(path.join(root, file), `${JSON.stringify(value, null, 2)}\n`);
|
||||
};
|
||||
await write("config/contracts/backend-contract-pin.json", {
|
||||
schemaVersion: 1,
|
||||
backend: { ...source, sectionsCompared: ["1", "2", "4"] },
|
||||
frontend: {
|
||||
contractDocument: "docs/architecture/backend-api-and-server-state-contract.md",
|
||||
contractSections: ["4.1", "6", "6.1"],
|
||||
readers: ["src/adapters/http/backend-envelope.ts"],
|
||||
},
|
||||
tables: {
|
||||
idempotencyAnswers: "config/contracts/backend-idempotency-answers.json",
|
||||
backendExcerpt: "config/contracts/backend-http-contract-excerpt.json",
|
||||
},
|
||||
notCopied: options.notCopied ?? NOT_COPIED,
|
||||
owner: "fixture",
|
||||
comparedOn: "2026-11-05",
|
||||
});
|
||||
await write("config/contracts/backend-idempotency-answers.json", {
|
||||
schemaVersion: 1,
|
||||
source,
|
||||
answers: (options.answers ?? ANSWERS).map((answer) => ({
|
||||
...answer,
|
||||
refusedBeforeWrite: false,
|
||||
sameKeyResend: true,
|
||||
})),
|
||||
});
|
||||
await write("config/contracts/backend-http-contract-excerpt.json", {
|
||||
schemaVersion: 1,
|
||||
source,
|
||||
sections: options.excerpt ?? SECTIONS,
|
||||
});
|
||||
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[
|
||||
path.resolve("scripts/check-backend-contract-drift.ts"),
|
||||
"--backend",
|
||||
options.backend ?? backend,
|
||||
...(options.flags ?? []),
|
||||
],
|
||||
{ cwd: root, encoding: "utf8" },
|
||||
);
|
||||
return {
|
||||
status: result.status,
|
||||
stdout: result.stdout,
|
||||
stderr: result.stderr,
|
||||
readExcerpt: async () =>
|
||||
JSON.parse(
|
||||
await readFile(path.join(root, "config/contracts/backend-http-contract-excerpt.json"), "utf8"),
|
||||
) as { sections: Sections },
|
||||
};
|
||||
}
|
||||
|
||||
describe("check:backend-contract-drift (1105/07-01)", () => {
|
||||
it("passes when the excerpt and the answer table match the pinned document", async () => {
|
||||
const result = await drift();
|
||||
|
||||
expect(result.stderr).toBe("");
|
||||
expect(result.status).toBe(0);
|
||||
});
|
||||
|
||||
it("fails when an answer's status is not the pinned document's", async () => {
|
||||
const result = await drift({
|
||||
answers: ANSWERS.map((answer) =>
|
||||
answer.code === "IDEMPOTENCY_COMPLETION_UNKNOWN" ? { ...answer, status: 500 } : answer,
|
||||
),
|
||||
});
|
||||
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"answer 500 IDEMPOTENCY_COMPLETION_UNKNOWN is not a row of the pinned document's §2",
|
||||
);
|
||||
});
|
||||
|
||||
it("fails when the excerpt is not the pinned document's, even if the answers follow it", async () => {
|
||||
const edited = T2B.map((line) => line.replace("| 503 |", "| 500 |"));
|
||||
const result = await drift({
|
||||
excerpt: { ...SECTIONS, "2": [T2A, edited] },
|
||||
answers: ANSWERS.map((answer) =>
|
||||
answer.code === "IDEMPOTENCY_COMPLETION_UNKNOWN" ? { ...answer, status: 500 } : answer,
|
||||
),
|
||||
});
|
||||
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"excerpt differs from the pinned document: §2 -| 결과 불명 | 500 |",
|
||||
);
|
||||
expect(result.stderr).toContain(
|
||||
"excerpt differs from the pinned document: §2 +| 결과 불명 | 503 |",
|
||||
);
|
||||
});
|
||||
|
||||
it("fails on a row of the pinned document neither copied nor listed as not copied", async () => {
|
||||
const result = await drift({ notCopied: [] });
|
||||
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(
|
||||
"§4 503 RATE_LIMIT_UNAVAILABLE is neither in the answer table nor in the pin's notCopied",
|
||||
);
|
||||
});
|
||||
|
||||
// D6g in the 2026-11-05 review: the backend changes a copied row after the pin.
|
||||
it("fails on a copied row the backend changed after the pin", async () => {
|
||||
const result = await drift({
|
||||
head: contractDocument({
|
||||
...SECTIONS,
|
||||
"2": [T2A, T2B.map((line) => line.replace("| 503 |", "| 500 |"))],
|
||||
}),
|
||||
});
|
||||
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("| 결과 불명 | 500 |");
|
||||
});
|
||||
|
||||
it("does not pass without a backend checkout", async () => {
|
||||
const result = await drift({ backend: path.join(tmpdir(), "no-such-backend-checkout") });
|
||||
|
||||
expect(result.status).toBe(2);
|
||||
expect(result.stderr).toContain("not compared");
|
||||
});
|
||||
|
||||
it("writes the excerpt from the pinned document with --write-excerpt", async () => {
|
||||
const result = await drift({
|
||||
excerpt: { "2": [T2A], "4": [T4.slice(0, 3)] },
|
||||
flags: ["--write-excerpt"],
|
||||
});
|
||||
|
||||
expect(result.stderr).toBe("");
|
||||
expect(result.status).toBe(0);
|
||||
expect((await result.readExcerpt()).sections).toEqual(SECTIONS);
|
||||
});
|
||||
});
|
||||
@@ -3,6 +3,10 @@ import { readFileSync } from "node:fs";
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import {
|
||||
answerTableProblems,
|
||||
excerptAnswerRows,
|
||||
} from "../../scripts/lib/backend-contract-excerpt.ts";
|
||||
import {
|
||||
envelopeFailureEffect,
|
||||
invitesKeyedResend,
|
||||
@@ -17,6 +21,11 @@ import {
|
||||
* that copy, in both directions. When the backend adds or changes an answer,
|
||||
* the copy changes with the pin and this test says which frontend verdict has
|
||||
* to follow.
|
||||
*
|
||||
* 1105/07-01. The answer table is also held to the backend's own table rows,
|
||||
* copied word for word at the pin (`tables.backendExcerpt`), so a mistyped
|
||||
* status or a row left out fails here without a backend checkout.
|
||||
* `check:backend-contract-drift` holds that copy to the backend document.
|
||||
*/
|
||||
const COMMIT = /^[0-9a-f]{40}$/u;
|
||||
|
||||
@@ -38,7 +47,22 @@ const pinSchema = z
|
||||
readers: z.array(z.string().min(1)).min(1),
|
||||
})
|
||||
.strict(),
|
||||
tables: z.object({ idempotencyAnswers: z.string().min(1) }).strict(),
|
||||
tables: z
|
||||
.object({
|
||||
idempotencyAnswers: z.string().min(1),
|
||||
backendExcerpt: z.string().min(1),
|
||||
})
|
||||
.strict(),
|
||||
// Rows of the compared sections the answer table leaves out, each with why.
|
||||
notCopied: z.array(
|
||||
z
|
||||
.object({
|
||||
section: z.string().min(1),
|
||||
code: z.string().regex(/^[A-Z0-9_]{1,64}$/u),
|
||||
reason: z.string().min(1),
|
||||
})
|
||||
.strict(),
|
||||
),
|
||||
owner: z.string().min(1),
|
||||
comparedOn: z.string().regex(/^\d{4}-\d{2}-\d{2}$/u),
|
||||
})
|
||||
@@ -79,6 +103,27 @@ const table = answersSchema.parse(
|
||||
JSON.parse(readFileSync(pin.tables.idempotencyAnswers, "utf8")),
|
||||
);
|
||||
|
||||
const excerptSchema = z
|
||||
.object({
|
||||
schemaVersion: z.literal(1),
|
||||
source: z
|
||||
.object({
|
||||
repository: z.string().min(1),
|
||||
commit: z.string().regex(COMMIT),
|
||||
document: z.string().min(1),
|
||||
})
|
||||
.strict(),
|
||||
// Section number → its tables, each the `|` lines as the backend wrote them.
|
||||
sections: z.record(
|
||||
z.string().regex(/^\d+$/u),
|
||||
z.array(z.array(z.string().startsWith("|")).min(2)).min(1),
|
||||
),
|
||||
})
|
||||
.strict();
|
||||
const excerpt = excerptSchema.parse(
|
||||
JSON.parse(readFileSync(pin.tables.backendExcerpt, "utf8")),
|
||||
);
|
||||
|
||||
/**
|
||||
* The refusal-table codes that come from the frontend's own reading of the
|
||||
* backend code (contract 6.1), not from the backend's answer table.
|
||||
@@ -94,9 +139,30 @@ describe("paired backend contract pin", () => {
|
||||
commit: pin.backend.commit,
|
||||
document: pin.backend.document,
|
||||
});
|
||||
expect(excerpt.source).toEqual(table.source);
|
||||
expect(pin.frontend.readers).toContain("src/adapters/http/backend-envelope.ts");
|
||||
});
|
||||
|
||||
// 1105/07-01. Each answer is a row of the backend table it names, with the
|
||||
// same code and status, and each backend row is either copied or listed in
|
||||
// `notCopied` with a reason. The excerpt covers the sections the answers
|
||||
// come from, and the parser finds rows in each.
|
||||
it("copies the answers from the backend table rows at the pin", () => {
|
||||
const sections = [...new Set(table.answers.map((answer) => answer.section))].sort();
|
||||
expect(Object.keys(excerpt.sections).sort()).toEqual(sections);
|
||||
expect(sections.every((section) => pin.backend.sectionsCompared.includes(section))).toBe(
|
||||
true,
|
||||
);
|
||||
const rows = excerptAnswerRows(excerpt.sections);
|
||||
for (const section of sections) {
|
||||
expect(
|
||||
rows.some((row) => row.section === section),
|
||||
`no answer row read from §${section}`,
|
||||
).toBe(true);
|
||||
}
|
||||
expect(answerTableProblems(table.answers, pin.notCopied, rows)).toEqual([]);
|
||||
});
|
||||
|
||||
it("copies each backend answer once", () => {
|
||||
const keys = table.answers.map((answer) => `${answer.status} ${answer.code}`);
|
||||
expect(new Set(keys).size).toBe(keys.length);
|
||||
|
||||
Reference in New Issue
Block a user