Merge lane K: CI, guardrails and release fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -10,6 +10,12 @@ registry: `APP_HOME`, `EXAMPLES_PLATFORM`, `EXAMPLES_UI`, `EXAMPLES_STATES`,
|
||||
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
|
||||
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
|
||||
|
||||
+1
-1
@@ -206,7 +206,7 @@ src/shared/api
|
||||
|
||||
### 1.2 계층 방향
|
||||
|
||||
현재 `config/architecture/layers.json`의 방향을 유지한다.
|
||||
현재 방향을 유지한다. 기준은 `.dependency-cruiser.json` 하나이고 `check:architecture`가 강제한다(`config/architecture/layers.json`은 아무도 읽지 않는 낡은 사본이라 지웠다, 리뷰 12-09).
|
||||
|
||||
```text
|
||||
domain -> domain only
|
||||
|
||||
@@ -50,7 +50,10 @@ architecture/security/type negative input으로 전환했다. 이는 7번 결정
|
||||
|
||||
- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
|
||||
- TS invalid-call, invalid port, discriminated-union fixture는 실패해야 한다.
|
||||
- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
|
||||
- ESLint와 `check:architecture`의 import 그래프(`scripts/check-architecture.ts`)가
|
||||
TS/TSX architecture fixture를 검사한다. dependency-cruiser 18은 TypeScript 7을
|
||||
해석하지 못해 0개 모듈을 검사하고 통과했으므로 실행하지 않는다(리뷰 12-05).
|
||||
`.dependency-cruiser.json`은 이름만 남은 규칙 파일이고 그래프가 읽는다.
|
||||
- registry scanner는 TS registry의 required field, uniqueness와 reference를
|
||||
검증한다.
|
||||
- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
|
||||
|
||||
@@ -38,9 +38,18 @@
|
||||
|
||||
## 경계와 검증
|
||||
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다.
|
||||
- design-system 검사기는 direct icon/headless import, deep import, raw palette,
|
||||
undefined token과 tooltip-only required information fixture를 거절한다.
|
||||
- 제품 코드는 `presentation/design-system/index`만 import한다. 예외는 규칙에
|
||||
이름으로 적는다. `presentation/components/ui/*.ts`는 아래 Rollback의 재수출
|
||||
facade이고, `presentation/templates/page-templates.tsx`는 index가 내보내지
|
||||
않는 `PaginationLandmarkContext`를 읽는다.
|
||||
- deep import와 direct icon import는 `check:architecture` 그래프 규칙
|
||||
`design-system-is-reached-through-its-index`, `icon-vendor-is-facade-only`
|
||||
(`.dependency-cruiser.json`)가 거절한다. 경로 해석이 끝난 간선을 보므로
|
||||
presentation 안의 상대 경로 import도 잡는다(리뷰 12-08). 음성 fixture는
|
||||
`tests/fixtures/architecture/dependency-graph/import-boundaries`다.
|
||||
- design-system 검사기(`scripts/check-design-system.ts`)는 headless vendor
|
||||
import, raw palette, undefined token과 tooltip-only required information
|
||||
fixture를 거절한다.
|
||||
- type negative fixture는 accessible name 없는 `IconButton`을 거절한다.
|
||||
- component test는 decorative icon, form control, Menu, Tabs, Drawer와 Toast를
|
||||
검증한다.
|
||||
|
||||
@@ -65,7 +65,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
|
||||
| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
|
||||
| --- | --- | --- | --- |
|
||||
| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
|
||||
| 계층 의존 방향 | 준비됨 | dependency-cruiser + TS-aware static graph, unresolved/parse/layer/cycle negative fixture | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
|
||||
| 계층 의존 방향 | 준비됨 | TS-aware static graph(`scripts/check-architecture.ts`, 규칙 `.dependency-cruiser.json`), unresolved/parse/layer/cycle negative fixture. dependency-cruiser 자체는 TS 7을 해석하지 못해 실행하지 않음(12-05) | 새 rule shape와 source extension도 같은 fail-closed graph에 추가 |
|
||||
| application facade | 준비됨 | module-augmented feature input registry, typed output catalog, provider, production composition test | feature별 input contribution과 제거 gate 유지 |
|
||||
| REST HTTP client | 준비됨 + hardening delta | reference vertical의 path/search/body projection, attempt timeout/retry, abort/cleanup은 `COMPOSED` | auth fail-close/final invariant, total deadline, bounded decoder, status/media/CSRF/conditional/pagination은 `DESIGNED_NOT_IMPLEMENTED` |
|
||||
| Browser RPC 공통 계약/runtime | 준비됨/미조립 | V3 operation/profile registry, typed application port, bounded unary/server-stream lifecycle와 unavailable adapter는 `AVAILABLE_NOT_COMPOSED` | actual descriptor/generated client, protocol transport, proxy/provider/browser conformance |
|
||||
|
||||
+40
-13
@@ -25,6 +25,15 @@ The following edges are forbidden:
|
||||
- an adapter to presentation, bootstrap internals, or another concrete adapter
|
||||
- feature domain/application to its presentation or outbound adapter, and
|
||||
feature presentation to its outbound adapter
|
||||
- a module presentation may import to a concrete adapter: files outside a
|
||||
feature's layer folders (`src/features/*.ts`, `src/features/<id>/*.ts`),
|
||||
`src/contexts` and `src/apps` (`feature-and-app-roots-do-not-reach-adapters`).
|
||||
The graph checks one edge at a time, so a re-export there would carry an
|
||||
adapter into presentation with every other rule passing. The one exception is
|
||||
the type-only `src/features/feature-adapter-contribution.ts`
|
||||
- presentation to `src/apps` or `src/contexts`, except
|
||||
`src/presentation/routes/app-router.tsx`, which mounts the app's route tree
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
|
||||
## The adapter kernel
|
||||
|
||||
@@ -35,14 +44,25 @@ purpose and is the only adapter code an adapter may reach across a group for:
|
||||
the bounded-capacity guard
|
||||
- `src/adapters/browser-file-storage/result.ts` — the browser-data result and
|
||||
failure constructors
|
||||
- `src/adapters/cross-context-invalidation/index.ts` — the cross-context
|
||||
invalidation transport and its types. Any adapter may import it; today
|
||||
`query-cache` does
|
||||
|
||||
Each rule above is enforced by `check:architecture`, including the kernel
|
||||
carve-out, so this table and the executable rules cannot drift apart. Two edges
|
||||
are still open and are named explicitly in `.dependency-cruiser.json` rather
|
||||
than left silent: the generic presentation modules that read the installed
|
||||
registries today, and the two collaborator types `query-cache` reads from
|
||||
`cross-context-invalidation`. Both lists are frozen — a new edge of either kind
|
||||
fails the gate.
|
||||
carve-out, so this table and the executable rules cannot drift apart.
|
||||
|
||||
Every exception is written in the rule itself (`.dependency-cruiser.json`): the
|
||||
exempted path in `pathNot`, and the reason, owner and revisit condition in
|
||||
`comment` (review 12-07). Besides the kernel, the exceptions are:
|
||||
|
||||
- the generic presentation modules that read the installed registries today
|
||||
(`generic-presentation-does-not-compose-the-product`). The list names exact
|
||||
files, so a new module that reads a registry fails the gate
|
||||
- `src/presentation/adapters/query`, the TanStack Query binding
|
||||
(`presentation-does-not-know-adapters`)
|
||||
- `src/presentation/routes/app-router.tsx` importing the app
|
||||
(`presentation-does-not-import-apps-or-contexts`)
|
||||
- the design-system facades (`design-system-is-reached-through-its-index`)
|
||||
|
||||
## 어댑터 그룹의 공개 경계
|
||||
|
||||
@@ -63,10 +83,15 @@ fails the gate.
|
||||
위한 것이다.
|
||||
|
||||
`storage`는 최상위 배럴이 `indexeddb/`·`opfs/` 서브배럴을 재수출하지
|
||||
않는다. 두 런타임이 각자 독립적으로 제거 가능하고
|
||||
(`test:browser-file-storage-removal`), 그래서 각 서브배럴이 곧 경계다.
|
||||
규칙의 도착점 정규식이 1단계 중첩 `index.ts`를 배럴로 인정하는 이유가
|
||||
이것이다.
|
||||
않는다. 두 폴더는 browser-file-storage 번들의 런타임이다. 제거 드릴
|
||||
(`test:browser-file-storage-removal`)은 그 번들 전체(`browser-file-storage`,
|
||||
`browser-files`, `browser-transfer`, `cache-storage`, `storage/indexeddb`,
|
||||
`storage/opfs`)를 함께 지운다. 최상위 `storage` 배럴(Web Storage)은 그 뒤에도
|
||||
남아야 하므로 두 폴더를 재수출하지 않고, 그래서 각 서브배럴이 그 런타임의 공개
|
||||
경계다.
|
||||
규칙의 도착점 정규식은 이 두 서브배럴만 배럴로 인정한다. 다른 그룹의 2단계
|
||||
`index.ts`(예: `http/internals/index.ts`)는 공개 배럴이 아니고, 그룹 바깥에서
|
||||
import하면 실패한다(리뷰 12-07, `dependency-graph/barrel` fixture).
|
||||
|
||||
`service-worker/index.ts`는 `tsconfig.service-worker.json`의 `exclude`에
|
||||
들어 있다. 그 설정이 그룹 폴더를 통째로 WebWorker lib로 컴파일하면서 페이지
|
||||
@@ -83,8 +108,9 @@ application APIs augment the generic typed input registry. Concrete output
|
||||
ports are composed in bootstrap and stay hidden behind the application facade.
|
||||
Project-selected capabilities still implement the same output boundaries.
|
||||
|
||||
`check:architecture` keeps dependency-cruiser's report and adds the
|
||||
authoritative TypeScript-aware graph below it:
|
||||
`check:architecture` writes the TypeScript-aware graph below. It reads the rules
|
||||
from `.dependency-cruiser.json` but does not run dependency-cruiser, which cannot
|
||||
parse TypeScript 7 and checked zero modules (review 12-05):
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -103,7 +129,8 @@ authoritative TypeScript-aware graph below it:
|
||||
```
|
||||
|
||||
The graph scans TypeScript and TSX, including static, dynamic, type, CommonJS
|
||||
and JSDoc import references. It applies the path rules from
|
||||
and JSDoc import references. `import.meta.glob` is a parse failure: it loads
|
||||
modules without naming one, so no edge rule could see them (review 12-06). It applies the path rules from
|
||||
`.dependency-cruiser.json`, requires explicit TypeScript extensions for local
|
||||
source imports, and fails closed on JavaScript-family source/specifiers,
|
||||
unsupported rule shapes, unresolved imports, parse failures, error-severity
|
||||
|
||||
@@ -130,6 +130,15 @@ Web Push를 함께 설치하지 않는다.
|
||||
integration test를 작성한다.
|
||||
9. runtime config schema, dependency inventory/approval, SBOM, bundle budget,
|
||||
browser support와 runbook을 갱신한다.
|
||||
운영 CSP(`config/hosting/security-headers.json`)도 여기서 넓힌다. 기본 CSP는
|
||||
아래 기능을 막는다(리뷰 13-08).
|
||||
- 다른 origin의 realtime: `connect-src`에 `wss://<realtime origin>`을 더한다.
|
||||
`https:`는 `wss:`를 허용하지 않는다(CSP3 scheme 비교).
|
||||
- 파일 preview(`src/adapters/browser-files/object-url-lease.ts`의 object URL):
|
||||
`img-src`에 `blob:`을 더한다.
|
||||
- 이미지 CDN: `img-src`에 CDN origin을 더한다.
|
||||
바꾼 CSP 아래에서 `tests/e2e/production-csp.spec.ts`가 그 기능의 화면을 열도록
|
||||
smoke를 늘린다.
|
||||
10. 실제 provider integration과 negative behavior가 통과한 뒤에만 catalog 상태를
|
||||
별도 project catalog에서 `INSTALLED`로 바꾼다.
|
||||
|
||||
|
||||
@@ -53,8 +53,9 @@ and exact input type.
|
||||
Route contracts/codecs, the route-input provider, and lazy runtime modules are
|
||||
separate modules so feature pages do not import the router that loads them.
|
||||
Expected application failures use the shared `Result`/`AppFailure` contract.
|
||||
The architecture gate analyzes TS/TSX imports independently of
|
||||
dependency-cruiser, rejects local JavaScript-family specifiers and executable
|
||||
The architecture gate analyzes TS/TSX imports with its own graph (the rules
|
||||
live in `.dependency-cruiser.json`; dependency-cruiser itself cannot parse
|
||||
TypeScript 7 and does not run), rejects local JavaScript-family specifiers and executable
|
||||
JavaScript-family files, and fails on unresolved imports, parse failures,
|
||||
forbidden layer edges, or cycles. The remaining project-owned work includes
|
||||
selecting and verifying real hosting, identity, telemetry, vulnerability and
|
||||
|
||||
@@ -29,5 +29,10 @@ sequenceDiagram
|
||||
CI->>Browser: boot, route, API, and reload-loop smoke
|
||||
```
|
||||
|
||||
In this repository the workflow stops at promotion. The upload, pointer switch
|
||||
and smoke steps above belong to the project's provider adapter; after it has
|
||||
deployed the promoted release, FE-GATE-019 probes the live headers (review
|
||||
13-05, [`release-cache-rollback.md`](../operations/release-cache-rollback.md)).
|
||||
|
||||
Rollback changes the active pointer only after confirming that the prior
|
||||
immutable release has a coherent HTML/assets/config/API/manifest tuple.
|
||||
|
||||
@@ -52,7 +52,9 @@ TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파
|
||||
1. ESLint가 product와 negative fixture의 `ts`/`tsx`를 모두 검사한다.
|
||||
2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
|
||||
도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
|
||||
3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
|
||||
3. `check:architecture`의 import 그래프가 TS/TSX를 해석한다. 규칙은
|
||||
`.dependency-cruiser.json`에 있지만 dependency-cruiser는 실행하지 않는다.
|
||||
TypeScript 7을 해석하지 못해 0개 모듈을 검사했기 때문이다(리뷰 12-05).
|
||||
4. `scripts/check-registries.ts`가 TS/TSX를 검색한다.
|
||||
5. `config/contracts/registry-governance.json`과 승인 baseline은 `.ts/.tsx`
|
||||
source 경로를 사용한다.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -11,3 +11,8 @@ Close only when compatibility and release-coherence gates pass, critical smoke
|
||||
passes, repeated `DEPLOY_MISMATCH` is absent, and the incident timeline records
|
||||
the restored release ID. Pointer-switch or cache-purge completion alone is not
|
||||
recovery evidence.
|
||||
|
||||
Verify the prior release before switching to it: `verify:promotion -- --root
|
||||
<bundle> --archived` and `drill:runbook -- FE-RB-005 --release-root <extracted
|
||||
archive>`. The commands and inputs are in
|
||||
[`docs/operations/release-cache-rollback.md`](../operations/release-cache-rollback.md).
|
||||
|
||||
@@ -7,7 +7,23 @@ maps are prohibited defaults.
|
||||
`config/hosting/security-headers.json` is the declared header set. Hosting
|
||||
verification compares that declaration with live responses. CSP deliberately
|
||||
omits `unsafe-inline` and `unsafe-eval`; production code and built assets must
|
||||
remain compatible with that baseline.
|
||||
remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of
|
||||
`test:e2e`, FE-GATE-008) serves the build with these headers and fails on a
|
||||
`securitypolicyviolation` event or console error (review 13-08). One
|
||||
violation is known: zod probes `Function("")` on its first object schema and
|
||||
the policy refuses it. Parsing still works, but the default build reports the
|
||||
violation on every boot until zod is configured `jitless` before the first
|
||||
schema is built. `z.config` in the entry module is too late, because the
|
||||
bundler evaluates the shared chunks that build schemas first. The smoke sets
|
||||
zod's global config before page scripts run so it can catch every other
|
||||
violation; the spec comment names when to remove that. Features that are off by
|
||||
default need CSP additions when a project selects them; see step 9 in
|
||||
[optional adapter recipes](../architecture/optional-adapter-recipes.md).
|
||||
`connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to
|
||||
the runtime config's `API_BASE_URL` and `TELEMETRY_ENDPOINT` origins needs a
|
||||
header generated per environment at deploy time, because those values are set
|
||||
per deployment (`scripts/generate-runtime-config.ts`). That generator does not
|
||||
exist yet; a project that deploys should add it with its provider adapter.
|
||||
|
||||
Route guards are UX hints and client validation does not replace backend
|
||||
authorization or validation.
|
||||
|
||||
@@ -39,6 +39,75 @@ Changing it requires `DEPENDENCY_BASELINE_OWNER` and
|
||||
`DEPENDENCY_BASELINE_REASON`; editing the digest or hardcoding an empty diff is
|
||||
rejected.
|
||||
|
||||
## 무엇을 증명하고 무엇을 증명하지 않는가
|
||||
|
||||
리뷰 13-12. 산출물마다 증명 범위가 다르다. 아래 "증명하지 못하는 것"을 증명된
|
||||
것으로 읽지 않는다.
|
||||
|
||||
| 산출물 | 증명하는 것 | 증명하지 못하는 것 |
|
||||
|---|---|---|
|
||||
| SBOM(`artifacts/release/sbom.cdx.json`) | lockfile에 고정된 설치 그래프(`pnpm list --depth Infinity`, `scripts/generate-supply-chain.ts`)와 각 패키지의 sha512 integrity, license | 배포물에 실제로 들어간 부분 집합, 취약점 없음 |
|
||||
| 번들 패키지 목록(`artifacts/quality/vite-module-inventory.json`의 `packages`) | 배포 번들에 모듈이 하나 이상 들어간 패키지의 `name@version`. Vite가 번들에 넣은 모듈에서 바로 만든다(`scripts/lib/vite-module-inventory.ts`) | 패키지 안의 어떤 코드가 실행되는지, 취약점 없음 |
|
||||
| local provenance(`artifacts/release/provenance.json`) | dist digest, lockfile, source set, SBOM digest가 서로 맞음 | 빌드 과정이 변조되지 않았음, 빌드한 주체. 서명이 없는 자기 보고다(`builder.id`가 `local:`, `invocationId`가 `LOCAL_UNSIGNED`). `predicateType`이 SLSA provenance v1이어도 SLSA 수준을 뜻하지 않는다 |
|
||||
| 외부 provenance 서명 | 지정 키 보유자가 이 run, source revision, 후보 digest를 보고 서명함 | 빌드 job 자체의 격리, provider가 성실히 검사했음 |
|
||||
| 외부 vulnerability 서명 | provider가 이 lockfile·dist에 대해 결과를 주장함 | 오프라인 DB의 최신성, 누락 없음 |
|
||||
|
||||
번들 패키지 목록은 SBOM의 production 항목에 모두 들어 있어야 한다. 2026-09-25
|
||||
기준으로 한 건이 어긋난다. `scheduler@0.27.0`은 `react-dom`의 의존성이라 번들에
|
||||
들어가지만, SBOM과 `config/security/dependency-baseline.json`은 이것을
|
||||
`development`로 분류한다. `pnpm list` JSON이 production 트리 아래에서 이 패키지를
|
||||
다시 보여 주지 않고, 그래서 `scripts/lib/supply-chain.ts`의 순회가 development
|
||||
경로에서만 이것을 만난다. 분류를 고치면 dependency baseline을 다시 승인해야 하므로
|
||||
(`update:dependency-baseline`) 이 문서에 알려진 차이로 남긴다.
|
||||
|
||||
## 최소 구성과 전체 구성
|
||||
|
||||
리뷰 13-13. 승격 단계까지 쓰려면 이 문서 아래의 runner 조건(bwrap, prlimit,
|
||||
systemd-run, systemd user manager 254 이상, cgroup v2 위임)과 오프라인 데이터로
|
||||
Ed25519 서명 보고서를 내는 provider 두 개가 필요하다. 이 repo는 그 환경에서
|
||||
workflow 전체를 한 번도 돌리지 않았다. 그래서 두 구성을 나눠 적는다.
|
||||
|
||||
| 구성 | 켜는 것 | 보장하는 것 | 보장하지 않는 것 |
|
||||
|---|---|---|---|
|
||||
| 최소 구성(provider 없음) | merge·release stage 게이트, `immutable_build`(FE-GATE-015·027). provider 변수는 비워 둔다 | lockfile 무결성과 설치 스크립트 차단, SBOM과 local provenance의 digest 정합, secret scan, 재현 빌드, 후보 archive의 exact member와 digest, release 대상 환경 승인(FE-GATE-027) | 외부 취약점 검사, 서명된 provenance. provider job은 명령과 키가 없어 실패하고, `promotion` job은 두 provider job의 성공을 요구하므로 돌지 않는다. 승격은 사람이 결정한다 |
|
||||
| 전체 구성 | 위 전부와 `vulnerability_provider`·`provenance_provider`·`promotion` job, 아래 runner 조건과 provider 키 | 위 전부와, 지정 키 보유자가 이 후보 digest·run·source에 서명했다는 것, 승격된 exact-five bundle(`verify:promotion`) | provider가 성실히 검사했는지, 빌드 job 격리(위 "무엇을 증명하고" 표 참고) |
|
||||
|
||||
최소 구성으로 운영할 때 승격은 수동 승인이다. 승인자는 `immutable_build`가
|
||||
올린 후보 archive의 SHA-256(job output `archive_sha256`)과 local evidence를
|
||||
기록하고, 그 archive를 그대로 배포한다. 다시 빌드하지 않는다. `production_gate`는
|
||||
`promotion` 뒤에만 돌므로 이 구성의 workflow에서는 실행되지 않는다. 운영
|
||||
게이트(FE-GATE-019, 021~025)는 배포한 release를 대상으로
|
||||
`corepack pnpm ci:gate -- FE-GATE-0xx`로 따로 돌려 기록한다.
|
||||
|
||||
### provider 신뢰 키 교체와 폐기
|
||||
|
||||
신뢰 키는 repo 변수 `VULNERABILITY_PUBLIC_KEY_PATH`·`VULNERABILITY_KEY_ID`,
|
||||
`PROVENANCE_PUBLIC_KEY_PATH`·`PROVENANCE_KEY_ID`가 가리키는 공개 키 파일이다
|
||||
(`scripts/lib/provider-trust.ts`). 두 provider는 서로 다른 키를 써야 한다
|
||||
(`assertDistinctProviderTrust`). 승격 기록은 키 ID·지문과 trust policy
|
||||
SHA-256을 남긴다.
|
||||
|
||||
교체 순서:
|
||||
|
||||
1. provider가 새 키 쌍을 만들고 공개 키만 넘긴다.
|
||||
2. 새 공개 키 파일을 runner가 읽을 수 있는 경로에 두고, 두 변수를 새 경로와 새
|
||||
key ID로 한꺼번에 바꾼다. 키 ID는 새 값을 쓴다. 이전 ID를 재사용하면 기록만
|
||||
보고 어느 키였는지 구분할 수 없다.
|
||||
3. provider 쪽 서명 키를 새 키로 바꾼 뒤 release를 한 번 돌려 `promotion`이
|
||||
통과하는지 확인한다.
|
||||
4. 이전 공개 키 파일은 지우지 않고 보관한다. 이전 키로 승격된 release를 나중에
|
||||
배포하거나 그 release로 롤백할 때 `verify:promotion -- --archived`가 그 키를
|
||||
요구한다(`docs/operations/release-cache-rollback.md`).
|
||||
|
||||
폐기 순서(키 유출 등):
|
||||
|
||||
1. 해당 변수에서 그 키를 즉시 뺀다. 그 키로 서명된 새 승격은 이때부터 실패한다.
|
||||
2. 보관 중인 이전 공개 키 파일도 지운다. 그 키로만 서명된 과거 release는
|
||||
`verify:promotion -- --archived`를 통과하지 못한다.
|
||||
3. 그런 release를 다시 써야 하면 새 키로 provider 검증을 다시 받는다. 같은 후보
|
||||
archive를 대상으로 한 새 provider 실행이 필요하고, 다시 빌드하지 않는다. 이
|
||||
repo에는 이 재검증 전용 job이 없다. 필요한 프로젝트가 만든다.
|
||||
|
||||
## External promotion controls
|
||||
|
||||
Promotion reads the provider files named by `VULNERABILITY_REPORT_PATH` and
|
||||
|
||||
@@ -1103,8 +1103,11 @@ validate한다.
|
||||
|
||||
외부 배포 주소나 28일 field evidence가 없는 skeleton 개발 단계에서는 해당 gate가
|
||||
실제 프로젝트가 채울 계약으로 남는다. 이를 fake data로 통과시키지 않는다.
|
||||
현재 `FE-GATE-009`의 signed manual accessibility review는 merge gate다. 이
|
||||
문서는 이를 production/field gate로 이동시키지 않는다.
|
||||
signed manual accessibility review는 release gate `FE-GATE-028`이다
|
||||
(`config/ci/gates.json`, 리뷰 08-06). 사람의 서명은 릴리스 후보 하나에 대해
|
||||
하므로 merge마다 요구할 수 없다. merge gate `FE-GATE-009`는 자동 axe 검사와
|
||||
기록 형식 검사(`review:a11y-manual -- --format-only`,
|
||||
`scripts/lib/manual-a11y-evidence.ts`의 `validateManualA11yRecordFormat`)만 한다.
|
||||
|
||||
### 16.4 병렬화와 shard
|
||||
|
||||
|
||||
Reference in New Issue
Block a user