Commit Graph
44 Commits
Author SHA1 Message Date
DongHyeonka 81ff05efc1 chore(review): 1106 화면·테마 조치 브랜치를 합친다 2026-11-06 07:24:11 +09:00
DongHyeonka 7625dc4548 fix(theme): 열린 modal의 가림막이 스크롤바 자리까지 덮게 한다
문제: :root의 scrollbar-gutter: stable(1105/15-05)은 일반 스크롤바를 쓰는
브라우저에서 문서가 스크롤되지 않아도 오른쪽 15 px를 비워 둔다. 그 자리에는
root의 배경색이 보인다. 고정 위치 상자와 top layer의 ::backdrop은 그 자리
앞에서 끝나서, drawer·modal을 열면 오른쪽 끝에 가림막이 덮지 않은 밝은
세로 띠가 남는다. compact 골든(390 px, drawer 열림)이 가림막이 375 px에서
끝나는 모습을 정답으로 고정했다. header 띠도 같은 자리 앞에서 끝난다.

고른 방법:
- modal이 열린 동안 root 배경색을 가림막을 페이지 바탕 위에 겹친 불투명한
  색으로 바꾼다. primitives.css의 :root:has(.ui-dialog[open])이
  background-color: var(--dialog-backdrop-on-surface)를 쓴다.
- 새 컴포넌트 토큰 셋(component.css). --dialog-backdrop-weight(55%)를
  --dialog-backdrop(::backdrop이 칠하는 반투명 가림막, 값은 전과 같다)과
  --dialog-backdrop-on-surface(color-mix in srgb로 페이지 바탕과 섞은 색)가
  같이 읽는다. 브라우저는 반투명 색을 sRGB에서 겹치므로 두 색이 맞는다.
- body가 페이지 바탕(--color-surface)을 직접 칠한다. 그래서 root 배경은
  스크롤바 자리(와 overscroll)에만 보이고, 열린 modal 아래 페이지가 두 번
  어두워지지 않는다. modal이 없으면 둘이 같은 색이라 화면이 그대로다.
- 검사: tests/visual/scrollbar-gutter.visual.spec.ts. 시각 프로젝트에서
  Chromium을 --hide-scrollbars 없이 띄우고, 스크롤되지 않는 /not-found
  (390x844)에서 스크롤바 자리와 바로 옆 가림막의 평균 픽셀 색을 비교한다.
  닫힘 → drawer 열림 → 다시 닫힘 세 번 본다. 실패 메시지에 root의 계산된
  배경(색·이미지)과 열린 .ui-dialog 수를 적어, 규칙이 안 맞은 것과 맞았는데
  그 자리에 안 그려진 것을 구분한다. 08-R2 probe의 잘못된 단언 둘을
  고쳤다. 자리가 비어 있으면 clientWidth가 창 폭이라 자리 위치는 body의
  오른쪽 끝으로 찾는다. 그 자리의 hit test는 늘 null이라 픽셀을 본다.
  허용 차이 12는 drawer 그림자(70 px blur)가 옆 띠를 약 3단계 어둡게 하는
  몫이다. 덮지 않은 띠는 약 120 차이 난다.
- header 띠는 받아들이고 design-system-platform.md 8.2에 적었다. header
  색으로 칠하려면 root 배경이 셸의 header 높이·색을 알아야 하고, 셸이 없는
  화면에서는 그 띠를 빼야 한다. 완료 기준은 가림막만 요구한다.
버린 대안:
- 첫 시도: :root:has(.ui-dialog:modal)에서 가림막 색 gradient 한 겹을 페이지
  바탕 위에 얹었다. desktop batch에서 그 자리가 페이지 바탕색 그대로였다
  (gutter rgb(248 250 252), 옆 가림막 rgb(122 128 136)). 그 실행만으로는
  규칙이 안 맞았는지(:modal의 :has() 무효화), 이미지 층이 그 자리에 안
  그려졌는지 가를 수 없다. 그래서 둘 다 피한다. 배경색 자체를 바꾸고,
  showModal()이 세우는 [open] 속성으로 고른다. Dialog primitive는 브라우저에서
  늘 showModal()로 열기 때문에 열린 .ui-dialog는 modal이다.
- ::backdrop에 음수 inset(right: -N px): 스크롤바 자리는 viewport의
  padding box 밖이라 고정 위치 상자가 잘린다(스펙 기준, 화면 확인은 안 함).
- scrollbar-gutter를 거두기: 15-05의 첫 화면 shift를 다시 연다.
- modal이 열린 동안 root 배경만 바꾸고 body를 비워 두기: 페이지 전체가
  가림막 아래에서 한 번 더 어두워진다.

위험·한계: :has()를 모르는 브라우저(Firefox 121 미만 등)는 이 규칙을 버리고
전처럼 띠가 남는다. 그 자리 색은 가림막의 blur(2px)를 따르지 않는 평평한
색이다. 오른쪽 drawer(placement="end")는 drawer와 창 끝 사이에 가림막 색 띠가
남는다(템플릿은 쓰지 않음, 미확인). RTL, Firefox, WebKit은 보지 않았다.
문서가 스크롤되면 그 자리의 스크롤바는 전처럼 가림막 밖이다.
--hide-scrollbars로 찍는 compact 골든은 전체 페이지(1377 px)를 찍으므로,
열린 modal 동안 어두워진 root 배경이 창 높이(844 px) 아래의 오른쪽 15 px
띠에도 보인다. 실제 브라우저에서 그 부분은 스크롤바 아래에 있다. compact
골든 1장은 desktop에서 다시 찍었다(test:visual:update). 바뀐 것은 x 375~390
띠가 높이 전체에서 가림막 색이 된 것뿐이다. 나머지 골든 4장은 바뀌지
않았다(body와 root가 같은 색). 레이아웃은 바꾸지 않았다.

검증: desktop batch에서 확인.
corepack pnpm test:visual tests/visual/scrollbar-gutter.visual.spec.ts
corepack pnpm test:visual:update 뒤 corepack pnpm test:visual
node scripts/r5-15-scrollbar.mjs 3 <out.json> (15-R3, 첫 화면 shift 0 유지)

Refs: 1106/08-03
2026-11-06 07:24:02 +09:00
DongHyeonka 68fde02777 fix(test-run): RUN_OUTPUT_ROOT가 있으면 빌드 뒤 검사가 멈춘다
문제: 1105/12-04 뒤 빌드는 `RUN_OUTPUT_ROOT` 아래에 쓰는데,
check:bundle의 두 단계(`generate-supply-chain.ts`, `check-bundle.ts`)는 이
변수를 읽지 않고 checkout의 `dist`와 `artifacts/`를 읽는다. 셸에 이 변수를
둔 채 빌드와 check:bundle을 돌리면 예산을 3,504 B 넘는 새 빌드 대신 이전
빌드를 재서 PASS한다(리뷰 12-R2). ci:gate의 신선도 검사도 bundle.json을
check:bundle이 다시 쓰므로 막지 못한다.

