화면 문구 셋이 어긋난다.
- 상태 화면 문구가 템플릿 개발자용이다(04-01). 생성 기능은 모두
`session-required`라 로그인 전 최종 사용자에게 "이 화면은 인증 연동 지점을
확인하기 위한 보호 라우트입니다."가 보인다. 끈 기능 화면은 "코드에는
포함되어 있으며 운영자가 다시 켤 수 있습니다.", 연동 실패 화면은 "외부 인증
소유자가 연결되면…"이다.
- 숫자를 locale formatter 없이 그린다(04-03). 생성 목록이 "총 12345개 항목"을
그리고, TextArea는 en에서 남은 1자도 "1 characters remaining"이다.
- ko·en 뜻이 다르다(04-07). en `form.conflict`에 "최신 상태를 확인해 주세요"가
없고, en 문서 제목 "Page not found"와 h1 "Page not found."가 다르다.
ErrorSummary가 번역 문장 사이에 JSX 글자 ": "를 넣는다.
고른 방법: 세 설명을 사용자 말("이 화면을 보려면 로그인해 주세요." 등)로 바꾸고
운영 설명은 뺐다. 생성 목록은 `useLocale().number(total)`을 넘긴다. TextArea는
`plural`로 `form.remaining.one`(en 단수)과 `form.remaining`을 고른다. en 충돌
문구에 행동을 더하고 not-found 제목을 h1과 같게 했다. 오류 요약 항목은
`form.errorSummary.item` "{label}: {message}"로 잇는다. 연동 실패 화면의 제목
"로그인 연동이 필요합니다."는 짝 백엔드 매뉴얼이 그 글자로 가리켜 그대로 뒀다.
검증 V4가 반박한 부분(세 화면에 행동 버튼이 없다, ProgressBar `%`)은 고치지
않았다: 셸 탐색이 늘 있고, `%`는 ko·en 결과가 같다.
위험·한계: 다운스트림이 이 키의 옛 문장을 시험으로 고정했으면 문장을 바꾼다.
이미 생성한 기능의 목록 페이지는 `count: query.data.total`을 그대로 갖는다.
`number(query.data.total)`로 바꾸면 된다(생성 명령의 새 출력과 같다).
검증: `tests/unit/i18n-contract.test.ts`(개발자 낱말, not-found 제목, 항목
문장), `tests/component/design-system-a11y.test.tsx`(en 단수·복수),
`tests/unit/create-feature.test.ts`(생성 목록의 `number(`)가 고치기 전에
실패하고 고친 뒤 통과한다. 생성 기능 시험의 total 12345 → "총 12,345개 항목"은
FE-GATE-005가 돌린다(desktop, PR 본문).
Refs: 1112/04-01, 1112/04-03, 1112/04-07
1855 lines
66 KiB
TypeScript
1855 lines
66 KiB
TypeScript
import { spawnSync } from "node:child_process";
|
|
import { randomBytes } from "node:crypto";
|
|
import { access, mkdir, readdir, rm, writeFile } from "node:fs/promises";
|
|
import path from "node:path";
|
|
import process from "node:process";
|
|
import { fileURLToPath } from "node:url";
|
|
import { parseArgs } from "node:util";
|
|
|
|
import {
|
|
composeContractContributions,
|
|
ContractContributionError,
|
|
} from "../src/contracts/external-contract-runtime.ts";
|
|
import {
|
|
planWriteSlice,
|
|
renderCreatePage,
|
|
renderCreatePageTest,
|
|
renderDetailPage,
|
|
renderForm,
|
|
renderRouteCodecs,
|
|
renderUseCreate,
|
|
renderUseItem,
|
|
renderWriteDescriptors,
|
|
renderWriteGatewayHelpers,
|
|
renderWriteGatewayMethods,
|
|
renderWriteGatewayOperations,
|
|
renderWriteGatewayTests,
|
|
renderWriteMapper,
|
|
renderWriteMessages,
|
|
renderWriteRouteRuntimeContracts,
|
|
renderWriteRoutes,
|
|
renderWriteSchemaRows,
|
|
renderWriteSchemas,
|
|
renderWriteValidators,
|
|
writeSliceMessageKeys,
|
|
type WriteSemantics,
|
|
type WriteSlice,
|
|
} from "./create-feature-write-slice.ts";
|
|
import { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
|
|
|
|
/**
|
|
* U7. `pnpm create:feature <id>` writes the smallest feature meant to pass
|
|
* every merge gate. test:feature-scaffold runs the merge stage on it except the
|
|
* commands SCAFFOLD_DRILL_EXCLUDED_SCRIPTS names (browser gates, test:system;
|
|
* scripts/lib/feature-scaffold-drill.ts). The feature has one list route
|
|
* without params, one GET (SAFE, EXTERNAL_BEARER),
|
|
* one query, one invalidation topic, one CollectionPage with ko-KR and en-US
|
|
* copy, and a router page test, a gateway test and an input test. It reads
|
|
* the paired backend's Envelope, at the path its new-feature.sh maps
|
|
* (`/<plural>`, 1103/03-07). `--with-create` adds the backend scaffold's
|
|
* create and read-by-id with their pages (`create-feature-write-slice.ts`).
|
|
* The templates live in these two files and import nothing from a sample
|
|
* feature, so the command keeps working after a product deletes the sample
|
|
* (test:sample-removal runs it there).
|
|
*
|
|
* Every global id carries the feature prefix (review 16, 8.3): a copied id
|
|
* collides in a registry that is global. The invalidation topic is random.
|
|
* Outside the feature folder it writes only the context declaration (for a
|
|
* new context) and the route's pending accessibility record; it never
|
|
* overwrites a file, and a failed run leaves nothing behind.
|
|
*/
|
|
|
|
export type InstalledFacts = Readonly<{
|
|
appIds: readonly string[];
|
|
/** Declared feature ids and every src/features directory name. */
|
|
featureIds: readonly string[];
|
|
contexts: readonly Readonly<{ id: string; routePath: string }>[];
|
|
contextDirectories: readonly string[];
|
|
routes: readonly Readonly<{
|
|
routeId: string;
|
|
path: string;
|
|
chunkId: string;
|
|
navigationOrder: number | null;
|
|
}>[];
|
|
topics: readonly string[];
|
|
messageKeys: readonly string[];
|
|
}>;
|
|
|
|
export type ContractPackageIdentity = Readonly<{
|
|
packageId: string;
|
|
version: string;
|
|
digest: string;
|
|
sourceRevision: string;
|
|
}>;
|
|
|
|
export type FeatureRequest = Readonly<{
|
|
id: string;
|
|
context?: string | undefined;
|
|
contractPackage?: ContractPackageIdentity | undefined;
|
|
/** `--with-create` (NEVER) or `--with-create --keyed` (KEYED). */
|
|
write?: WriteSemantics | undefined;
|
|
}>;
|
|
|
|
export type FeaturePlan = Readonly<{
|
|
id: string;
|
|
contextId: string;
|
|
newContext: boolean;
|
|
routeId: string;
|
|
routePath: string;
|
|
topic: string;
|
|
/** No package was given; the placeholder identity is pinned. */
|
|
placeholder: boolean;
|
|
/** Every route the feature declares, the list first. */
|
|
routes: readonly Readonly<{ routeId: string; path: string }>[];
|
|
/** Repository-relative path -> content. */
|
|
files: ReadonlyMap<string, string>;
|
|
}>;
|
|
|
|
export class CreateFeatureError extends Error {}
|
|
|
|
const KEBAB = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u;
|
|
/** Telemetry kinds allow 40 characters per segment; the base is one. */
|
|
const MAX_ID_LENGTH = 40;
|
|
const TOPIC_SUFFIX = /^[0-9a-z]{26}$/u;
|
|
/** Crockford base32, lower case: 32 symbols, so `byte & 31` has no bias. */
|
|
const TOPIC_ALPHABET = "0123456789abcdefghjkmnpqrstvwxyz";
|
|
const NEW_CONTEXT_MAX_FEATURES = 20;
|
|
const NAVIGATION_STEP = 10;
|
|
|
|
export function randomTopicSuffix(): string {
|
|
return [...randomBytes(26)]
|
|
.map((byte) => TOPIC_ALPHABET[byte & 31])
|
|
.join("");
|
|
}
|
|
|
|
/**
|
|
* 1103/03-07. The path segment the paired backend's new-feature.sh maps for
|
|
* the same name: its camel-case name plus `es` after s, x, ch or sh, `ies`
|
|
* for a consonant and y, `s` otherwise.
|
|
*/
|
|
export function backendPathSegment(camel: string): string {
|
|
if (/(?:s|x|ch|sh)$/u.test(camel)) return `${camel}es`;
|
|
if (/[^aeiou]y$/u.test(camel)) return `${camel.slice(0, -1)}ies`;
|
|
return `${camel}s`;
|
|
}
|
|
|
|
function baseOf(id: string): string {
|
|
return id.endsWith("-feature") && id !== "feature"
|
|
? id.slice(0, -"-feature".length)
|
|
: id;
|
|
}
|
|
|
|
export function namesOf(id: string) {
|
|
const base = baseOf(id);
|
|
const pascal = base
|
|
.split("-")
|
|
.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
|
|
.join("");
|
|
return Object.freeze({
|
|
id,
|
|
base,
|
|
upper: base.toUpperCase().replaceAll("-", "_"),
|
|
pascal,
|
|
camel: pascal.charAt(0).toLowerCase() + pascal.slice(1),
|
|
title: base.charAt(0).toUpperCase() + base.slice(1).replaceAll("-", " "),
|
|
});
|
|
}
|
|
|
|
type Names = ReturnType<typeof namesOf>;
|
|
|
|
function fail(message: string): never {
|
|
throw new CreateFeatureError(message);
|
|
}
|
|
|
|
function assertKebab(value: string, label: string, maxLength: number): void {
|
|
if (!KEBAB.test(value) || value.length > maxLength) {
|
|
fail(
|
|
`${label} "${value}" must be kebab-case (lower-case words joined by single hyphens), at most ${maxLength} characters`,
|
|
);
|
|
}
|
|
}
|
|
|
|
function assertPackageIdentity(
|
|
featureId: string,
|
|
identity: ContractPackageIdentity,
|
|
): void {
|
|
try {
|
|
composeContractContributions([
|
|
{
|
|
contributionId: "create-feature-check",
|
|
featureId,
|
|
source: {
|
|
kind: "EXTERNAL_PACKAGE",
|
|
package: {
|
|
...identity,
|
|
digest: identity.digest as `sha256:${string}`,
|
|
runtimeProtocolVersion: 1,
|
|
},
|
|
},
|
|
http: [],
|
|
events: [],
|
|
},
|
|
]);
|
|
} catch (error) {
|
|
fail(
|
|
`contract package ${identity.packageId}@${identity.version} is not a pinned identity: ${
|
|
error instanceof ContractContributionError ? error.reason : String(error)
|
|
}`,
|
|
);
|
|
}
|
|
}
|
|
|
|
/** The routes, files and ids of one feature. Pure apart from the topic. */
|
|
export function planFeature(
|
|
request: FeatureRequest,
|
|
installed: InstalledFacts,
|
|
topicSuffix: () => string = randomTopicSuffix,
|
|
): FeaturePlan {
|
|
const { id } = request;
|
|
assertKebab(id, "feature id", MAX_ID_LENGTH);
|
|
const names = namesOf(id);
|
|
const contextIds = new Set([
|
|
...installed.contexts.map((context) => context.id),
|
|
...installed.contextDirectories,
|
|
]);
|
|
if (installed.featureIds.includes(id) || contextIds.has(id)) {
|
|
fail(`feature id ${id} is already a feature or context`);
|
|
}
|
|
const sameBase = installed.featureIds.find(
|
|
(featureId) => baseOf(featureId) === names.base,
|
|
);
|
|
if (sameBase !== undefined) {
|
|
fail(
|
|
`feature id ${id} would prefix its ids with "${names.base}", which ${sameBase} already uses`,
|
|
);
|
|
}
|
|
|
|
const contextId = request.context ?? `${names.base}-context`;
|
|
assertKebab(contextId, "context id", 64);
|
|
if (installed.featureIds.includes(contextId)) {
|
|
fail(`context id ${contextId} is a feature id`);
|
|
}
|
|
const existing = installed.contexts.find((context) => context.id === contextId);
|
|
if (request.context === undefined && contextIds.has(contextId)) {
|
|
fail(
|
|
`context ${contextId} already exists; pass --context ${contextId} to add the feature to it`,
|
|
);
|
|
}
|
|
if (existing === undefined && contextIds.has(contextId)) {
|
|
fail(`src/contexts has a ${contextId} directory without a context declaration`);
|
|
}
|
|
const contextRoot = existing
|
|
? existing.routePath.replace(/\/?\*$/u, "")
|
|
: contextId.replace(/-context$/u, "");
|
|
if (
|
|
existing === undefined &&
|
|
installed.contexts.some((context) => context.routePath === `${contextRoot}/*`)
|
|
) {
|
|
fail(`another context already owns the route root ${contextRoot}/*`);
|
|
}
|
|
if (existing === undefined && installed.appIds.length !== 1) {
|
|
fail(
|
|
`a new context needs exactly one deployable app (declared: ${installed.appIds.join(", ") || "none"}); pass --context <an existing context>`,
|
|
);
|
|
}
|
|
// A new context gives the feature its root; in an existing one the feature
|
|
// takes a segment below the root.
|
|
const routePath = existing ? `/${contextRoot}/${names.base}` : `/${contextRoot}`;
|
|
const routeId = `${names.upper}_LIST`;
|
|
const chunkId = `route-${names.base}-list`;
|
|
const write =
|
|
request.write === undefined ? null : planWriteSlice(names, routePath, request.write);
|
|
const planned = [
|
|
{ routeId, path: routePath, chunkId },
|
|
...(write ? [write.detail, write.create] : []),
|
|
];
|
|
for (const own of planned) {
|
|
for (const route of installed.routes) {
|
|
if (
|
|
route.routeId === own.routeId ||
|
|
route.path === own.path ||
|
|
route.chunkId === own.chunkId
|
|
) {
|
|
fail(
|
|
`route ${own.routeId} (${own.path}, ${own.chunkId}) collides with installed route ${route.routeId} (${route.path}, ${route.chunkId})`,
|
|
);
|
|
}
|
|
}
|
|
}
|
|
const messageKeys = [
|
|
`route.${routeId}.navigation`,
|
|
`route.${routeId}.title`,
|
|
`${names.camel}.list.title`,
|
|
`${names.camel}.list.description`,
|
|
`${names.camel}.list.resultCount`,
|
|
`${names.camel}.list.items`,
|
|
...(write ? writeSliceMessageKeys(names, write) : []),
|
|
];
|
|
const takenKeys = messageKeys.filter((key) => installed.messageKeys.includes(key));
|
|
if (takenKeys.length > 0) {
|
|
fail(`message keys already exist: ${takenKeys.join(", ")}`);
|
|
}
|
|
|
|
const suffix = topicSuffix();
|
|
const topic = `qinv.${suffix}`;
|
|
if (!TOPIC_SUFFIX.test(suffix)) fail(`invalid generated topic ${topic}`);
|
|
if (installed.topics.includes(topic)) {
|
|
fail(`generated topic ${topic} is already installed; run the command again`);
|
|
}
|
|
if (request.contractPackage) assertPackageIdentity(id, request.contractPackage);
|
|
|
|
const navigationOrder =
|
|
Math.max(
|
|
0,
|
|
...installed.routes.flatMap((route) =>
|
|
route.navigationOrder === null ? [] : [route.navigationOrder],
|
|
),
|
|
) + NAVIGATION_STEP;
|
|
const appId = installed.appIds[0] ?? "";
|
|
const shape: Shape = Object.freeze({
|
|
names,
|
|
contextId,
|
|
routeId,
|
|
routePath,
|
|
chunkId,
|
|
navigationOrder,
|
|
topic,
|
|
operationId: `${names.upper}_LIST_ITEMS`,
|
|
apiPath: `/${backendPathSegment(names.camel)}`,
|
|
owner: `feature-frontend-${id}`,
|
|
contractPackage: request.contractPackage ?? null,
|
|
write,
|
|
});
|
|
|
|
const feature = `src/features/${id}`;
|
|
const { base } = names;
|
|
const files = new Map<string, string>([
|
|
...(existing
|
|
? []
|
|
: ([
|
|
[
|
|
`src/contexts/${contextId}/context-module.ts`,
|
|
renderContextModule(contextId, appId, contextRoot),
|
|
],
|
|
] as const)),
|
|
[`${feature}/feature-module.ts`, renderFeatureModule(shape)],
|
|
[`${feature}/feature-runtime.ts`, renderFeatureRuntime(shape)],
|
|
[`${feature}/context-routes.ts`, renderContextRoutes(shape)],
|
|
[`${feature}/contracts/${base}-feature-contract.ts`, renderFeatureContract(shape)],
|
|
[`${feature}/contracts/${base}-schemas.ts`, renderSchemas(shape)],
|
|
[`${feature}/contracts/${base}-mapper.ts`, renderMapper(shape)],
|
|
[`${feature}/contracts/${base}-schema-metadata.ts`, renderSchemaMetadata(shape)],
|
|
[
|
|
`${feature}/contracts/${base}-contract-contribution.ts`,
|
|
renderContractContribution(shape),
|
|
],
|
|
[`${feature}/contracts/${base}-message-catalog.ts`, renderMessageCatalog(shape)],
|
|
[`${feature}/application/${base}-feature-api.ts`, renderFeatureApi(shape)],
|
|
[`${feature}/adapters/${base}-http-gateway.ts`, renderHttpGateway(shape)],
|
|
[`${feature}/adapters/create-${base}-feature-input.ts`, renderCreateInput(shape)],
|
|
[`${feature}/presentation/${base}-feature-runtime.ts`, renderRouteRuntime(shape)],
|
|
[`${feature}/presentation/${base}-routes.ts`, renderRoutes(shape)],
|
|
[`${feature}/presentation/use-${base}-items.ts`, renderUseItems(shape)],
|
|
[`${feature}/presentation/${base}-list-page.tsx`, renderListPage(shape)],
|
|
...(write
|
|
? ([
|
|
[`${feature}/presentation/${base}-route-codecs.ts`, renderRouteCodecs({ ...shape, write })],
|
|
[`${feature}/presentation/use-${base}-item.ts`, renderUseItem({ ...shape, write })],
|
|
[`${feature}/presentation/use-${base}-create.ts`, renderUseCreate({ ...shape, write })],
|
|
[`${feature}/presentation/${base}-form.ts`, renderForm({ ...shape, write })],
|
|
[`${feature}/presentation/${base}-detail-page.tsx`, renderDetailPage({ ...shape, write })],
|
|
[`${feature}/presentation/${base}-create-page.tsx`, renderCreatePage({ ...shape, write })],
|
|
] as const)
|
|
: []),
|
|
[`tests/features/${id}/${base}-test-app.tsx`, renderTestApp(shape)],
|
|
[`tests/features/${id}/${base}-feature-input.test.ts`, renderInputTest(shape)],
|
|
[`tests/features/${id}/${base}-list-page.test.tsx`, renderPageTest(shape)],
|
|
[`tests/features/${id}/${base}-http-gateway.test.ts`, renderGatewayTest(shape)],
|
|
...(write
|
|
? ([
|
|
[
|
|
`tests/features/${id}/${base}-create-page.test.tsx`,
|
|
renderCreatePageTest({ ...shape, write }),
|
|
],
|
|
] as const)
|
|
: []),
|
|
...planned.map(
|
|
(route) =>
|
|
[`docs/accessibility/route-reviews/${route.routeId}.md`, renderA11yRecord(route.routeId)] as const,
|
|
),
|
|
]);
|
|
return Object.freeze({
|
|
id,
|
|
contextId,
|
|
newContext: existing === undefined,
|
|
routeId,
|
|
routePath,
|
|
topic,
|
|
placeholder: request.contractPackage === undefined,
|
|
routes: Object.freeze(
|
|
planned.map((route) => Object.freeze({ routeId: route.routeId, path: route.path })),
|
|
),
|
|
files,
|
|
});
|
|
}
|
|
|
|
type Shape = Readonly<{
|
|
names: Names;
|
|
contextId: string;
|
|
routeId: string;
|
|
routePath: string;
|
|
chunkId: string;
|
|
navigationOrder: number;
|
|
topic: string;
|
|
operationId: string;
|
|
apiPath: string;
|
|
owner: string;
|
|
contractPackage: ContractPackageIdentity | null;
|
|
/** `--with-create`: the paired backend scaffold's create and read-by-id. */
|
|
write: WriteSlice | null;
|
|
}>;
|
|
|
|
const GENERATED = "Generated by `pnpm create:feature`.";
|
|
|
|
function renderContextModule(contextId: string, appId: string, root: string): string {
|
|
return `/**
|
|
* Ownership declaration of the ${contextId} bounded context
|
|
* (docs/architecture/starter-experience.md, "소유 선언"): the
|
|
* app that owns it, its route root and its direct-feature budget.
|
|
* ${GENERATED}
|
|
*/
|
|
export const CONTEXT_MODULE_ID = "${contextId}";
|
|
export const CONTEXT_APP_ID = "${appId}";
|
|
export const CONTEXT_ROUTE_PATH = "${root}/*";
|
|
export const CONTEXT_MAX_FEATURES = ${NEW_CONTEXT_MAX_FEATURES};
|
|
`;
|
|
}
|
|
|
|
function renderFeatureModule({ names, contextId }: Shape): string {
|
|
const { base, upper } = names;
|
|
return `import { defineFeatureModule } from "../feature-module.ts";
|
|
import {
|
|
${upper}_FEATURE_CONTRACT,
|
|
${upper}_FEATURE_ID,
|
|
} from "./contracts/${base}-feature-contract.ts";
|
|
import { ${upper}_MESSAGE_CATALOGS } from "./contracts/${base}-message-catalog.ts";
|
|
|
|
export const FEATURE_MODULE_ID = "${names.id}" satisfies typeof ${upper}_FEATURE_ID;
|
|
/** Owning bounded context (route root and budget live in its declaration). */
|
|
export const FEATURE_CONTEXT_ID = "${contextId}";
|
|
|
|
/**
|
|
* Declaration only: this file and what it imports statically are in the
|
|
* initial chunk. The executable half, \`feature-runtime.ts\`, is imported
|
|
* dynamically when a route of this feature is entered. ${GENERATED}
|
|
*/
|
|
export const FEATURE_MODULE = defineFeatureModule({
|
|
id: FEATURE_MODULE_ID,
|
|
contracts: ${upper}_FEATURE_CONTRACT,
|
|
routes: ${upper}_FEATURE_CONTRACT.routes,
|
|
messages: ${upper}_MESSAGE_CATALOGS,
|
|
loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME,
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderFeatureRuntime({ names }: Shape): string {
|
|
const { base, upper } = names;
|
|
return `import { defineFeatureRuntime } from "../feature-module.ts";
|
|
import { ${upper}_FEATURE_ADAPTER_CONTRIBUTION } from "./adapters/create-${base}-feature-input.ts";
|
|
import { ${upper}_CONTRACT_CONTRIBUTION } from "./contracts/${base}-contract-contribution.ts";
|
|
import { ${upper}_FEATURE_ID } from "./contracts/${base}-feature-contract.ts";
|
|
import { ${upper}_SCHEMA_METADATA } from "./contracts/${base}-schema-metadata.ts";
|
|
|
|
/**
|
|
* The executable half. \`feature-module.ts\` imports this file dynamically, so
|
|
* none of it is in the initial chunk.
|
|
*/
|
|
export const FEATURE_RUNTIME = defineFeatureRuntime({
|
|
featureId: ${upper}_FEATURE_ID,
|
|
schemas: ${upper}_SCHEMA_METADATA,
|
|
adapters: [${upper}_FEATURE_ADAPTER_CONTRIBUTION],
|
|
contractContributions: [${upper}_CONTRACT_CONTRIBUTION],
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderContextRoutes({ names, write }: Shape): string {
|
|
const { base, upper } = names;
|
|
return `import type { RouteObject } from "react-router-dom";
|
|
|
|
import { ${upper}_FEATURE_CONTRACT } from "./contracts/${base}-feature-contract.ts";
|
|
import { ${upper}_ROUTE_RUNTIME } from "./presentation/${base}-feature-runtime.ts";
|
|
${write ? `import { ${upper}_ROUTE_CODECS } from "./presentation/${base}-route-codecs.ts";\n` : ""}
|
|
/**
|
|
* The routes the owning context loads when its root is visited. A route with
|
|
* params or search also puts its codecs on the handle (\`codecs\`).
|
|
*/
|
|
export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze(
|
|
Object.values(${upper}_FEATURE_CONTRACT.routes).map((definition) =>
|
|
Object.freeze({
|
|
id: definition.routeId,
|
|
path: definition.path,
|
|
handle: Object.freeze({
|
|
routeId: definition.routeId,
|
|
runtime: ${upper}_ROUTE_RUNTIME[definition.routeId],${
|
|
write ? `\n codecs: ${upper}_ROUTE_CODECS,` : ""
|
|
}
|
|
}),
|
|
}),
|
|
),
|
|
);
|
|
`;
|
|
}
|
|
|
|
function renderContractPackage({ names, contractPackage }: Shape): Readonly<{
|
|
imports: string;
|
|
doc: string;
|
|
fields: string;
|
|
}> {
|
|
if (contractPackage === null) {
|
|
return {
|
|
imports: `import {
|
|
PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,
|
|
PLACEHOLDER_CONTRACT_PACKAGE_REVISION,
|
|
PLACEHOLDER_CONTRACT_PACKAGE_VERSION,
|
|
} from "../../../contracts/deployment-admission.ts";
|
|
`,
|
|
doc: ` * PLACEHOLDER: no package was given to create:feature. Local and development
|
|
* builds work; release admission refuses this identity for staging and
|
|
* production. Pin the published package's id, exact version, sha256 digest
|
|
* and source revision here.`,
|
|
fields: ` packageId: "@org-contracts/${names.base}",
|
|
version: PLACEHOLDER_CONTRACT_PACKAGE_VERSION,
|
|
digest: PLACEHOLDER_CONTRACT_PACKAGE_DIGEST,
|
|
runtimeProtocolVersion: 1 as const,
|
|
sourceRevision: PLACEHOLDER_CONTRACT_PACKAGE_REVISION,`,
|
|
};
|
|
}
|
|
return {
|
|
imports: "",
|
|
doc: ` * Pinned when the feature was created; change all four fields together.`,
|
|
fields: ` packageId: "${contractPackage.packageId}",
|
|
version: "${contractPackage.version}",
|
|
digest: "${contractPackage.digest}",
|
|
runtimeProtocolVersion: 1 as const,
|
|
sourceRevision: "${contractPackage.sourceRevision}",`,
|
|
};
|
|
}
|
|
|
|
function renderFeatureContract(shape: Shape): string {
|
|
const { names, routeId } = shape;
|
|
const { base, upper } = names;
|
|
const contractPackage = renderContractPackage(shape);
|
|
return `${contractPackage.imports}import { defineQueryInvalidationTopic } from "../../../contracts/query-invalidation.ts";
|
|
import { defineQueryNamespaceIdentity } from "../../../contracts/query-keys.ts";
|
|
|
|
export const ${upper}_FEATURE_ID = "${names.id}";
|
|
export const ${upper}_ITEM_QUERY_NAMESPACE = defineQueryNamespaceIdentity(
|
|
"${base}-item",
|
|
1,
|
|
);
|
|
/** Random, not copied: a topic id is global and a copy collides. */
|
|
export const ${upper}_ITEM_INVALIDATION_TOPIC =
|
|
defineQueryInvalidationTopic("${shape.topic}");
|
|
|
|
/**
|
|
* The contract package this feature's API comes from. The release manifest is
|
|
* checked against it at boot.
|
|
${contractPackage.doc}
|
|
*/
|
|
export const ${upper}_CONTRACT_PACKAGE = Object.freeze({
|
|
${contractPackage.fields}
|
|
});
|
|
|
|
/**
|
|
* The declaration half: what the shell reads before a route of this feature
|
|
* is entered. It is in the initial chunk, so it holds data only. Route, chunk,
|
|
* schema, operation and topic ids are global; keep the feature prefix.
|
|
*/
|
|
export const ${upper}_FEATURE_CONTRACT = Object.freeze({
|
|
featureId: ${upper}_FEATURE_ID,
|
|
routes: Object.freeze({
|
|
${routeId}: Object.freeze({
|
|
routeId: "${routeId}",
|
|
path: "${shape.routePath}",
|
|
paramsSchema: null,
|
|
searchSchema: null,
|
|
access: "session-required",
|
|
loadingSurface: "${base}-list",
|
|
errorSurface: "feature-boundary",
|
|
chunkId: "${shape.chunkId}",
|
|
title: "${names.title}",
|
|
navigationLabel: "${names.title}",
|
|
navigationOrder: ${shape.navigationOrder},
|
|
}),
|
|
${shape.write ? renderWriteRoutes({ ...shape, write: shape.write }) : ""} }),
|
|
routeRuntimeContracts: Object.freeze({
|
|
${routeId}: Object.freeze({
|
|
routeId: "${routeId}",
|
|
moduleId: "${base}-list-page",
|
|
paramsCodec: "none",
|
|
searchCodec: "none",
|
|
}),
|
|
${shape.write ? renderWriteRouteRuntimeContracts({ ...shape, write: shape.write }) : ""} }),
|
|
invalidation: Object.freeze({
|
|
topics: Object.freeze([${upper}_ITEM_INVALIDATION_TOPIC]),
|
|
namespaces: Object.freeze([${upper}_ITEM_QUERY_NAMESPACE]),
|
|
edges: Object.freeze([
|
|
Object.freeze({
|
|
topicId: ${upper}_ITEM_INVALIDATION_TOPIC,
|
|
namespace: ${upper}_ITEM_QUERY_NAMESPACE,
|
|
}),
|
|
]),
|
|
}),
|
|
topicVersions: Object.freeze([
|
|
Object.freeze({ topicId: ${upper}_ITEM_INVALIDATION_TOPIC, topicVersion: 1 }),
|
|
]),
|
|
contractPackages: Object.freeze([${upper}_CONTRACT_PACKAGE]),
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderSchemas(shape: Shape): string {
|
|
const { names, write } = shape;
|
|
const { camel, pascal, upper } = names;
|
|
return `import { z } from "../../../contracts/zod.ts";
|
|
import { zodValidator } from "../../../contracts/zod-validator.ts";
|
|
|
|
/** The GET takes no input. Schema ids are global, so this one is prefixed too. */
|
|
export const ${camel}NoRequestSchema = z.object({}).strict();
|
|
|
|
export const ${camel}ItemDtoSchema = z
|
|
.object({
|
|
id: z.string().min(1).max(120),
|
|
name: z.string().min(1).max(240),
|
|
})
|
|
.strip();
|
|
|
|
export type ${pascal}ItemDto = z.output<typeof ${camel}ItemDtoSchema>;
|
|
|
|
export const ${camel}ItemListPayloadSchema = z.array(${camel}ItemDtoSchema).max(100);
|
|
|
|
/**
|
|
* The paired backend's Envelope \`error\` (clean-architecture-backend-template
|
|
* docs/web/http-contract.md §1). Branch on \`code\`; the backend message is
|
|
* never kept.
|
|
*/
|
|
export const ${camel}ProblemSchema = z
|
|
.object({
|
|
code: z.string().regex(/^[A-Z0-9_]{1,64}$/u),
|
|
category: z.string().min(1).max(64).optional(),
|
|
retryable: z.boolean().optional(),
|
|
details: z.unknown().optional(),
|
|
})
|
|
.strip();
|
|
|
|
export type ${pascal}Problem = z.output<typeof ${camel}ProblemSchema>;
|
|
${write ? renderWriteSchemas({ ...shape, write }) : ""}
|
|
export const ${upper}_VALIDATORS = Object.freeze({
|
|
${pascal}NoRequest: zodValidator("${pascal}NoRequest", ${camel}NoRequestSchema),
|
|
${pascal}ItemListPayload: zodValidator(
|
|
"${pascal}ItemListPayload",
|
|
${camel}ItemListPayloadSchema,
|
|
),
|
|
${pascal}Problem: zodValidator("${pascal}Problem", ${camel}ProblemSchema),
|
|
${write ? renderWriteValidators({ ...shape, write }) : ""}});
|
|
`;
|
|
}
|
|
|
|
function renderMapper(shape: Shape): string {
|
|
const { names, write } = shape;
|
|
const { base, pascal } = names;
|
|
return `import {
|
|
mappingSuccess,
|
|
type BoundaryMappingResult,
|
|
} from "../../../contracts/boundary-mapper.ts";
|
|
import type { ${pascal}ItemDto } from "./${base}-schemas.ts";
|
|
|
|
/** What the page shows. A wire field never reaches presentation by its wire name. */
|
|
export type ${pascal}ItemView = Readonly<{ itemId: string; name: string }>;
|
|
|
|
/**
|
|
* 1103/03-02. The items and how many there are in all. A page list's
|
|
* \`meta.page.total\` counts every page; the array is only this page
|
|
* (the backend's default size is 20). Without \`meta.page\` the total is
|
|
* the items received.
|
|
*/
|
|
export type ${pascal}ItemList = Readonly<{
|
|
items: readonly ${pascal}ItemView[];
|
|
total: number;
|
|
}>;
|
|
|
|
function toView(dto: ${pascal}ItemDto): ${pascal}ItemView {
|
|
return Object.freeze({ itemId: dto.id, name: dto.name });
|
|
}
|
|
|
|
/**
|
|
* The HTTP contract has already validated the wire shape (\`outputValidator\`),
|
|
* so this owns only wire -> view. Put business rules in a \`domain/\` model
|
|
* when the feature has some.
|
|
*/
|
|
export function map${pascal}ItemList(
|
|
payload: readonly ${pascal}ItemDto[],
|
|
{ page }: Readonly<{ page?: Readonly<{ total: number }> }> = {},
|
|
): BoundaryMappingResult<${pascal}ItemList> {
|
|
const items = Object.freeze(payload.map(toView));
|
|
return mappingSuccess(Object.freeze({ items, total: page?.total ?? items.length }));
|
|
}
|
|
${write ? renderWriteMapper({ ...shape, write }) : ""}`;
|
|
}
|
|
|
|
function renderSchemaMetadata(shape: Shape): string {
|
|
const { names, owner, write } = shape;
|
|
const { pascal, upper } = names;
|
|
return `const OWNER = "${owner}";
|
|
|
|
/**
|
|
* FE-REG-SCHEMA rows of the feature's schemas (\`check:registries\`). The HTTP
|
|
* operation is written once, in \`${names.base}-contract-contribution.ts\`;
|
|
* FE-REG-API rows are projected from it. Runtime half only:
|
|
* \`feature-runtime.ts\` loads it. \`boundary\`, \`direction\` and
|
|
* \`unknownFieldPolicy\` must say where and how each schema is used:
|
|
* tests/unit/schema-metadata-policy.test.ts compares them with the
|
|
* descriptors, the routes and the zod validators.
|
|
*/
|
|
export const ${upper}_SCHEMA_METADATA = Object.freeze({
|
|
${pascal}NoRequest: Object.freeze({
|
|
schemaId: "${pascal}NoRequest",
|
|
boundary: "api-request",
|
|
owner: OWNER,
|
|
runtime: "zod",
|
|
schemaVersion: 1,
|
|
direction: "REQUEST",
|
|
unknownFieldPolicy: "REJECT_UNKNOWN",
|
|
}),
|
|
${pascal}ItemListPayload: Object.freeze({
|
|
schemaId: "${pascal}ItemListPayload",
|
|
boundary: "api-response",
|
|
owner: OWNER,
|
|
runtime: "zod",
|
|
schemaVersion: 1,
|
|
direction: "RESPONSE",
|
|
unknownFieldPolicy: "STRIP_UNKNOWN",
|
|
}),
|
|
${pascal}Problem: Object.freeze({
|
|
schemaId: "${pascal}Problem",
|
|
boundary: "api-problem",
|
|
owner: OWNER,
|
|
runtime: "zod",
|
|
schemaVersion: 1,
|
|
direction: "RESPONSE",
|
|
unknownFieldPolicy: "STRIP_UNKNOWN",
|
|
}),
|
|
${write ? renderWriteSchemaRows({ ...shape, write }) : ""}} as const);
|
|
`;
|
|
}
|
|
|
|
function renderContractContribution(shape: Shape): string {
|
|
const { names, operationId, apiPath, write } = shape;
|
|
const { base, pascal, upper } = names;
|
|
return `import type {
|
|
${write ? "CommandEffectDescriptor,\n " : ""}InstalledContractContribution,
|
|
InstalledHttpContract,
|
|
} from "../../../contracts/external-contract-runtime.ts";
|
|
import {
|
|
${upper}_CONTRACT_PACKAGE,
|
|
${upper}_FEATURE_ID,
|
|
} from "./${base}-feature-contract.ts";
|
|
import {
|
|
${upper}_VALIDATORS,
|
|
type ${pascal}ItemDto,${write ? `\n type ${pascal}CreateRequest,\n type ${pascal}Params,` : ""}
|
|
type ${pascal}Problem,
|
|
} from "./${base}-schemas.ts";
|
|
|
|
/**
|
|
* 1103/03-07. The paired backend's new-feature.sh maps the feature at this
|
|
* resource path (its \`--path\`, by default the plural of the name): POST
|
|
* creates and \`GET /{id}\` reads one. It generates no list: add the \`GET\`
|
|
* page list (\`PageParams\`) on the backend, or the list answers 405. The
|
|
* backend's \`api-base-path\` (\`/v1\`, \`/api\` locally) belongs in
|
|
* \`API_BASE_URL\`, which ends with a slash.
|
|
*/
|
|
const API_PATH = "${apiPath}";
|
|
|
|
/**
|
|
* The HTTP descriptor of ${operationId}, the one place the operation is
|
|
* written: it executes, and FE-REG-API reads it. It belongs to the contract
|
|
* package pinned in \`${base}-feature-contract.ts\`: import \`@org-contracts/*\`
|
|
* only in this file (external-contract-package-single-import-path) and take
|
|
* the package's descriptor instead of this local one.
|
|
*/
|
|
export const ${operationId}_CONTRACT = Object.freeze({
|
|
contract: Object.freeze({
|
|
operationId: "${operationId}",
|
|
method: "GET" as const,
|
|
pathTemplate: API_PATH,
|
|
inputValidator: ${upper}_VALIDATORS.${pascal}NoRequest,
|
|
outputValidator: ${upper}_VALIDATORS.${pascal}ItemListPayload,
|
|
problemValidator: ${upper}_VALIDATORS.${pascal}Problem,
|
|
acceptedStatuses: Object.freeze([200]),
|
|
emptyBodyStatuses: Object.freeze([]),
|
|
retrySemantics: "SAFE" as const,
|
|
requestBody: "NONE" as const,
|
|
responseBody: "REQUIRED_JSON" as const,
|
|
// The paired backend wraps every JSON body (http-contract.md §1). Every
|
|
// operation of this contribution says so (1103/16-01: composition refuses
|
|
// one that does not, and check:types one without the line). Write
|
|
// "NONE" on all of them for a backend that sends the DTO and problem
|
|
// details bare.
|
|
responseEnvelope: "ENVELOPE_V1" as const,
|
|
commandRecovery: null,
|
|
commandEffect: null,
|
|
projectRequest() {
|
|
return Object.freeze({
|
|
pathValues: Object.freeze({}),
|
|
queryEntries: Object.freeze([]),
|
|
body: null,
|
|
});
|
|
},
|
|
}),
|
|
frontend: Object.freeze({
|
|
policyId: "${upper}_LIST_V1",
|
|
requestByteLimit: 0,
|
|
responseByteLimit: 262_144,
|
|
totalDeadlineMs: 10_000,
|
|
retryBudget: 2 as const,
|
|
authProfileId: "EXTERNAL_BEARER",
|
|
diagnosticsOperation: "${base}.list",
|
|
}),
|
|
}) satisfies InstalledHttpContract<
|
|
Readonly<Record<never, never>>,
|
|
readonly ${pascal}ItemDto[],
|
|
${pascal}Problem
|
|
>;
|
|
${write ? renderWriteDescriptors({ ...shape, write }) : ""}
|
|
export const ${upper}_CONTRACT_CONTRIBUTION: InstalledContractContribution =
|
|
Object.freeze({
|
|
contributionId: "${names.id}-http-v1",
|
|
featureId: ${upper}_FEATURE_ID,
|
|
source: Object.freeze({
|
|
kind: "EXTERNAL_PACKAGE" as const,
|
|
package: ${upper}_CONTRACT_PACKAGE,
|
|
}),
|
|
http: Object.freeze([
|
|
${operationId}_CONTRACT,${
|
|
write
|
|
? `\n ${write.getOperationId}_CONTRACT,\n ${write.createOperationId}_CONTRACT,`
|
|
: ""
|
|
}
|
|
]) as readonly InstalledHttpContract<unknown, unknown, unknown>[],
|
|
events: Object.freeze([]),
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderMessageCatalog(shape: Shape): string {
|
|
const { names, routeId, write } = shape;
|
|
const { camel, title, upper } = names;
|
|
return `/** ko-KR is the source catalog; every locale has the same keys and placeholders. */
|
|
export const ${upper}_MESSAGE_CATALOGS = Object.freeze({
|
|
"ko-KR": Object.freeze({
|
|
"route.${routeId}.navigation": "${title}",
|
|
"route.${routeId}.title": "${title}",
|
|
"${camel}.list.title": "${title}",
|
|
"${camel}.list.description": "create:feature가 만든 목록입니다. 제품 문구로 바꾸세요.",
|
|
"${camel}.list.resultCount": "총 {count}개 항목",
|
|
"${camel}.list.items": "${title} 목록",
|
|
${write ? renderWriteMessages({ ...shape, write }, "ko") : ""} }),
|
|
"en-US": Object.freeze({
|
|
"route.${routeId}.navigation": "${title}",
|
|
"route.${routeId}.title": "${title}",
|
|
"${camel}.list.title": "${title}",
|
|
"${camel}.list.description": "A list create:feature generated. Replace this copy with the product's.",
|
|
"${camel}.list.resultCount": "Total items: {count}",
|
|
"${camel}.list.items": "${title} items",
|
|
${write ? renderWriteMessages({ ...shape, write }, "en") : ""} }),
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderFeatureApi(shape: Shape): string {
|
|
const { names, write } = shape;
|
|
const { base, pascal, upper } = names;
|
|
const writeTypes = write
|
|
? `
|
|
/**
|
|
* A write takes the mutation's intent: it names the operation and, for a
|
|
* KEYED command, carries the idempotency key. The executor refuses a KEYED
|
|
* command without one before sending.
|
|
*/
|
|
export type ${pascal}CommandContext = Readonly<{ signal?: AbortSignal; intent: MutationIntent }>;
|
|
|
|
export type ${pascal}CreateCommand = Readonly<{ name: string }>;
|
|
`
|
|
: "";
|
|
return `import type {} from "../../../application/ports/in/application-api.ts";
|
|
import { isAbortFailure } from "../../../contracts/errors.ts";
|
|
${write ? `import type { MutationIntent } from "../../../contracts/mutation-intent.ts";\n` : ""}import type { Result } from "../../../contracts/result.ts";
|
|
import {
|
|
failOpenTelemetryPort,
|
|
NO_OP_TELEMETRY_PORT,
|
|
type TelemetryPort,
|
|
} from "../../../platform/telemetry/telemetry-port.ts";
|
|
import { ${upper}_FEATURE_ID } from "../contracts/${base}-feature-contract.ts";
|
|
import type {
|
|
${pascal}ItemList,${write ? `\n ${pascal}ItemView,` : ""}
|
|
} from "../contracts/${base}-mapper.ts";
|
|
|
|
export type ${pascal}CallContext = Readonly<{ signal?: AbortSignal }>;
|
|
${writeTypes}
|
|
/** What the feature's pages call. Name methods after what the user does. */
|
|
export type ${pascal}FeatureInput = Readonly<{
|
|
listItems(context?: ${pascal}CallContext): Promise<Result<${pascal}ItemList>>;${
|
|
write
|
|
? `
|
|
getItem(itemId: string, context?: ${pascal}CallContext): Promise<Result<${pascal}ItemView>>;
|
|
createItem(
|
|
command: ${pascal}CreateCommand,
|
|
context: ${pascal}CommandContext,
|
|
): Promise<Result<${pascal}ItemView>>;`
|
|
: ""
|
|
}
|
|
}>;
|
|
|
|
declare module "../../../application/ports/in/application-api.ts" {
|
|
interface ApplicationFeatureInputs {
|
|
"${names.id}": ${pascal}FeatureInput;
|
|
}
|
|
}
|
|
|
|
/** The port the feature's HTTP adapter implements. */
|
|
export type ${pascal}Gateway = Readonly<{
|
|
list(context?: ${pascal}CallContext): Promise<Result<${pascal}ItemList>>;${
|
|
write
|
|
? `
|
|
get(${write.idParam}: string, context?: ${pascal}CallContext): Promise<Result<${pascal}ItemView>>;
|
|
create(
|
|
command: ${pascal}CreateCommand,
|
|
context: ${pascal}CommandContext,
|
|
): Promise<Result<${pascal}ItemView>>;`
|
|
: ""
|
|
}
|
|
}>;
|
|
|
|
export function create${pascal}FeatureInput(
|
|
gateway: ${pascal}Gateway,
|
|
{ telemetry = NO_OP_TELEMETRY_PORT }: Readonly<{ telemetry?: TelemetryPort }> = {},
|
|
): ${pascal}FeatureInput {
|
|
// scale-architecture.md §24, §26: telemetry is best-effort and never changes the result.
|
|
const events = failOpenTelemetryPort(telemetry);
|
|
function reported<Value>(kind: string, result: Result<Value>): Result<Value> {
|
|
// An aborted or fenced request did not fail (isAbortFailure).
|
|
if (!result.ok && !isAbortFailure(result.error)) {
|
|
void events.emit({
|
|
kind,
|
|
severity: "warning",
|
|
featureId: ${upper}_FEATURE_ID,
|
|
payload: Object.freeze({ reason: result.error.kind }),
|
|
});
|
|
}
|
|
return result;
|
|
}
|
|
return Object.freeze({
|
|
async listItems(context) {
|
|
return reported("${base}.list.failed", await gateway.list(context));
|
|
},${
|
|
write
|
|
? `
|
|
async getItem(itemId, context) {
|
|
return reported("${base}.detail.failed", await gateway.get(itemId, context));
|
|
},
|
|
async createItem(command, context) {
|
|
return reported("${base}.create.failed", await gateway.create(command, context));
|
|
},`
|
|
: ""
|
|
}
|
|
});
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderHttpGateway(shape: Shape): string {
|
|
const { names, operationId, routeId, write } = shape;
|
|
const { base, pascal, upper } = names;
|
|
return `import {
|
|
defineFeatureHttpOperationForRoutes,
|
|
type FeatureHttpBinding,
|
|
} from "../../../adapters/http/index.ts";
|
|
import type { ${pascal}Gateway } from "../application/${base}-feature-api.ts";
|
|
import {
|
|
${operationId}_CONTRACT,${
|
|
write
|
|
? `
|
|
${write.createOperationId}_CONTRACT,
|
|
${write.getOperationId}_CONTRACT,`
|
|
: ""
|
|
}
|
|
} from "../contracts/${base}-contract-contribution.ts";
|
|
import type { ${upper}_FEATURE_CONTRACT } from "../contracts/${base}-feature-contract.ts";
|
|
import {${write ? `\n map${pascal}Item,` : ""}
|
|
map${pascal}ItemList,
|
|
} from "../contracts/${base}-mapper.ts";
|
|
|
|
const define${pascal}HttpOperation = defineFeatureHttpOperationForRoutes<
|
|
keyof typeof ${upper}_FEATURE_CONTRACT.routes
|
|
>();
|
|
|
|
export const ${upper}_HTTP_OPERATIONS = Object.freeze({
|
|
${operationId}: define${pascal}HttpOperation({
|
|
contract: ${operationId}_CONTRACT,
|
|
routeId: "${routeId}",
|
|
// A page list's meta.page arrives as the second argument (1103/03-02).
|
|
mapSuccess: map${pascal}ItemList,
|
|
}),
|
|
${write ? renderWriteGatewayOperations({ ...shape, write }) : ""}} as const);
|
|
|
|
export function create${pascal}HttpGateway(
|
|
http: FeatureHttpBinding<typeof ${upper}_HTTP_OPERATIONS>,
|
|
): ${pascal}Gateway {
|
|
return Object.freeze({
|
|
list(context) {
|
|
return http.execute("${operationId}", Object.freeze({}), context);
|
|
},
|
|
${write ? renderWriteGatewayMethods({ ...shape, write }) : ""} });
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderCreateInput({ names }: Shape): string {
|
|
const { base, pascal, upper } = names;
|
|
return `import { createFeatureHttpBinding } from "../../../adapters/http/index.ts";
|
|
import { defineFeatureAdapterContribution } from "../../feature-adapter-contribution.ts";
|
|
import { create${pascal}FeatureInput } from "../application/${base}-feature-api.ts";
|
|
import { ${upper}_FEATURE_ID } from "../contracts/${base}-feature-contract.ts";
|
|
import {
|
|
create${pascal}HttpGateway,
|
|
${upper}_HTTP_OPERATIONS,
|
|
} from "./${base}-http-gateway.ts";
|
|
|
|
/** The feature receives only the capabilities it names in \`needs\`. */
|
|
export const ${upper}_FEATURE_ADAPTER_CONTRIBUTION = defineFeatureAdapterContribution({
|
|
featureId: ${upper}_FEATURE_ID,
|
|
needs: ["http", "telemetry"] as const,
|
|
createInput: ({ http, telemetry }) =>
|
|
Object.freeze({
|
|
featureId: ${upper}_FEATURE_ID,
|
|
input: create${pascal}FeatureInput(
|
|
create${pascal}HttpGateway(createFeatureHttpBinding(http, ${upper}_HTTP_OPERATIONS)),
|
|
{ telemetry },
|
|
),
|
|
}),
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderRouteRuntime({ names, routeId, write }: Shape): string {
|
|
const { base, upper } = names;
|
|
const page = (id: string, moduleId: string, file: string) => ` ${id}: Object.freeze({
|
|
moduleId: "${moduleId}",
|
|
Component: lazy(() => import("./${file}")),
|
|
}),
|
|
`;
|
|
return `import { lazy } from "react";
|
|
|
|
/** The lazy page of each route; \`moduleId\` equals the route runtime contract's. */
|
|
export const ${upper}_ROUTE_RUNTIME = {
|
|
${page(routeId, `${base}-list-page`, `${base}-list-page.tsx`)}${
|
|
write
|
|
? page(write.detail.routeId, write.detail.moduleId, `${base}-detail-page.tsx`) +
|
|
page(write.create.routeId, write.create.moduleId, `${base}-create-page.tsx`)
|
|
: ""
|
|
}} as const;
|
|
`;
|
|
}
|
|
|
|
function renderRoutes({ names, write }: Shape): string {
|
|
const { base, camel, pascal, upper } = names;
|
|
if (write === null) {
|
|
return `import { buildRouteUrl } from "../../../presentation/routes/route-codecs.ts";
|
|
import type { ${upper}_FEATURE_CONTRACT } from "../contracts/${base}-feature-contract.ts";
|
|
|
|
/**
|
|
* 16-04. A link names its route ID and the router's builder fills in the
|
|
* contract's \`path\`, so the contract stays the one place a path is written.
|
|
* Once a route has params or search, pass its codecs as the third argument.
|
|
*/
|
|
export function ${camel}RouteUrl(
|
|
routeId: keyof typeof ${upper}_FEATURE_CONTRACT.routes,
|
|
input?: Parameters<typeof buildRouteUrl>[1],
|
|
): string {
|
|
return buildRouteUrl(routeId, input);
|
|
}
|
|
`;
|
|
}
|
|
return `import { buildRouteUrl } from "../../../presentation/routes/route-codecs.ts";
|
|
import { useRouteInput } from "../../../presentation/routes/route-input.tsx";
|
|
import type { ${upper}_FEATURE_CONTRACT } from "../contracts/${base}-feature-contract.ts";
|
|
import { ${upper}_ROUTE_CODECS } from "./${base}-route-codecs.ts";
|
|
|
|
/**
|
|
* 16-04. A link names its route ID and the router's builder fills in the
|
|
* contract's \`path\` through the codecs that parse it, so the contract stays
|
|
* the one place a path is written.
|
|
*/
|
|
export function ${camel}RouteUrl(
|
|
routeId: keyof typeof ${upper}_FEATURE_CONTRACT.routes,
|
|
input?: Parameters<typeof buildRouteUrl>[1],
|
|
): string {
|
|
return buildRouteUrl(routeId, input, ${upper}_ROUTE_CODECS);
|
|
}
|
|
|
|
/** The detail route's id, read back through the codec that accepted it. */
|
|
export function use${pascal}ItemId(): string {
|
|
return ${upper}_ROUTE_CODECS.${pascal}Params.parse(useRouteInput().params).${write.idParam};
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderUseItems({ names }: Shape): string {
|
|
const { base, pascal, upper } = names;
|
|
return `import { bindQuery, type QueryResultMeasure } from "../../../contracts/server-state.ts";
|
|
import { useApplicationQuery } from "../../../presentation/adapters/query/application-query.ts";
|
|
import { useServerStateScope } from "../../../presentation/adapters/query/server-state-scope-provider.tsx";
|
|
import { useApplicationFeature } from "../../../presentation/providers/application-provider.tsx";
|
|
import {
|
|
${upper}_FEATURE_ID,
|
|
${upper}_ITEM_QUERY_NAMESPACE,
|
|
} from "../contracts/${base}-feature-contract.ts";
|
|
import type { ${pascal}ItemList } from "../contracts/${base}-mapper.ts";
|
|
|
|
const UTF8 = new TextEncoder();
|
|
const NO_INPUT = Object.freeze({});
|
|
|
|
/**
|
|
* §10.4. Bounded estimate of the mapped value: string bytes plus a fixed
|
|
* per-item overhead, never \`JSON.stringify\`.
|
|
*/
|
|
function measureItems(list: ${pascal}ItemList): QueryResultMeasure {
|
|
let estimatedBytes = 24;
|
|
for (const item of list.items) {
|
|
estimatedBytes +=
|
|
UTF8.encode(item.itemId).byteLength + UTF8.encode(item.name).byteLength + 16;
|
|
}
|
|
return { itemCount: list.items.length, estimatedBytes };
|
|
}
|
|
|
|
export function use${pascal}Items() {
|
|
const input = useApplicationFeature(${upper}_FEATURE_ID);
|
|
const scope = useServerStateScope();
|
|
return useApplicationQuery(
|
|
bindQuery(
|
|
{
|
|
definitionId: "${base}-item-list-v1",
|
|
definitionVersion: 1,
|
|
namespace: ${upper}_ITEM_QUERY_NAMESPACE,
|
|
profileId: "LIST_STANDARD",
|
|
measureResult: measureItems,
|
|
execute: (_input: typeof NO_INPUT, { signal }) => input.listItems({ signal }),
|
|
},
|
|
NO_INPUT,
|
|
scope,
|
|
),
|
|
);
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderListPage({ names, write }: Shape): string {
|
|
const { base, camel, pascal } = names;
|
|
const item = write
|
|
? `<li key={item.itemId}>
|
|
<Link
|
|
to={${camel}RouteUrl("${write.detail.routeId}", {
|
|
params: { ${write.idParam}: item.itemId },
|
|
})}
|
|
>
|
|
{item.name}
|
|
</Link>
|
|
</li>`
|
|
: `<li key={item.itemId}>{item.name}</li>`;
|
|
return `${write ? `import { Link } from "react-router-dom";\n\n` : ""}import {
|
|
AsyncSurface,
|
|
CollectionPage,
|
|
EmptySurface,
|
|
} from "../../../presentation/design-system/index.ts";
|
|
import { useLocale } from "../../../presentation/i18n/index.ts";
|
|
${write ? `import { ${camel}RouteUrl } from "./${base}-routes.ts";\n` : ""}import { use${pascal}Items } from "./use-${base}-items.ts";
|
|
|
|
/**
|
|
* The result count is the backend's total (\`meta.page.total\`), not the
|
|
* length of this page. An empty list renders the shared empty state under
|
|
* the page heading.
|
|
*/
|
|
export default function ${pascal}ListPage() {
|
|
const { message, number } = useLocale();
|
|
const query = use${pascal}Items();
|
|
return (
|
|
<CollectionPage
|
|
heading={{
|
|
title: message("${camel}.list.title"),
|
|
description: message("${camel}.list.description"),
|
|
}}${
|
|
write
|
|
? `
|
|
actions={[
|
|
{
|
|
kind: "link",
|
|
label: message("${camel}.list.create"),
|
|
to: ${camel}RouteUrl("${write.create.routeId}"),
|
|
variant: "primary",
|
|
},
|
|
]}`
|
|
: ""
|
|
}
|
|
resultCount={
|
|
query.data
|
|
? message("${camel}.list.resultCount", { count: number(query.data.total) })
|
|
: null
|
|
}
|
|
>
|
|
<AsyncSurface state={query.state} onRetry={query.retry}>
|
|
{query.data?.items.length ? (
|
|
<ul aria-label={message("${camel}.list.items")}>
|
|
{query.data.items.map((item) => (
|
|
${item}
|
|
))}
|
|
</ul>
|
|
) : (
|
|
<EmptySurface />
|
|
)}
|
|
</AsyncSurface>
|
|
</CollectionPage>
|
|
);
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderInputTest({ names, operationId }: Shape): string {
|
|
const { base, pascal } = names;
|
|
return `import { describe, expect, it, vi } from "vitest";
|
|
|
|
import { createFailure } from "../../../src/contracts/errors.ts";
|
|
import { create${pascal}FeatureInput } from "../../../src/features/${names.id}/application/${base}-feature-api.ts";
|
|
import type { TelemetryPort } from "../../../src/platform/telemetry/telemetry-port.ts";
|
|
|
|
const ITEMS = Object.freeze({
|
|
items: Object.freeze([Object.freeze({ itemId: "item-1", name: "First item" })]),
|
|
total: 1,
|
|
});
|
|
|
|
/** A gateway whose other methods are never called. */
|
|
function gatewayListing(list: () => Promise<unknown>) {
|
|
return { list } as unknown as Parameters<typeof create${pascal}FeatureInput>[0];
|
|
}
|
|
|
|
describe("${names.id} application input", () => {
|
|
it("returns the gateway's items without telemetry", async () => {
|
|
const emit = vi.fn<TelemetryPort["emit"]>();
|
|
const input = create${pascal}FeatureInput(
|
|
gatewayListing(async () => ({ ok: true, value: ITEMS })),
|
|
{ telemetry: { emit } },
|
|
);
|
|
|
|
await expect(input.listItems()).resolves.toEqual({ ok: true, value: ITEMS });
|
|
expect(emit).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("returns a failed load and reports its kind", async () => {
|
|
const failure = createFailure("REQUEST_TIMEOUT", "${operationId}", 0);
|
|
const emit = vi.fn<TelemetryPort["emit"]>();
|
|
const input = create${pascal}FeatureInput(
|
|
gatewayListing(async () => ({ ok: false, error: failure })),
|
|
{ telemetry: { emit } },
|
|
);
|
|
|
|
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
|
expect(emit).toHaveBeenCalledWith({
|
|
kind: "${base}.list.failed",
|
|
severity: "warning",
|
|
featureId: "${names.id}",
|
|
payload: { reason: "REQUEST_TIMEOUT" },
|
|
});
|
|
});
|
|
|
|
it("does not report a load its caller aborted", async () => {
|
|
const failure = createFailure("REQUEST_ABORTED", "${operationId}", 0);
|
|
const emit = vi.fn<TelemetryPort["emit"]>();
|
|
const input = create${pascal}FeatureInput(
|
|
gatewayListing(async () => ({ ok: false, error: failure })),
|
|
{ telemetry: { emit } },
|
|
);
|
|
|
|
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
|
expect(emit).not.toHaveBeenCalled();
|
|
});
|
|
|
|
it("does not report a load a scope fence ended", async () => {
|
|
const failure = createFailure("SCOPE_GENERATION_CHANGED", "${operationId}", 0);
|
|
const emit = vi.fn<TelemetryPort["emit"]>();
|
|
const input = create${pascal}FeatureInput(
|
|
gatewayListing(async () => ({ ok: false, error: failure })),
|
|
{ telemetry: { emit } },
|
|
);
|
|
|
|
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
|
expect(emit).not.toHaveBeenCalled();
|
|
});
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderPageTest({ names, operationId, routeId, apiPath }: Shape): string {
|
|
const { base, camel, upper } = names;
|
|
return `// @vitest-environment jsdom
|
|
|
|
import { screen } from "@testing-library/react";
|
|
import { http, HttpResponse } from "msw";
|
|
import { setupServer } from "msw/node";
|
|
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
|
|
|
|
import { ${operationId}_CONTRACT } from "../../../src/features/${names.id}/contracts/${base}-contract-contribution.ts";
|
|
import { ${upper}_MESSAGE_CATALOGS } from "../../../src/features/${names.id}/contracts/${base}-message-catalog.ts";
|
|
import { ${camel}RouteUrl } from "../../../src/features/${names.id}/presentation/${base}-routes.ts";
|
|
import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts";
|
|
import { createHttpScenarioHandler } from "../../mocks/handlers/http-scenarios.ts";
|
|
import { API, openSignedIn } from "./${base}-test-app.tsx";
|
|
|
|
const MESSAGES = ${upper}_MESSAGE_CATALOGS["ko-KR"];
|
|
|
|
const api = setupServer();
|
|
beforeAll(() => api.listen({ onUnhandledRequest: "error" }));
|
|
afterEach(() => api.resetHandlers());
|
|
afterAll(() => api.close());
|
|
|
|
/** Enters the list through the router, as a signed-in user. */
|
|
async function openList() {
|
|
const user = await openSignedIn(${camel}RouteUrl("${routeId}"));
|
|
expect(
|
|
await screen.findByRole("heading", { level: 1, name: MESSAGES["${camel}.list.title"] }),
|
|
).toBeVisible();
|
|
return user;
|
|
}
|
|
|
|
describe("${names.id} list page through the router", () => {
|
|
it("lists the items the API returns", async () => {
|
|
api.use(
|
|
createHttpScenarioHandler(${operationId}_CONTRACT, {
|
|
payload: [{ id: "item-1", name: "First item" }],
|
|
}),
|
|
);
|
|
await openList();
|
|
|
|
expect(await screen.findByText("First item")).toBeVisible();
|
|
});
|
|
|
|
// 1103/03-02. The backend's page list counts every page in meta.page.
|
|
it("counts the items the backend counted, not the first page", async () => {
|
|
api.use(
|
|
http.get(\`\${API}${apiPath}\`, () =>
|
|
HttpResponse.json({
|
|
success: true,
|
|
data: [{ id: "item-1", name: "First item" }],
|
|
meta: { page: { number: 0, size: 20, total: 12345, sort: null } },
|
|
}),
|
|
),
|
|
);
|
|
await openList();
|
|
|
|
// 1112/04-03. The count is a locale-formatted number.
|
|
expect(await screen.findByText("총 12,345개 항목")).toBeVisible();
|
|
});
|
|
|
|
// The backend answers an empty list as \`data: []\`, never by dropping \`data\`.
|
|
it("renders an empty list as the empty state", async () => {
|
|
api.use(createHttpScenarioHandler(${operationId}_CONTRACT, { scenario: "empty", payload: [] }));
|
|
await openList();
|
|
|
|
expect(await screen.findByRole("heading", { name: KO_MESSAGES["async.empty"] })).toBeVisible();
|
|
});
|
|
|
|
it("shows a failed load and loads again on retry", async () => {
|
|
api.use(
|
|
createHttpScenarioHandler(${operationId}_CONTRACT, {
|
|
scenario: "server-terminal-503",
|
|
payload: [],
|
|
}),
|
|
);
|
|
const user = await openList();
|
|
const retry = await screen.findByRole("button", { name: KO_MESSAGES["action.retry"] });
|
|
api.use(
|
|
createHttpScenarioHandler(${operationId}_CONTRACT, {
|
|
payload: [{ id: "item-2", name: "Second item" }],
|
|
}),
|
|
);
|
|
await user.click(retry);
|
|
|
|
expect(await screen.findByText("Second item")).toBeVisible();
|
|
});
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderTestApp({ names }: Shape): string {
|
|
return `import { render, screen } from "@testing-library/react";
|
|
import userEvent from "@testing-library/user-event";
|
|
|
|
import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.ts";
|
|
import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.tsx";
|
|
import { KO_MESSAGES } from "../../../src/presentation/i18n/catalog.ts";
|
|
|
|
/**
|
|
* The whole app for the ${names.id} page tests: boot documents from here,
|
|
* every API call to MSW at \`API\`. Retries are off so a failure shows at
|
|
* once; the gateway test runs the app's default of two.
|
|
*/
|
|
export const API = "https://api.test";
|
|
|
|
const RUNTIME_CONFIG = {
|
|
APP_ENV: "local",
|
|
API_BASE_URL: API,
|
|
REQUEST_TIMEOUT_MS: 10_000,
|
|
MAX_RETRY_ATTEMPTS: 0,
|
|
TELEMETRY_ENABLED: false,
|
|
AUTH_MODE: "demo",
|
|
CONFIG_SCHEMA_VERSION: "1",
|
|
API_CONTRACT_VERSION: "1",
|
|
RELEASE_MANIFEST_URL: "/release-manifest.json",
|
|
BUILD_ID: "local-build",
|
|
RELEASE_ID: "local-release",
|
|
};
|
|
const RELEASE_MANIFEST = {
|
|
schemaVersion: 1,
|
|
appVersion: "0.0.0",
|
|
buildId: "local-build",
|
|
commitSha: "local",
|
|
configSchemaVersion: "1",
|
|
apiContractVersion: "1",
|
|
assetManifestHash: "test-hash",
|
|
releaseId: "local-release",
|
|
builtAt: "2026-01-01T00:00:00.000Z",
|
|
routeChunks: { "route-home": "assets/home.js" },
|
|
};
|
|
|
|
const fetcher: typeof fetch = (input, init) => {
|
|
const url = new URL(input instanceof Request ? input.url : String(input), "http://app.test");
|
|
if (url.pathname === "/config.json") return Promise.resolve(Response.json(RUNTIME_CONFIG));
|
|
if (url.pathname === "/release-manifest.json") {
|
|
return Promise.resolve(Response.json(RELEASE_MANIFEST));
|
|
}
|
|
return fetch(input instanceof Request ? input : url, init);
|
|
};
|
|
|
|
/** Opens a URL of the feature through the router and signs in (demo mode). */
|
|
export async function openSignedIn(url: string) {
|
|
const user = userEvent.setup();
|
|
window.history.pushState({}, "", url);
|
|
render(
|
|
<RuntimeApplication
|
|
composition={await createRuntimeComposition({ fetcher, host: {} })}
|
|
/>,
|
|
);
|
|
await user.click(await screen.findByRole("button", { name: KO_MESSAGES["action.signIn"] }));
|
|
return user;
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderGatewayTest(shape: Shape): string {
|
|
const { names, apiPath, write } = shape;
|
|
const { base, pascal, upper } = names;
|
|
return `import { http, HttpResponse, type JsonBodyType } from "msw";
|
|
import { setupServer } from "msw/node";
|
|
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
|
|
|
|
import {
|
|
createContractHttpExecutor,
|
|
createFeatureHttpBinding,
|
|
type InstalledHttpOperationExecutor,
|
|
} from "../../../src/adapters/http/index.ts";
|
|
${write ? `import { defineMutationIntent } from "../../../src/contracts/mutation-intent.ts";\n` : ""}import {
|
|
create${pascal}HttpGateway,
|
|
${upper}_HTTP_OPERATIONS,
|
|
} from "../../../src/features/${names.id}/adapters/${base}-http-gateway.ts";
|
|
|
|
/**
|
|
* The paired backend's wire (clean-architecture-backend-template
|
|
* docs/web/http-contract.md §1): every JSON body is an Envelope, and a null
|
|
* field is dropped with its key. The bodies are written out here rather than
|
|
* taken from the shared scenarios, so this fails if a descriptor stops
|
|
* reading that wire (1103/16-01). Add a case here for each operation you add.
|
|
*/
|
|
const API = "https://api.test";
|
|
const META = { requestId: "req-1", traceId: "0af7651916cd43dd8448eb211c80319c" };
|
|
|
|
const api = setupServer();
|
|
beforeAll(() => api.listen({ onUnhandledRequest: "error" }));
|
|
afterEach(() => api.resetHandlers());
|
|
afterAll(() => api.close());
|
|
|
|
function answer(status: number, body: JsonBodyType) {
|
|
api.use(http.get(\`\${API}${apiPath}\`, () => HttpResponse.json(body, { status })));
|
|
}
|
|
|
|
function failure(code: string, details?: JsonBodyType, category = "VALIDATION") {
|
|
return {
|
|
success: false,
|
|
error: {
|
|
code,
|
|
category,
|
|
message: "backend message",
|
|
retryable: false,
|
|
...(details === undefined ? {} : { details }),
|
|
},
|
|
meta: META,
|
|
};
|
|
}
|
|
${write ? renderWriteGatewayHelpers({ ...shape, write }) : ""}
|
|
/**
|
|
* The app's default retry limit (MAX_RETRY_ATTEMPTS 2 in config/runtime) with
|
|
* no backoff wait, so the descriptors' own retry budgets decide.
|
|
*/
|
|
function gateway() {
|
|
const executor = createContractHttpExecutor({
|
|
baseUrl: API,
|
|
maxRetryAttempts: 2,
|
|
random: () => 0,
|
|
attachCredentials: () => ({
|
|
kind: "READY" as const,
|
|
headers: { authorization: "Bearer test-token" },
|
|
}),
|
|
});
|
|
const installed: InstalledHttpOperationExecutor = Object.freeze({
|
|
execute: (contract, input, context) =>
|
|
executor.execute(contract, input, {
|
|
routeId: context.routeId,
|
|
...(context.intent === undefined ? {} : { intent: context.intent }),
|
|
scope: Object.freeze({
|
|
generation: 1,
|
|
fingerprint: "${names.id}-test-scope",
|
|
identities: Object.freeze({}) as never,
|
|
signal: new AbortController().signal,
|
|
isCurrent: () => true,
|
|
}),
|
|
}),
|
|
});
|
|
return create${pascal}HttpGateway(createFeatureHttpBinding(installed, ${upper}_HTTP_OPERATIONS));
|
|
}
|
|
|
|
describe("${names.id} HTTP gateway on the paired backend's Envelope", () => {
|
|
it("reads the success Envelope's data", async () => {
|
|
answer(200, { success: true, data: [{ id: "item-1", name: "First item" }], meta: META });
|
|
|
|
await expect(gateway().list()).resolves.toEqual({
|
|
ok: true,
|
|
value: { items: [{ itemId: "item-1", name: "First item" }], total: 1 },
|
|
});
|
|
});
|
|
|
|
// 1103/03-02. A page list counts every page in meta.page.
|
|
it("reads the total of a page list from meta.page", async () => {
|
|
answer(200, {
|
|
success: true,
|
|
data: [{ id: "item-1", name: "First item" }],
|
|
meta: { ...META, page: { number: 0, size: 20, total: 41, sort: null } },
|
|
});
|
|
|
|
await expect(gateway().list()).resolves.toMatchObject({ ok: true, value: { total: 41 } });
|
|
});
|
|
|
|
it("reads an Envelope whose null keys the backend dropped", async () => {
|
|
// No id keys: the answer was written before the request id filter.
|
|
answer(200, { success: true, data: [], meta: {} });
|
|
|
|
await expect(gateway().list()).resolves.toEqual({
|
|
ok: true,
|
|
value: { items: [], total: 0 },
|
|
});
|
|
});
|
|
|
|
it("reads the failure Envelope's code and drops its message", async () => {
|
|
answer(404, failure("NOT_FOUND"));
|
|
const result = await gateway().list();
|
|
|
|
expect(result).toMatchObject({
|
|
ok: false,
|
|
error: { kind: "NOT_FOUND", code: "NOT_FOUND", httpStatus: 404 },
|
|
});
|
|
expect(JSON.stringify(result)).not.toContain("backend message");
|
|
});
|
|
|
|
it("reads a parameter validation failure's field list", async () => {
|
|
answer(
|
|
400,
|
|
failure("VALIDATION_FAILED", [{ field: "size", code: "MAX", message: "too large" }]),
|
|
);
|
|
|
|
await expect(gateway().list()).resolves.toMatchObject({
|
|
ok: false,
|
|
error: {
|
|
kind: "VALIDATION_REJECTED",
|
|
code: "VALIDATION_FAILED",
|
|
validationIssues: [{ path: "size", code: "MAX" }],
|
|
},
|
|
});
|
|
});
|
|
|
|
it("refuses a bare DTO", async () => {
|
|
answer(200, [{ id: "item-1", name: "First item" }]);
|
|
|
|
await expect(gateway().list()).resolves.toMatchObject({
|
|
ok: false,
|
|
error: { kind: "ENVELOPE_MISMATCH" },
|
|
});
|
|
});
|
|
${write ? renderWriteGatewayTests({ ...shape, write }) : ""}});
|
|
`;
|
|
}
|
|
|
|
function renderA11yRecord(routeId: string): string {
|
|
return `# ${routeId} accessibility review
|
|
|
|
Status: pending-manual-review
|
|
Route ID: ${routeId}
|
|
Release ID:
|
|
Reviewer:
|
|
Reviewed at:
|
|
Signature:
|
|
Attestation: pending
|
|
M1 Keyboard: pending
|
|
M2 Visible focus: pending
|
|
M3 Route focus: pending
|
|
M4 Modal focus: pending
|
|
M5 Error association: pending
|
|
M6 Color signal: pending
|
|
M7 Reduced motion: pending
|
|
Screen reader: pending
|
|
Notes: Human review pending. ${GENERATED}
|
|
`;
|
|
}
|
|
|
|
async function exists(target: string): Promise<boolean> {
|
|
return access(target).then(
|
|
() => true,
|
|
() => false,
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Writes every file or none. An existing file or feature directory is never
|
|
* overwritten; a write that fails removes what this call created.
|
|
*/
|
|
export async function writeFeatureFiles(
|
|
root: string,
|
|
files: ReadonlyMap<string, string>,
|
|
ownedDirectories: readonly string[] = [],
|
|
): Promise<readonly string[]> {
|
|
const taken: string[] = [];
|
|
for (const relative of [...ownedDirectories, ...files.keys()]) {
|
|
if (await exists(path.join(root, relative))) taken.push(relative);
|
|
}
|
|
if (taken.length > 0) {
|
|
throw new CreateFeatureError(`refusing to overwrite: ${taken.join(", ")}`);
|
|
}
|
|
const created: string[] = [];
|
|
try {
|
|
for (const [relative, content] of files) {
|
|
const target = path.join(root, relative);
|
|
const firstDirectory = await mkdir(path.dirname(target), { recursive: true });
|
|
if (firstDirectory !== undefined) created.push(firstDirectory);
|
|
await writeFile(target, content, { flag: "wx" });
|
|
created.push(target);
|
|
}
|
|
} catch (error) {
|
|
await rollBack(created);
|
|
throw error;
|
|
}
|
|
return Object.freeze(created);
|
|
}
|
|
|
|
async function rollBack(created: readonly string[]): Promise<void> {
|
|
for (const target of [...created].reverse()) {
|
|
await rm(target, { recursive: true, force: true });
|
|
}
|
|
}
|
|
|
|
async function directoryNames(directory: string): Promise<string[]> {
|
|
const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
|
|
return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
|
|
}
|
|
|
|
async function readInstalledFacts(root: string): Promise<InstalledFacts> {
|
|
const source = await createFileSystemDeclarationSource(root);
|
|
const contexts = source.appIds().flatMap((appId) => source.contextsOf(appId));
|
|
// The script's generator run (package.json) made these current.
|
|
const { ROUTE_REGISTRY, INVALIDATION_REGISTRY } = await import(
|
|
"../src/features/installed-feature-contracts.ts"
|
|
);
|
|
const { KO_MESSAGES } = await import("../src/presentation/i18n/catalog.ts");
|
|
return Object.freeze({
|
|
appIds: source.appIds(),
|
|
featureIds: [
|
|
...new Set([
|
|
...contexts.flatMap((context) =>
|
|
source.featuresOf(context.id).map((feature) => feature.id),
|
|
),
|
|
...(await directoryNames(path.join(root, "src/features"))),
|
|
]),
|
|
],
|
|
contexts: contexts.map(({ id, routePath }) => ({ id, routePath })),
|
|
contextDirectories: await directoryNames(path.join(root, "src/contexts")),
|
|
routes: Object.values(ROUTE_REGISTRY).map((route) => ({
|
|
routeId: route.routeId,
|
|
path: route.path,
|
|
chunkId: route.chunkId,
|
|
navigationOrder: route.navigationOrder,
|
|
})),
|
|
topics: [...INVALIDATION_REGISTRY.topics],
|
|
messageKeys: Object.keys(KO_MESSAGES),
|
|
});
|
|
}
|
|
|
|
/**
|
|
* 1105/16-01. Tracked template files that change with every added feature,
|
|
* and the command that writes each. A feature branch commits them with the
|
|
* feature; two feature branches change the same lines, and the merge takes
|
|
* the command again instead of a hand-merged value. docs/manual/03 (A) and
|
|
* the "feature 추가" table in docs/architecture/starter-experience.md
|
|
* list them (tests/unit/feature-tracked-files.test.ts).
|
|
*/
|
|
export const FEATURE_TRACKED_FILE_REWRITES = Object.freeze([
|
|
Object.freeze({
|
|
path: "public/release-manifest.json",
|
|
command: "node scripts/write-dev-release-manifest.ts",
|
|
when: "create:feature runs it: the dev server's manifest names the installed contract packages",
|
|
}),
|
|
Object.freeze({
|
|
path: "config/scale/feature-shape-ceilings.json",
|
|
command: "node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write",
|
|
when: "by hand with the feature: test:unit compares it with a build",
|
|
}),
|
|
]);
|
|
|
|
const USAGE =
|
|
"Usage: pnpm create:feature <id> [--context <context id>] [--with-create [--keyed]] " +
|
|
"[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]";
|
|
|
|
export function parseRequest(argv: readonly string[]): FeatureRequest {
|
|
const args = argv[0] === "--" ? argv.slice(1) : [...argv];
|
|
const { values, positionals } = parseArgs({
|
|
args,
|
|
allowPositionals: true,
|
|
options: {
|
|
context: { type: "string" },
|
|
package: { type: "string" },
|
|
digest: { type: "string" },
|
|
revision: { type: "string" },
|
|
"with-create": { type: "boolean" },
|
|
keyed: { type: "boolean" },
|
|
},
|
|
});
|
|
const [id, ...extra] = positionals;
|
|
if (id === undefined || extra.length > 0) fail(USAGE);
|
|
const given = [values.package, values.digest, values.revision].filter(
|
|
(value) => value !== undefined,
|
|
);
|
|
if (given.length !== 0 && given.length !== 3) {
|
|
fail(`--package, --digest and --revision go together. ${USAGE}`);
|
|
}
|
|
let contractPackage: ContractPackageIdentity | undefined;
|
|
if (values.package !== undefined) {
|
|
const at = values.package.lastIndexOf("@");
|
|
if (at <= 0) fail(`--package must be @scope/name@<exact version>. ${USAGE}`);
|
|
contractPackage = Object.freeze({
|
|
packageId: values.package.slice(0, at),
|
|
version: values.package.slice(at + 1),
|
|
digest: values.digest ?? "",
|
|
sourceRevision: values.revision ?? "",
|
|
});
|
|
}
|
|
if (values.keyed === true && values["with-create"] !== true) {
|
|
fail(`--keyed needs --with-create. ${USAGE}`);
|
|
}
|
|
const write: WriteSemantics | undefined =
|
|
values["with-create"] === true ? (values.keyed === true ? "KEYED" : "NEVER") : undefined;
|
|
return Object.freeze({ id, context: values.context, contractPackage, write });
|
|
}
|
|
|
|
function report(plan: FeaturePlan): string {
|
|
const lines = [
|
|
`create:feature: ${plan.id} in ${plan.contextId}${plan.newContext ? " (new context)" : ""}, ${plan.routes
|
|
.map((route) => `route ${route.routeId} at ${route.path}`)
|
|
.join(", ")}`,
|
|
...[...plan.files.keys()].map((file) => ` created ${file}`),
|
|
"",
|
|
"Next:",
|
|
` 1. Before a release, have a person review and sign ${plan.routes
|
|
.map((route) => `docs/accessibility/route-reviews/${route.routeId}.md`)
|
|
.join(", ")} (FE-GATE-028). The merge gates check only their format.`,
|
|
" 2. Run the merge gates: corepack pnpm ci:gate -- FE-GATE-<NNN> for each gate of the merge stage in config/ci/gates.json (README lists the loop). test:feature-scaffold runs them on a generated feature except the browser gates FE-GATE-008/009 and test:system.",
|
|
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
|
|
" A failing gate's log is artifacts/quality/gates/FE-GATE-<NNN>.txt. Locally FE-GATE-013 needs VITE_COMMIT_SHA=$(git rev-parse HEAD); to run them as CI does, set CI=true and the CI build identity (README).",
|
|
" 3. The initial JavaScript changes. Rewrite config/scale/feature-shape-ceilings.json with node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write and commit it with the feature; test:unit compares it with a build. corepack pnpm check:bundle checks the budget.",
|
|
" public/release-manifest.json (the dev server's manifest) now names the feature's contract package; commit it with the feature.",
|
|
" Two feature branches change the same lines of these files. On a merge conflict, take either side and run the command again:",
|
|
...FEATURE_TRACKED_FILE_REWRITES.map((file) => ` ${file.path}: ${file.command}`),
|
|
" The registry baseline does not change: new routes, operations, schemas and invalidation topics are additive.",
|
|
];
|
|
return `${lines.join("\n")}\n`;
|
|
}
|
|
|
|
async function main(): Promise<void> {
|
|
const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
|
|
const root = path.resolve(scriptDirectory, "..");
|
|
let request: FeatureRequest;
|
|
try {
|
|
request = parseRequest(process.argv.slice(2));
|
|
} catch (error) {
|
|
process.stderr.write(`create:feature: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
process.exitCode = 2;
|
|
return;
|
|
}
|
|
try {
|
|
const plan = planFeature(request, await readInstalledFacts(root));
|
|
const created = await writeFeatureFiles(root, plan.files, [
|
|
`src/features/${plan.id}`,
|
|
`tests/features/${plan.id}`,
|
|
]);
|
|
// The generator reads the new declarations; it fails on any it rejects.
|
|
const generated = spawnSync(
|
|
process.execPath,
|
|
[path.join(scriptDirectory, "generate-product-feature-index.ts")],
|
|
{ cwd: root, encoding: "utf8" },
|
|
);
|
|
if (generated.status !== 0) {
|
|
await rollBack(created);
|
|
fail(`the feature index generator rejected the feature, nothing was kept:\n${generated.stderr}`);
|
|
}
|
|
// 1103 X2 #3. The dev server's release manifest names the installed
|
|
// contract packages; the new feature declares one.
|
|
const manifest = spawnSync(
|
|
process.execPath,
|
|
[path.join(scriptDirectory, "write-dev-release-manifest.ts")],
|
|
{ cwd: root, encoding: "utf8" },
|
|
);
|
|
if (manifest.status !== 0) {
|
|
fail(`public/release-manifest.json could not be rewritten:\n${manifest.stderr}`);
|
|
}
|
|
process.stdout.write(report(plan));
|
|
if (plan.placeholder) {
|
|
process.stderr.write(
|
|
`create:feature warning: no --package was given, so src/features/${plan.id}/contracts/${namesOf(plan.id).base}-feature-contract.ts pins the placeholder contract identity. ` +
|
|
"Local and development builds work; release admission refuses it for staging and production. " +
|
|
"Pin the published package's id, version, digest and revision there, and take the package's descriptor in the contract contribution.\n",
|
|
);
|
|
}
|
|
} catch (error) {
|
|
process.stderr.write(`create:feature: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
process.exitCode = 1;
|
|
}
|
|
}
|
|
|
|
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
|
|
await main();
|
|
}
|