문제 QueryDefinition의 owner·operationId와 BoundMutation의 owner는 필수 칸이다. bindQuery가 돌려주는 객체에는 둘 다 없고, src 어디서도 읽지 않는다. 기능 작성자는 효과 없는 값을 매번 채우고, 매뉴얼은 그 오타를 "못 잡는 위험"으로 적어 오히려 신경 쓰게 한다(리뷰 16-06 ①②). 고른 방법 세 칸을 @deprecated 선택 칸으로 바꾼다. 참조 기능과 생성 뼈대는 더는 채우지 않는다. 요청 기록의 operation ID는 지금처럼 descriptor에서 온다. 매뉴얼 6·7단계와 patterns.md에 "적지 않는다"와, 라우트 계약 title· navigationLabel을 무엇이 읽는지(FE-REG-ROUTE, lab 측정)를 적었다. 버린 대안 - 칸을 바로 지우기: 객체 리터럴의 초과 속성 검사로 테스트 3파일과 다운스트림 정의가 컴파일 오류가 난다. 선택 칸으로 한 릴리스 두고 지운다. - 쿼리 operationId를 진단 이름표로 잇기: HTTP 실행 기록이 이미 descriptor의 operation ID를 싣는다. 같은 값을 두 번 싣는다. 위험·한계 - 라우트 계약의 title·navigationLabel(16-06 ③)은 그대로 둔다. 지우려면 FE-REG-ROUTE 기준선 행을 catalog에서 만들고, 플랫폼 라우트와 test-performance.ts를 함께 바꿔야 한다. 다른 작업(예제 화면 이동)과 같은 파일이라 이번에는 문서로만 적었다. 검증 - RED: application-query-scope-fence 새 테스트가 tsconfig.test에서 owner· operationId 누락으로 타입 오류. 선택 칸으로 바꾼 뒤 통과. - tests/features/reference-feature, tests/unit/create-feature.test.ts, scope-fence 129건 통과. check:types(app·node·test), lint 통과. Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-06
1467 lines
50 KiB
TypeScript
1467 lines
50 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 { createFileSystemDeclarationSource } from "./generate-product-feature-index.ts";
|
|
|
|
/**
|
|
* U7. `pnpm create:feature <id>` writes the smallest feature that passes every
|
|
* merge gate: 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 plus an input test. The templates live in this
|
|
* file 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;
|
|
}>;
|
|
|
|
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;
|
|
/** 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("");
|
|
}
|
|
|
|
function baseOf(id: string): string {
|
|
return id.endsWith("-feature") && id !== "feature"
|
|
? id.slice(0, -"-feature".length)
|
|
: id;
|
|
}
|
|
|
|
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`;
|
|
for (const route of installed.routes) {
|
|
if (route.routeId === routeId || route.path === routePath || route.chunkId === chunkId) {
|
|
fail(
|
|
`route ${routeId} (${routePath}, ${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`,
|
|
];
|
|
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: `/api/${names.base}-items`,
|
|
owner: `feature-frontend-${id}`,
|
|
contractPackage: request.contractPackage ?? null,
|
|
});
|
|
|
|
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)],
|
|
[`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)],
|
|
[`artifacts/tests/a11y-manual/${routeId}.md`, renderA11yRecord(routeId)],
|
|
]);
|
|
return Object.freeze({
|
|
id,
|
|
contextId,
|
|
newContext: existing === undefined,
|
|
routeId,
|
|
routePath,
|
|
topic,
|
|
placeholder: request.contractPackage === undefined,
|
|
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;
|
|
}>;
|
|
|
|
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, "Ownership declarations"): 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 }: 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";
|
|
|
|
/**
|
|
* 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],
|
|
}),
|
|
}),
|
|
),
|
|
);
|
|
`;
|
|
}
|
|
|
|
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},
|
|
}),
|
|
}),
|
|
routeRuntimeContracts: Object.freeze({
|
|
${routeId}: Object.freeze({
|
|
routeId: "${routeId}",
|
|
moduleId: "${base}-list-page",
|
|
paramsCodec: "none",
|
|
searchCodec: "none",
|
|
}),
|
|
}),
|
|
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({ names }: Shape): string {
|
|
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>;
|
|
|
|
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),
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderMapper({ names }: Shape): string {
|
|
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 }>;
|
|
|
|
/**
|
|
* 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[],
|
|
): BoundaryMappingResult<readonly ${pascal}ItemView[]> {
|
|
return mappingSuccess(
|
|
Object.freeze(
|
|
payload.map((dto) => Object.freeze({ itemId: dto.id, name: dto.name })),
|
|
),
|
|
);
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderSchemaMetadata({ names, owner }: Shape): string {
|
|
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.
|
|
*/
|
|
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",
|
|
}),
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderContractContribution({ names, operationId, apiPath }: Shape): string {
|
|
const { base, pascal, upper } = names;
|
|
return `import type {
|
|
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,
|
|
type ${pascal}Problem,
|
|
} from "./${base}-schemas.ts";
|
|
|
|
/**
|
|
* 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: "${apiPath}",
|
|
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). Drop
|
|
// this line 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
|
|
>;
|
|
|
|
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,
|
|
]) as readonly InstalledHttpContract<unknown, unknown, unknown>[],
|
|
events: Object.freeze([]),
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderMessageCatalog({ names, routeId }: Shape): string {
|
|
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} 목록",
|
|
}),
|
|
"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",
|
|
}),
|
|
} as const);
|
|
`;
|
|
}
|
|
|
|
function renderFeatureApi({ names }: Shape): string {
|
|
const { base, pascal, upper } = names;
|
|
return `import type {} from "../../../application/ports/in/application-api.ts";
|
|
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}ItemView } from "../contracts/${base}-mapper.ts";
|
|
|
|
export type ${pascal}CallContext = Readonly<{ signal?: AbortSignal }>;
|
|
|
|
/** What the feature's pages call. Name methods after what the user does. */
|
|
export type ${pascal}FeatureInput = Readonly<{
|
|
listItems(context?: ${pascal}CallContext): Promise<Result<readonly ${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<readonly ${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);
|
|
return Object.freeze({
|
|
async listItems(context) {
|
|
const result = await gateway.list(context);
|
|
if (!result.ok && result.error.kind !== "REQUEST_ABORTED") {
|
|
void events.emit({
|
|
kind: "${base}.list.failed",
|
|
severity: "warning",
|
|
featureId: ${upper}_FEATURE_ID,
|
|
payload: Object.freeze({ reason: result.error.kind }),
|
|
});
|
|
}
|
|
return result;
|
|
},
|
|
});
|
|
}
|
|
`;
|
|
}
|
|
|
|
function renderHttpGateway({ names, operationId, routeId }: Shape): string {
|
|
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 } from "../contracts/${base}-contract-contribution.ts";
|
|
import type { ${upper}_FEATURE_CONTRACT } from "../contracts/${base}-feature-contract.ts";
|
|
import { 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}",
|
|
mapSuccess: map${pascal}ItemList,
|
|
}),
|
|
} 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);
|
|
},
|
|
});
|
|
}
|
|
`;
|
|
}
|
|
|
|
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 }: Shape): string {
|
|
const { base, upper } = names;
|
|
return `import { lazy } from "react";
|
|
|
|
/** The lazy page of each route; \`moduleId\` equals the route runtime contract's. */
|
|
export const ${upper}_ROUTE_RUNTIME = {
|
|
${routeId}: Object.freeze({
|
|
moduleId: "${base}-list-page",
|
|
Component: lazy(() => import("./${base}-list-page.tsx")),
|
|
}),
|
|
} as const;
|
|
`;
|
|
}
|
|
|
|
function renderRoutes({ names }: Shape): string {
|
|
const { base, camel, upper } = names;
|
|
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);
|
|
}
|
|
`;
|
|
}
|
|
|
|
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}ItemView } 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(items: readonly ${pascal}ItemView[]): QueryResultMeasure {
|
|
let estimatedBytes = 16;
|
|
for (const item of items) {
|
|
estimatedBytes +=
|
|
UTF8.encode(item.itemId).byteLength + UTF8.encode(item.name).byteLength + 16;
|
|
}
|
|
return { itemCount: 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 }: Shape): string {
|
|
const { base, camel, pascal } = names;
|
|
return `import {
|
|
AsyncSurface,
|
|
CollectionPage,
|
|
} from "../../../presentation/design-system/index.ts";
|
|
import { useLocale } from "../../../presentation/i18n/index.ts";
|
|
import { use${pascal}Items } from "./use-${base}-items.ts";
|
|
|
|
/** An empty list renders the shared empty state under the page heading. */
|
|
export default function ${pascal}ListPage() {
|
|
const { message } = useLocale();
|
|
const query = use${pascal}Items();
|
|
return (
|
|
<CollectionPage
|
|
heading={{
|
|
title: message("${camel}.list.title"),
|
|
description: message("${camel}.list.description"),
|
|
}}
|
|
resultCount={
|
|
query.state.base === "success" || query.state.base === "empty"
|
|
? message("${camel}.list.resultCount", { count: query.data?.length ?? 0 })
|
|
: null
|
|
}
|
|
>
|
|
<AsyncSurface state={query.state} onRetry={query.retry}>
|
|
<ul aria-label={message("${camel}.list.items")}>
|
|
{(query.data ?? []).map((item) => (
|
|
<li key={item.itemId}>{item.name}</li>
|
|
))}
|
|
</ul>
|
|
</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([Object.freeze({ itemId: "item-1", name: "First item" })]);
|
|
|
|
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(
|
|
{ list: 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(
|
|
{ list: 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 input = create${pascal}FeatureInput({
|
|
list: async () => ({ ok: false, error: failure }),
|
|
});
|
|
|
|
await expect(input.listItems()).resolves.toEqual({ ok: false, error: failure });
|
|
});
|
|
});
|
|
`;
|
|
}
|
|
|
|
function renderPageTest({ names, operationId, routeId }: Shape): string {
|
|
const { base, camel, upper } = names;
|
|
return `// @vitest-environment jsdom
|
|
|
|
import { render, screen } from "@testing-library/react";
|
|
import userEvent from "@testing-library/user-event";
|
|
import { setupServer } from "msw/node";
|
|
import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
|
|
|
|
import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.ts";
|
|
import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.tsx";
|
|
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";
|
|
|
|
const MESSAGES = ${upper}_MESSAGE_CATALOGS["ko-KR"];
|
|
const RUNTIME_CONFIG = {
|
|
APP_ENV: "local",
|
|
API_BASE_URL: "https://api.test",
|
|
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" },
|
|
};
|
|
|
|
/** The boot documents come from here; every API call goes to MSW. */
|
|
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);
|
|
};
|
|
|
|
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 = userEvent.setup();
|
|
window.history.pushState({}, "", ${camel}RouteUrl("${routeId}"));
|
|
render(
|
|
<RuntimeApplication
|
|
composition={await createRuntimeComposition({ fetcher, host: {} })}
|
|
/>,
|
|
);
|
|
await user.click(await screen.findByRole("button", { name: KO_MESSAGES["action.signIn"] }));
|
|
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();
|
|
});
|
|
|
|
// 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 renderGatewayTest({ names, apiPath }: Shape): string {
|
|
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";
|
|
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 the contract stops
|
|
* reading that wire.
|
|
*/
|
|
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) {
|
|
return {
|
|
success: false,
|
|
error: {
|
|
code,
|
|
category: "VALIDATION",
|
|
message: "backend message",
|
|
retryable: false,
|
|
...(details === undefined ? {} : { details }),
|
|
},
|
|
meta: META,
|
|
};
|
|
}
|
|
|
|
function gateway() {
|
|
const executor = createContractHttpExecutor({
|
|
baseUrl: API,
|
|
maxRetryAttempts: 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,
|
|
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: [{ itemId: "item-1", name: "First item" }],
|
|
});
|
|
});
|
|
|
|
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: [] });
|
|
});
|
|
|
|
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" },
|
|
});
|
|
});
|
|
});
|
|
`;
|
|
}
|
|
|
|
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),
|
|
});
|
|
}
|
|
|
|
const USAGE =
|
|
"Usage: pnpm create:feature <id> [--context <context id>] " +
|
|
"[--package @scope/name@x.y.z --digest sha256:<64 hex> --revision <hex>]";
|
|
|
|
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" },
|
|
},
|
|
});
|
|
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 ?? "",
|
|
});
|
|
}
|
|
return Object.freeze({ id, context: values.context, contractPackage });
|
|
}
|
|
|
|
function report(plan: FeaturePlan): string {
|
|
const lines = [
|
|
`create:feature: ${plan.id} in ${plan.contextId}${plan.newContext ? " (new context)" : ""}, route ${plan.routeId} at ${plan.routePath}`,
|
|
...[...plan.files.keys()].map((file) => ` created ${file}`),
|
|
"",
|
|
"Next:",
|
|
` 1. Before a release, have a person review and sign artifacts/tests/a11y-manual/${plan.routeId}.md (FE-GATE-028). The merge gates check only its format.`,
|
|
" 2. Run the merge gates: corepack pnpm check:types, lint, check:architecture, check:registries, check:i18n, check:design-system, check:diagnostics, verify:documentation, test:unit, test:component, test:integration, test:coverage, check:ci, build.",
|
|
` The feature's own tests: node scripts/run-vitest.ts run tests/features/${plan.id} (test:coverage runs them in CI)`,
|
|
" 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}`);
|
|
}
|
|
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();
|
|
}
|