문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.
고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
`aria-description`, `aria-roledescription`, `aria-valuetext`,
`aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
`src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
"I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
`english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
(`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
`reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
`reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
된다.
버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).
위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
`eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).
검증:
- RED(수정 전):
- E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
user-facing locale literal in .../reference-resource-status-page.tsx",
exit 1
- E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
- `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
english-accessible-name.tsx, english-jsx-text.tsx", exit 2
- 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
- E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
- E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
- `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
"I18n allowed fixture was rejected", exit 2
- ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
`verify-documentation-readiness.ts` PASS_SCOPED
Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
문제
MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의
MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고
부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는
{ ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름
MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을
요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper,
참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거
조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수
없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다.
eslint 설정에 폐기 검사가 없다.
고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로)
- boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry,
mappingSuccess, mappingFailure와 바인딩 mapSuccess가
BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도
옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서
런타임과 공개 시그니처는 바뀌지 않는다.
- D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은
BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가
필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는
같은 type의 alias" 문장도 고쳤다.
- 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어
@typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core
no-restricted-imports의 patterns.importNames로 boundary-mapper의
MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다.
층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로
restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은
그 앞에 둔 공통 블록이 받는다.
버린 대안
- 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2)
후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상
공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0,
lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다.
- typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint
설정(속도·설정 범위)이 필요하다.
- 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유
문자열로 넓어져 계약이 약해진다.
위험·한계
- 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭).
리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야
충족된다. 제거 시점은 릴리스 결정으로 남긴다.
- 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint
오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데,
반환 타입은 같은 모양이라 영향 없음).
- adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다.
같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다.
검증
- RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors
("'MappingResult' import from '../../contracts/boundary-mapper.ts' is
restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure
같은 꼴).
- GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일)
--max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep).
- 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit
tests/features tests/platform tests/component tests/contract
tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외)
273 files / 3136 tests 중 3135 통과. 실패 1건은
provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이
변경과 무관한 scripts/lib 프로세스 테스트).
check-registries PASS, verify-documentation-readiness PASS_SCOPED,
check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로
사실상 미검증.
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
Graph violations printed only the rule name and file pair, and ESLint only the
pattern. The graph now prints the import specifier and the rule's comment,
every rule has one, and ESLint pattern groups carry a message.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
config/architecture/layers.json was read by nothing and contradicted the
enforced adapter rule. It is deleted; .dependency-cruiser.json is the one rule
source, and the ESLint layer patterns are marked as an editor aid.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
getBuildConfig defaulted to the whole import.meta.env, so Vite inlined every
loaded VITE_* value, read or not. Values are now read by key, a lint rule bans
whole-object references in src, and vite.config refuses VITE_* names missing
from ENV_REGISTRY. A build test pins the values that must stay in the bundle.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>