고른 방법: `scripts/lib/run-isolation.ts`에 `checkoutBuildReadFailure`를
두고, 두 스크립트가 무엇을 읽기 전에 부른다. 출력 루트가 `.`이 아니면 변수
값과 이유를 적고 exit 1로 멈춘다. `.`(Playwright 설정이 run ID 없이 web
server에 넘기는 값)과 빈 값은 그대로 돈다. 그래서
`RUN_OUTPUT_ROOT=.tmp/x corepack pnpm ci:gate -- FE-GATE-012`도 check-bundle
단계에서 변수 이름을 적고 실패한다.
버린 대안: ci:gate가 시작 전에 거절하기(리뷰 문서 (b)). 12-R2처럼
check:bundle을 직접 돌리는 경우를 막지 못한다. 두 스크립트가 같은 루트를
읽게 하기(c)는 supply-chain 산출물 전부와 CI upload 경로를 함께 옮겨야 한다.

위험·한계:
- FE-GATE-012는 빌드 단계를 끝까지 돈 뒤 check-bundle에서 실패한다. 빌드
  시간만큼 늦게 알린다.
- 같은 모양일 수 있는 `check:app-build-input:bundle`,
  `check:optional-recipes --require-dist`, release candidate 조립은 보지
  않았다. FE-GATE-012에서는 check-bundle이 먼저 실패해 거기까지 가지 않는다.
- 디버깅으로 변수를 둔 사람은 check:bundle 전에 지워야 한다(문서에 적음).
- 이 노트북에서는 실행하지 못했다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/check-bundle-output.test.ts tests/unit/run-isolation.test.ts
리뷰 12-R2 명령(stale-bundle-rc=1, stderr에 RUN_OUTPUT_ROOT), check:types,
lint, verify:documentation, ci:gate FE-GATE-012

Refs: 1106/12-02
2026-11-06 05:35:48 +09:00
DongHyeonka 703a33559f chore(review): 1105 가드레일·CI 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 1a29d4aa85 chore(review): 1105 실행 격리 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka d5a70b4267 chore(review): 1105 테스트 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 510e2bbceb docs(testing): 한 checkout 두 실행의 run ID·포트 변수를 적는다
문제: 실행 격리(앞 두 커밋)의 변수(`TEST_RUN_ID`, `RUN_OUTPUT_ROOT`,
`TEST_*_PORT`)와 "게이트는 한 checkout에서 하나씩"이라는 전제가 어디에도
적혀 있지 않다. 테스트 전략 13.1은 dev E2E가 떠 있는 서버를 재사용한다고
적고 있어 바뀐 동작과 다르다(1105/12-04 "결정의 근거"는 이 선택이 어디에도
적혀 있지 않다고 지적했다).

고른 방법: 테스트 전략에 13.6절을 더한다. 핵심, 흐름도, 변수 표, 두 실행
예, 한계(게이트·증거 검사는 기본 경로만 읽음, 같은 run ID, 선택이 다른 두
실행의 `src/.generated`, Storybook 캐시, `.tmp/runs` 정리)를 적는다. 13.1의
재사용 문구를 고친다. 매뉴얼 "merge 전에 돌릴 것"과 README 게이트 반복문
아래에 짧게 적고 13.6절을 가리킨다.
버린 대안: README에 표 전체를 두기. README는 게이트를 돌리는 법만 적고
상세는 테스트 전략 문서에 두는 지금 구조를 따른다.

위험·한계: 문서만 바꾼다. 경로·스크립트 이름·링크는 verify:documentation이
검사한다.

검증: desktop batch에서 확인.
corepack pnpm verify:documentation

Refs: 1105/12-04
2026-11-06 02:58:00 +09:00
DongHyeonka 7ead8d369a fix(test): test:all이 test:coverage가 도는 Vitest 경로를 모두 돌린다
문제
taxonomy는 test:all을 일상 개발 루프라고 적는다. 그런데 test:all은
tests/features 중 참조 샘플만(test:reference-feature) 돌리고,
test:coverage(FE-GATE-005)가 도는 tests/features의 나머지(설치 표면,
feature-module, 예제 기능 2파일), tests/scripts,
tests/scale/browser-soak.contract.test.ts를 빠뜨린다. 로컬에서 초록이고
CI에서 빨강이 될 수 있다.

고른 방법과 버린 대안
- package.json test:all의 test:reference-feature 자리를 tests/features
  전체 + tests/scripts + browser-soak 계약 테스트를 한 번에 도는 Vitest
  실행으로 바꾼다. 참조 샘플 테스트도 tests/features 안이라 그대로
  돈다. 샘플을 지우면 그 폴더만 빠진다.
- tests/unit/test-all-paths.test.ts(새 파일): package script graph로
  test:all과 test:coverage의 Vitest 경로를 모아, coverage 쪽 경로가
  모두 test:all 경로 안에 있는지 본다. 다시 빠지면 이 테스트가 잡는다.
- 새 package script(test:features)를 만드는 안은 버렸다. 그 이름이
  tests/scripts까지 도는 것을 말하지 못하고, test:all만 쓰는 스크립트가
  하나 늘 뿐이다.
- taxonomy에 "CI와 같은 집합은 test:coverage"라고만 적는 안은 버렸다.
  완료 기준(test:all ⊇ test:coverage의 Vitest 파일)을 못 채운다.
- docs/testing/taxonomy.md의 test:all 설명을 바꾼다.

위험·한계
- 제거 드릴 셋(optional recipe, realtime, browser-file-storage)은
  fixture 안에서 test:all만 돈다. 이제 이 파일들도 그 fixture에서
  처음 돈다. import를 보면 제거 대상에 기대지 않지만 실행으로는 확인하지
  못했다. 드릴 시간이 몇 초씩 는다(1101/10-06과 반대 방향).

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/test-all-paths.test.ts
  corepack pnpm test:all, corepack pnpm check:ci, FE-GATE-020
- RED: 부모 커밋의 package.json에서 "runs every Vitest path
  test:coverage runs"가 tests/features·tests/scripts·browser-soak
  경로를 빠졌다고 실패한다.

Refs: 0929/10-05
2026-11-06 01:05:22 +09:00
DongHyeonka e02552998d test(e2e): strict fixture가 preload 기록으로 test를 실패시키는지 고정한다
문제
tests/e2e/preload-use.spec.ts는 preload tracker만 증명한다. 안 쓴
preload를 넣는 test는 맨 test에서 tracker를 직접 부르고, strict
fixture를 쓰는 test는 "통과해야 한다" 방향 하나뿐이다. 그래서
strict-browser-test.ts가 tracker 결과를 버려도(11-R3) 커밋된 test는
하나도 실패하지 않았고, WebKit 무시 정규식을 넓혀도 볼 test가 없다.
3번 test는 지연시킬 청크를 못 찾으면 조용히 평범한 방문이 된다.

