b96d61d8f773855257b66d219e1ea2c33059fcb9
5
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
7f633106bb |
test(a11y): 접근성 e2e가 기능 API를 descriptor 모양의 빈 목록으로 답한다
문제 tests/e2e/accessibility.spec.ts는 보호 라우트의 모든 API에 맨 배열 `[]`를 답했다. create:feature가 만드는 기능은 responseEnvelope: "ENVELOPE_V1"이라 `[]`는 ENVELOPE_MISMATCH가 되고, 페이지는 경고 상자를 그린다. spec은 h1과 axe만 봐서 오류 화면을 검사하고도 통과했고, 증거는 그 라우트를 "passed"로 적었다. 경로 파라미터는 `:resourceId`만 바꿔서 다른 이름을 쓰는 기능은 이 템플릿 파일을 고쳐야 했다. 고른 방법 (결정 D4 (b)) - tests/e2e/support/installed-api-answers.ts가 요청을 설치된 GET descriptor에서 method와 pathTemplate으로 찾는다. 출력 스키마가 빈 목록을 받으면 그 operation의 모양으로 답한다(Envelope면 MSW 시나리오와 같은 successEnvelope, 아니면 맨 배열). - 목록만 읽은 라우트는 로딩이 끝난 뒤 경고 상자(role="alert")가 없다고 단언한다. 모양이 다시 어긋나면 axe 통과 대신 여기서 실패한다. - 경로 파라미터는 이름과 상관없이 모두 a11y-1로 바꾼다. 기능을 더해도 spec을 고치지 않는다(16-03 앞 절반). - 설치된 GET이 아닌 요청, 빈 목록을 받지 않는 파라미터 없는 GET은 501로 답하고 그 목록이 비어 있다고 단언한다. - 매뉴얼 01·03, starter-experience, create-feature 참조, 수동 점검 문서의 "모든 API에 []", ".replace를 잇는다" 문장을 동작에 맞췄다. - 버린 대안: 전역 Envelope 응답(참조 기능 DTO가 거꾸로 깨짐), 기능마다 접근성 spec 생성(파일·실행 시간 증가). 위험·한계 - 한 자원을 읽는 GET(상세 페이지)에는 빈 목록 말고 줄 본문이 없다. 그 라우트는 지금처럼 실패 상태로 검사하고 a11y-data-state annotation만 남긴다. 경고 상자 단언은 그 라우트에서 건너뛴다. - write-a11y-report.ts의 증거는 annotation을 읽지 않는다. 상세 라우트도 "passed"로 적힌다. 검증 - 새 unit 테스트 6건: helper가 없을 때 실패, 추가 뒤 통과. - 템플릿 상태 chromium test:a11y 대상 spec 14건 통과. - create:feature sample-feature 상태에서 `@a11y /sample` 세 엔진 통과. 변이 1(Envelope 대신 맨 배열): 세 엔진 모두 경고 상자 단언으로 실패. 변이 2(빈·성공 상태에서만 보이는 이름 없는 버튼): 세 엔진 모두 axe button-name으로 실패. 생성 파일은 지웠다. - check:types:test, eslint, verify:documentation, check:ci 통과. Refs: docs/reviews/2026-11-03-maturity-review/11-tests-browser-release-scale.md 11-01 Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-03 |
||
|
|
365d8c3c02 |
fix(contracts): 쿠키 인증 쓰기는 CSRF 헤더를 요구하는 프로필만 조립한다
문제 브라우저는 쿠키를 어느 사이트의 요청에든 붙이므로, 쿠키로 인증하는 쓰기 요청은 페이지만 넣을 수 있는 헤더(CSRF 토큰)가 있어야 서버가 진짜 요청을 가른다. V2 클라이언트는 resolveRestSecurityProfiles로 "쿠키 프로필 + GET·HEAD 밖 method면 HEADER CSRF 프로필"을 강제했다. 048f490·12f3bb7이 V2를 지운 뒤 V3에는 이 검사가 없다. V3 프로필 설치 규칙은 SAME_ORIGIN_COOKIE에 쿠키 전송과 bearer 금지만 요구한다. 그래서 제품이 CSRF 헤더 없는 쿠키 프로필을 POST에 붙여도 조립이 통과한다. 고른 방법 assertHttpContract가 operation의 auth profile을 설치된 레지스트리에서 찾아, 쓰기(GET·HEAD 밖)인데 SAME_ORIGIN_COOKIE이고 requiredCredentialHeaders에 x-csrf-token·x-xsrf-token이 없으면 operation·method·프로필 이름을 담아 거절한다. 읽기 쿠키 프로필은 CSRF 없이 그대로 된다(tech-log·memento 예시와 같다). 버린 대안 - 프로필 설치 때 모든 쿠키 프로필에 CSRF 요구: 읽기 전용 쿠키 프로필 (MEMENTO_BFF_READ 등)까지 막는다. method는 operation에만 있다. - 요청 때(attachCredentials) 검사: 조립 때 잡을 수 있는 설정 실수를 사용자 요청 시점까지 미룬다. 위험·한계 - 이미 CSRF 없는 쿠키 쓰기 프로필을 쓰는 제품은 조립이 실패한다. 의도한 실패다(CHANGELOG [보안]). - 헤더 값이 올바른 CSRF 토큰인지는 서버만 안다. 프론트는 헤더가 반드시 실리는지만 보장한다(requiredCredentialHeaders가 없으면 fetch 0회). 검증 - RED: tests/unit/rest-profile-contract.test.ts "refuses a write whose cookie profile requires no CSRF header" 실패(조립이 통과). - GREEN: 같은 파일 7건 통과. CSRF를 요구하는 쓰기와 CSRF 없는 쿠키 읽기는 조립된다. - check:types, lint, check:architecture, check:registries, test:unit 2,568, test:integration 117, test:component 245 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7 |
||
|
|
12f3bb7862 |
refactor(contracts)!: V2 API 행을 지우고 FE-REG-API를 HTTP descriptor에서 뽑는다
문제 기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행 (defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고, contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게 http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가 없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을 위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석 (resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만 남기고, 레지스트리 기준선 재승인을 승인했다. 고른 방법 - src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다. 조립된 contribution의 descriptor마다 operationId, featureId, method, path, authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope, request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는 같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다. requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다. - FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다. installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고 FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다. - realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과 retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics· replayPolicy 대신). - rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립 때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다. - 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로 바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를 지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다. - create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를 만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다. - 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다 (digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음). - 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다. 버린 대안 - V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은 실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다. - 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary· unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를 쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다. 위험·한계 - BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes 의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다. 옮기는 법은 CHANGELOG에 적는다. - V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF 모드)가 사라졌다. V3 descriptor에는 그 칸이 없다. - BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2 필드를 갖지만 자체 계약이라 바꾸지 않았다. 검증 - check:types, lint, check:architecture, check:registries(11 registries PASS, compatibility=none), check:ci, check:diagnostics, check:adapter-inventory, verify:documentation 통과. - test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함), test:integration 114, test:component 245, test:contract 23, test:runtime-schema 56, tests/features 99 통과. - tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두 번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다. - check:bundle 통과. 초기 JS 201,598 → 200,911 B. - test:feature-scaffold 16개, test:sample-removal 23개 검사 통과. BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다. defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS, createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile, loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은 operation을 contract contribution에만 적고, schemas 행을 feature-runtime에 넘긴다. |
||
|
|
5c2f8b875c |
docs(manual): 매뉴얼만으로 기능을 추가한 실험의 막힘 5건을 메운다 (1101/16-01)
문제: docs/manual(
|
||
|
|
8b2048763b |
docs(manual): 새 기능 추가 매뉴얼을 docs/manual에 쓴다 (U9, 1101/16-01)
문제 - 새 기능을 추가하는 절차가 starter-experience.md의 영어 단계 7개와 폴더 밖 파일 표뿐이다. 무엇을 고르는지(context, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿), 어느 검사가 무엇을 못 잡는지, 실패 메시지가 어느 파일을 가리키는지는 리뷰 문서(16 영역 8절)에만 있다. 리뷰 문서는 복사한 프로젝트가 지울 수 있는 작업 이력이다. - create:feature(U7)가 생겼지만 그 인자, 만드는 파일, 사람이 해야 하는 일 (a11y 서명, 자리표시자 계약 신원 교체)을 설명하는 문서가 없다. 고른 방법 - docs/manual/을 한국어로 쓴다(결정 5). README(독자, 읽는 순서, 두는 것과 안 두는 것), 01 작업 순서 0~11단계, 02 결정표 6개, 03 기능 폴더 밖 파일, reference/ 4개(create-feature, global-ids, patterns, errors). - 01은 1단계에서 create:feature로 시작하는 길을 기본으로 두고, 단계마다 정할 것, 기준, 잡는 검사(명령·게이트 ID·메시지)와 못 잡는 것, 쓸 스킬을 적는다. 리뷰 시점의 "못 잡음"은 지금 코드로 다시 확인해 고쳤다(예: 루트 밖 라우트는 이제 앱 모듈이 적재 때 거부한다). - 실패 메시지는 src·scripts의 문자열을 그대로 옮기고 값 자리만 <...>로 바꿨다. - 목록 대신 정본 위치를 적는다(공통 원칙 8). route ID는 ROUTE_REGISTRY, 게이트는 config/ci/gates.json, 백엔드 멱등성 응답은 백엔드 템플릿 docs/web/http-contract.md §2를 가리키고 표를 옮기지 않는다. 공통 원칙은 design-docs의 conventions/feature-design-principles.md를 번호로만 가리킨다. - 03은 starter-experience.md의 폴더 밖 표를 정본으로 링크하고 복사하지 않는다. 생성 명령이 하는 것 / 사람이 꼭 하는 것 / 조건부 / 고치지 않는 것으로 나누고, 표에 없는 절차(a11y 서명, 자리표시자 교체, 기능 삭제)만 더한다. - 16 영역 8.4의 금지 목록(목표 디렉터리 구조 절, 예전 폴더 밖 표, 참조 페이지의 경로 문자열)은 링크하지 않고 README에 그 이유를 적는다. - 버린 대안: 리뷰 8절을 그대로 옮기기(리뷰 시점 사실이 지금 코드와 다르고 지울 수 있는 이력에 기댄다), starter-experience.md에 한국어 절을 더하기 (입구 문서는 영어이고 다른 에이전트 소유다), 실패 메시지를 요약해 쓰기 (메시지로 문서를 검색할 수 없다). 위험·한계 - docs/README.md §1 링크는 넣지 않았다(오케스트레이터 몫). 링크하기 전에는 verify:documentation이 이 폴더를 검사하지 않는다. 폴더 링크는 바로 아래 .md만 검사하므로 reference/도 따로 링크해야 한다. - 플랫폼 규칙 근거는 다른 에이전트가 옮기는 scale-architecture.md를 절 번호로 가리킨다. 이 커밋에는 그 파일이 없어 링크 대신 백틱 이름으로 썼다. - 매뉴얼로 막을 수 없는 것이 남는다. 기능 전용 e2e spec은 tests/e2e에만 둘 수 있어 기능 폴더 밖이다. --context reference-context는 참조 기능 테스트 하나를 깨뜨린다. 생성 드릴은 check:bundle을 돌리지 않는다. - "실험 E를 매뉴얼만 보고 다시 하기"는 문서로만 점검했고 실제로 다시 돌리지 않았다. 검증 - docs/README.md §1에 manual/, manual/reference/ 링크를 임시로 넣고 node scripts/verify-documentation-readiness.ts: PASS_SCOPED. 7개 문서 모두 missingPaths·missingScripts·unknownGateIds 0. 임시 링크는 되돌렸다. - 변이: patterns.md에 없는 경로·script·게이트 ID를 넣으면 세 항목을 모두 말하며 FAIL_UNVERIFIED. - 메시지 대조 스크립트: 백틱 안 148개 문구 중 106개는 코드에 그대로 있고, 42개는 코드가 조각을 이어 만드는 문구(접두어·필드 이름·값 채움)라 하나씩 코드에서 확인했다. - node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts tests/unit/repository-file-inventory.test.ts: 3파일 38건 통과. |