docs(manual): 샘플 대신 생성 기능 경로와 시험하는 코드 조각을 예제로 둔다

매뉴얼 예제 칸 14곳(S4 3.3절)과 산문 30여 곳이 참조 기능을
가리킨다. problem details(Envelope가 아닌 백엔드) 응답 매핑의 예는
참조 기능에만 있다.

생성기 출력이 그 모양을 만들면 그 경로로 바꿨다. 없으면 매뉴얼 안
코드 조각으로 썼다: problem details의 분류와 매핑(02 결정표 4절,
소유자 결정 D1), 도메인 모델, 검색값 스키마와 hook, 실패 행동 hook,
403 페이지 시험. 조각마다 manual-code-block 표식에 둘 경로를 적는다.
tests/unit/manual-code-blocks.test.ts가 저장소 사본에 create:feature
invoice-feature --with-create를 만들고 조각을 그 경로에 그대로 넣어
tsc(app, test), eslint, check:architecture, 그 기능 폴더의 vitest를
돈다. 조각의 동작은 tests/fixtures/manual-code-blocks/가 본다.

위험: 403 조각은 본문 없는 403으로 답한다. 공유 시나리오
forbidden-403(JSON 본문)은 jsdom + MSW에서 실행기의 본문 cancel이
끝나지 않아 화면이 로딩에 머물렀다. 실행기는 고치지 않았다. 사본에
이미 invoice-feature가 있는 프로젝트에서는 이 시험이 생성 단계에서
실패한다.