고른 방법과 버린 대안
- strict fixture의 마지막 판정을 browserFailureVerdict fixture로
  뺀다. 기본값은 지금과 같다(allowedBrowserFailure로 거르고 빈 목록
  단언). page fixture는 기록을 그 판정에 넘긴다.
- spec은 그 판정을 "기록을 받아 두는" 판정으로 바꾼 recordedTest를
  둔다. page fixture가 판정에 의존하므로 판정의 teardown은 page
  teardown 뒤에 돈다. 거기서 fixture가 넘긴 줄이 fixtureReports와 정확히
  같은지 본다.
  - 안 쓴 modulepreload 하나 → `preloadunused:/assets/<청크>.js` 한 줄.
  - WebKit 문구 그대로(무시), Chromium 문구, WebKit 문구 + 뒤 글자,
    같은 문구의 console.error, 다른 warning → 뒤의 네 줄만, 순서대로.
- 기본 판정이 실제로 test를 실패시키는지는 strictTest.fail()로 console
  error 한 줄을 내는 test 하나가 본다. 기록이 맞다는 것은 위 두 test가
  따로 증명하므로, 이 test가 엉뚱한 이유로 실패해도 놓치는 것이 적다.
- 3번 test는 지연시킬 청크가 없으면 이유를 적고 실패한다.
- 모든 probe를 test.fail()로만 고정하는 안은 버렸다. 어떤 이유로든
  실패하면 통과해서 fixture가 무엇을 기록했는지 보지 못한다.
- 커밋한 문서: docs/testing/frontend-platform-testing-strategy.md에
  증명 위치와 판정을 바꾸는 곳이 그 spec 하나라는 것을 적는다.

위험·한계
- 모든 browser spec이 쓰는 fixture의 구조가 바뀐다. 판정 내용은 같다.
- 다른 spec도 browserFailureVerdict를 바꿔 strict 검사를 끌 수 있다.
  allowedBrowserFailure를 /.*/로 주는 것과 같은 수준의 노출이고 막는
  검사는 더하지 않았다.
- 샘플을 지운 제품에서 기능 실행부 모양이 바뀌면 3번 test가 실패한다.
  그때는 test를 다른 청크로 옮기거나 이유를 적고 지워야 한다.

검증
- desktop batch에서 확인:
  corepack pnpm exec playwright test tests/e2e/preload-use.spec.ts (세 엔진)
- 테스트 장치만 바꾼 커밋이라 RED는 변이로 본다.
  - 11-R3(strict fixture가 check 결과를 버림): "records a modulepreload
    the page never runs"가 세 엔진에서 실패해야 한다.
  - WEBKIT_UNUSED_PRELOAD_GUESS를 /.*/로: "ignores WebKit's
    unused-preload guess word for word and nothing else"가 실패해야 한다.
  - browserFailureVerdict 기본값의 expect 제거: "fails a test whose page
    writes a console error"가 "expected to fail" 위반으로 실패해야 한다.

Refs: 1105/11-01
2026-11-06 01:05:22 +09:00
DongHyeonka e72fb6e290 docs(testing): 테스트 전략이 지운 auth-recovery 테스트 대신 V3의 401 판정을 가리킨다
문제
docs/testing/frontend-platform-testing-strategy.md 11.2절이 "401 뒤 인증 복구
흐름은 tests/integration/auth-recovery.test.ts가 다룬다"고 적는다. 그 파일은
V2 클라이언트를 지울 때(048f490a) 같이 지웠고, V3 실행기에는 401 뒤 복구·재전송
흐름이 없다. 문서를 따라가면 없는 테스트와 없는 동작을 찾게 된다. 이 문서는
docs/README.md 1절 밖(목표 설계)이라 verify:documentation이 보지 않는다.

고른 방법
- 문장을 지금 동작으로 고친다: V3는 401을 UNAUTHENTICATED로 끝내고 다시 보내지
  않는다(http-execution-v3.ts), 판정은 tests/unit/http-execution-v3.test.ts가
  검사한다. 지운 파일 이름은 backtick 경로로 남기지 않는다.
- 1103/12-05의 남은 둘(지운 심볼 이름 검사, 1절 밖 문서 검사)은 이 커밋에서
  하지 않는다. 심볼 검사는 지난 리뷰가 버린 대안이다(지운 이름 목록을 따로
  관리해야 하고 오탐이 많다). 1절 밖 문서는 목표 설계라 일부러 없는 경로를
  적는다. 2절 문서의 backtick repo 경로 중 없는 것이 15개쯤이고 대부분
  계획 경로다(src/domain, src/generated, V2 파일 등). 검사로 넓히려면 문서별
  예외 방식부터 정해야 한다(결정 대기).

위험·한계
- 같은 종류의 옛 경로는 1절 밖 다른 문서에 남아 있다(2026-07-30 결정 정본의
  V2 http 파일 등). 이 커밋은 리뷰가 든 한 곳만 고친다.

검증
- 문서만 바꿨다. 이 문서를 보는 자동 검사는 없다(1절 밖). desktop batch에서
  corepack pnpm verify:documentation이 그대로 통과하는지만 본다.

Refs: 1103/12-05
2026-11-05 22:41:50 +09:00
DongHyeonka 9655958bda fix(ci): test:system 사전 점검이 bwrap namespace를 실제로 만들어 본다
문제: FE-GATE-013의 provider sandbox는 bwrap을 --unshare-pid
--unshare-ipc --unshare-uts --unshare-net으로 띄운다. bwrap이 setuid가
아니므로 비특권 user namespace가 있어야 한다. 사전 점검
(scripts/check-system-test-prerequisites.ts)은 실행 파일·cgroup·systemd
bus만 보고 bwrap을 한 번도 실행하지 않는다. 그래서 이 제한이 있는 호스트
(Ubuntu 24.04, kernel.apparmor_restrict_unprivileged_userns=1)에서 PASS를
낸 뒤 provider 테스트 114건 중 18건이 "bwrap: loopback: Failed
RTM_NEWADDR: Operation not permitted" 또는 그 provider를 기다린 시간
초과로 실패한다. 이 조건은 runner 요구 목록, gate 정의, workflow 어디에도
없고 운영 원장의 일회성 메모에만 있다.

