Commit Graph
13 Commits
Author SHA1 Message Date
DongHyeonka 16202fd48d 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에서 금지).
2026-11-03 01:13:16 +09:00
DongHyeonka e714c0d770 fix(design-system): 디자인 검사가 deg 색상각과 시스템 글꼴 이름을 받는다 (12-04)
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.

고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
  그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
  <값>; contrast needs an opaque oklch(L C H), hue in degrees with or
  without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
  검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
  규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
  해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
  새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
  곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.

위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.

검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
  실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
  "names the value it cannot compute …" 메시지 불일치, "-apple-system"
  expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
  null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
  probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
  oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
  / 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
  documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
2026-11-01 22:16:26 +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
donghyeon-kaandClaude Opus 5.5 a5fff8f4b7 fix(presentation): draw query access failures with the access surfaces (08-11)
AsyncSurface drew auth-required, forbidden and not-found query failures with
its own copy while the gallery used AccessSurface. Both now use one set, and
a state surface without a handler shows no dead button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:03:27 +09:00
DongHyeonkaandClaude Opus 5.5 b691e38cc6 refactor(presentation): split theme.css into ordered files (Q-6.8-13d)
theme.css (1435 lines) is now an import-order entry point: tailwind, the
three token files, then styles/theme/{base,shell,primitives,templates,
pages,responsive}.css holding the original rules verbatim and in the same
order (components-layer chunks each wrap their part in
`@layer components`). check-design-system now reads every CSS file under
styles/ so the undefined-token check still covers the moved rules; the
design-system doc names the new layout.

Verified: `corepack pnpm build` before and after produce the same CSS
asset, dist/assets/index-6KRF2bCu.css, byte-identical (cmp and sha256
bdaa8521...). A probe undefined token in theme/pages.css fails
check:design-system. Lane gates pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:44:38 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +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 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 9a92c11792 feat: add Tailwind semantic design tokens 2026-07-25 21:09:07 +09:00