fix(docs): 현재 계약 문서의 경로·명령·게이트 ID를 검사한다 (14-05)
문제: docs/README.md 1절은 현재 계약 문서를 "게이트가 검사한다"고
소개하지만 verify:documentation은 route ID 목록, 빌드 변수, src 구조,
그리고 repo 밖 2026-07-18 diagram 리뷰 기록의 두 사본끼리의 일치만 본다.
diagram 검사는 구조가 바뀌어도 늘 통과한다. 그래서 이미 drift가 쌓였다.
README 라우트 표에 /examples/platform이 없고 언어 선택기를 적지 않는다.
design-tokens.md는 theme.css를 SSOT라고 하고 3계층 토큰과
check:design-system 규칙 4개를 모른다. compatibility.md의 줄 번호가
어긋났다. ledger는 옮겨진 tests/unit/ci-artifact-contract.test.ts를
설명 없이 가리킨다. 또 README와 수동 접근성 체크리스트가 route ID를
모두 나열해야 해서, 기능을 하나 더할 때마다 템플릿 소유 문서 두 개를
고쳐야 한다(다운스트림 동기화 충돌 지점).
고른 방법: 리뷰 5.3의 (b)+(d)와 오케스트레이터 결정 3.
- route ID 나열을 지운다. verify:documentation은 설치된 라우트마다
artifacts/tests/a11y-manual/<ROUTE_ID>.md가 있는지 보고, 없으면 route
ID를 적고 실패한다. README·체크리스트에는 목록 대신 정본 위치
(ROUTE_REGISTRY, 기록 폴더)를 적는다. README 라우트 표도 같은 이유로
starter-experience.md처럼 ROUTE_REGISTRY와 /examples/platform을
가리키게 바꾼다.
- docs/README.md와 그 1절이 링크한 문서(폴더 링크는 안의 .md 전부)에
적힌 repo 경로·링크·package script·FE-GATE ID가 있는지 검사한다.
문서 목록은 1절 링크에서 읽으므로 손으로 둔 목록이 없다. 문서는
작업 폴더에서 읽고, 존재 여부·script·게이트는 14-03 검사처럼 이 repo
기준으로 본다. 예외는 셋이다: git이 무시하는 생성 산출물(.gitignore에서
읽는다), README "Files you can delete after copying"의 이력 중 지워진
것, 아직 없는 src/adapters/web-worker(규칙이 자리를 잡아 둠). 은퇴한
FE-GATE-016은 RETIRED_GATE_IDS에서 읽는다. CHANGELOG는 지난 상태를
적는 문서라 뺀다.
- compatibility.md의 줄 번호를 심볼 이름으로 바꾸고, design-tokens.md에
3계층 파일과 UI-01·02·03·05 규칙을 적고, ledger의 옮겨진 테스트
경로를 현재 위치로 고치고 그 사실을 머리에 적는다.
- diagram 검사의 실패 이름을 "2026-07-18 diagram review copy …"로 바꾸고
ci-quality-gates.md에 원본이 repo 밖이라 늘 통과한다고 적는다.
- documentation-review.json에 documentReferences를 더한다. routeScope는
모양을 유지하고 기록 폴더 한 항목으로 쓴다.
버린 대안: 라우트 표를 route registry와 대조 — 기능마다 README를
고치게 되어 결정 3의 이유와 충돌한다. 문서 전체 내용 검사(c) — 자연어
주장은 기계로 검사할 수 없다. 생성 산출물 제외를 접두어 목록으로 —
artifacts/ 안의 커밋된 기록까지 빠지고 목록이 따로 낡는다. git
check-ignore 호출 — git이 없는 복사본에서 모든 생성 경로가 실패한다.
위험·한계:
- 경로는 백틱 안의 "최상위 항목/…" 또는 "문서 옆 항목/…" 꼴과 마크다운
링크만 잡는다. 슬래시 없는 파일 이름, 자리표시자(<id>, *, {…})가 든
경로, 심볼 이름이 맞는지는 보지 않는다.
- script는 "corepack pnpm x", "`pnpm x`", 그리고 기존 script 접두어로
시작하는 "`접두:이름`"만 본다.
- 다운스트림 영향: 참조 기능을 지운 복사본은 그 파일을 가리키는 현재
계약 문서(README, compatibility.md, starter-experience.md,
manual-checklist.md)를 고쳐야 이 게이트를 통과한다. 이력 폴더를 지운
복사본은 그대로 통과한다.
- 수동 기록 파일의 존재는 FE-GATE-009(review:a11y-manual --format-only)도
본다. 이 검사는 문서 목록 대신 같은 사실을 문서 게이트에서 보는 것이다.
- CHANGELOG.md:11의 해시 문장(리뷰 (마))은 이 커밋에서 고치지 않는다.
검증:
- RED: 새 테스트를 기준(61baf96) 스크립트에 돌리면 14개 중 9개 실패.
기록 파일을 지워도 통과했고, README·체크리스트에서 route ID를 지우면
"failed: route scope"로 실패했고, 경로·script·게이트 ID 변이는 모두
통과했다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 14개 통과. 고치기 전 문서에
돌리면 ledger의 옮겨진 테스트 경로 두 개를 잡았다.
- 변이: src/contracts/routes.ts에 라우트를 하나 더하면 README·체크리스트를
고치지 않아도 "artifacts/tests/a11y-manual/ has no record for route IDs:
EXAMPLES_DRIFT"로만 실패하고, 기록 파일을 더하면 통과했다(되돌림).
- 회귀: tests/unit 전체(fixture-node-modules 제외) 173파일 2505개 통과.
deletable-history-documents 통과. tsc(node, test) 통과. 바꾼 ts 파일
eslint 통과. check-ci-contract, generate-artifact-schemas --check,
generate-ci-workflow --check, check-adapter-inventory 통과.
check-remediation-ledger는 기준 커밋과 같은 4건으로 실패(게이트 밖,
이번 변경과 무관).
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
This commit is contained in:
@@ -82,16 +82,14 @@ list is in [`docs/operations/ci-quality-gates.md`](docs/operations/ci-quality-ga
|
||||
## Included starter experience
|
||||
|
||||
The default build mounts a domain-neutral application shell with a header,
|
||||
responsive sidebar, route focus management, session integration status, and a
|
||||
persistent `system` / `light` / `dark` theme selector.
|
||||
responsive sidebar, route focus management, session integration status, a
|
||||
persistent `system` / `light` / `dark` theme selector, and a language selector.
|
||||
|
||||
| Route | Purpose |
|
||||
| --- | --- |
|
||||
| `/` | implementation readiness and starter links |
|
||||
| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
|
||||
| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
|
||||
| `/examples/auth` | reactive external-auth integration seam |
|
||||
| `/examples/reference-resources` | removable, session-required reference feature |
|
||||
The route list is `ROUTE_REGISTRY` (`src/features/installed-feature-contracts.ts`):
|
||||
the platform routes of `src/contracts/routes.ts` plus the routes of every
|
||||
installed feature, the removable reference feature included. The platform
|
||||
overview page (`/examples/platform`) shows the composed list at runtime, so
|
||||
this README keeps no copy of it and adding a feature does not edit it.
|
||||
|
||||
`AUTH_MODE=demo` is credential-free and accepted only in local/development
|
||||
environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
|
||||
@@ -295,12 +293,10 @@ corepack pnpm exec playwright install --with-deps chromium firefox webkit
|
||||
Two gates intentionally need external evidence:
|
||||
|
||||
- `review:a11y-manual` (release gate FE-GATE-028) needs a signed human
|
||||
keyboard/focus/screen-reader review for all ten registered routes: `APP_HOME`, `EXAMPLES_PLATFORM`,
|
||||
`EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`, `NOT_FOUND`,
|
||||
`REFERENCE_RESOURCE_LIST`, `REFERENCE_RESOURCE_DETAIL`,
|
||||
`REFERENCE_RESOURCE_FORM` and `REFERENCE_RESOURCE_STATUS`.
|
||||
`verify:documentation` derives that list from the route registry and fails if
|
||||
this paragraph falls behind it. The merge gate FE-GATE-009 runs only
|
||||
keyboard/focus/screen-reader review of every registered route, one record
|
||||
per route at `artifacts/tests/a11y-manual/<ROUTE_ID>.md`. The routes are
|
||||
`ROUTE_REGISTRY`; `verify:documentation` fails, naming the route ID, when a
|
||||
registered route has no record. The merge gate FE-GATE-009 runs only
|
||||
`review:a11y-manual -- --format-only`, which checks that every route record
|
||||
keeps the template's fields, reviewed or still pending.
|
||||
- `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
|
||||
|
||||
+8
-1
@@ -37,11 +37,18 @@ README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어
|
||||
- 디자인 토큰과 수동 접근성 검토: [`styling/design-tokens.md`](styling/design-tokens.md), [`accessibility/manual-checklist.md`](accessibility/manual-checklist.md)
|
||||
- 버전별 변경: [`../CHANGELOG.md`](../CHANGELOG.md)
|
||||
|
||||
`verify:documentation`은 이 파일과 이 절에서 링크한 문서(폴더 링크는 그 안의 `.md` 전부)에
|
||||
적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지 검사한다. `CHANGELOG.md`는
|
||||
지난 상태를 적는 문서라 빼고, git이 무시하는 생성 산출물과 복사한 프로젝트가 지운 작업 이력은
|
||||
없어도 된다. 설명·수치가 코드와 맞는지는 검사하지 않는다. 규칙과 예외의 정본은
|
||||
`scripts/verify-documentation-readiness.ts`다.
|
||||
|
||||
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
|
||||
|
||||
| 파일 | 읽는 명령 |
|
||||
|---|---|
|
||||
| `architecture/review-ledger.json`, `architecture/review-evidence.md`, `accessibility/manual-checklist.md` | `verify:documentation` (FE-GATE-017) |
|
||||
| 이 파일, `architecture/review-ledger.json`, `architecture/review-evidence.md` | `verify:documentation` (FE-GATE-017) |
|
||||
| repo 루트의 `artifacts/tests/a11y-manual/` 라우트별 기록 | `verify:documentation` (FE-GATE-017), `review:a11y-manual` (FE-GATE-009, FE-GATE-028) |
|
||||
| `reviews/adapters/INVENTORY.md` | `check:adapter-inventory` (FE-GATE-010) |
|
||||
| `operations/adapter-remediation-ledger.md`, `operations/adapter-remediation-dispositions.json` | `check:remediation-ledger` (게이트 밖. 이유는 `config/ci/ungated-scripts.json`) |
|
||||
|
||||
|
||||
@@ -1,14 +1,12 @@
|
||||
# Manual accessibility review checklist
|
||||
|
||||
Automated axe checks do not establish WCAG conformance. A human reviewer must
|
||||
review all ten route records in `artifacts/tests/a11y-manual/` against one
|
||||
release candidate and sign them. The required scope is derived from the route
|
||||
registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
|
||||
`EXAMPLES_AUTH`, `NOT_FOUND`, `REFERENCE_RESOURCE_LIST`,
|
||||
`REFERENCE_RESOURCE_DETAIL`, `REFERENCE_RESOURCE_FORM` and
|
||||
`REFERENCE_RESOURCE_STATUS`. Copy the template fields exactly; the gate rejects
|
||||
blank identity/timestamp/signature fields, pending verdicts, mismatched release
|
||||
IDs, or missing routes.
|
||||
review every route record in `artifacts/tests/a11y-manual/` against one
|
||||
release candidate and sign them. The required scope is the route registry
|
||||
(`ROUTE_REGISTRY` in `src/features/installed-feature-contracts.ts`): one
|
||||
record per route, named `<ROUTE_ID>.md`. Copy the template fields exactly; the
|
||||
gate rejects blank identity/timestamp/signature fields, pending verdicts,
|
||||
mismatched release IDs, or missing routes.
|
||||
|
||||
The signed review is the release gate FE-GATE-028 (`review:a11y-manual`), so
|
||||
it is required once per release candidate, not on every merge. The merge gate
|
||||
@@ -16,11 +14,11 @@ FE-GATE-009 runs `review:a11y-manual -- --format-only`: each record must keep
|
||||
the fields below with `pending`, `pass` or `not-applicable (<reason>)` verdicts,
|
||||
and a record marked `reviewed` must be complete.
|
||||
|
||||
This list is not maintained by hand: `verify:documentation` compares it against
|
||||
the installed route registry and fails when a registered route is absent. It
|
||||
said six routes while ten were registered, which put the platform overview and
|
||||
the three reference-resource screens outside the declared manual review scope
|
||||
without anyone deciding they should be.
|
||||
This document keeps no route list. A list here once said six routes while ten
|
||||
were registered, and keeping it current made every new feature edit this file.
|
||||
Instead `verify:documentation` fails, naming the route ID, when a registered
|
||||
route has no record file. A new route starts from a copy of a pending record
|
||||
with its title and `Route ID` changed.
|
||||
|
||||
Allowed item verdicts:
|
||||
|
||||
|
||||
@@ -20,15 +20,15 @@ reader that accepts it must ship before any writer sends it.
|
||||
|
||||
| Boundary | Reader policy | Adding a field or value | Code |
|
||||
|---|---|---|---|
|
||||
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` |
|
||||
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` |
|
||||
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` |
|
||||
| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` |
|
||||
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` |
|
||||
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` |
|
||||
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` |
|
||||
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` |
|
||||
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:148-150` |
|
||||
| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `runtimeConfigV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `capabilityOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `featureOverrideArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| Release manifest V2 | strict object | breaking | `releaseManifestV2ArtifactSchema` in `src/contracts/release-artifacts.ts` |
|
||||
| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `src/adapters/http/schema-registry.ts` |
|
||||
| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `referenceResourceDtoSchema` in `src/features/reference-feature/contracts/reference-schemas.ts` |
|
||||
| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `decodeUnsafe` in `src/adapters/realtime/event-codec.ts` |
|
||||
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` |
|
||||
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` |
|
||||
|
||||
`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids
|
||||
vary per build because each downstream project installs its own features, and
|
||||
@@ -39,7 +39,7 @@ addition.
|
||||
|
||||
## Schema change classifier and FE-GATE-014
|
||||
|
||||
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers
|
||||
`classifyObjectSchemaChange` (`src/contracts/compatibility.ts`) answers
|
||||
for a reader built against `before`. It is fail-closed: only a new property
|
||||
under a reader without `additionalProperties: false` is `additive`. A removed
|
||||
or changed property (type, enum, nullable, format, ...), a different required
|
||||
|
||||
@@ -5,6 +5,11 @@
|
||||
>
|
||||
> Plan: [2026-08-13 adapter remediation](../superpowers/plans/2026-08-13-adapter-remediation.md).
|
||||
> Baseline revision: `develop` / `4dc033cf33a5b6173bbf960d5eb464a406dc4c92`.
|
||||
>
|
||||
> Test paths are given at their current location. Two suites moved after
|
||||
> these runs: `ci-artifact-contract.test.ts` from `tests/unit/` to
|
||||
> `tests/system/ci-runner/`, and `provider-guardian-transaction.test.ts` from
|
||||
> `tests/unit/` to `tests/integration/`.
|
||||
|
||||
## Containment state (plan Task 1, Step 1)
|
||||
|
||||
@@ -44,7 +49,7 @@ Captured on the baseline revision before any source change.
|
||||
|
||||
### `test:unit` failure attribution
|
||||
|
||||
The single failing file is `tests/unit/ci-artifact-contract.test.ts`. All 19 failures come from
|
||||
The single failing file is `tests/system/ci-runner/ci-artifact-contract.test.ts`. All 19 failures come from
|
||||
child-process, cgroup, and filesystem-permission behavior of the sandboxed execution
|
||||
environment, not from adapter code. Verbatim causes recorded from the run log:
|
||||
|
||||
@@ -208,7 +213,7 @@ No finding remains `NOT_STARTED`.
|
||||
|
||||
| Gate | Status | Attribution |
|
||||
| --- | --- | --- |
|
||||
| `tests/unit/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 failed | Identical to the baseline capture. Sandbox child-process, cgroup and `/tmp` permission behavior; unrelated to adapters. Count did not change across any task. |
|
||||
| `corepack pnpm test:browser-capabilities` (webkit) | 6 failed / 24 passed | WebKit cannot launch: missing `libevent-2.1-7t64` and `libavif16`. Chromium passes. **UNVERIFIED**, not PASS. |
|
||||
| `corepack pnpm test:browser-file-storage-removal` | exit 1 | The reduced-removal-fixture prunes the CI contract to 77/89/102 while `scripts/contracts/ci-gates.ts:481` demands exactly 81/93/105. That file, the CI contract and `scripts/lib/removal-fixture.ts` are **unchanged since the baseline revision** (`git diff --name-only 4dc033c..HEAD` outside `src/`, `tests/` and `docs/` lists only the two Service Worker build scripts), so this is pre-existing, not a regression from this work. |
|
||||
| `corepack pnpm test:realtime-removal` | exit 1 | Same pre-existing reduced-fixture arithmetic. |
|
||||
@@ -336,8 +341,8 @@ Run on the landed tree. Only what actually passed is claimed as passing.
|
||||
| Gate | Status | Attribution |
|
||||
| --- | --- | --- |
|
||||
| `tests/unit/ci-workflow-generation.test.ts` | 82 failed / 325 passed | Identical on the pre-change baseline (`git stash` comparison). The subprocess gates it spawns cannot run in this sandbox. |
|
||||
| `tests/unit/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/unit/security-followup.test.ts`, `tests/unit/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | fails | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/unit/security-followup.test.ts`, `tests/integration/provider-guardian-transaction.test.ts`, `tests/unit/risk-coverage.test.ts` | flaky under full-suite load | Historical baseline result. All three passed in a fresh process (78 passed together). |
|
||||
|
||||
> Current classification update (2026-09-18): the provider guardian transaction
|
||||
> suite moved to `tests/integration/provider-guardian-transaction.test.ts`.
|
||||
@@ -356,7 +361,7 @@ fixture with a single directory symlink at `<fixture>/node_modules`:
|
||||
- `scripts/lib/removal-fixture.ts`
|
||||
- `scripts/check-supply-chain-provider-fixtures.ts`
|
||||
- `tests/integration/security-followup-archive.test.ts`
|
||||
- `tests/unit/ci-artifact-contract.test.ts`
|
||||
- `tests/system/ci-runner/ci-artifact-contract.test.ts`
|
||||
|
||||
Each fixture then runs `pnpm` inside itself. pnpm does not recognise the modules
|
||||
directory it finds there and purges it; with `CI=true` it does so without a
|
||||
@@ -380,9 +385,9 @@ files above plus the two flaky-under-load ones:
|
||||
| File | Failed | Attribution |
|
||||
| --- | ---: | --- |
|
||||
| `tests/unit/ci-workflow-generation.test.ts` | 82 | Identical on the pre-change baseline (`git stash` comparison). Its subprocess gates cannot run in this sandbox. |
|
||||
| `tests/unit/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/system/ci-runner/ci-artifact-contract.test.ts` | 19 | Unchanged pre-existing sandbox, cgroup and `/tmp` permission behaviour. |
|
||||
| `tests/unit/security-followup.test.ts` | 2 | Passes in isolation. |
|
||||
| `tests/unit/provider-guardian-transaction.test.ts` (historical path; now `tests/integration/provider-guardian-transaction.test.ts`) | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
|
||||
| `tests/integration/provider-guardian-transaction.test.ts` | 1 | Historical baseline: passed in isolation; current suite is classified as process integration. |
|
||||
|
||||
1619 passed / 1723 total, and `tests/unit/removal-fixture.test.ts`,
|
||||
`tests/unit/supply-chain.test.ts` and
|
||||
@@ -465,7 +470,7 @@ forward as if it were green.
|
||||
|
||||
The full `tests/unit` + `tests/integration` run is **1,845 passed / 1,864**,
|
||||
128 of 129 files green. Every one of the 19 failures is in
|
||||
`tests/unit/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
|
||||
`tests/system/ci-runner/ci-artifact-contract.test.ts` and is the pre-existing sandbox,
|
||||
cgroup, RLIMIT and `/tmp` permission behaviour already recorded above — the same
|
||||
file failed identically before this work. No adapter test fails.
|
||||
|
||||
|
||||
@@ -126,11 +126,16 @@ DOCUMENTATION_READY (off-chain)
|
||||
`DOCUMENTATION_READY`(`verify:documentation`)가 검사하는 범위는 좁다
|
||||
(`scripts/verify-documentation-readiness.ts`).
|
||||
|
||||
- diagram 리뷰 ledger(`docs/architecture/review-ledger.json`)와
|
||||
`review-evidence.md`가 같은 경로·해시·점수를 담는지
|
||||
- README와 `docs/accessibility/manual-checklist.md`가 설치된 route ID를 모두
|
||||
적는지
|
||||
- 설치된 라우트마다 수동 접근성 기록 `artifacts/tests/a11y-manual/<ROUTE_ID>.md`가
|
||||
있는지. 없으면 route ID를 적고 실패한다
|
||||
- README가 빌드와 승인 단계가 읽는 환경 변수를 모두 적는지
|
||||
- 입구 문서가 실제 `src` 최상위 폴더와 `.dependency-cruiser.json` 규칙 이름을
|
||||
적는지
|
||||
- `docs/README.md` 1절의 현재 계약 문서에 적힌 repo 경로·링크·package script·
|
||||
FE-GATE ID가 실제로 있는지
|
||||
- 2026-07-18 diagram 리뷰 기록의 두 사본(`docs/architecture/review-ledger.json`,
|
||||
`review-evidence.md`)이 같은 해시·점수를 담는지. 원본 diagram은 repo 밖에
|
||||
있으므로 이 항목은 구조가 바뀌어도 통과한다
|
||||
|
||||
문서의 다른 내용(수치, 목록, 설명)이 코드와 맞는지는 검사하지 않는다(리뷰 14-07).
|
||||
|
||||
|
||||
@@ -1,8 +1,32 @@
|
||||
# Design-token styling contract
|
||||
|
||||
`src/presentation/styles/theme.css` is the styling SSOT. Components consume
|
||||
semantic color, spacing, typography, status, and radius tokens through static
|
||||
classes. `/examples/ui` is the executable token and primitive gallery.
|
||||
Tokens are defined in three layers under `src/presentation/design-system/tokens/`:
|
||||
`primitive.css` holds the raw palette and scales, `semantic.css` maps them to
|
||||
roles (surface, content, border, action, status) and overrides those roles for
|
||||
the dark theme, and `component.css` maps roles to per-component values.
|
||||
`src/presentation/styles/theme.css` only imports the three files and the style
|
||||
files under `src/presentation/styles/theme/`. Components consume semantic
|
||||
color, spacing, typography, status, and radius tokens through static classes.
|
||||
`/examples/ui` is the executable token and primitive gallery.
|
||||
|
||||
## Rules a rebrand must keep
|
||||
|
||||
`check:design-system` (`scripts/check-design-system.ts`) fails when a token
|
||||
edit breaks one of these. The reasons are next to each rule in
|
||||
`scripts/lib/design-system-rules.ts`.
|
||||
|
||||
- UI-01: `--color-focus` has at least 3:1 contrast against every surface a
|
||||
focus ring can sit on, in both themes. Those tokens must resolve to opaque
|
||||
`oklch()` values so the contrast can be computed.
|
||||
- UI-02: `color-mix()` mixes in `oklab`, never in a hue-based space.
|
||||
- UI-03: every component token is read by some style.
|
||||
- UI-05: `--font-sans` starts with a generic family or one the repository
|
||||
ships with `@font-face`.
|
||||
|
||||
The same check requires the token names in `token-contract.ts`, the dark
|
||||
overrides of the core semantic roles, a forced-colors fallback in
|
||||
`component.css`, no raw palette values outside the token files, and no direct
|
||||
headless-library imports.
|
||||
|
||||
## Theme contract
|
||||
|
||||
|
||||
@@ -1393,9 +1393,9 @@ export const documentationReviewArtifactSchema = z
|
||||
.strict(),
|
||||
reportDigestValid: z.boolean(),
|
||||
/**
|
||||
* The declared review scope, derived from the installed route registry
|
||||
* rather than read off a sentence. Both scope documents claimed six routes
|
||||
* while ten were registered.
|
||||
* The manual accessibility review scope: the installed routes that have no
|
||||
* record file under artifacts/tests/a11y-manual/. It is derived from the
|
||||
* route registry, not read off a document (1101/14-05).
|
||||
*/
|
||||
routeScope: z.array(
|
||||
z
|
||||
@@ -1421,6 +1421,18 @@ export const documentationReviewArtifactSchema = z
|
||||
})
|
||||
.strict(),
|
||||
).min(1),
|
||||
// 1101/14-05: repo paths, package scripts and gate IDs that the current
|
||||
// contract documents (docs/README.md §1) name but that do not exist.
|
||||
documentReferences: z.array(
|
||||
z
|
||||
.object({
|
||||
path: nonEmptyString,
|
||||
missingPaths: z.array(nonEmptyString),
|
||||
missingScripts: z.array(nonEmptyString),
|
||||
unknownGateIds: z.array(nonEmptyString),
|
||||
})
|
||||
.strict(),
|
||||
).min(1),
|
||||
results: z.array(
|
||||
z
|
||||
.object({
|
||||
@@ -1466,9 +1478,15 @@ export const documentationReviewArtifactSchema = z
|
||||
entry.unknownFolders.length === 0 &&
|
||||
entry.missingRules.length === 0,
|
||||
) &&
|
||||
artifact.documentReferences.every(
|
||||
(entry) =>
|
||||
entry.missingPaths.length === 0 &&
|
||||
entry.missingScripts.length === 0 &&
|
||||
entry.unknownGateIds.length === 0,
|
||||
) &&
|
||||
artifact.results.every(({ passed }) => passed))
|
||||
) {
|
||||
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure and review results" });
|
||||
context.addIssue({ code: "custom", path: ["passed"], message: "must agree with report digest, documented scope, source structure, document references and review results" });
|
||||
}
|
||||
});
|
||||
|
||||
|
||||
@@ -1,24 +1,22 @@
|
||||
import { access, mkdir, readdir, readFile } from "node:fs/promises";
|
||||
import { existsSync } from "node:fs";
|
||||
import { mkdir, readdir, readFile } from "node:fs/promises";
|
||||
import { dirname, join, matchesGlob, normalize } from "node:path/posix";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.ts";
|
||||
import { RETIRED_GATE_IDS } from "./contracts/ci-gates.ts";
|
||||
import { documentationReviewArtifactSchema } from "./contracts/release-artifacts.ts";
|
||||
import { RUNTIME_OVERRIDES } from "./generate-runtime-config.ts";
|
||||
import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.ts";
|
||||
import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts";
|
||||
|
||||
/**
|
||||
* Documents that state the review scope. The route registry is the source of
|
||||
* truth for what that scope is, so these have to enumerate exactly the
|
||||
* installed routes.
|
||||
*
|
||||
* Both said "six routes" while ten were registered: the four newest — the
|
||||
* platform overview and three reference-resource screens — were outside the
|
||||
* declared manual accessibility scope without anybody deciding they should be.
|
||||
* A hand-typed count drifts silently, so it is derived here instead.
|
||||
* The manual accessibility review scope is one record per installed route.
|
||||
* README and the checklist used to list the route IDs and this script checked
|
||||
* the lists (they had said six routes while ten were registered). That made
|
||||
* every new feature edit two template-owned documents (1101/14-05), so the
|
||||
* documents now name this folder and the record files are what is checked.
|
||||
*/
|
||||
const ROUTE_SCOPE_DOCUMENTS = Object.freeze([
|
||||
"README.md",
|
||||
"docs/accessibility/manual-checklist.md",
|
||||
]);
|
||||
const MANUAL_A11Y_RECORDS = "artifacts/tests/a11y-manual/";
|
||||
|
||||
type DocumentationReview = Readonly<{
|
||||
sourcePath: string;
|
||||
@@ -77,25 +75,13 @@ const reportDigestValid =
|
||||
/^[0-9a-f]{64}$/.test(ledger.evidenceReport.canonicalSha256) &&
|
||||
evidence.includes(ledger.evidenceReport.canonicalSha256);
|
||||
|
||||
const installedRouteIds = Object.values(ROUTE_REGISTRY)
|
||||
.map((route) => route.routeId)
|
||||
.sort();
|
||||
const routeScope = [];
|
||||
for (const path of ROUTE_SCOPE_DOCUMENTS) {
|
||||
let text: string;
|
||||
try {
|
||||
await access(path);
|
||||
text = await readFile(path, "utf8");
|
||||
} catch {
|
||||
routeScope.push({ path, missingRouteIds: [...installedRouteIds], documented: false });
|
||||
continue;
|
||||
}
|
||||
const missingRouteIds = installedRouteIds.filter(
|
||||
(routeId) => !text.includes(routeId),
|
||||
);
|
||||
routeScope.push({ path, missingRouteIds, documented: missingRouteIds.length === 0 });
|
||||
}
|
||||
const routeScopeDocumented = routeScope.every((entry) => entry.documented);
|
||||
const missingRouteIds = MANUAL_A11Y_ROUTE_IDS.filter(
|
||||
(routeId) => !existsSync(`${MANUAL_A11Y_RECORDS}${routeId}.md`),
|
||||
).sort();
|
||||
const routeScope = [
|
||||
{ path: MANUAL_A11Y_RECORDS, missingRouteIds, documented: missingRouteIds.length === 0 },
|
||||
];
|
||||
const routeScopeDocumented = missingRouteIds.length === 0;
|
||||
|
||||
// 13-15. README is where a project learns how to build for production. It
|
||||
// named none of the variables the build and admission read, so each one is
|
||||
@@ -164,16 +150,150 @@ const sourceStructureDocumented = sourceStructure.every(
|
||||
entry.missingRules.length === 0,
|
||||
);
|
||||
|
||||
// 1101/14-05. docs/README.md §1 says the gates check the current contract
|
||||
// documents, while only the checks above did. Every repo path, package script
|
||||
// and FE-GATE ID that the index and the documents its §1 links name must
|
||||
// exist. Documents are read from the working directory; what they name is
|
||||
// looked up in this repository, as for the src structure above.
|
||||
const DOCUMENT_INDEX = "docs/README.md";
|
||||
// Past states are its subject: it names removed scripts and paths on purpose.
|
||||
const UNCHECKED_DOCUMENTS = new Set(["CHANGELOG.md"]);
|
||||
const NOT_CREATED = new Set([
|
||||
// Reserved by generic-worker-has-no-network-or-credentials. The generic CPU
|
||||
// worker is NOT_SELECTED (tsconfig.web-worker.json).
|
||||
"src/adapters/web-worker",
|
||||
]);
|
||||
// pnpm's own commands, which are not package scripts.
|
||||
const PNPM_COMMANDS = new Set(["add", "dlx", "exec", "install", "list", "why"]);
|
||||
|
||||
const rootDirectory = fileURLToPath(repositoryRoot);
|
||||
const exists = (file: string) => existsSync(join(rootDirectory, file));
|
||||
const topLevelEntries = new Set(await readdir(rootDirectory));
|
||||
const scripts = new Set(
|
||||
Object.keys(
|
||||
(JSON.parse(await readFile(join(rootDirectory, "package.json"), "utf8")) as { scripts: Record<string, string> })
|
||||
.scripts,
|
||||
),
|
||||
);
|
||||
const scriptPrefixes = new Set([...scripts].map((name) => name.split(":")[0]));
|
||||
const gateIds = new Set([
|
||||
...(
|
||||
JSON.parse(await readFile(join(rootDirectory, "config/ci/gates.json"), "utf8")) as { gates: { id: string }[] }
|
||||
).gates.map((gate) => gate.id),
|
||||
...RETIRED_GATE_IDS,
|
||||
]);
|
||||
// Generated output is what git ignores, so a document may name it before a
|
||||
// run has written it.
|
||||
const ignorePatterns = (await readFile(join(rootDirectory, ".gitignore"), "utf8").catch(() => ""))
|
||||
.split("\n")
|
||||
.map((line) => line.trim())
|
||||
.filter((line) => line !== "" && !line.startsWith("#"));
|
||||
function generated(file: string): boolean {
|
||||
let ignored = false;
|
||||
for (const line of ignorePatterns) {
|
||||
const pattern = line.replace(/^!/u, "").replace(/^\/|\/$/gu, "");
|
||||
const glob = pattern.includes("/") ? pattern : `**/${pattern}`;
|
||||
if (matchesGlob(file, glob) || matchesGlob(file, `${glob}/**`)) ignored = !line.startsWith("!");
|
||||
}
|
||||
return ignored;
|
||||
}
|
||||
// A copy may delete the history README lists under "Files you can delete
|
||||
// after copying". A path under an entry that is gone is not drift.
|
||||
const deletedHistory = [
|
||||
...(readme.match(/^### Files you can delete after copying\n[\s\S]*?(?=^#)/mu)?.[0] ?? "").matchAll(
|
||||
/^\| (.+?) \|/gmu,
|
||||
),
|
||||
]
|
||||
.flatMap(([, cell = ""]) => [...cell.matchAll(/`([^`]+)`/gu)].map(([, entry = ""]) => entry.replace(/\/$/u, "")))
|
||||
.filter((entry) => !exists(entry));
|
||||
|
||||
// A backtick span is a path when it starts at a top-level entry or at an
|
||||
// entry beside the document; line numbers and anchors are dropped.
|
||||
function namedPath(token: string, document: string): string | null {
|
||||
const candidate = token.replace(/#.*$/u, "").replace(/:\d[\d,:-]*$/u, "");
|
||||
if (!candidate.includes("/") || candidate.startsWith("/") || /[\s*<>{}$()|]|\.\.\./u.test(candidate)) return null;
|
||||
const first = candidate.split("/")[0] ?? "";
|
||||
if (topLevelEntries.has(first)) return candidate;
|
||||
return first !== "." && first !== ".." && exists(join(dirname(document), first))
|
||||
? join(dirname(document), candidate)
|
||||
: null;
|
||||
}
|
||||
function linkedPath(target: string, document: string): string | null {
|
||||
if (/^(?:[a-z][a-z+.-]*:|#)/iu.test(target)) return null;
|
||||
const resolved = normalize(join(dirname(document), target.replace(/#.*$/u, "")));
|
||||
return resolved.startsWith("../") ? null : resolved;
|
||||
}
|
||||
|
||||
const index = await readFile(DOCUMENT_INDEX, "utf8").catch(() => "");
|
||||
const contractDocuments = new Set([DOCUMENT_INDEX]);
|
||||
for (const [, target = ""] of (index.match(/^## 1\.[\s\S]*?(?=^## )/mu)?.[0] ?? "").matchAll(/\]\(([^)#\s]+)\)/gu)) {
|
||||
const linked = normalize(join(dirname(DOCUMENT_INDEX), target));
|
||||
const entries = await readdir(linked).catch(() => null);
|
||||
const documents =
|
||||
entries === null ? [linked] : entries.filter((name) => name.endsWith(".md")).map((name) => join(linked, name));
|
||||
for (const document of documents) if (!UNCHECKED_DOCUMENTS.has(document)) contractDocuments.add(document);
|
||||
}
|
||||
const documentReferences = [];
|
||||
for (const document of contractDocuments) {
|
||||
const text = await readFile(document, "utf8").catch(() => null);
|
||||
if (text === null) {
|
||||
// A linked document that is gone is reported as the index's broken link.
|
||||
if (document === DOCUMENT_INDEX) {
|
||||
documentReferences.push({ path: document, missingPaths: [document], missingScripts: [], unknownGateIds: [] });
|
||||
}
|
||||
continue;
|
||||
}
|
||||
const named = [
|
||||
...[...text.matchAll(/`([^`\n]+)`/gu)].map(([, token = ""]) => namedPath(token, document)),
|
||||
...[...text.matchAll(/\]\(([^)\s]+)\)/gu)].map(([, target = ""]) => linkedPath(target, document)),
|
||||
];
|
||||
const missingPaths = new Set<string>();
|
||||
for (const file of named) {
|
||||
if (file === null) continue;
|
||||
const trimmed = file.replace(/\/$/u, "");
|
||||
if (
|
||||
!exists(trimmed) &&
|
||||
!NOT_CREATED.has(trimmed) &&
|
||||
!generated(trimmed) &&
|
||||
!deletedHistory.some((entry) => trimmed === entry || trimmed.startsWith(`${entry}/`))
|
||||
) {
|
||||
missingPaths.add(trimmed);
|
||||
}
|
||||
}
|
||||
const missingScripts = new Set<string>();
|
||||
for (const [, name = ""] of text.matchAll(/(?:corepack pnpm|`pnpm) (?:run )?([a-z](?:[\w:-]*\w)?)/gu)) {
|
||||
if (!PNPM_COMMANDS.has(name) && !scripts.has(name)) missingScripts.add(name);
|
||||
}
|
||||
for (const [, name = ""] of text.matchAll(/`([a-z][\w-]*:[\w:-]*\w)(?=[` ])/gu)) {
|
||||
if (scriptPrefixes.has(name.split(":")[0]) && !scripts.has(name)) missingScripts.add(name);
|
||||
}
|
||||
documentReferences.push({
|
||||
path: document,
|
||||
missingPaths: [...missingPaths].sort(),
|
||||
missingScripts: [...missingScripts].sort(),
|
||||
unknownGateIds: [...new Set([...text.matchAll(/\bFE-GATE-\d+\b/gu)].map(([id]) => id))]
|
||||
.filter((id) => !gateIds.has(id))
|
||||
.sort(),
|
||||
});
|
||||
}
|
||||
const documentReferencesValid = documentReferences.every(
|
||||
(entry) => entry.missingPaths.length === 0 && entry.missingScripts.length === 0 && entry.unknownGateIds.length === 0,
|
||||
);
|
||||
|
||||
// 1101/14-06. Each failed check is named, so the stderr points at the file to
|
||||
// fix rather than at the diagram review whatever failed.
|
||||
// fix rather than at the diagram review whatever failed. 1101/14-05: the last
|
||||
// two only compare the two hand-kept copies of the 2026-07-18 diagram review;
|
||||
// the diagrams are outside this repository, so they pass whatever the
|
||||
// structure becomes, and their names say so.
|
||||
const failedChecks = [
|
||||
...(routeScopeDocumented ? [] : ["route scope"]),
|
||||
...(missingRuntimeVariables.length === 0 ? [] : ["runtime variables"]),
|
||||
...(sourceStructureDocumented ? [] : ["source structure"]),
|
||||
...(reportDigestValid ? [] : ["review report digest"]),
|
||||
...(documentReferencesValid ? [] : ["document references"]),
|
||||
...(reportDigestValid ? [] : ["2026-07-18 diagram review copy digest"]),
|
||||
...(results.length === 2 && results.every((result) => result.passed)
|
||||
? []
|
||||
: ["diagram reviews"]),
|
||||
: ["2026-07-18 diagram review copies"]),
|
||||
];
|
||||
const passed = failedChecks.length === 0;
|
||||
await mkdir("artifacts/quality", { recursive: true });
|
||||
@@ -192,14 +312,14 @@ await writeValidatedJsonArtifact({
|
||||
routeScopeDocumented,
|
||||
missingRuntimeVariables,
|
||||
sourceStructure,
|
||||
documentReferences,
|
||||
results,
|
||||
passed,
|
||||
},
|
||||
});
|
||||
if (!passed) {
|
||||
for (const entry of routeScope) {
|
||||
if (entry.documented) continue;
|
||||
process.stderr.write(`${entry.path} does not name route IDs: ${entry.missingRouteIds.join(", ")}\n`);
|
||||
if (!routeScopeDocumented) {
|
||||
process.stderr.write(`${MANUAL_A11Y_RECORDS} has no record for route IDs: ${missingRouteIds.join(", ")}\n`);
|
||||
}
|
||||
if (missingRuntimeVariables.length > 0) {
|
||||
process.stderr.write(`README.md does not name: ${missingRuntimeVariables.join(", ")}\n`);
|
||||
@@ -217,6 +337,19 @@ if (!passed) {
|
||||
);
|
||||
}
|
||||
}
|
||||
for (const entry of documentReferences) {
|
||||
if (entry.missingPaths.length > 0) {
|
||||
process.stderr.write(`${entry.path} names paths that do not exist: ${entry.missingPaths.join(", ")}\n`);
|
||||
}
|
||||
if (entry.missingScripts.length > 0) {
|
||||
process.stderr.write(`${entry.path} names package scripts that do not exist: ${entry.missingScripts.join(", ")}\n`);
|
||||
}
|
||||
if (entry.unknownGateIds.length > 0) {
|
||||
process.stderr.write(
|
||||
`${entry.path} names gate IDs that config/ci/gates.json does not define: ${entry.unknownGateIds.join(", ")}\n`,
|
||||
);
|
||||
}
|
||||
}
|
||||
if (!reportDigestValid) {
|
||||
process.stderr.write(
|
||||
`${ledger.evidenceReport.repoPath} does not contain the ledger's canonicalSha256\n`,
|
||||
|
||||
@@ -5,23 +5,25 @@ import path from "node:path";
|
||||
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
const INPUTS = [
|
||||
"README.md",
|
||||
"docs/accessibility/manual-checklist.md",
|
||||
"docs/architecture/review-ledger.json",
|
||||
"docs/architecture/review-evidence.md",
|
||||
"docs/architecture/layers.md",
|
||||
"docs/architecture/overview.md",
|
||||
"docs/architecture/frontend-application-foundation.md",
|
||||
];
|
||||
const INPUTS = ["README.md", "docs", "artifacts/tests/a11y-manual"];
|
||||
|
||||
/** Runs verify:documentation on a copy of its inputs, `mutate` applied to `document`. */
|
||||
async function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
|
||||
/**
|
||||
* Runs verify:documentation on a copy of its inputs, each `changes` entry
|
||||
* applied to its document and every `removed` file deleted. Code facts (src,
|
||||
* package.json, gates.json) are read from this repository, not the copy.
|
||||
*/
|
||||
async function verify(
|
||||
changes: Readonly<Record<string, (text: string) => string>>,
|
||||
removed: readonly string[] = [],
|
||||
) {
|
||||
const root = await mkdtemp(path.join(tmpdir(), "documentation-readiness-"));
|
||||
try {
|
||||
for (const input of INPUTS) await cp(input, path.join(root, input), { recursive: true });
|
||||
const target = path.join(root, document);
|
||||
await writeFile(target, mutate(await readFile(target, "utf8")));
|
||||
for (const [document, mutate] of Object.entries(changes)) {
|
||||
const target = path.join(root, document);
|
||||
await writeFile(target, mutate(await readFile(target, "utf8")));
|
||||
}
|
||||
for (const file of removed) await rm(path.join(root, file));
|
||||
return spawnSync(process.execPath, [path.resolve("scripts/verify-documentation-readiness.ts")], {
|
||||
cwd: root,
|
||||
encoding: "utf8",
|
||||
@@ -31,32 +33,101 @@ async function verifyWithReadme(mutate: (readme: string) => string, document = "
|
||||
}
|
||||
}
|
||||
|
||||
function verifyWithReadme(mutate: (readme: string) => string, document = "README.md") {
|
||||
return verify({ [document]: mutate });
|
||||
}
|
||||
|
||||
// 1101/14-06. A route missing from a scope document used to fail with only
|
||||
// "canonical scoped-review evidence is incomplete", which points at the
|
||||
// diagram review instead of the document to fix.
|
||||
// diagram review instead of the file to fix.
|
||||
describe("verify:documentation failure output (1101/14-06)", () => {
|
||||
it("passes the documents as they are", async () => {
|
||||
const result = await verifyWithReadme((readme) => readme);
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
});
|
||||
|
||||
it("names the document and the route ID it is missing", async () => {
|
||||
const result = await verifyWithReadme((readme) => readme.replaceAll("`EXAMPLES_PLATFORM`", ""));
|
||||
it("names the route ID that has no manual review record", async () => {
|
||||
const result = await verify({}, ["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"]);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("README.md does not name route IDs: EXAMPLES_PLATFORM");
|
||||
expect(result.stderr).toContain("artifacts/tests/a11y-manual/ has no record for route IDs: EXAMPLES_PLATFORM");
|
||||
expect(result.stderr).toMatch(/FAIL_UNVERIFIED \(failed: route scope\)/u);
|
||||
expect(result.stderr).not.toContain("scoped-review evidence");
|
||||
});
|
||||
|
||||
it("names every failed check", async () => {
|
||||
const result = await verifyWithReadme((readme) =>
|
||||
readme.replaceAll("`EXAMPLES_PLATFORM`", "").replaceAll("`RELEASE_TARGET`", ""),
|
||||
const result = await verify(
|
||||
{ "README.md": (readme) => readme.replaceAll("`RELEASE_TARGET`", "") },
|
||||
["artifacts/tests/a11y-manual/EXAMPLES_PLATFORM.md"],
|
||||
);
|
||||
expect(result.stderr).toContain("README.md does not name: RELEASE_TARGET");
|
||||
expect(result.stderr).toMatch(/\(failed: route scope, runtime variables\)/u);
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/14-05. README and the manual checklist listed every route ID, so each
|
||||
// new feature edited two template-owned documents. The scope is the record
|
||||
// files now, and the current contract documents (docs/README.md §1) may only
|
||||
// name paths, package scripts and gate IDs that exist.
|
||||
describe("verify:documentation current contract documents (1101/14-05)", () => {
|
||||
const ROUTE_IDS = /`(?:APP_HOME|EXAMPLES_[A-Z]+|NOT_FOUND|REFERENCE_RESOURCE_[A-Z]+)`/gu;
|
||||
|
||||
it("does not need README or the checklist to list route IDs", async () => {
|
||||
const result = await verify({
|
||||
"README.md": (readme) => readme.replaceAll(ROUTE_IDS, ""),
|
||||
"docs/accessibility/manual-checklist.md": (checklist) => checklist.replaceAll(ROUTE_IDS, ""),
|
||||
});
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
});
|
||||
|
||||
it.each([
|
||||
["README.md", "scripts/verify-documentation-readiness.ts", "scripts/verify-documentation-readyness.ts"],
|
||||
["docs/contracts/compatibility.md", "scripts/check-compatibility.ts", "scripts/check-compatibilty.ts"],
|
||||
// reached through the `operations/` directory link
|
||||
["docs/operations/release-cache-rollback.md", "scripts/lib/hosting-probe.ts", "scripts/lib/hosting-prob.ts"],
|
||||
])("fails when %s names a path that does not exist", async (document, before, after) => {
|
||||
const result = await verifyWithReadme((text) => text.replace(`\`${before}\``, `\`${after}\``), document);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain(`${document} names paths that do not exist: ${after}`);
|
||||
expect(result.stderr).toMatch(/\(failed: document references\)/u);
|
||||
});
|
||||
|
||||
it("fails when docs/README.md links a document that does not exist", async () => {
|
||||
const result = await verifyWithReadme(
|
||||
(index) => index.replace("(architecture/layers.md)", "(architecture/layer.md)"),
|
||||
"docs/README.md",
|
||||
);
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("docs/README.md names paths that do not exist: docs/architecture/layer.md");
|
||||
});
|
||||
|
||||
it("fails when a document names a package script or a gate ID that does not exist", async () => {
|
||||
const result = await verify({
|
||||
"README.md": (readme) => readme.replace("`verify:documentation` fails", "`verify:documentaton` fails"),
|
||||
"docs/README.md": (index) => index.replace("(FE-GATE-017)", "(FE-GATE-099)"),
|
||||
});
|
||||
expect(result.status).toBe(1);
|
||||
expect(result.stderr).toContain("README.md names package scripts that do not exist: verify:documentaton");
|
||||
expect(result.stderr).toContain("docs/README.md names gate IDs that config/ci/gates.json does not define: FE-GATE-099");
|
||||
});
|
||||
|
||||
it("does not ask generated output to exist", async () => {
|
||||
const result = await verifyWithReadme((readme) => `${readme}\nSee \`artifacts/quality/not-generated-yet.json\`.\n`);
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
});
|
||||
|
||||
it("accepts a path under history a copy deleted, and only that", async () => {
|
||||
const naming = (readme: string) => `${readme}\nSee \`docs/retired-notes/plan.md\`.\n`;
|
||||
const deleted = await verifyWithReadme((readme) =>
|
||||
naming(readme).replace("| Path | Contents |\n| --- | --- |\n", "$&| `docs/retired-notes/` | deleted |\n"),
|
||||
);
|
||||
expect(deleted.status, deleted.stderr).toBe(0);
|
||||
|
||||
const missing = await verifyWithReadme(naming);
|
||||
expect(missing.status).toBe(1);
|
||||
expect(missing.stderr).toContain("README.md names paths that do not exist: docs/retired-notes/plan.md");
|
||||
});
|
||||
});
|
||||
|
||||
// 1101/14-03. The entry documents drew a top-level domain layer that does not
|
||||
// exist, left out three of the nine src folders, and layers.md named a
|
||||
// minority of the architecture rules while claiming it could not drift.
|
||||
|
||||
Reference in New Issue
Block a user