고른 방법:
- 사전 점검이 provider와 같은 namespace 옵션으로 bwrap에서 /bin/true를 한
  번 띄운다. 실패하면 "this host does not allow unprivileged user and
  network namespaces", bwrap stderr(최대 4줄), user namespace sysctl 값,
  고치는 방법 셋(AppArmor profile, sysctl, 다른 runner)을 적고 exit 1.
  기존 검사(실행 파일 3개, cgroup v2, systemd bus)는 그대로 둔다.
- 옵션 목록을 scripts/lib/provider-sandbox-namespaces.ts로 옮기고
  run-and-validate-provider.ts와 사전 점검이 같은 상수를 쓴다. 둘이
  갈라지면 점검이 다른 것을 시험하게 된다.
- 점검을 findSystemTestPrerequisiteFailures(host)로 내보내고 access·
  readFile·spawn을 주입받는다. CLI 동작(출력·exit 코드)은 같다.
- config/ci/gates.json의 FE-GATE-013에 hostRequirements 두 줄을 둔다.
  gate schema에 선택 필드를 더하고, generator가 그 gate를 도는 job의
  runs-on 바로 위에 "# FE-GATE-013 runner requirement: ..." 주석으로
  그린다. runner를 고르는 사람이 보는 자리다. 줄바꿈은 기존 nonEmpty
  규칙이 막으므로 주석 밖으로 나갈 수 없다. 이 필드는 gate의 명령·증거가
  아니라 runner 설명이라 기준선 gate shape 해시에는 넣지 않았다(기준선
  재기록 불필요).
- 요구 목록 세 곳(docs/operations/ci-quality-gates.md,
  docs/security/supply-chain.md, docs/testing/taxonomy.md)과 README merge
  게이트 절에 조건을 적었다. ci-quality-gates.md에 AppArmor profile 예시를
  두었다.

버린 대안:
- namespace가 없으면 provider 테스트를 skip: 거짓 초록이다.
- FE-GATE-013을 release 단계로 옮김: PR마다 sandbox 검사를 잃는다.
- probe를 systemd-run --user --scope 안에서 돌림: 리뷰 11-R10에서 scope
  안과 밖의 결과가 같았다. 직접 실행이 더 단순하다.
- workflow에 요구 사항을 runs-on label로 표현: runner label 체계가 아직
  없다. 주석이 지금 가능한 가장 작은 표시다.

위험·한계:
- probe는 bwrap에 --ro-bind / /만 준다. --size 같은 provider의 다른
  옵션 지원은 여기서 보지 않는다(기존과 같다). probe가 다른 이유로
  실패해도 namespace 문구가 나오지만 bwrap stderr를 같이 적는다.
- 호스트를 고칠지는 호스트 소유자가 정한다. 이 커밋은 조건을 적고 알리기만
  한다. 이 desktop에서 FE-GATE-013은 여전히 실패하고, 이제 첫 단계에서
  이유와 함께 실패한다.
- gate schema에 선택 필드 hostRequirements가 생겼다. 기존 gates.json과
  제품 overlay는 그대로 통과한다.

검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/system-test-prerequisites.test.ts tests/unit/ci-workflow-generation.test.ts
- corepack pnpm check:ci, check:types, lint, verify:documentation
- desktop에서 node scripts/check-system-test-prerequisites.ts가 exit 1과
  namespace 문구를 내는지, FE-GATE-013이 그 단계에서 멈추는지

Refs: 1105/12-01, 1105/11-02
2026-11-05 22:06:59 +09:00
DongHyeonka aad005cbce fix(test): 브라우저 테스트가 WebKit의 3초 preload 추정 대신 실제 사용을 검사한다
문제: FE-GATE-008이 webkit에서 가끔 "The resource … was preloaded using
link preload but not used within a few seconds from the window's load
event" 경고로 떨어졌다(desktop 부하 0.68, i18n.spec.ts:60, 반복 10회 중
3회). 부하 탓이 아니었다. WebKit은 load 3초 뒤 한 번, 아직 아무 요청도 쓰지
않은 preload를 경고한다. 플랫폼 구성 화면은 들어갈 때 기능 실행부를 모두
불러오고(15-01), Vite는 그 청크와 정적 의존 청크를 한꺼번에 modulepreload
한다. 화면을 load 뒤 2.5초쯤 열면 module graph가 가장 깊은
reference-schemas에 닿기 전에 WebKit 검사가 돈다. 그 청크는 곧 쓰인다(표가
그려지고 link로 한 번만 받는다). 반대로 정말 안 쓰는 preload는 Chromium·
Firefox에서 늘, WebKit에서도 test가 3초 전에 끝나면 아무도 잡지 않았다
(1103/11-09).

고른 방법:
- strict fixture가 WebKit의 그 문구 하나만 정확한 패턴으로 무시한다. 다른
  console warning·error는 그대로 실패다.
- 대신 tests/support/browser/preload-use.ts가 세 엔진에서 같은 방법으로
  "preload한 script가 실제로 실행됐는가"를 본다.
  - 문서가 받은 `<link rel=modulepreload|preload>`를 첫 바이트 전부터
    MutationObserver로 적고, 끝에 남은 link도 더한다.
  - page.route로 build script(`/assets/*.js`)에 "이 URL이 평가됐다"를 적는
    문장 하나를 앞에 붙인다.
  - test 끝에 preload됐는데 평가되지 않은 script를 `preloadunused:`로
    실패시킨다. 진행 중인 dynamic import는 5초까지 기다린다.
- "사용"을 평가로 판정하는 이유: preload는 받기만 하거나(WebKit·Firefox)
  받아서 parse만 한다(Chromium). 어느 엔진도 평가하지 않는다. 그래서 그
  문장은 module graph가 그 청크를 실제로 실행했을 때만 돈다. WebKit의
  "참조됨"과 달리 시각에 기대지 않는다.
- 볼 수 없는 것은 따로 이름을 붙여 실패시킨다(fail closed).
  - script가 아닌 preload는 `preloadunverifiable:<as>:`.
  - Service Worker가 문서를 제어할 때 만든 preload는
    `preloadunverifiable:service-worker:`. 그 요청은 worker가 답해서
    page.route가 못 본다. context.route로 worker가 받는 것을 표시하면
    release manifest의 sha256 대조가 깨진다.
  - route.fetch가 세 번 실패해 표시 없이 넘어간 script는
    `preloadunverifiable:unmarked:`. 처음 구현은 이때 조용히
    route.continue()로 넘겨 쓰인 청크를 안 쓴 것으로 보고했다(webkit
    reference-form 1건).
- 일부러 실패를 일으키는 spec은 그 실패가 남기는 preload만 허용한다.
  - boot-module-failure: 깨진 build의 boot 정적 closure.
  - old-tab-chunk-recovery: 없어진 청크와 함께 preload된 청크. 전에는 이
    허용이 WebKit 경고 문구로만 있었다.
  - service-worker-update: worker 제어 중 preload만.
  - production-csp는 build script를 직접 fulfill하므로, 표시를 유지하는
    fulfillBuildScript를 쓴다.

