Merge lane K: CI, guardrails and release fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# CI quality-gate orchestration
|
||||
|
||||
`config/ci/gates.json` is the executable registry for all 26 gates and the sole
|
||||
`config/ci/gates.json` is the executable registry for all 27 gates and the sole
|
||||
workflow model. `.gitea/workflows/quality-gates.yml` is generated from that
|
||||
strict v2 contract; it is not an independent configuration authority. Update
|
||||
the registry, run `corepack pnpm generate:ci-workflow`, and commit the generated
|
||||
@@ -35,9 +35,20 @@ canonical `check:ci`를 돌린다(`scripts/lib/removal-fixture.ts`의
|
||||
`check:ci`는 `tests/` 아래 테스트 파일(`tests/fixtures` 제외)이 모두 CI 게이트
|
||||
명령에서 실행되는지도 확인한다. 게이트 명령이 닿는 package script의 Vitest 경로와
|
||||
Playwright 설정의 `testDir`를 모아 비교한다(`scripts/lib/ungated-tests.ts`).
|
||||
`run-scale-profile.ts <tier>`를 부르는 명령은 그 tier의 Vitest 경로로 센다.
|
||||
게이트가 돌리지 않는 테스트는 `config/ci/ungated-tests.json`에 이유와 함께 적어야
|
||||
한다. 지금은 `tests/scale`의 규모 테스트 13개만 있다(리뷰 11-03에서 PR tier로
|
||||
옮길 때 뺀다). 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
|
||||
한다. 게이트가 이미 돌리는 파일을 이 목록에 남겨 두면 실패한다.
|
||||
|
||||
규모 테스트는 이렇게 나뉜다(리뷰 11-03, `scripts/scale/run-scale-profile.ts`).
|
||||
|
||||
- `check:scale:pr`은 merge gate `FE-GATE-005`에서 돈다. 개수·상한·증가 모양만
|
||||
검사하므로 CPU가 달라도 결과가 같다. S0~S2 조합 증가 검사가 여기 있다. S0/S1만
|
||||
재면 모든 workload가 noise floor 아래라 이차 누적을 놓친다. 조합 timing은
|
||||
산출물(`artifacts/scale/pr/composition-s0-s2.json`)에 기록만 한다.
|
||||
- `main`·`nightly`·`release` tier는 CI에서 돌지 않는다. 이 tier들은
|
||||
`baseline-regression`을 포함한다. 이 단계는 `config/scale/benchmark-baseline.json`을
|
||||
기록한 CPU 모델에서만 timing을 비교하고, 다른 CPU에서는 `incomplete`로 끝난다.
|
||||
이 tier에만 있는 테스트 6개는 `ungated-tests.json`에 이유와 함께 남아 있다.
|
||||
|
||||
템플릿을 복사해 새 프로젝트를 시작하면 아래 기준선은 템플릿의 값이다. 샘플을
|
||||
지우거나 구조를 바꾸면 프로젝트 값으로 다시 찍는다.
|
||||
@@ -83,6 +94,16 @@ The gate runner checks the same inherited environment names before loading the
|
||||
contract or entering the execution callback, so they cannot reach a child gate
|
||||
process.
|
||||
|
||||
이 셸 파서(`scripts/lib/package-script-graph.ts`)는 리뷰 12-10에서 줄일 수
|
||||
있는지 확인했고 남겼다. workflow 설치의 `--ignore-scripts`와
|
||||
`pnpm-workspace.yaml`의 `allowBuilds`로는 막히지 않는 위험이 있기 때문이다.
|
||||
첫째, 게이트 명령이 직접 설치를 돈다(`verify:lockfile`, 제거 fixture).
|
||||
`allowBuilds`는 pnpm의 의존성 build script만 제한한다. 루트 프로젝트의 install
|
||||
hook과 npm/yarn 설치는 `--ignore-scripts`가 없으면 그대로 돈다. 둘째, 게이트가
|
||||
부르는 이름이 다른 manifest의 script로 바뀌는 경로다(`--prefix`, `--filter`,
|
||||
`-C`, npm pre/post hook, `npm_config_*`). 이것은 설치 옵션과 관계가 없다. 이유는
|
||||
파일 머리 주석에도 있다.
|
||||
|
||||
The dependency graph is:
|
||||
|
||||
```text
|
||||
@@ -94,9 +115,11 @@ MERGE_READY
|
||||
DOCUMENTATION_READY (off-chain)
|
||||
```
|
||||
|
||||
`check:architecture`는 dependency-cruiser 결과와 별도로 Babel parser/Node
|
||||
resolver 기반 `staticImportGraph`를 `artifacts/quality/dependency-report.json`에
|
||||
기록한다. TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
|
||||
`check:architecture`는 Babel parser/Node resolver 기반 `staticImportGraph`를
|
||||
`artifacts/quality/dependency-report.json`에 기록한다. 규칙은
|
||||
`.dependency-cruiser.json`에서 읽지만 dependency-cruiser는 실행하지 않는다.
|
||||
dependency-cruiser 18은 TypeScript 7을 해석하지 못해 0개 모듈을 검사하고
|
||||
통과했다(리뷰 12-05). TS/TSX의 static, dynamic, type, CommonJS 및 JSDoc import를 검사하고,
|
||||
로컬 source import에는 실제 TypeScript 확장자를 요구한다. 실행 source나 로컬
|
||||
specifier에 `.js/.jsx/.mjs/.cjs`가 있거나 unresolved dependency, parse failure,
|
||||
error-severity layer violation, cycle 또는 지원하지 않는 architecture rule
|
||||
@@ -269,7 +292,20 @@ promotion, and field evidence through aggregation.
|
||||
|
||||
Runbook jobs write to the stable path
|
||||
`artifacts/runbooks/<runbook-id>/record.json`; the dynamic release identity is
|
||||
stored inside the record. This keeps gate evidence lookup independent from
|
||||
stored inside the record.
|
||||
|
||||
A runbook drill (`drill:runbook`, FE-GATE-021..025) records each verdict as
|
||||
`PASS`, `FAIL` or `UNVERIFIED` (`scripts/drill-runbook.ts`, record schema in
|
||||
`scripts/contracts/release-artifacts.ts`). `PASS`/`FAIL` means the drill checked
|
||||
it against the local `dist/` build; it reads no `public/` placeholder, so a
|
||||
missing build fails. Browser boot, live API traffic, smoke after a provider
|
||||
switch, and anything the runbook marks as needing provider verification are
|
||||
`UNVERIFIED`. One `FAIL` makes the drill `FAIL` (exit 1). Otherwise any
|
||||
`UNVERIFIED` makes it `UNVERIFIED` (exit 3), and the gate is not `PASS`. So
|
||||
without provider evidence the production stage stays open. That is the intended
|
||||
result: a local drill cannot show that the promoted release can be rolled back.
|
||||
FE-GATE-016 (`rollback-drill`) is retired because it ran the same FE-RB-005
|
||||
drill as FE-GATE-025 (`RETIRED_GATE_IDS` in `scripts/contracts/ci-gates.ts`). This keeps gate evidence lookup independent from
|
||||
slashes or other provider-specific characters in `RELEASE_ID`, while each
|
||||
workflow artifact remains scoped to its own run.
|
||||
|
||||
@@ -335,7 +371,9 @@ Repository variables required by higher tiers:
|
||||
- `RUNNER_IMAGE_DIGEST` for the immutable job-container image digest used by the
|
||||
`ubuntu-latest` runner label; the workflow exposes it to gates as
|
||||
`CI_RUNNER_IMAGE` (required by every tier)
|
||||
- `HOSTING_BASE_URL` for live header verification
|
||||
- `HOSTING_BASE_URL` for live header verification of the deployed promoted
|
||||
release (FE-GATE-019, production stage). Without it the gate fails; the
|
||||
local fixture result is `UNVERIFIED`
|
||||
- `APP_PROFILE` for the runtime profile the release candidate is built from
|
||||
(`local`, `development`, `staging`, `production`;
|
||||
`scripts/generate-runtime-config.ts`). An unset value builds `local`; an empty
|
||||
|
||||
@@ -10,6 +10,42 @@ Performance evidence is deliberately split by measurement context:
|
||||
release-specific production samples over 28 days and evaluates p75 LCP, CLS,
|
||||
and INP against 2.5 s, 0.10, and 200 ms.
|
||||
|
||||
## 번들 예산의 기준선과 여유
|
||||
|
||||
리뷰 13-14. 예산은 `config/performance/budgets.json`에 있고
|
||||
`scripts/check-bundle.ts`가 강제한다. 템플릿 기본 화면만으로 초기 JS 예산의
|
||||
96%를 쓴다. 첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다.
|
||||
|
||||
| 항목 | 값 |
|
||||
|---|---|
|
||||
| 초기 JS 예산 | 204,800 gzip bytes(200 KiB) |
|
||||
| 템플릿 기준선(2026-09-25 측정) | 196,573 gzip bytes. 빌드 ID가 번들에 들어가므로 빌드마다 수백 바이트 달라진다(196,386~196,623 관측) |
|
||||
| 여유 | 약 8,200 bytes(4%) |
|
||||
| lazy chunk 예산 | 파일마다 122,880 gzip bytes(120 KiB). 기준선의 가장 큰 lazy chunk는 약 8 KB |
|
||||
|
||||
초기 JS 9개 파일 중 세 개가 대부분이다. `index` 93.5 KB, `design-system`
|
||||
65.6 KB, `preload-helper` 28.5 KB(zod 포함). 나머지 여섯은 합쳐 9 KB 정도다.
|
||||
|
||||
측정 조건:
|
||||
|
||||
- 초기 파일은 Vite manifest의 entry와 그 static import다
|
||||
(`scripts/lib/classify-vite-bundle.ts`). dynamic import chunk는 lazy다.
|
||||
- 합계는 JavaScript만 센다. CSS(`index-*.css`, 8.5 KB gzip)는 예산에 들어가지
|
||||
않는다.
|
||||
- gzip은 Node `zlib.gzipSync` 기본 수준(6)으로 잰다
|
||||
(`scripts/lib/release-candidate.ts`). 호스팅이 brotli로 보내면 전송 크기는 더
|
||||
작다. 예산은 gzip 기준 그대로 둔다.
|
||||
- Node·pnpm·runner 이미지는 `artifacts/performance/bundle.json`의 `context`에
|
||||
기록된다.
|
||||
|
||||
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
|
||||
|
||||
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
|
||||
`vite preview`로 띄워 한 번만 잰다. named interaction 시간은 Node의
|
||||
`performance.now()`로 Playwright 클릭부터 heading 대기까지 재므로 Playwright
|
||||
왕복 시간이 들어간다. 한 번 측정한 값은 흔들린다. 경계 근처 값으로 판단할
|
||||
때는 여러 번 돌려 중앙값을 본다.
|
||||
|
||||
The field minimum eligible-sample threshold is intentionally unresolved until
|
||||
a privacy-approved telemetry baseline exists. Therefore the field command
|
||||
fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
|
||||
|
||||
@@ -12,6 +12,32 @@ cache action, and repeats the smoke checks. Rebuilding an old commit, replacing
|
||||
HTML alone, or declaring recovery from cache-purge completion is prohibited.
|
||||
Recovery is established by old/new reachability probes.
|
||||
|
||||
Before deploying a promoted release later, or rolling back to one, re-verify
|
||||
its promoted bundle (the five files uploaded by the `promotion` job) with the
|
||||
archived mode (review 13-04). Provider evidence expires two hours after issue,
|
||||
so the normal mode refuses any release promoted before that. The archived mode
|
||||
still checks signatures, digests and the exact five members, and judges
|
||||
freshness at the release's recorded promotion time
|
||||
(`promotion-verification.json` `verifiedAt`, which may not lie in the future).
|
||||
New promotion never uses it (`scripts/lib/exact-promotion-bundle.ts`).
|
||||
|
||||
```bash
|
||||
VULNERABILITY_PUBLIC_KEY_PATH=... VULNERABILITY_KEY_ID=... \
|
||||
PROVENANCE_PUBLIC_KEY_PATH=... PROVENANCE_KEY_ID=... \
|
||||
EXPECTED_PROMOTION_RUN_ID=<run id> EXPECTED_PROMOTION_RUN_ATTEMPT=<attempt> \
|
||||
EXPECTED_PROMOTION_SOURCE_REVISION=<commit> \
|
||||
EXPECTED_PROMOTION_ARCHIVE_SHA256=<archive sha256> \
|
||||
corepack pnpm verify:promotion -- --root <promoted bundle directory> --archived
|
||||
|
||||
mkdir <release dir> && tar -xzf <promoted bundle directory>/release-candidate.tar.gz -C <release dir>
|
||||
corepack pnpm drill:runbook -- FE-RB-005 --release-root <release dir>
|
||||
```
|
||||
|
||||
The expected values come from the release record, not from the bundle. The
|
||||
drill then checks that release's build/config/manifest tuple and its assets,
|
||||
not the local build. It ends `UNVERIFIED` until the provider switch and smoke
|
||||
are recorded, because those happen outside this repository.
|
||||
|
||||
The provider-independent cache defaults are:
|
||||
|
||||
- hashed assets: `public, max-age=31536000, immutable`
|
||||
@@ -26,9 +52,24 @@ HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
|
||||
to the declared allowlist; a cache-correct response with a mismatched
|
||||
`Content-Type` still fails the hosting gate.
|
||||
|
||||
`corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
|
||||
Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
|
||||
requires the artifact to report `mode: "live"`. The live target must be its
|
||||
canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
|
||||
200 without leaving that origin before its cache, content-type, and security
|
||||
headers can count as deployment evidence.
|
||||
`corepack pnpm verify:hosting-headers` compares the declared headers with a
|
||||
deterministic fixture when `HOSTING_BASE_URL` is unset. That only shows the
|
||||
declarations agree with each other, so its result is `UNVERIFIED` (exit 3), not
|
||||
`PASS` (review 13-05, `scripts/lib/hosting-probe.ts` `hostingVerdict`). Only
|
||||
`mode: "live"` can pass. The live target must be its canonical, non-loopback
|
||||
HTTPS root URL. Each required surface must return HTTP 200 without leaving that
|
||||
origin before its cache, content-type, and security headers can count as
|
||||
deployment evidence. The hashed asset it requests is the entry script named by
|
||||
the served `index.html`, so it checks the release that is actually deployed.
|
||||
|
||||
FE-GATE-019 is therefore a production-stage gate (`production_gate` job,
|
||||
`PROD_PROMOTION_READY`). It runs after `promotion` and after the project has
|
||||
deployed the promoted release. This repository's workflow stops at promotion:
|
||||
uploading the release, switching the active pointer, and the post-switch smoke
|
||||
are the project's provider adapter, chosen with the hosting provider.
|
||||
|
||||
Keep a retired release's hashed assets reachable while any open tab may still
|
||||
request them. The minimum is the previous release while the next one is
|
||||
active (the rolling window modeled in `tests/release/release-fixture.ts`).
|
||||
Size it to the longest session the product supports; a tab older than that
|
||||
depends on the reload-once recovery (FE-RB-002).
|
||||
|
||||
Reference in New Issue
Block a user