검증(desktop): test:unit 213 files 3096 passed(이 커밋까지),
verify:documentation PASS_SCOPED, lint 통과.
This commit is contained in:
DongHyeonka
2026-11-08 13:51:55 +09:00
parent b72cd7d4a7
commit 01cac930e0
11 changed files with 626 additions and 53 deletions
+144 -20
View File
@@ -5,9 +5,12 @@
- 뼈대는 손으로 만들지 않는다. `corepack pnpm create:feature <id>`로 만든다.
- 뼈대를 실제 기능으로 바꾸는 순서가 아래 0~11단계다.
참조 기능(`src/features/reference-feature/`)을 복사해 이름을 바꾸는 방법은 쓰지 않는다.
그 방법은 접두어 없는 전역 ID, 참조 전용 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다.
다른 기능 폴더를 복사해 이름을 바꾸는 방법은 쓰지 않는다.
그 방법은 접두어 없는 전역 ID, 복사된 계약 출처, 기능 밖 테스트 의존 때문에 여러 번 막힌다.
생성 명령은 이 문제를 미리 피한 파일을 쓴다.
템플릿에는 복사해 볼 기능 샘플이 없다. 생성 뼈대에 없는 모양은 이 매뉴얼 안의 코드 조각으로 보인다.
코드 조각 위의 `manual-code-block` 표식이 그 조각을 둘 자리다. 조각은 `create:feature invoice-feature --with-create`로 만든 기능을 기준으로 쓴다.
`tests/unit/manual-code-blocks.test.ts`가 그 기능을 저장소 사본에 만들고 조각을 그 자리에 그대로 넣어 타입 검사와 동작 시험을 돌린다.
## 전체 흐름
@@ -107,7 +110,7 @@ corepack pnpm create:feature invoice-feature
→ 만든 파일과 다음 할 일 출력
```
- 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와, 참조 기능이 있는 동안의 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 [03 문서 A](03-outside-feature-folder.md#a-생성-명령이-만든다)에 있다.
- 기능과 함께 커밋할 추적 파일은 둘이다. dev server manifest와 초기 JS 기록이다. 기능 브랜치 둘이 같은 줄에서 충돌하면 명령을 다시 돌린다. 표와 명령은 [03 문서 A](03-outside-feature-folder.md#a-생성-명령이-만든다)에 있다.
① **정할 것**
@@ -130,8 +133,6 @@ corepack pnpm create:feature invoice-feature
- 생성기가 거부한다. 선언 헤더가 리터럴이 아님, 없는 context, 예산 초과.
- 이때 명령은 만든 파일을 모두 지우고 `the feature index generator rejected the feature, nothing was kept:`로 끝난다.
- 생성한 context 선언은 `tests/unit/create-feature.test.ts`가 생성기의 선언 읽기와 앱 모듈 조립으로 실행한다. 라우트가 그 루트 밖이면 그 테스트가 실패한다.
- `--context reference-context`로 참조 context에 넣을 수는 있다. 참조 기능의 라우팅 테스트는 참조 기능 자신의 라우트만 본다.
- 다만 경로가 `/examples/reference-resources/<base>`가 된다. 참조 기능을 지우면 context가 그 기능 때문에 남고, 그 경로 문자열이 제거 드릴(`test:sample-removal`)의 잔여 검사(`reference-resource`)에 걸린다(추론, 실행하지 않음). 남길 기능은 제품 context에 둔다.
④ **쓸 스킬**: `clean-architecture`, `codebase-design`
@@ -150,12 +151,34 @@ corepack pnpm create:feature invoice-feature
- 업무 규칙이 없으면 만들지 않는다. mapper가 DTO를 화면 값으로 바꾸는 것으로 충분하다.
- 있으면 `domain/<model>.ts`에 둔다.
- 생성 함수에서 불변식을 검사하고 `Object.freeze`로 고정한다.
- 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(참조 기능은 `name`을 `displayName`으로 바꾼다).
- 예제(참조 기능): `src/features/reference-feature/domain/`
- 이름은 와이어 필드가 아니라 업무 이름으로 짓는다(예: 와이어 `name`을 화면 값 `displayName`으로).
- 예: 청구서는 발행일 뒤에만 마감된다. `domain/<model>.ts` 한 파일이다.
<!-- manual-code-block: src/features/invoice-feature/domain/invoice.ts -->
```ts
export type Invoice = Readonly<{
invoiceId: string;
/** Calendar dates, YYYY-MM-DD. */
issuedOn: string;
dueOn: string;
}>;
/** An invoice falls due on or after the day it is issued. */
export function createInvoice(input: Invoice): Invoice {
if (!/^\d{4}-\d{2}-\d{2}$/u.test(input.issuedOn) || !/^\d{4}-\d{2}-\d{2}$/u.test(input.dueOn)) {
throw new RangeError("Invoice dates are calendar dates (YYYY-MM-DD).");
}
if (input.dueOn < input.issuedOn) {
throw new RangeError("An invoice falls due on or after the day it is issued.");
}
return Object.freeze({ ...input });
}
```
- 길이 제한(예: 제목 100자)은 domain이 아니라 경계 검증에 둔다.
- 경계 검증: 값이 앱에 들어오거나 나가는 자리(요청·응답 스키마, 폼 스키마)에서 하는 검사다.
- 서버가 정한 제한이면 `contracts/<base>-schemas.ts`에 상수로 두고 요청 스키마와 폼 스키마가 같은 상수를 쓴다. 숫자가 두 곳에서 갈라지지 않는다.
- 참조 기능도 이름 길이를 스키마(`reference-schemas.ts`)와 폼(`reference-resource-form.ts`)에만 둔다. `domain/`에는 없다.
- 생성 판(`--with-create`)도 이름 길이 상수(`<BASE>_NAME_MAX_LENGTH`)를 스키마(`contracts/<base>-schemas.ts`)와 폼(`presentation/<base>-form.ts`)에만 둔다. `domain/`에는 없다.
- domain에는 서버 제한이 바뀌어도 그대로인 업무 규칙만 둔다(예: "마감일은 시작일 뒤").
③ **잡는 검사 / 못 잡는 것**
@@ -241,7 +264,7 @@ DTO와 problem details(`type`·`title`·`status`)를 감싸지 않고 보내는
2. problem 스키마를 problem details 모양으로 바꾼다.
3. `classifyProblem`이 모든 판정을 정한다. 실행기가 먼저 정하는 판정은 없다.
참조 기능(`src/features/reference-feature/`)이 이 모양이다. 참조 기능의 MSW 본문도 DTO와 problem details다.
problem 스키마, 작성의 `commandEffect`, `mapProblem`의 예는 [02 결정표 4절](02-decision-tables.md#4-결과-불명)의 「problem details 백엔드의 예」에 있다. 그 기능의 MSW 본문도 DTO와 problem details로 손으로 적는다.
**입력과 스키마 메타데이터**
@@ -305,8 +328,8 @@ projectRequest: (input) => Object.freeze({
- 오류의 `reason`: `<featureId>/<operationId>: unknown authProfileId <id>`
- 스키마 ID나 operation ID가 겹치면 적재 때 그 ID를 말하며 실패한다.
- 예: `Invalid or duplicate schema definition: <schemaId>`, 계약 조립 `duplicate operation: <operationId>`
- `TEMPLATE_FIXTURE` 출처를 참조 기능 밖에서 쓰면 계약 조립이 거부한다.
- 오류의 `reason`: `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE`
- `TEMPLATE_FIXTURE` 출처를 제품 기능에 쓰면 계약 조립이 거부한다.
- 오류의 `reason`: `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to <fixture owner> only; pin an EXTERNAL_PACKAGE`
- zod를 직접 import하면 `check:architecture`가 `zod-is-reached-through-contracts-zod`로 막는다.
- 계약 패키지를 다른 파일에서 import하면 `external-contract-package-single-import-path`로 막는다.
- 자리표시자 신원은 staging·production 승인(`check:release-admission`, FE-GATE-027)이 거절한다.
@@ -376,10 +399,9 @@ projectRequest: (input) => Object.freeze({
- 읽기: 데이터를 그리는 화면. 목록 GET은 목록 route, 상세 GET은 상세 route.
- 쓰기: 저장 버튼이 있는 화면. 작성 폼 route가 따로 있으면 그 route.
- 여러 화면에서 부르면 주로 부르는 화면 하나를 고른다. 이름표는 하나뿐이다.
- 참조 기능은 생성 operation에 목록 route(`REFERENCE_RESOURCE_LIST`)를 적었다. 실제로 보내는 화면은 폼 route다. 동작은 같고 기록의 이름표만 다르다. 새 기능은 위 기준을 따른다.
- `needs`에는 실제로 쓰는 것만 적는다.
- 템플릿이 만들지 않는 capability(예: `indexedDb`)는 `src/bootstrap/product-composition.ts`에서 만든다. 제품이 새로 만드는 capability의 타입은 `src/features/product-capabilities.ts`에 적는다. [03 문서](03-outside-feature-folder.md)를 본다.
- 문제 응답 매핑 예제(참조 기능): `src/features/reference-feature/adapters/reference-http-gateway.ts`
- 문제 응답 매핑 예제: 짝 백엔드는 `create:feature <id> --with-create`의 `adapters/<base>-http-gateway.ts`(400 `<BASE>_INVALID` → 이름 칸). problem details 백엔드는 [02 결정표 4절](02-decision-tables.md#4-결과-불명)의 조각 2.
③ **잡는 검사 / 못 잡는 것**
@@ -423,11 +445,49 @@ projectRequest: (input) => Object.freeze({
② **기준**
- 경로는 계약에만 적는다. 페이지와 링크는 route ID와 `buildRouteUrl`로 URL을 만든다. 경로 문자열을 페이지에 다시 적지 않는다.
- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제(참조 기능): `src/features/reference-feature/context-routes.ts`.
- 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: <codecId>`로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제(참조 기능): `src/features/reference-feature/presentation/reference-routes.ts`.
- 파라미터나 검색값이 있는 라우트는 `context-routes.ts`의 handle에 `codecs`를 싣는다. 예제: `create:feature <id> --with-create`의 `context-routes.ts`(상세 라우트의 params codec).
- 링크용 URL 함수도 같은 codec을 `buildRouteUrl`의 세 번째 인자로 넘긴다. 기본 생성 판의 목록 라우트는 파라미터가 없어서 넘기지 않는다. `--with-create` 판의 상세 라우트는 codec을 넘긴다. 안 넘기면 `Unregistered route codec: <codecId>`로 throw한다. codec ID는 계약 `routeRuntimeContracts`의 `paramsCodec`·`searchCodec` 값이다. 예제: `--with-create` 판의 `presentation/<base>-routes.ts`.
- 검색값(`?status=open`)을 읽는 목록은 아래 두 조각을 더한다. 생성 뼈대의 목록 라우트에는 검색값이 없다.
- 조각 1(`contracts/<base>-list-search.ts`)이 검색값 스키마다. 그 스키마를 `presentation/<base>-route-codecs.ts`의 `<BASE>_ROUTE_CODECS`에 `<Pascal>ListSearch`라는 codec ID로 싣는다.
- 계약의 목록 라우트 `searchSchema`와 `routeRuntimeContracts`의 `searchCodec`을 그 codec ID로 바꾼다. 기본 판처럼 `context-routes.ts` handle에 `codecs`가 없으면 `--with-create` 판처럼 싣는다.
- 라우터는 페이지를 그리기 전에 그 codec으로 검색값을 해석한다. 틀린 값이면 페이지 대신 잘못된 경로 화면을 그린다.
- 조각 2(`presentation/use-<base>-list-filters.ts`)가 페이지에서 그 값을 타입대로 읽는 hook이다. 같은 codec으로 다시 읽으므로 cast가 없다.
<!-- manual-code-block: src/features/invoice-feature/contracts/invoice-list-search.ts -->
```ts
import { z } from "../../../contracts/zod.ts";
/** The list route's search values (`?status=open`). Absent means every invoice. */
export const invoiceListSearchSchema = z
.object({ status: z.enum(["open", "paid"]).optional() })
.strict();
export type InvoiceListSearch = z.output<typeof invoiceListSearchSchema>;
```
<!-- manual-code-block: src/features/invoice-feature/presentation/use-invoice-list-filters.ts -->
```ts
import { useMemo } from "react";
import { useRouteInput } from "../../../presentation/routes/route-input.tsx";
import {
invoiceListSearchSchema,
type InvoiceListSearch,
} from "../contracts/invoice-list-search.ts";
/**
* The router parsed the search with this codec before the page rendered.
* Reading it back through the same codec gives its type without a cast.
*/
export function useInvoiceListFilters(): InvoiceListSearch {
const { search } = useRouteInput();
return useMemo(() => invoiceListSearchSchema.parse(search), [search]);
}
```
- 상세 경로는 목록 경로 뒤에 `/items/:<id 이름>`을 붙인다. 예: `/notice/items/:noticeId`. `/notice/:noticeId`로 두지 않는다.
- 라우터(React Router)는 같은 자리에서 정적 경로를 먼저 고른다. 작성 폼 `/notice/new`가 있으면 id가 `new`인 공지는 `/notice/:noticeId`로 열 수 없다.
- `items/`를 끼우면 정적 경로와 겹치지 않는다. 참조 기능도 이렇게 한다(`/examples/reference-resources/items/:resourceId`).
- `items/`를 끼우면 정적 경로와 겹치지 않는다. 생성 판(`--with-create`)의 상세 라우트도 이렇게 한다(`<목록 경로>/items/:<camel>Id`).
- `tests/e2e/accessibility.spec.ts`는 기능마다 고치지 않는다(1103/16-03).
- 이 spec은 등록된 모든 라우트를 열어 axe로 검사한다. 경로 파라미터는 이름과 상관없이 모두 `a11y-1`로 바꾼다. 파라미터 스키마가 이 값을 거부하면 기능 페이지 대신 잘못된 경로 화면을 검사하므로, id 스키마는 짧은 영문·숫자 문자열을 받게 둔다.
- API 요청은 설치된 descriptor에서 method와 `pathTemplate`으로 찾아 답한다. 목록 조회에는 빈 목록을 그 operation의 모양(`responseEnvelope: "ENVELOPE_V1"`이면 Envelope)으로 답한다. 그 뒤 경고 상자(`role="alert"`)가 없는지 본다. 그래서 목록 페이지는 빈 상태로 검사된다.
@@ -492,7 +552,7 @@ projectRequest: (input) => Object.freeze({
});
```
- 예제(참조 기능): `src/features/reference-feature/presentation/use-reference-feature.ts`의 생성 뮤테이션 정책.
- 예제: `create:feature <id> --with-create`의 `presentation/use-<base>-create.ts`.
③ **잡는 검사 / 못 잡는 것**
@@ -524,7 +584,40 @@ projectRequest: (input) => Object.freeze({
- 화면 문구는 모두 catalog에서 가져온다(`message(key)`).
- 링크는 6단계의 URL 함수로 만든다.
- 결과 불명 화면 예제: `create:feature <id> --with-create`의 `presentation/<base>-create-page.tsx`(짝 백엔드 Envelope), 참조 기능의 `src/features/reference-feature/presentation/reference-resource-form-page.tsx`(problem details)
- 결과 불명 화면 예제: `create:feature <id> --with-create`의 `presentation/<base>-create-page.tsx`. problem details 백엔드도 화면은 같다. 다른 것은 `commandEffect`와 `mapProblem`뿐이다([02 결정표 4절](02-decision-tables.md#4-결과-불명)).
- 다시 시도가 아닌 실패 행동(다시 로그인, 안전한 화면으로 이동)의 버튼은 페이지가 handler를 넘길 때만 그려진다. 생성된 목록 페이지는 `onRetry`만 넘긴다.
- 실패의 `action`(`src/contracts/errors.ts`의 `ERROR_REGISTRY`)이 `reauth`(401)·`navigate`(403·404)일 때 쓸 hook이다. `AsyncSurface`에 `onAction={useInvoiceFailureAction(query.state.failure)}`로 넘긴다.
- `retry`는 쿼리(`onRetry`)가, `reload-once`는 청크 복구 경계가 맡는다. 이 hook은 `undefined`를 돌려준다.
<!-- manual-code-block: src/features/invoice-feature/presentation/use-invoice-failure-action.ts -->
```ts
import { useCallback } from "react";
import { useLocation, useNavigate } from "react-router-dom";
import type { AppFailure } from "../../../contracts/errors.ts";
import { useSession } from "../../../presentation/providers/session-provider.tsx";
/** Sign in again and come back here, or leave for the home screen. */
export function useInvoiceFailureAction(
failure: AppFailure | undefined,
): (() => void) | undefined {
const location = useLocation();
const navigate = useNavigate();
const { beginSignIn } = useSession();
const action = failure?.action;
const handleAction = useCallback(() => {
if (action === "reauth") {
const returnTo = `${location.pathname}${location.search}${location.hash}`;
void beginSignIn(returnTo).catch(() => {
void navigate("/");
});
return;
}
if (action === "navigate") void navigate("/");
}, [action, beginSignIn, location.hash, location.pathname, location.search, navigate]);
return action === "reauth" || action === "navigate" ? handleAction : undefined;
}
```
③ **잡는 검사 / 못 잡는 것**
@@ -621,7 +714,38 @@ projectRequest: (input) => Object.freeze({
expect(await posts[0]!.json()).toEqual({ title: "새 공지", body: "본문입니다." });
```
- 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제(참조 기능): `tests/features/reference-feature/reference-production-vertical.test.tsx`의 504 재전송 테스트.
- 핸들러를 직접 써서 요청을 모으는 방법도 있다. 예제: `create:feature <id> --with-create --keyed`의 `tests/features/<id>/<base>-create-page.test.tsx`(POST를 받을 때마다 사본을 모으고 같은 키 재전송을 본다).
- 서버 권한 거절(403)은 라우터를 거치는 페이지 테스트로 본다. 생성된 페이지 테스트와 같은 도우미(`<base>-test-app.tsx`)를 쓴다.
- 403은 본문 없이 답한다. 실행기는 401·403의 본문을 읽지 않고 닫는다. 페이지 테스트 환경(jsdom + MSW)에서 본문이 있는 403(공유 시나리오 `forbidden-403`)은 그 닫기가 끝나지 않아 화면이 로딩에 머물렀다(2026-11-08 확인).
<!-- manual-code-block: tests/features/invoice-feature/invoice-forbidden.test.tsx -->
```tsx
// @vitest-environment jsdom
import { screen, within } from "@testing-library/react";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { afterAll, afterEach, beforeAll, expect, it } from "vitest";
import { invoiceRouteUrl } from "../../../src/features/invoice-feature/presentation/invoice-routes.ts";
import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts";
import { API, openSignedIn } from "./invoice-test-app.tsx";
const api = setupServer();
beforeAll(() => api.listen({ onUnhandledRequest: "error" }));
afterEach(() => api.resetHandlers());
afterAll(() => api.close());
it("shows the forbidden state when the backend refuses the list", async () => {
api.use(http.get(`${API}/invoices`, () => new HttpResponse(null, { status: 403 })));
await openSignedIn(invoiceRouteUrl("INVOICE_LIST"));
const alert = await screen.findByRole("alert");
expect(
within(alert).getByRole("heading", { name: KO_MESSAGES["access.forbidden.title"] }),
).toBeVisible();
});
```
- 빠르게 돌리기: `node scripts/run-vitest.ts run tests/features/<id>`
- CI에서는 `test:coverage`(FE-GATE-005)가 `tests/features`를 돈다. `test:unit`은 `tests/unit`만 돈다.
@@ -683,7 +807,7 @@ corepack pnpm test:sample-removal -- --feature=invoice-feature
- 지연 페이지가 셸과 같은 구성요소(`Button`, `SearchField` 등)를 쓰면 그 구성요소가 공유 청크로 떨어져 초기 파일 수도 하나 늘 수 있다. 파일 수 상한(`initialJsFiles`)은 여유가 있다.
- 예산은 `config/performance/budgets.json`에 있다. 넘었을 때 고르는 법은 `docs/operations/performance-evidence.md`에 있다. 넘으면 예산을 올리기 전에 팀이 정한다.
- 생성 명령의 드릴(`test:feature-scaffold`)도 merge 단계 명령으로 이 검사를 돈다.
- 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)은 지운 뒤 기록을 다시 쓰고 검사한다.
- 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 기능과 함께 바뀐다. `test:unit`이 빌드와 대조한다. 생성 명령 출력 `Next:` 3번의 명령으로 다시 쓰고 같은 커밋에 넣는다. 기능 제거 드릴(`test:sample-removal -- --feature=<id>`)은 지운 뒤 기록을 다시 쓰고 검사한다.
- 로컬에서 FE-GATE-013을 돌리려면 `VITE_COMMIT_SHA=$(git rev-parse HEAD)`를 준다. 없으면 release candidate가 `source.revision`을 거절한다. 실패한 게이트의 로그는 `artifacts/quality/gates/FE-GATE-<NNN>.txt`에 있다.
- workflow와 같은 조건으로 돌리려면 README 로컬 merge 게이트 반복문 아래의 env 블록대로 `CI=true`와 CI 빌드 식별값(`VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)을 주고 깨끗한 clone에서 돌린다. 이 값 없이 통과해도 CI에서 떨어질 수 있다(1103/11-07, 11-08).
- 게이트는 한 checkout에서 하나씩 돌린다. 게이트와 증거 검사는 `dist`와 `artifacts/`의 고정 경로를 읽는다.
+122 -6
View File
@@ -50,9 +50,9 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
| | 배포된 계약 패키지 | 자리표시자 신원 | `TEMPLATE_FIXTURE` |
|---|---|---|---|
| 언제 | 백엔드가 `@org-contracts/<service>` 패키지를 배포했다 | 패키지가 아직 없다 | 쓰지 않는다. 참조 기능 전용이다 |
| 언제 | 백엔드가 `@org-contracts/<service>` 패키지를 배포했다 | 패키지가 아직 없다 | 쓰지 않는다. 템플릿이 예전 참조 샘플에 쓰던 출처다 |
| 만드는 법 | `create:feature`에 `--package`, `--digest`, `--revision`을 준다 | `create:feature`에 패키지 인자를 주지 않는다 | — |
| 로컬·개발 빌드 | 된다 | 된다 | 참조 기능 밖에서는 계약 조립이 거부한다 |
| 로컬·개발 빌드 | 된다 | 된다 | 제품 기능에 쓰면 계약 조립이 거부한다 |
| staging·production 승인 | 된다 | `check:release-admission`(FE-GATE-027)이 거절한다 | — |
자리표시자 값은 `src/contracts/deployment-admission.ts`의 세 상수다.
@@ -88,7 +88,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
|---|---|---|---|
| 서버 보장 | 멱등 키(`Idempotency-Key` 헤더)로 같은 요청의 중복 적용을 막는다 | 같은 요청을 여러 번 적용해도 결과가 같다 (키 없이) | 중복을 막지 못한다 |
| 자동 재시도 | 실제로 보내기 전까지만. 보낸 뒤 결과를 모르면 결과 불명(4절)으로 넘긴다. 예외: 짝 백엔드가 503 `IDEMPOTENCY_UNAVAILABLE`(실행 전 거절)로 답하면 `retryBudget` 안에서 같은 키로 다시 보낸다 | 된다 | 하지 않는다 |
| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 짝 백엔드는 `retryBudget: 1`(아래 표), 참조 기능은 `0` | — | `retryBudget: 0` 필수 |
| descriptor | `commandRecovery: { mode: "IDEMPOTENCY_REPLAY", operationIdentityField }` 필수. 짝 백엔드는 `retryBudget: 1`(아래 표). 503 같은 키 재전송 규칙이 없는 백엔드는 `0` | — | `retryBudget: 0` 필수 |
| 뮤테이션 정책 | `...commandMutationIdentity(<OPERATION>_CONTRACT)`가 `requiresIdempotencyKey: true`, `resendSafe: true`를 준다 | 같은 함수가 `requiresIdempotencyKey: false`, `resendSafe: true`를 준다 | 같은 함수가 둘 다 `false`로 준다 |
| 결과 불명 뒤 | "같은 요청으로 다시 보내기"와 같은 입력 저장이 같은 키로 간다 | 다시 보내기와 같은 입력 저장이 키 없이 간다(1106/03-03) | 확인만 남는다. 같은 입력 저장은 보내지 않는다 |
@@ -198,8 +198,8 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
→ V3 실행기
├─ responseEnvelope: "ENVELOPE_V1" (생성한 기능) → 실행기가 MAYBE_APPLIED로 정한다
│ KEYED이고 retryBudget > 0이면 먼저 같은 키로 다시 보낸다(3절). 예산을 다 쓰면 결과 불명
└─ Envelope 없음 (참조 기능) → 기능의 classifyProblem이 정한다
참조 기능: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED
└─ Envelope 없음 (problem details 백엔드) → 기능의 classifyProblem이 정한다
아래 예: 400·422와 정해 둔 409 code만 NOT_APPLIED → 503은 MAYBE_APPLIED
→ 결과 불명 화면 → "같은 요청으로 다시 보내기"가 같은 키로 보낸다
```
@@ -210,7 +210,123 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
**정본**: 어떤 status·code가 "적용 안 됨"인지는 `clean-architecture-backend-template/docs/web/http-contract.md` §2다.
**어디에 적나**: `contracts/<base>-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 예제(참조 기능): `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts`의 `CREATE_EFFECT`.
**어디에 적나**: `contracts/<base>-contract-contribution.ts`의 `commandEffect`(`classifyProblem`, `classifyStatus`, Envelope operation이면 `refusedBeforeWrite`). 짝 백엔드 예제는 `create:feature <id> --with-create`가 만든 그 파일이다. Envelope가 없는 백엔드의 예는 아래에 있다.
**problem details 백엔드의 예**
짝 백엔드가 아닌 백엔드는 DTO와 problem details(RFC 9457의 `type`·`title`·`status`)를 감싸지 않고 보낸다. 그 백엔드의 작성 operation이 쓰는 두 조각이다. 기능 이름은 `invoice-feature`(`create:feature invoice-feature --with-create`로 만든 기능)로 두었다. 자기 기능의 이름으로 바꿔 쓴다.
- 조각 1은 `contracts/<base>-problem-details.ts`다. problem 스키마와 검증기, 작성의 `commandEffect`를 둔다.
- descriptor마다 `responseEnvelope: "NONE" as const`, `problemValidator: <BASE>_PROBLEM_VALIDATOR`를 적는다. 작성 descriptor의 `commandEffect`는 `<BASE>_CREATE_EFFECT`다. Envelope operation 전용인 `refusedBeforeWrite`는 적지 않는다.
- 스키마 ID(`InvoiceProblem`)도 다른 스키마처럼 스키마 메타데이터(`contracts/<base>-schema-metadata.ts`)에 적는다. 없으면 `check:registries`가 실패한다.
- 조각 2는 `adapters/<base>-problem-mapping.ts`다. HTTP 바인딩의 `mapProblem`이 되는 함수다.
- `adapters/<base>-http-gateway.ts`의 작성 operation 정의에 `mapProblem: map<Base>CreateProblem`으로 넘긴다.
- 정하지 않은 status는 `undefined`를 돌려준다. 그러면 실행기가 status로 실패 종류를 정한다.
<!-- manual-code-block: src/features/invoice-feature/contracts/invoice-problem-details.ts -->
```ts
import { z } from "../../../contracts/zod.ts";
import type { CommandEffectDescriptor } from "../../../contracts/external-contract-runtime.ts";
import { zodValidator } from "../../../contracts/zod-validator.ts";
export const invoiceProblemSchema = z
.object({
type: z.string().min(1).max(512),
title: z.string().min(1).max(240),
status: z.int().min(100).max(599),
code: z.string().min(1).max(120).optional(),
// 422 field issues. The backend's messages are not kept.
issues: z
.array(
z
.object({
path: z.string().min(1).max(120),
code: z.string().min(1).max(80),
})
.strip(),
)
.max(50)
.optional(),
})
.strip();
export type InvoiceProblem = z.output<typeof invoiceProblemSchema>;
export const INVOICE_PROBLEM_VALIDATOR = zodValidator(
"InvoiceProblem",
invoiceProblemSchema,
);
/**
* A 409 is not by itself "refused": a resend with the same key can meet the
* first attempt still running. Only the conflict codes the backend sends
* before it writes are NOT_APPLIED; any other 409 stays MAYBE_APPLIED, so the
* next send reuses the key.
*/
const NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set(["CONFLICT"]);
export const INVOICE_CREATE_EFFECT: CommandEffectDescriptor<InvoiceProblem> =
Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem({
status,
problem,
}: Readonly<{ status: number; problem: InvoiceProblem }>) {
if (status === 400 || status === 422) return "NOT_APPLIED";
if (
status === 409 &&
problem.code !== undefined &&
NOT_APPLIED_CONFLICT_CODES.has(problem.code)
) {
return "NOT_APPLIED";
}
return "MAYBE_APPLIED";
},
// The backend refuses an unauthenticated, forbidden or rate-limited
// create before it touches state. Delete this line if it does not.
classifyStatus: () => "NOT_APPLIED" as const,
});
```
<!-- manual-code-block: src/features/invoice-feature/adapters/invoice-problem-mapping.ts -->
```ts
import type {
FeatureHttpProblemMapping,
SafeResponseMetadata,
} from "../../../adapters/http/index.ts";
import type { InvoiceProblem } from "../contracts/invoice-problem-details.ts";
export function mapInvoiceCreateProblem(
problem: InvoiceProblem,
metadata: SafeResponseMetadata,
): FeatureHttpProblemMapping | undefined {
if (metadata.status === 409) {
return Object.freeze({
kind: "CONFLICT" as const,
code: problem.code ?? "INVOICE_CONFLICT",
});
}
// The executor checked the key before it sent, so this names a key rule
// the two sides disagree on: keep the code for diagnostics.
if (metadata.status === 400 && problem.code === "IDEMPOTENCY_KEY_INVALID") {
return Object.freeze({
kind: "UNKNOWN_CLIENT_FAILURE" as const,
code: problem.code,
});
}
if (metadata.status === 422) {
return Object.freeze({
kind: "VALIDATION_REJECTED" as const,
code: problem.code ?? "INVOICE_REJECTED",
validationIssues: problem.issues ?? [],
});
}
return undefined;
}
```
- 이 두 조각은 `tests/unit/manual-code-blocks.test.ts`가 시험한다. 저장소 사본에 `create:feature invoice-feature --with-create`로 기능을 만들고, 조각을 위 경로에 그대로 넣어 타입 검사를 하고, 분류와 매핑이 위 설명대로인지 돌려 본다(`tests/fixtures/manual-code-blocks/`).
**틀리면**
+2 -2
View File
@@ -38,7 +38,7 @@
| 파일 | 누가 쓰나 | 다시 쓰는 명령 | 안 넣으면 |
|---|---|---|---|
| `public/release-manifest.json` (dev server의 manifest) | `create:feature`가 생성 뒤 바로 쓴다. 설치된 계약 패키지 목록(`packages`)과 그 다이제스트(`setDigest`) | `node scripts/write-dev-release-manifest.ts` | `test:unit`(`tests/unit/dev-release-manifest.test.ts`)이 다시 쓰는 명령을 말하며 실패한다. dev server가 `CONTRACT_SET_PACKAGE_MISSING`으로 부팅하지 못한다 |
| `config/scale/feature-shape-ceilings.json`의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 참조 기능이 설치돼 있는 동안만 있다(참조 기능과 함께 지워진다) | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write` | `test:unit`이 빌드와 대조해 실패한다 |
| `config/scale/feature-shape-ceilings.json`의 `initialJavascript` (초기 JS 기록) | 사람이 명령으로 쓴다. 기능을 더하거나 뺄 때마다 바뀐다 | `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write` | `test:unit`이 빌드와 대조해 실패한다 |
- **브랜치 둘이 충돌한다.** `setDigest`는 설치된 패키지 전체의 해시 한 줄이고, `initialJavascript`는 빌드 전체의 합계다. 기능을 하나씩 더한 두 브랜치는 같은 줄을 다른 값으로 바꾼다. 둘째 브랜치를 합칠 때 텍스트 충돌이 난다.
- **충돌하면 손으로 값을 합치지 않는다.** 아무 쪽이나 고른 뒤 위 명령을 다시 돌려 그 결과를 커밋한다. 두 기능이 다 들어간 상태의 값이 나온다. 손으로 합친 값이 틀리면 `test:unit`이 같은 명령을 말하며 실패한다.
@@ -212,7 +212,7 @@ src/features/product-capabilities.ts (SERVICE_WORKER = ACTIVE)
- `config/testing/risk-coverage.json`에서 그 기능을 가리키는 행
- 그 기능만 쓰던 제품 capability, 제품 인증 프로필, 계약 패키지 의존성
그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 참조 기능이 설치돼 있으면 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다.
그다음 dev manifest(`public/release-manifest.json`)의 계약 패키지를 `node scripts/write-dev-release-manifest.ts`로 다시 쓰고, 초기 JS 기록(`config/scale/feature-shape-ceilings.json`)도 `node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write`로 다시 쓴다(위 A의 표). 그리고 레지스트리 기준선을 다시 찍는다. 행을 빼는 것은 breaking 변경이다.
```bash
REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON="<id> removed" corepack pnpm update:registry-baseline
+2 -2
View File
@@ -75,8 +75,8 @@ README (이 문서)
- `docs/architecture/starter-experience.md`의 예전 "폴더 밖 수정" 4행 표와 "governance는 바뀌지 않는다" 문장(2026-11-01 리뷰 시점 판).
- 그 판은 실제로 고쳐야 하는 파일을 다 적지 않았다.
- 지금 판의 "Adding a feature" 절 표가 정본이다. 03 문서가 이 표를 링크한다.
- 참조 기능 페이지의 경로 문자열과 route 입력 cast.
- 지금은 고쳐졌다. 그래도 이 매뉴얼의 예시는 route ID와 `buildRouteUrl`로만 쓴다.
- 템플릿이 예전에 두던 참조 샘플 기능과 예제 화면을 가리키는 문서와 리뷰 기록.
- 그 샘플은 지웠다. 이 매뉴얼의 예시는 생성 명령 출력과 매뉴얼 안 코드 조각이다(`tests/unit/manual-code-blocks.test.ts`가 시험한다).
## 문서와 코드가 다를 때
+2 -3
View File
@@ -2,7 +2,7 @@
모든 merge 게이트를 통과하는 가장 작은 기능을 만드는 명령이다. 정본은 `scripts/create-feature.ts`이고, `--with-create`가 더하는 부분은 `scripts/create-feature-write-slice.ts`다.
`test:feature-scaffold`가 생성한 기능으로 `config/ci/gates.json`의 merge 단계 명령을 돌려 확인한다. 브라우저 게이트(FE-GATE-008·009의 브라우저 명령)와 `test:system`은 빼고 돈다. 뺀 명령과 이유는 `scripts/lib/feature-scaffold-drill.ts`에 있다.
템플릿 문자열이 두 파일 안에 있고, 참조 기능을 import하지 않는다. 그래서 참조 기능을 지운 프로젝트에서도 동작한다.
템플릿 문자열이 두 파일 안에 있고, 다른 기능을 import하지 않는다. 그래서 기능이 하나도 없는 템플릿에서도 동작한다.
## 사용법
@@ -150,7 +150,7 @@ node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의
- `tests/unit/create-feature.test.ts` (`test:unit`, FE-GATE-005)
- 렌더 결과만 본다. 저장소를 건드리지 않는다.
- 접두어, 참조 기능 이름이 없음, topic 형식과 충돌, `navigationOrder`, 거부 조건, 덮어쓰기 거부와 되돌리기.
- 접두어, 예전 참조 샘플 이름이 없음, topic 형식과 충돌, `navigationOrder`, 거부 조건, 덮어쓰기 거부와 되돌리기.
- 백엔드 경로 규칙, `--with-create`·`--keyed`의 descriptor 값, 모든 operation의 Envelope 선언.
- 생성한 context 선언을 임시 폴더에 써서 생성기의 선언 읽기(`createFileSystemDeclarationSource`)로 읽고, 그 모듈을 import해 라우트 루트가 기능 라우트를 모두 받는지 앱 모듈 조립으로 확인한다.
- `test:feature-scaffold` (FE-GATE-020)
@@ -161,6 +161,5 @@ node scripts/write-dev-release-manifest.ts # dev manifest에서 그 기능의
## 알려진 한계
- `--context reference-context`로 참조 context에 넣은 기능은 경로가 `/examples/reference-resources/<base>`다. 참조 기능을 지우면 context가 남고 그 경로가 제거 드릴의 잔여 검사에 걸린다. 남길 기능은 제품 context에 둔다.
- 드릴은 브라우저 테스트(FE-GATE-008·009의 `test:e2e`, `test:a11y` 등)와 `test:system`을 돌리지 않는다. `check:bundle`(FE-GATE-012)은 돈다.
- 새 context는 앱이 하나일 때만 만든다. 앱이 여럿이면 `--context`로 기존 context를 고른다.
+1 -1
View File
@@ -95,7 +95,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| `reason` | 원인 | 고칠 곳 |
|---|---|---|
| `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to reference-feature only; pin an EXTERNAL_PACKAGE` | 참조 기능 전용 출처를 다른 기능이 썼다 | `contracts/<base>-contract-contribution.ts`의 `source`를 `EXTERNAL_PACKAGE`로 |
| `<id>: TEMPLATE_FIXTURE REFERENCE_FEATURE_V1 belongs to <fixture owner> only; pin an EXTERNAL_PACKAGE` | 템플릿 fixture 출처(예전 참조 샘플용)를 제품 기능이 썼다 | `contracts/<base>-contract-contribution.ts`의 `source`를 `EXTERNAL_PACKAGE`로 |
| `duplicate operation: <operationId>` | 두 기여가 같은 operation ID | 접두어를 붙인다 |
| `duplicate contributionId: <id>` | 두 기여가 같은 `contributionId` | `contracts/<base>-contract-contribution.ts` |
| `<id>/<operationId>: unknown authProfileId <profile>` | V3 `frontend.authProfileId`가 없는 프로필 | V3 `frontend.authProfileId` |
+1 -1
View File
@@ -49,7 +49,7 @@
- 무효화 topic은 새로 만든다.
- 형식: `qinv.` + 소문자·숫자 26자.
- `scripts/create-feature.ts`의 `randomTopicSuffix`가 같은 형식으로 만든다.
- 다른 기능이나 참조 기능의 값을 복사하지 않는다.
- 다른 기능의 값을 복사하지 않는다.
- route ID는 `<BASE>_<화면>` 꼴로 짓는다(`INVOICE_DETAIL`). 라우트를 더하면 a11y 기록 파일도 더한다(`artifacts/tests/a11y-manual/<ROUTE_ID>.md`).
- 문구 키는 ko-KR과 en-US에 같은 키를 넣는다. `check:i18n`이 비교한다.
+18 -18
View File
@@ -3,22 +3,22 @@
기능을 만들 때 쓰는 패턴과, 그 패턴의 정의와 예제가 어디 있는지 적는다.
- **정의**: 플랫폼(기능 밖)에서 패턴을 제공하는 파일.
- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature <id> --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `참조 기능`은 `src/features/reference-feature/`다(Envelope가 아닌 problem details 모양). 참조 기능 경로도 다른 경로처럼 백틱으로 적는다. 문서 검사(`verify:documentation`)는 참조 기능이 있는 동안 그 경로가 있는지 확인하고, 참조 기능을 지운 사본에서는 없어도 된다고 본다(`scripts/lib/removable-template-features.ts`).
- **예제**: 복사해 볼 수 있는 기능 코드. `생성 뼈대`는 `create:feature`가 만드는 코드다. `쓰기 slice`는 `create:feature <id> --with-create`가 더 만드는 코드다(짝 백엔드 Envelope 모양). `코드 조각`은 매뉴얼 안의 코드 블록이다. 생성 뼈대에 없는 모양을 보이고, `tests/unit/manual-code-blocks.test.ts`가 생성 기능 위에서 타입 검사와 동작 시험을 돌린다.
- 예제가 없는 패턴은 **없음**이라고 적었다. 그 패턴은 정의를 읽고 직접 쓴다.
참조 기능은 예제일 뿐이다. 복사해 이름을 바꾸지 않는다. 모양을 보고 생성 뼈대에 옮긴다.
템플릿에는 복사해 볼 기능 샘플이 없다. 모양을 보고 생성 뼈대에 옮긴다.
## 기능 조립
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 기능 모듈 등록 | `src/features/feature-module.ts` (`defineFeatureModule`, `defineFeatureRuntime`), 생성기 | 생성 뼈대 `feature-module.ts`, `feature-runtime.ts` | 생성기, 기능 ID와 계약 `featureId` 일치 |
| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 참조 기능의 `src/contexts/reference-context/context-module.ts` | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) |
| context 소속 선언 | `src/contexts/bounded-context-module.ts` | 생성 뼈대 `src/contexts/<base>-context/context-module.ts`(새 context를 만들 때) | 생성기(없는 context, 예산), 앱 모듈(루트 밖 라우트) |
| context 전용 레이아웃 | `docs/architecture/starter-experience.md` "Product home and layouts" | `tests/helpers/fixture-layout-product.tsx` (테스트 fixture) | `tests/component/context-layouts.test.tsx` |
| 앱 홈 대신하기 | `src/contracts/routes.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` | 없음 (기능 예제) | 조립 (두 기능이 `APP_HOME`을 선언하면 실패) |
| 조립 기여(`needs`) | `src/features/feature-adapter-contribution.ts` | 생성 뼈대 `adapters/create-<base>-feature-input.ts` | 조립 (없는 capability, 다른 기능의 input) |
| 제품 capability | `src/features/product-capabilities.ts`(타입), `src/bootstrap/product-composition.ts`(값), `src/bootstrap/product-composition-contract.ts` | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` | `check:types` |
| 기능 끄기 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | 참조 기능의 `tests/component/product-feature-switch.test.tsx` |
| 기능 끄기 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | `config/runtime/local.json` | `tests/component/product-feature-switch.test.tsx`(시험 전용 기능으로 메뉴·홈 링크·직접 주소를 본다) |
## 라우트
@@ -26,9 +26,9 @@
|---|---|---|---|
| 라우트 선언 | `src/contracts/routes.ts`, `src/contracts/route-runtime-contract.ts` | 생성 뼈대 계약 `routes`, `routeRuntimeContracts` | 조립(중복 route ID), `check:registries`(경로·chunk 중복) |
| context 라우트 적재 | `src/platform/routing/context-route-module.ts` | 생성 뼈대 `context-routes.ts` | context 적재(계약에 없는 handle) |
| route ID로 URL 만들기 | `src/presentation/routes/route-codecs.ts`의 `buildRouteUrl` | 생성 뼈대 `presentation/<base>-routes.ts`, 참조 기능 `presentation/reference-routes.ts` | 타입(기능의 route ID만 받음) |
| 파라미터·검색값 codec | `src/presentation/routes/route-codecs.ts` | 쓰기 slice `presentation/<base>-route-codecs.ts`(상세 params), 참조 기능 `presentation/reference-route-codecs.ts` | 해석 실패 시 잘못된 경로 화면 |
| URL 검색값 읽기 | `src/presentation/routes/route-input.tsx`의 `useRouteInput` + 검색값 codec | 참조 기능 `presentation/reference-routes.ts` | 해석 실패 시 잘못된 경로 화면 |
| route ID로 URL 만들기 | `src/presentation/routes/route-codecs.ts`의 `buildRouteUrl` | 생성 뼈대 `presentation/<base>-routes.ts` | 타입(기능의 route ID만 받음) |
| 파라미터·검색값 codec | `src/presentation/routes/route-codecs.ts` | 쓰기 slice `presentation/<base>-route-codecs.ts`(상세 params). 검색값 codec은 [01 문서 6단계](../01-add-a-feature.md#6단계-라우트)의 코드 조각 | 해석 실패 시 잘못된 경로 화면 |
| URL 검색값 읽기 | `src/presentation/routes/route-input.tsx`의 `useRouteInput` + 검색값 codec | 코드 조각: [01 문서 6단계](../01-add-a-feature.md#6단계-라우트)의 `contracts/<base>-list-search.ts`, `presentation/use-<base>-list-filters.ts` | 해석 실패 시 잘못된 경로 화면 |
| URL 검색값을 바꾸는 폼 | `buildRouteUrl`의 `search`, 디자인 시스템 `SearchField`, `CollectionPage`의 `toolbar` | 기능 예제 없음. 아래 짧은 예 | 라우터를 거치는 페이지 테스트 |
### URL 검색값을 바꾸는 폼 (짧은 예)
@@ -46,7 +46,7 @@
- 목록 라우트의 `searchSchema`와 `routeRuntimeContracts`의 `searchCodec`.
- 그 codec을 `context-routes.ts` handle의 `codecs`와 URL 함수(`buildRouteUrl`의 세 번째 인자)에 함께 넘긴다.
- 검색값을 읽는 hook. 참조 기능 `reference-routes.ts`의 `useReferenceListFilters`가 예제다.
- 검색값을 읽는 hook. [01 문서 6단계](../01-add-a-feature.md#6단계-라우트)의 코드 조각 `use-<base>-list-filters.ts`가 예제다.
```tsx
// 공지 기능의 목록 페이지. noticeRouteUrl은 생성된 <base>-routes.ts의 URL 함수다.
@@ -84,9 +84,9 @@ const search = (q: string) =>
| 검증 생략 | `src/contracts/unvalidated-payload.ts`의 `unvalidatedPayload` | 없음 (기능 예제) | 이유가 비면 throw, `listUnvalidatedPayloads`가 목록을 보임 |
| DTO → 화면 값 mapper | `src/contracts/boundary-mapper.ts`의 `BoundaryMappingResult` | 생성 뼈대 `contracts/<base>-mapper.ts` | 타입 검사 |
| gateway port + HTTP 어댑터 | `src/adapters/http/index.ts`의 `createFeatureHttpBinding`, `defineFeatureHttpOperationForRoutes` | 생성 뼈대 `adapters/<base>-http-gateway.ts` | 음성 타입 fixture (operation ID, route ID, 입력) |
| 문제 응답 → 업무 실패 | `mapProblem` (HTTP 바인딩) | 쓰기 slice `adapters/<base>-http-gateway.ts`(400 `<BASE>_INVALID` → 이름 칸), 참조 기능 `adapters/reference-http-gateway.ts` (409, 422) | 기능 테스트 |
| 문제 응답 → 업무 실패 | `mapProblem` (HTTP 바인딩) | 쓰기 slice `adapters/<base>-http-gateway.ts`(400 `<BASE>_INVALID` → 이름 칸). problem details 백엔드(409, 422)는 [02 결정표 4절](../02-decision-tables.md#4-결과-불명)의 코드 조각 | 기능 테스트 |
| 결과와 실패 | `src/contracts/result.ts`, `src/contracts/errors.ts` | 생성 뼈대 `application/<base>-feature-api.ts` | `FailureKind` 닫힌 어휘(타입) |
| 실패 → 화면 행동 | `src/contracts/errors.ts`의 `action` | 참조 기능 `presentation/use-reference-failure-action.ts` | 페이지 테스트 |
| 실패 → 화면 행동 | `src/contracts/errors.ts`의 `action` | 코드 조각: [01 문서 8단계](../01-add-a-feature.md#8단계-페이지)의 `presentation/use-<base>-failure-action.ts` | 페이지 테스트 |
| 파일 업로드 (짝 백엔드 Fileserver) | `src/adapters/http/index.ts`의 `createFileserverUploadClient` (`POST /v1/files`) | 없음 (기능 예제). 조립은 [02 결정표 7절](../02-decision-tables.md#7-파일-업로드) | `tests/integration/fileserver-upload.test.ts` |
## 서버 상태
@@ -95,29 +95,29 @@ const search = (q: string) =>
|---|---|---|---|
| 쿼리 바인딩 | `src/contracts/server-state.ts`의 `bindQuery`, `src/presentation/adapters/query/application-query.ts` | 생성 뼈대 `presentation/use-<base>-items.ts` | profile ID (실행 때). `owner`·`operationId`는 읽는 곳이 없는 `@deprecated` 칸이라 적지 않는다 |
| 무효화 topic | `src/contracts/query-invalidation.ts` | 생성 뼈대 계약 `invalidation` | 조립(중복, 고아 topic) |
| 멱등 키 쓰기 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 정책(`src/contracts/server-state.ts`의 `commandMutationIdentity`로 operation ID와 키 여부를 descriptor에서 받는다) | 쓰기 slice `--keyed`(`contracts/<base>-contract-contribution.ts`, `presentation/use-<base>-create.ts`), 참조 기능 생성 명령(`use-reference-feature.ts`, `reference-feature-contract-contribution.ts`) | 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름, 손으로 적은 operation ID는 `MutationOperationId`가 아니다), 기능 테스트 |
| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect` | 쓰기 slice `presentation/<base>-create-page.tsx`, 참조 기능 `presentation/reference-resource-form-page.tsx` | 기능 테스트만(쓰기 slice는 `<base>-create-page.test.tsx`) |
| 수정·삭제 명령 | 같은 V3 계약 (`PUT`, `PATCH`, `DELETE`) | 없음 (참조 기능은 생성 명령만 있다) | — |
| 멱등 키 쓰기 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 정책(`src/contracts/server-state.ts`의 `commandMutationIdentity`로 operation ID와 키 여부를 descriptor에서 받는다) | 쓰기 slice `--keyed`(`contracts/<base>-contract-contribution.ts`, `presentation/use-<base>-create.ts`) | 계약 조립(복구 descriptor 필수), 타입(descriptor 상수 이름, 손으로 적은 operation ID는 `MutationOperationId`가 아니다), 기능 테스트 |
| 결과 불명 화면 | `src/presentation/components/async-surface.tsx`의 `onReconcileUnknownEffect`, `onResendUnknownEffect` | 쓰기 slice `presentation/<base>-create-page.tsx` | 기능 테스트만(쓰기 slice는 `<base>-create-page.test.tsx`) |
| 수정·삭제 명령 | 같은 V3 계약 (`PUT`, `PATCH`, `DELETE`) | 없음 (쓰기 slice는 작성 명령만 만든다) | — |
| 낙관적 갱신 | `useApplicationMutation`의 `optimistic` 옵션 (`application-query.ts`) | 없음 | 런타임 테스트만 |
| 페이지 넘김 | `src/adapters/query-cache/index.ts`의 `createCursorPaginationRuntime` | 없음 (참조 기능은 커서 필터만, 다음 커서 없음) | 런타임 테스트만 |
| 페이지 넘김 | `src/adapters/query-cache/index.ts`의 `createCursorPaginationRuntime` | 없음 (생성 뼈대 목록은 첫 페이지와 `meta.page.total`만 읽는다) | 런타임 테스트만 |
| 로컬 저장(IndexedDB) | `recipes/frontend-capabilities/indexeddb-feature-capability.ts` + `product-composition.ts` | `tests/fixtures/indexeddb-consumer/` (시험이 조립하는 소비자 fixture, 기능 폴더 모양) | 계약 테스트 |
## 화면
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 페이지 템플릿 | `src/presentation/templates/page-templates.tsx` | 생성 뼈대 `CollectionPage`, 참조 기능 페이지 4개 | `page-templates-own-layout-only` |
| 페이지 템플릿 | `src/presentation/templates/page-templates.tsx` | 생성 뼈대 `CollectionPage`, 쓰기 slice `DetailPage`·`FormPage` | `page-templates-own-layout-only` |
| 비동기 상태 화면 | `src/presentation/components/async-surface.tsx`의 `AsyncSurface` | 생성 뼈대 목록 페이지 | 페이지 테스트 |
| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm` | 쓰기 slice `presentation/<base>-form.ts`와 `<base>-create-page.tsx`, 참조 기능 `presentation/reference-resource-form.ts`와 폼 페이지 | 페이지 테스트(서버 필드 오류, 이탈 확인) |
| 폼 | `src/presentation/forms/use-app-form.ts`의 `useAppForm` | 쓰기 slice `presentation/<base>-form.ts`와 `<base>-create-page.tsx` | 페이지 테스트(서버 필드 오류, 이탈 확인) |
| 화면 문구 | `src/presentation/i18n/index.ts`, 기능 문구 catalog | 생성 뼈대 `contracts/<base>-message-catalog.ts` | `lint`(문구 literal), `check:i18n`(ko-KR·en-US 키) |
| 권한 분기 | 라우트 `access`, 서버 403 → 실패 | 참조 기능 403 화면 테스트 | 가드 테스트. 역할·권한 힌트 예제는 없음 |
| 권한 분기 | 라우트 `access`, 서버 403 → 실패 | 코드 조각: [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 403 페이지 테스트 `tests/features/<id>/<base>-forbidden.test.tsx` | 가드 테스트. 역할·권한 힌트 예제는 없음 |
## 테스트
| 패턴 | 정의 | 예제 | 검사 |
|---|---|---|---|
| 응답 시나리오 | `tests/mocks/handlers/http-scenarios.ts`의 `createHttpScenarioHandler` | 생성 뼈대 페이지 테스트 | `test:coverage` |
| 보낸 요청(헤더·본문) 확인 | MSW `setupServer().events.on("request:start")` | [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 짧은 예. 핸들러에서 모으는 방법은 참조 기능 `reference-production-vertical.test.tsx`의 504 재전송 테스트 | `test:coverage` |
| 보낸 요청(헤더·본문) 확인 | MSW `setupServer().events.on("request:start")` | [01 문서 10단계](../01-add-a-feature.md#10단계-테스트)의 짧은 예. 핸들러에서 모으는 방법은 쓰기 slice `--keyed`의 `tests/features/<id>/<base>-create-page.test.tsx` | `test:coverage` |
| 같은 멱등 키 재전송 | 시나리오 `in-flight-409` + 위 요청 모으기 | 01 문서 10단계 | `test:coverage` |
## 관측
+2
View File
@@ -84,6 +84,8 @@ export const REMOVAL_FIXTURE_DOCUMENT_TESTS = Object.freeze([
"tests/unit/template-feature-removal-documents.test.ts",
// 1105/14-02. Reads a code block of docs/manual.
"tests/unit/manual-paired-backend-settings.test.ts",
// Reads the marked code blocks of docs/manual.
"tests/unit/manual-code-blocks.test.ts",
] as const);
/** The tests a fixture copied from `copyTargets` cannot run. */
@@ -0,0 +1,192 @@
// @vitest-environment jsdom
// What the manual's code blocks do. tests/unit/manual-code-blocks.test.ts
// copies this file into the tests folder of the feature the blocks are
// written for, in a repository copy that has that feature and the blocks at
// their marked paths, and puts the feature's folder name for `{{feature}}`.
// The imports resolve there, not here: written out, they would read as a
// product feature's residue to the removal drill (scripts/lib/feature-residue.ts).
import { act, renderHook } from "@testing-library/react";
import type { ReactNode } from "react";
import { MemoryRouter, useLocation } from "react-router-dom";
import { describe, expect, it, vi } from "vitest";
import { createAnonymousSessionAdapter } from "../../../src/adapters/auth/index.ts";
import { createFailure } from "../../../src/contracts/errors.ts";
import { mapInvoiceCreateProblem } from "../../../src/features/{{feature}}/adapters/invoice-problem-mapping.ts";
import { invoiceListSearchSchema } from "../../../src/features/{{feature}}/contracts/invoice-list-search.ts";
import {
INVOICE_CREATE_EFFECT,
INVOICE_PROBLEM_VALIDATOR,
} from "../../../src/features/{{feature}}/contracts/invoice-problem-details.ts";
import { createInvoice } from "../../../src/features/{{feature}}/domain/invoice.ts";
import { useInvoiceFailureAction } from "../../../src/features/{{feature}}/presentation/use-invoice-failure-action.ts";
import { useInvoiceListFilters } from "../../../src/features/{{feature}}/presentation/use-invoice-list-filters.ts";
import { ApplicationProvider } from "../../../src/presentation/providers/application-provider.tsx";
import { SessionProvider } from "../../../src/presentation/providers/session-provider.tsx";
import { RouteInputProvider } from "../../../src/presentation/routes/route-input.tsx";
import { createTestApplication } from "../../helpers/create-test-application.ts";
const PROBLEM = Object.freeze({
type: "https://problems.example/invoice",
title: "Invoice refused",
});
describe("01 step 2: the domain model", () => {
it("keeps an invoice that falls due on or after its issue day, frozen", () => {
const invoice = createInvoice({ invoiceId: "inv-1", issuedOn: "2026-11-01", dueOn: "2026-11-01" });
expect(invoice).toEqual({ invoiceId: "inv-1", issuedOn: "2026-11-01", dueOn: "2026-11-01" });
expect(Object.isFrozen(invoice)).toBe(true);
});
it("refuses an invoice due before it is issued, and a date that is no calendar date", () => {
expect(() =>
createInvoice({ invoiceId: "inv-1", issuedOn: "2026-11-02", dueOn: "2026-11-01" }),
).toThrow(RangeError);
expect(() =>
createInvoice({ invoiceId: "inv-1", issuedOn: "2026-11-02", dueOn: "next week" }),
).toThrow(RangeError);
});
});
describe("02 section 4: a problem-details backend", () => {
it("reads a problem details body and keeps only its fields", () => {
const read = INVOICE_PROBLEM_VALIDATOR.safeParse({
...PROBLEM,
status: 422,
code: "INVOICE_REJECTED",
detail: "a backend message the screen never shows",
issues: [{ path: "dueOn", code: "BEFORE_ISSUE", message: "dropped" }],
});
expect(read).toEqual({
success: true,
data: {
...PROBLEM,
status: 422,
code: "INVOICE_REJECTED",
issues: [{ path: "dueOn", code: "BEFORE_ISSUE" }],
},
});
expect(INVOICE_PROBLEM_VALIDATOR.safeParse({ type: PROBLEM.type, status: 400 }).success).toBe(false);
expect(INVOICE_PROBLEM_VALIDATOR.schemaId).toBe("InvoiceProblem");
});
it("calls a create refused only for 400, 422 and the declared 409 code", () => {
const classify = (status: number, code?: string) =>
INVOICE_CREATE_EFFECT.classifyProblem({
status,
problem: { ...PROBLEM, status, ...(code === undefined ? {} : { code }) },
});
expect(classify(400)).toBe("NOT_APPLIED");
expect(classify(422, "INVOICE_REJECTED")).toBe("NOT_APPLIED");
expect(classify(409, "CONFLICT")).toBe("NOT_APPLIED");
// A resend that meets the first attempt still running keeps its key.
expect(classify(409, "IDEMPOTENT_IN_FLIGHT")).toBe("MAYBE_APPLIED");
expect(classify(409)).toBe("MAYBE_APPLIED");
expect(classify(503, "IDEMPOTENCY_UNAVAILABLE")).toBe("MAYBE_APPLIED");
expect(classify(500)).toBe("MAYBE_APPLIED");
expect(INVOICE_CREATE_EFFECT.classifyStatus?.(403)).toBe("NOT_APPLIED");
});
it("maps a conflict, a key rule mismatch and field issues, and leaves the rest to the executor", () => {
const problem = (status: number, extra: Readonly<Record<string, unknown>> = {}) => ({
...PROBLEM,
status,
...extra,
});
expect(mapInvoiceCreateProblem(problem(409, { code: "CONFLICT" }), { status: 409 })).toEqual({
kind: "CONFLICT",
code: "CONFLICT",
});
expect(mapInvoiceCreateProblem(problem(409), { status: 409 })).toEqual({
kind: "CONFLICT",
code: "INVOICE_CONFLICT",
});
expect(
mapInvoiceCreateProblem(problem(400, { code: "IDEMPOTENCY_KEY_INVALID" }), { status: 400 }),
).toEqual({ kind: "UNKNOWN_CLIENT_FAILURE", code: "IDEMPOTENCY_KEY_INVALID" });
expect(
mapInvoiceCreateProblem(problem(422, { issues: [{ path: "dueOn", code: "BEFORE_ISSUE" }] }), {
status: 422,
}),
).toEqual({
kind: "VALIDATION_REJECTED",
code: "INVOICE_REJECTED",
validationIssues: [{ path: "dueOn", code: "BEFORE_ISSUE" }],
});
expect(mapInvoiceCreateProblem(problem(400), { status: 400 })).toBeUndefined();
expect(mapInvoiceCreateProblem(problem(503), { status: 503 })).toBeUndefined();
});
});
describe("01 step 6: reading the list route's search values", () => {
const withSearch = (search: Readonly<Record<string, unknown>>) =>
function Search({ children }: Readonly<{ children: ReactNode }>) {
return (
<RouteInputProvider input={{ routeId: "INVOICE_LIST", params: {}, search }}>
{children}
</RouteInputProvider>
);
};
it("reads the search the codec accepted, typed", () => {
expect(renderHook(useInvoiceListFilters, { wrapper: withSearch({ status: "open" }) }).result.current).toEqual({
status: "open",
});
expect(renderHook(useInvoiceListFilters, { wrapper: withSearch({}) }).result.current).toEqual({});
});
it("refuses a value the router must answer with the invalid-route screen", () => {
expect(invoiceListSearchSchema.safeParse({ status: "void" }).success).toBe(false);
expect(invoiceListSearchSchema.safeParse({ status: "open", page: "2" }).success).toBe(false);
});
});
describe("01 step 8: the failure action of a page", () => {
function renderAction(failure: Parameters<typeof useInvoiceFailureAction>[0]) {
const beginSignIn = vi.fn(async (_returnTo?: string) => {});
const application = createTestApplication({
session: { ...createAnonymousSessionAdapter(), beginSignIn },
});
const rendered = renderHook(
() => ({ handle: useInvoiceFailureAction(failure), location: useLocation() }),
{
wrapper: ({ children }: Readonly<{ children: ReactNode }>) => (
<ApplicationProvider application={application}>
<SessionProvider>
<MemoryRouter initialEntries={["/invoice?status=open#total"]}>{children}</MemoryRouter>
</SessionProvider>
</ApplicationProvider>
),
},
);
return { beginSignIn, rendered };
}
it("signs in again and comes back to the same URL", async () => {
const { beginSignIn, rendered } = renderAction(createFailure("AUTH_REQUIRED", "INVOICE_LIST_ITEMS", 0));
await act(async () => rendered.result.current.handle?.());
expect(beginSignIn).toHaveBeenCalledWith("/invoice?status=open#total");
});
it("leaves a forbidden screen for home", async () => {
const { rendered } = renderAction(createFailure("FORBIDDEN", "INVOICE_LIST_ITEMS", 0));
await act(async () => rendered.result.current.handle?.());
expect(rendered.result.current.location.pathname).toBe("/");
});
it("gives no handler for a retry or for no failure: the query owns retry", () => {
expect(
renderAction(createFailure("NETWORK_UNREACHABLE", "INVOICE_LIST_ITEMS", 0)).rendered.result.current.handle,
).toBeUndefined();
expect(renderAction(undefined).rendered.result.current.handle).toBeUndefined();
});
});
+140
View File
@@ -0,0 +1,140 @@
import { spawnSync } from "node:child_process";
import { existsSync } from "node:fs";
import { cp, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterAll, describe, expect, it } from "vitest";
import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts";
import { REMOVAL_FIXTURE_COPY_TARGETS } from "../../scripts/lib/removal-fixture.ts";
/**
* 2026-11-07. The template ships no sample feature: what the generated
* feature does not show, docs/manual shows as code blocks a product copies
* into its feature folder. Each such block has `<!-- manual-code-block: <path> -->`
* above it, the path in the feature `create:feature invoice-feature
* --with-create` writes. Here a copy of the repository gets that feature, each
* block goes to its path unchanged, and the app and test typecheck programs,
* lint and the feature's tests run on it. A block that is a test runs as it
* is; what the other blocks do is checked by tests/fixtures/manual-code-blocks.
*/
const MANUAL = "docs/manual";
const FEATURE_ID = "invoice-feature";
const CHECKS = "tests/fixtures/manual-code-blocks";
const MARKED_BLOCK = /<!-- manual-code-block: (\S+) -->\n```tsx?\n([\s\S]*?)\n```/gu;
async function manualDocuments(directory: string): Promise<string[]> {
const documents: string[] = [];
for (const entry of await readdir(directory, { withFileTypes: true })) {
const target = path.join(directory, entry.name);
if (entry.isDirectory()) documents.push(...(await manualDocuments(target)));
else if (entry.name.endsWith(".md")) documents.push(target);
}
return documents.sort();
}
/** Each marked block by the path it goes to. */
async function markedBlocks(): Promise<ReadonlyMap<string, string>> {
const blocks = new Map<string, string>();
for (const document of await manualDocuments(MANUAL)) {
for (const [, target = "", body = ""] of (await readFile(document, "utf8")).matchAll(MARKED_BLOCK)) {
if (blocks.has(target)) throw new Error(`${target} is marked twice in ${MANUAL}`);
blocks.set(target, `${body}\n`);
}
}
return blocks;
}
const roots: string[] = [];
afterAll(async () => {
await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true })));
});
async function copyRepository(): Promise<string> {
const root = await mkdtemp(path.join(tmpdir(), "manual-code-blocks-"));
roots.push(root);
for (const entry of REMOVAL_FIXTURE_COPY_TARGETS) {
// A removal drill runs this test in a copy that has already lost some.
if (!existsSync(path.resolve(entry))) continue;
await cp(path.resolve(entry), path.join(root, entry), {
recursive: true,
filter: (source) => !source.includes(`${path.sep}.generated`),
});
}
await linkFixtureNodeModules(root);
return root;
}
function run(root: string, command: string, args: readonly string[]) {
const result = spawnSync(command, args, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
return { status: result.status, output: `${result.stdout}${result.stderr}` };
}
describe("docs/manual code blocks, pasted into a generated feature", () => {
it("marks each block with a path in the feature it is written for", async () => {
const targets = [...(await markedBlocks()).keys()].sort();
expect(targets).toEqual([
"src/features/invoice-feature/adapters/invoice-problem-mapping.ts",
"src/features/invoice-feature/contracts/invoice-list-search.ts",
"src/features/invoice-feature/contracts/invoice-problem-details.ts",
"src/features/invoice-feature/domain/invoice.ts",
"src/features/invoice-feature/presentation/use-invoice-failure-action.ts",
"src/features/invoice-feature/presentation/use-invoice-list-filters.ts",
"tests/features/invoice-feature/invoice-forbidden.test.tsx",
]);
});
it("typechecks, lints and does what the manual says", async () => {
const blocks = await markedBlocks();
const root = await copyRepository();
const node = process.execPath;
// The generator runs first, as `corepack pnpm create:feature` does.
const indexed = run(root, node, ["scripts/generate-product-feature-index.ts"]);
expect(indexed.status, indexed.output).toBe(0);
const created = run(root, node, ["scripts/create-feature.ts", FEATURE_ID, "--with-create"]);
expect(created.status, created.output).toBe(0);
for (const [target, block] of blocks) {
const file = path.join(root, target);
// A block adds a file; it never stands in for one the command wrote.
expect(existsSync(file), `${target} exists before the block is pasted`).toBe(false);
await mkdir(path.dirname(file), { recursive: true });
await writeFile(file, block);
}
const checks = (await readdir(CHECKS)).filter((name) => name.endsWith(".check.tsx"));
expect(checks.length).toBeGreaterThan(0);
for (const check of checks) {
await writeFile(
path.join(root, "tests/features", FEATURE_ID, check.replace(/\.check\.tsx$/u, ".test.tsx")),
(await readFile(path.join(CHECKS, check), "utf8")).replaceAll("{{feature}}", FEATURE_ID),
);
}
for (const program of ["tsconfig.app.json", "tsconfig.test.json"]) {
const typecheck = run(root, path.resolve("node_modules/.bin/tsc"), ["--project", program]);
expect(typecheck.output, program).toBe("");
expect(typecheck.status, program).toBe(0);
}
const lint = run(root, path.resolve("node_modules/.bin/eslint"), [
`src/features/${FEATURE_ID}`,
`tests/features/${FEATURE_ID}`,
"--max-warnings=0",
]);
expect(lint.output).toBe("");
expect(lint.status).toBe(0);
const architecture = run(root, node, ["scripts/check-architecture.ts"]);
expect(architecture.status, architecture.output).toBe(0);
const tests = run(root, node, [
"scripts/run-vitest.ts",
"run",
`tests/features/${FEATURE_ID}`,
"--reporter=dot",
]);
expect(tests.status, tests.output).toBe(0);
}, 300_000);
});