버린 대안:
- (A) lazy dynamic import의 JS 의존성 preload를 끈다. 경고는 원리상 없어지지만
  test의 추정에 맞춰 제품을 바꾸는 것이다. lazy 라우트 첫 진입마다 1~2 RTT가
  늘고, 그 화면은 lab이 재는 화면(FE-GATE-026)이다.
- 청크 단계를 줄인다. 창이 좁아질 뿐이다.
- 3초 뒤에 화면에 들어간다. 사용자가 보는 경고를 test에서 숨긴다.

위험·한계:
- 모든 strict fixture test가 build script를 page.route로 받는다.
- 끝에 열려 있는 문서만 검사한다. 이동해 버린 문서의 기록은 같이 사라진다.
- fixture가 검사하는 것은 fixture의 page 하나다(console 검사와 같다).
- worker가 제어하는 문서의 preload는 검사하지 못한다(이름을 붙여 실패,
  service-worker-update만 허용).

검증 (desktop, CI=true와 workflow env):
- RED(검사 stub): 새 preload-use.spec 9건 중 7건 실패.
  - 변이 test는 세 엔진 모두 Expected
    ["preloadunused:/assets/async-state-Cxfod8c-.js"], Received [].
  - 부모 청크 3.5초 지연 scenario는 webkit만 "console:warning:The resource
    …/reference-schemas-DICBcHlO.js was preloaded using link preload but not
    used …"로 실패.
- GREEN: 9 passed.
- 변이를 fixture에 직접 넣은 probe(커밋 안 함), 안 쓰는 modulepreload 하나:
  - 이전 fixture(8a3b16a): chromium·firefox·webkit 3/3 통과(놓침).
  - 새 fixture: 3/3 실패,
    "preloadunused:/assets/async-state-Cxfod8c-.js".
- 부모 청크 3.5초 지연 probe:
  - 이전 fixture: webkit 실패.
  - 새 fixture: 3/3 통과. webkit은 여전히 reference-schemas 경고를 냈다
    (probe guesses ["reference-schemas-DICBcHlO.js was preloa…"]).
- 전체 e2e(playwright.config.ts): 202 passed, 3 skipped(기존 firefox SW skip).
- check:types:test, 바꾼 파일 eslint 통과.
2026-11-05 08:13:56 +09:00
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00
DongHyeonka fd11d08a89 fix(docs): 참조 기능 전용 script를 문서 검사가 요구하지 않게 적는다
문제
test:sample-removal은 참조 기능을 지울 때 그 전용 script
test:reference-feature도 package.json에서 지운다. 샘플을 지운 프로젝트도
같다. 그런데 docs/testing/taxonomy.md와 원장 두 행이 그 script를 백틱·명령
형태로 적어, 문서 검사가 "names package scripts that do not exist:
test:reference-feature"로 실패했다(b6bfc9b snapshot의 드릴 실행).

고른 방법
- 참조 기능 경로와 같은 규칙(patterns.md 첫머리): 참조 기능이 가진 script는
  백틱이나 `corepack pnpm` 없이 적고 "참조 기능과 함께 지워진다"를 붙인다.

위험·한계
- 템플릿에서도 문서 검사가 이 script 이름의 존재를 보지 않는다.

검증
- 샘플·SAMPLE_EXTRAS·fixture 전용 테스트를 지우고 test:reference-feature를
  package.json에서 뺀 복사본(sim-sample-docs.sh)에서 verify:documentation
  PASS_SCOPED. 저장소에서도 PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-04
2026-11-04 22:08:25 +09:00
DongHyeonka b0195e3d59 ci(visual): 브라우저 설치 단계가 시각 테스트 글꼴 패키지를 설치한다
문제
tests/visual/fonts.conf는 Noto Sans·Noto Sans CJK·Liberation Mono가
있는 OS 글꼴 디렉터리만 읽는다. 생성 workflow의 브라우저 설치 단계는
`playwright install --with-deps` 한 줄이고, Playwright 의존 패키지에는
이 글꼴이 없다. 그래서 빈 러너에서는 FE-GATE-008이 코드와 무관하게
`visual-fonts` 단계에서 실패한다(1101/11-02의 남은 절반).

고른 방법
- 생성기(scripts/generate-ci-workflow.ts)의 browser-install 단계가
  `--with-deps` 뒤에 글꼴 패키지 4개를 apt-get으로 설치한다.
  `--with-deps`가 이미 패키지 목록을 갱신했으므로 update를 다시 하지
  않는다. root가 아닌 러너에서만 sudo를 붙인다.
- 패키지 목록을 scripts/lib/visual-test-fonts.ts 한 곳에 두고 생성기와
  tests/visual/fonts.setup.ts의 설치 안내가 같이 읽는다.
- 글꼴이 필요한 것은 FE-GATE-008뿐이지만 브라우저 단계 두 곳 모두에
  넣었다. 게이트 ID로 갈라 쓰면 생성기가 게이트 목록에 묶인다.
- 버린 대안: job container 고정(러너의 컨테이너 지원 미확인),
  ci:gate가 패키지 설치(개발자 PC에서도 sudo 요구).

위험·한계
- 실제 러너나 깨끗한 Ubuntu 24.04 컨테이너에서 이 단계를 돌리지
  않았다. 패키지 이름과 디렉터리는 이 호스트(Ubuntu)와 fonts.conf로만
  확인했다.
- CJK 패키지 때문에 브라우저 job 설치 시간이 수십 MB만큼 는다.
- gates.json은 바꾸지 않았다(단계 종류는 그대로 browser-install).

검증
- ci-workflow-generation 새 테스트: 생성기 수정 전 실패, 수정 뒤 통과.
  파일 전체 424건 통과(스냅샷 1건 갱신).
- generate:ci-workflow로 workflow 재생성. check:ci PASS.
- lint, check:types:node, check:types:test, verify:documentation PASS.

Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-02
2026-11-04 20:18:40 +09:00
DongHyeonka 5d064b8ace test(features): 기능을 더해도 기능 밖 테스트와 시나리오 하네스가 깨지지 않게 한다 (16-02)
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).

방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
  context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
  만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.

위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
  실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
  제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
  http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
  스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
  테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
  a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
  breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
  않았다.

검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
2026-11-03 01:49:11 +09:00
DongHyeonka 498ae87554 test(evidence): HTTP 시나리오와 타입 음성 fixture를 테스트 계약으로 옮긴다 (0929/10-02)
문제: 샘플 제거 절차(scripts/test-sample-removal.ts)의 SAMPLE_EXTRAS가
플랫폼 검사도 함께 지운다. HTTP 실패 시나리오 카탈로그(57개)와 tests/mocks,
test:http-scenario-evidence(FE-GATE-007), 기능 API 타입 음성 fixture 8개와
check:types:fixture:* 8개(FE-GATE-003)가 참조 기능 계약을 import해서
샘플 소유로 묶여 있었다. 드릴은 플랫폼 경로 4개만 확인하므로 통과하고,
제품은 가드레일이 줄었다는 것을 모른다.

방법: 카탈로그와 handler를 tests/helpers/external-contract-fixture.ts의
테스트 계약(TEST_LIST/DETAIL, 명령)으로 옮겼다. 바이트 상한·명령 여부·성공
status는 계약에서 읽는다. 명령은 효과를 분류하는 패키지처럼
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT를 더해 기존 기대값(401/403/429·422·
409 CONFLICT는 NOT_APPLIED, 409 IN_FLIGHT·404·503은 MAYBE_APPLIED)을
그대로 지킨다. TEST_CREATE_HTTP_CONTRACT의 분류기는 실행기 테스트가
"분류기 없음"을 확인하는 데 쓰므로 바꾸지 않았다. 문제 스키마에 선택
code만 더했다.
타입 fixture는 fixture tsconfig만 컴파일하는 fixture-feature-contract.ts의
테스트 기능(operation ID를 literal로 좁힌 테스트 계약, "fixture-feature"
입력 등록)을 쓴다. 등록 augmentation이 app·test 프로그램에 들어가지 않는다.
참조 기능 전용 handler(성공 응답만 쓰였다)는 tests/features/reference-feature
로 옮겼다. test-evidence.json의 owner는 platform이다. SAMPLE_EXTRAS에서
이 경로·스크립트를 빼고, 드릴의 플랫폼 보존 확인 목록에 16개 경로를 더했다.
샘플이 증거 정책을 갖지 않으므로 "등록 안 됨" 오류 검사는 지웠다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
검사는 계속 사라진다.

위험: fixture 스크립트 이름(check:types:fixture:reference-operation)과
파일 이름은 그대로라 이름이 내용(TEST_GET_ENTITY)과 다르다. CI 스크립트·
gates·워크플로 스냅샷을 함께 바꿔야 해서 미뤘다. 드릴의 제외 목록에 있는
tests/unit/http-scenario-evidence.test.ts는 그대로 뒀다.
test:sample-removal 자체는 pnpm이 필요해 돌리지 않았다.

검증: RED는 기준 복사본에 드릴의 삭제 목록을 적용했다. 카탈로그 테스트·
tests/mocks·타입 fixture 16파일이 지워지고 CI 스크립트 9개가 빠지는데 보존
확인은 4/4로 통과한다. GREEN은 같은 적용 뒤 보존 확인 16/16, 잔여 이름은
드릴이 빼는 removal-fixture.test.ts 하나, 타입 fixture 8개가 기존과 같은
진단(TS2345·2741·2353·2322·2345·2322·2322·2339) 1건씩으로 실패, 카탈로그
57/57 실행·check-test-evidence --scenario-only PASS, tests/component와
카탈로그 36파일 226개 통과, tsc -p tsconfig.test.json 통과. worktree에서는
테스트 계약 사용 파일·참조 기능·카탈로그 59파일 535개, scale session 2파일
통과, 음성 fixture의 양성 대조 컴파일 통과, tsc test·node 통과,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
2026-11-03 01:18:36 +09:00
DongHyeonka 1604ef132e docs(testing): 시각 회귀 13.4절을 실제 기준선 5장에 맞춘다 (11-04)
문제: 테스트 전략 문서 13.4절은 "필수 baseline"으로 각 page template,
모든 primitive group, invalid form, 열린 dialog·drawer·menu,
pseudo-locale·RTL 등을 적는다. 실제 기준선은
tests/visual/platform.visual.spec.ts의 5장이다. invalid form, 열린
dialog·menu, RTL, page template별 기준선은 없다. check-test-evidence는
기준선이 4장 이상인지만 본다. 다운스트림이 이 목록을 보고 보호되지 않는
화면을 보호된다고 믿을 수 있다.

고른 방법: 리뷰 최소 개선안대로 목록을 "현재 기준선 5장"과 "제품이 늘릴
후보"로 나눈다. 5장마다 경로, viewport·테마·locale, 덮는 상태를 적고,
VD-08 5항의 최초 기준선 4장에 플랫폼 개요가 더해진 범위라고 밝힌다.
검사가 장 수만 본다는 것도 적는다. VD-08은 "최초 기준선은 … 포함한다"는
결정 기록이라 고치지 않았다(5장과 모순되지 않는다).

버린 대안: 기준선을 문서 목록만큼 늘리기. 골든이 늘고 11-03의 골든
재촬영과 겹친다. 리뷰도 기준선 확장은 11-02·11-03 뒤로 미뤘다.

위험·한계: check-test-evidence가 각 화면의 존재를 검사하게 바꾸지는
않았다. 문서만 고친다.

검증(문서와 코드 대조, RED 대신):
- 수정 전: 13.4절 목록 8항목 중 invalid form, open dialog/menu, RTL,
  page template은 platform.visual.spec.ts의 5개 toHaveScreenshot과
  __snapshots__ PNG 5장 어디에도 없다.
- 수정 뒤: 문서의 5장 이름이 __snapshots__ 파일 이름(-chromium-visual-linux
  앞부분)과 일치. state 기준선이 401·403·404를 담는 것은
  src/presentation/examples/state-gallery-page.tsx의 AuthRequired·
  Forbidden·NotFound 표면으로 확인.
- verify-documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-04
2026-11-01 23:18:45 +09:00
DongHyeonka 5ce3db98ef test(visual): 시각 회귀 허용치를 절대 픽셀 50으로 바꾼다 (11-03)
문제: 시각 회귀 허용치가 maxDiffPixelRatio 0.002(이미지의 0.2%)라서
긴 화면일수록 허용 픽셀이 커진다. 넓은 셸 1440×900은 2,592 px를
허용한다. 그래서 UI-04 수정을 되돌린 회귀(선택 상자 값 잘림, 1,145 px)가
통과한다. 골든이 코드와 조금씩 달라져도 실패하지 않아 어느 골든이 낡았는지
알 수 없다. VD-08 8항은 작은 rasterization 차이만 허용한다고 적는다.

고른 방법: maxDiffPixels 50. 11-02로 글꼴과 래스터 설정을 고정한 뒤
같은 호스트에서 깨끗한 빌드를 다시 찍으면 0 px 차이다(아래 검증). 50은
흩어진 anti-aliasing만 덮고, 지금까지 잰 가장 작은 실제 변화(낡은
compact 골든 175 px)보다 작다. tests/unit/visual-regression-tolerance.test.ts가
비율 허용치가 다시 들어오거나 절대값이 175 이상이 되면 실패한다.

버린 대안:
- 0 px: 이 호스트에서는 흔들리지 않았지만 다른 Linux 러너의 래스터는
  재 보지 못했다(U-1). 50은 실제 회귀를 놓치지 않는 범위의 여유다.
- 위험 영역만 따로 찍어 비율의 분모를 줄이기: 골든이 늘어난다.
- 현상 유지: 회귀를 놓친다.

위험·한계:
- 커밋된 골든 2장이 새 허용치에서 실패한다. 깨끗한 빌드 기준으로 넓은
  셸 614 px, compact 6,955 px 다르다. compact는 이 변경 전 0.2%에서도
  이미 실패한다(08-01의 서랍 변경). 골든은 다시 찍지 않았다. 오케스트레이터가
  마지막에 한 번 찍는다. 나머지 3장은 0 px로 통과한다.
- 다른 호스트의 래스터 차이는 재 보지 못했다. 수십 px 넘게 나오면 그
  측정값으로 허용치를 정한다(리뷰 재검토 조건).

검증 (pnpm을 부르지 않으려고 build-frontend.ts로 빌드하고 webServer만
vite preview로 바꾼 로컬 설정 사본으로 실행, flock, 비교 대상은 깨끗한
빌드로 새로 찍은 scratch 골든. 저장소 골든은 건드리지 않았다):
- 깨끗한 빌드 vs scratch 골든, 허용치 0, --repeat-each=3: 16 passed.
- RED: UI-04 변이(f1b9d3c의 shell.css 변경을 git apply -R)를 넣은 빌드,
  0.2% 비율: 6 passed. 허용치 0: 넓은 셸만 "1145 pixels are different".
- GREEN: 같은 변이, maxDiffPixels 50: 넓은 셸 실패(1,145 px), 나머지 통과.
  변이를 되돌리고 다시 빌드, --repeat-each=2: 11 passed.
- 새 단위 테스트는 수정 전 "expected 0.002 to be undefined"로 실패,
  수정 뒤 2 passed. supply-chain·deletable-history-documents·
  test-evidence-source-rules와 함께 37 passed.
- tsc(node·test), eslint, check-test-evidence --source-only PASS,
  verify-documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-03
2026-11-01 23:18:45 +09:00
DongHyeonka 95e7d1107c test(vitest): skip·todo·only가 남은 실행을 실패시킨다 (10-04)
문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나
`it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다.
`context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고,
로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다.
check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(`
글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다.

고른 방법:
- vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다.
- scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에
  state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다.
  -t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다.
  게이트는 실행을 좁히지 않는다.
- reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의
  reporters를 대체하므로 config에 두면 package script에서 빠진다.
  run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다.
  호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다.

버린 대안:
- 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가
  skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼
  적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog,
  로컬 단일 파일)은 아예 보지 못한다.
- tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이
  돌지 않아 잡지 못한다.
- eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고
  `context.skip()`을 못 잡는다.

위험·한계:
- run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지
  않는다. allowOnly는 config라서 그때도 적용된다.
- 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다.
  Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가
  나온다.
- 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다.
- check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만
  이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은
  Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에
  "quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도
  quarantine이 필요해지면 허용 목록을 따로 둬야 한다.
- 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다.

검증:
- RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을
  CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1
  skipped | 1 todo"). only+CI=true만 exit 1.
- 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find
  module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패.
- GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s)
  did not run" 목록, only는 "Unexpected .only modifier". junit reporter를
  준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트
  11 passed.
- 빠른 계층 전체(unit·component·integration·contract·runtime-schema·
  platform·architecture·features·release·scripts·recipes, pnpm 설치를
  하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed,
  1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트
  inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록
  출력은 없었다.
- tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일),
  check-ci-contract, generate-ci-workflow --check,
  verify-documentation-readiness(PASS_SCOPED) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04
2026-11-01 23:18:45 +09:00
DongHyeonka 08b5ccc86e test(visual): 시각 테스트 글꼴을 fonts.conf로 고정하고 먼저 검사한다 (11-02)
시각 골든은 작성자 PC가 고른 글꼴 4종(Noto Sans, Noto Sans CJK KR
Regular·Black, Liberation Mono)으로 찍혀 있는데, 설정은 글꼴을 고정하지
않는다. 같은 dist에서 FONTCONFIG_FILE만 Playwright가 맨 Ubuntu에 까는
글꼴 구성으로 바꿔도 5장이 모두 실패한다. 실패는 화면 전체가 밀린 pixel
diff라서 원인이 글꼴이라는 것을 알기 어렵다. CI 러너도 같은 처지다.

고른 방법 (리뷰 4.1절 c′, 사용자 결정):
- tests/visual/fonts.conf가 Debian/Ubuntu 경로의 세 디렉터리
  (truetype/noto, opentype/noto, truetype/liberation)만 보이게 한다.
  playwright.visual.config.ts가 use.launchOptions.env로 그 파일을
  FONTCONFIG_FILE에 넣는다. 바깥 FONTCONFIG_FILE은 덮어쓴다. CI
  workflow는 바꾸지 않았다.
- 같은 파일에서 래스터 설정(antialias, hintslight, rgb, lcddefault,
  autohint 끔)을 호스트 규칙 뒤에 고정한다. 글꼴 이름이 같아도 hint와
  sub-pixel 기본값이 다른 호스트에서는 5장이 모두 실패했다(검증 참고).
- visual-fonts setup 프로젝트(tests/visual/fonts.setup.ts)를
  chromium-visual의 의존으로 둔다. 실제 앱 페이지에 탐침 요소를 넣고
  CDP CSS.getPlatformFontsForNode로 실제로 그려진 글꼴을 비교한다.
  다르면 설치할 패키지 이름과 함께 실패하고, 스크린샷 테스트는 돌지
  않는다. 글꼴이 하나도 없으면 렌더러가 죽으므로 그 경우도 같은 안내로
  감싼다. test:visual:update도 같은 검사를 먼저 거친다.

버린 대안:
- fc-match 사전 검사: fontconfig CLI가 러너에 있다는 보장이 없고,
  Chromium이 실제로 고르는 글꼴과 다를 수 있다. 앱 페이지의 code는
  Liberation Mono인데, lang 없는 빈 페이지에서는 Noto Mono가 잡혔다.
  그래서 탐침도 앱 페이지 안에 넣는다.
- document.fonts.check: 시스템 글꼴은 없어도 true를 돌려준다.
- /etc/fonts/conf.d를 빼고 별칭 규칙을 직접 쓰기: system-ui와
  Courier New(Chromium 기본 monospace) 해석을 다시 만들어야 한다.
  리뷰 실험 D(호스트 규칙 포함, 5/5)에서 벗어난다.
- 컨테이너 이미지, 글꼴 파일 커밋, 임계값 완화: 리뷰 4.1절에서 기각.

위험·한계:
- 바이트가 아니라 패키지 이름을 고정한다. 배포판이 글꼴 버전을 바꾸면
  이름 검사는 통과하고 pixel diff로 실패할 수 있다.
- generic family 별칭(sans-serif → Noto Sans, Courier New → Liberation
  Mono)은 호스트의 /etc/fonts/conf.d를 따른다. 별칭이 다른 호스트
  (예: Noto Sans를 우선하지 않는 fontconfig 2.14 미만)에서는
  visual-fonts가 실패한다. 조용히 다른 글꼴로 바뀌지는 않는다.
- 사용자 fontconfig(50-user.conf)가 디렉터리를 더하면 그 글꼴도
  보인다. 탐침 4종이 바뀌면 검사가 잡는다.
- Linux 전용이다. macOS와 Windows의 Chromium은 fontconfig를 읽지 않는다.
- 실제 Gitea 러너에서는 돌려 보지 못했다(U-1). CI에 apt 설치 단계를
  넣지 않았고, 필요한 패키지는 테스트 전략 문서 13.4절에 적었다.
- 골든은 다시 찍지 않았다.

검증 (같은 dist, flock, `npx playwright test --config
playwright.visual.config.ts`. pnpm을 부르지 않으려고 webServer만
vite preview로 바꾼 로컬 사본으로 실행):
- 수정 전, 바깥 FONTCONFIG_FILE=A(Playwright Ubuntu 글꼴 + DejaVu):
  5 failed, toHaveScreenshot diff(46,356 px, 4%)
- 검사만 넣고 같은 A: 1 failed, 5 did not run. 설치 안내와 함께
  latin=DejaVu Sans, korean=WenQuanYi Zen Hei
- RED, fonts.conf가 빈 디렉터리만 볼 때: 1 failed, 5 did not run.
  같은 설치 안내 + "The font probe page did not render"
- GREEN, 호스트 환경: 6 passed. 바깥 A: 6 passed(기존 골든 5/5)
- 러너 근사(호스트 conf.d에서 language-selector, ubuntulegacy,
  sub-pixel-rgb 제외): 6 passed
- 다른 래스터 기본값(hinting-full, sub-pixel-none): 고정 블록 없이
  5 failed(setup만 통과, diff 2%), 고정 블록 포함 6 passed
- tsc(app·node·test), eslint, check-test-evidence --source-only PASS,
  verify-documentation-readiness PASS_SCOPED, vitest supply-chain과
  tests/architecture 53 passed

Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-02, 4.1절
2026-11-01 21:00:06 +09:00
DongHyeonka 112c870fe3 fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).

고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.

버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
  NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
  같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
  APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
  틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
  변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
  목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
  응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
  요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
  만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.

위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
  contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
  적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
  고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
  백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
  (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
  템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
  Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
  참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
  referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
  code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
  (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
  이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
  "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
  확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
  run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
  두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.

검증
- RED(수정 전): reference-production-vertical "keeps the key when the
  resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
  분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
  (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
  카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
  tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
  제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
  PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
  읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
  check:ci 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 19:09:47 +09:00
DongHyeonkaandClaude Opus 5.5 84f2ab929f docs(testing): match determinism, scenario and taxonomy text to the code (10-07)
The strategy doc promised clock/random/scheduler helpers that no test used
(the helper's clearTimeout did nothing), listed three scenario IDs the
catalog does not have, and the taxonomy described an older test:all and a
child-process rule tests/unit does not follow. Removes the unused helper.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:30:28 +09:00
DongHyeonkaandClaude Opus 5.5 d68e25a2ad test(coverage): ratchet live retry, contract bridge and IndexedDB modules (10-04)
The policy guarded legacy retry-policy.ts but not the live V3 retry and
contract path rules, and the strategy doc claimed 19 modules at 90% targets.
The doc now states the enforced ratchet. The below-threshold fixture used the
pre-counter summary shape and failed with a TypeError instead of the
'Risk coverage failed:' diagnostic the negative gate expects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:28:02 +09:00
DongHyeonkaandClaude Opus 5.5 72e7ae1139 test(vitest): collect only Vitest files and document running one file (10-05)
A bare vitest run collected 26 Playwright specs and the host-bound system
suite. The documented one-file command goes through run-vitest.ts, which
renders the gitignored product index a fresh clone lacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:22:16 +09:00
DongHyeonkaandClaude Opus 5.5 7298275271 ci: move the signed manual a11y review to release gate FE-GATE-028 (08-06)
The signed review is per release candidate, so the merge gate could never pass.
FE-GATE-009 now checks only the record format; the checked-in records are
source-controlled evidence, not command output.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:07:53 +09:00
donghyeon-ka ec7f20e2ee refactor: 프론트엔드 리펙토링 2026-09-18 22:05:42 +09:00
donghyeon-ka 5cc41467ae refactor: 프론트 템플릿 리펙토링 2026-09-18 15:16:58 +09:00
DongHyeonka 76bf9f1aa3 test: lock V8 coverage counter semantics 2026-08-02 10:12:34 +09:00
DongHyeonka 5cecbb9820 refactor: align coverage counter provenance 2026-08-02 09:31:28 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 6c73b845bd feat: add optional frontend adapter recipes 2026-07-26 17:57:04 +09:00
donghyeon-ka 98d4fd4960 feat: harden test and registry evidence 2026-07-26 17:15:26 +09:00
donghyeon-ka 5173b6c8d6 feat: add diagnostics and telemetry runtime 2026-07-26 16:42:27 +09:00
donghyeon-ka 668bf05b48 feat: add internationalization message platform 2026-07-26 16:17:39 +09:00
donghyeon-ka 13f28ef811 feat: add design system platform 2026-07-26 15:49:07 +09:00
donghyeon-ka b327d7370b feat: add form and page platform 2026-07-26 15:22:52 +09:00
donghyeon-ka c11be43f20 feat: add removable reference feature vertical slice 2026-07-26 14:56:34 +09:00
donghyeon-ka ce0040e407 feat: execute route and release recovery contracts 2026-07-26 14:26:39 +09:00
donghyeon-ka ad55e21a3d feat: execute HTTP and query runtime contracts 2026-07-26 14:05:12 +09:00
donghyeon-ka 0fed35586a feat: establish TypeScript-aware frontend tooling 2026-07-26 13:41:23 +09:00
donghyeon-ka 68342e25ce docs: audit frontend platform capabilities 2026-07-26 02:09:06 +09:00
donghyeon-ka 236909be64 test: harden starter experience quality contract 2026-07-26 00:28:09 +09:00
donghyeon-ka 946cf407b0 test: establish frontend gate taxonomy 2026-07-25 20:41:44 +09:00