perf: 공개 첫 화면에서 MOCK·Studio 코드를 빼고 초기 JS 예산을 측정값으로 정한다 #9

Merged
donghyeon.kang merged 5 commits from perf/initial-js-budget into main 2026-11-12 21:51:04 +00:00
15 changed files with 662 additions and 46 deletions
+1 -1
View File
@@ -1,7 +1,7 @@
{
"schemaVersion": 1,
"bundle": {
"initialJsGzipBytes": 204800,
"initialJsGzipBytes": 230400,
"lazyChunkGzipBytes": 122880
},
"lab": {
+1 -1
View File
@@ -23,7 +23,7 @@
"axis": "Initial JavaScript",
"verified": "Grows by about 2.9 KB gzip and one file per feature: every installed feature's contracts and module load at boot",
"condition": "Same",
"notVerified": "The initial budget (204,800 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
"notVerified": "The initial budget (230,400 B, config/performance/budgets.json) is exceeded after a few more reference-shaped features, far below the context ceiling"
},
{
"axis": "Lazy JavaScript",
+55 -1
View File
@@ -3,7 +3,7 @@
Performance evidence is deliberately split by measurement context:
- `bundle.json` records production build output and enforces initial JavaScript
at 200 KiB gzip and every lazy chunk at 120 KiB gzip.
at 225 KiB gzip and every lazy chunk at 120 KiB gzip.
- `lab.json` records Chromium/runner/viewport/network/CPU/cache/build context and
enforces LCP 2.5 s, CLS 0.10, and the named route interaction at 200 ms.
- `field-web-vitals.json` records consent-filtered, route-ID aggregated,
@@ -40,6 +40,60 @@ Performance evidence is deliberately split by measurement context:
예산을 올릴 때는 이 표의 기준선과 새 측정값, 이유를 같은 변경에 적는다.
### TechLog 예산 (2026-11-12, FE-GATE-012)
위 표는 템플릿을 받을 때의 기록이다. TechLog는 기능을 붙인 뒤 예산을 다시 정하지
않았고, 초기 JS가 main(`e5fe335e`)에서 300,869 B로 예산을 96,069 B 넘었다.
| 항목 | 값 |
|---|---|
| 초기 JS 예산 | 230,400 gzip bytes(225 KiB) |
| 바꾸기 전(main `e5fe335e`, CI env) | 300,869 B, 초기 파일 26개 |
| 바꾼 뒤(CI env) | 229,224 B, 초기 파일 28개 |
| 그중 템플릿 공통 부분 | 약 205 KB. react-dom·scheduler 56.5 KB 청크, react-router, zod, tanstack, 플랫폼 `src` |
| 그중 TechLog 코드 | 약 24 KB. 문구 카탈로그, 공개 HTTP gateway와 mapping, Studio·관리·공개 계약, 라우트 표, 공개 셸 |
| 가장 큰 lazy chunk | 40,038 B(마크다운 파서와 content-format). 예산 122,880 B |
두 몫은 분석 빌드의 모듈별 minify 바이트 비율(TechLog 10.5%)로 나눈 추정이다.
이번에 초기 JS에서 뺀 것(바꾸기 전 대비 -71,645 B):
- **MOCK 소스.** 런타임 문서가 MOCK·HTTP를 고르므로 두 소스가 모든 빌드에 들어
있다. MOCK 공개 콘텐츠와 MOCK Studio gateway가 운영(HTTP) 공개 화면의 초기 JS에
있었고, MOCK이 쓰는 content-format이 마크다운 파서(micromark·mdast·unified)를
끌고 왔다. 지금은 첫 조회 때 받는다(`adapters/deferred-async-port.ts`).
- **Studio.** Studio 셸(StudioProvider, Studio 머리말, 문서 server state)과
MOCK·HTTP Studio gateway를 `/studio`에 들어갈 때 받는다. gateway는 Studio가
마운트될 때 바로 받기 시작한다.
- **쓰이지 않는 design-system·폼 모듈.** 템플릿 1101/08-08(`51941a54`)처럼
design-system 모듈을 side effect 없음으로 선언했다.
`tests/features/tech-log/boot-graph.test.ts`가 MOCK 소스와 Studio 코드가 부팅
그래프에 다시 들어오지 않는지 빌드 없이 본다.
예산 값을 정한 규칙은 템플릿과 같다(템플릿
`docs/operations/performance-evidence.md` 1106/15-01, 결정 D9). 측정값에 기능
하나의 상한 1 KiB를 더해 KiB 단위로 올린다. 229,224 + 1,024 = 230,248 B를
올리면 225 KiB = 230,400 B다. 여유 1,176 B는 기능 하나(1,024 B)와 올림(152 B)
몫이다. 빌드 id에 따라 합계가 수백 B 움직인다.
204,800 B로 되돌리지 못한 이유:
- 템플릿 공통 부분만 약 205 KB다. TechLog 코드를 초기 JS에서 모두 빼도 예산
안에 남는 여유가 없다.
- 남은 TechLog 몫(문구, 공개 gateway, 계약)은 공개 첫 화면이 실제로 쓴다. 공개
gateway를 지연 로드하면 첫 화면 데이터 요청 앞에 청크 왕복이 하나 더 생긴다.
- 템플릿은 1101/15-01(`298201f3`)에서 기능 실행부(계약 contribution, adapter)를
라우트 진입 때 받게 바꿨다. TechLog는 템플릿 `af3d8e6`(2026-09-28)에 머물러 있고,
계약·문구 catalog를 부팅 때 합친다. 그 구조를 옮기는 것은 템플릿 동기화 일이다.
다시 볼 때:
- 예산을 다시 넘을 때. 늘린 변경이 무엇을 초기 그래프에 넣었는지 먼저 본다.
- 템플릿 동기화로 15-01(기능 실행부 지연 적재)을 받을 때. 그때 다시 재고 같은
규칙으로 예산을 내린다. 측정값이 203,776 B 이하이면 규칙의 값이 200 KiB 이하가
되어 원래 예산으로 돌아간다.
lab 측정(`scripts/test-performance.ts`, FE-GATE-026)은 local 프로필 build를
`vite preview --strictPort`로 띄워 잰다(리뷰 11-07).
+17 -1
View File
@@ -27,6 +27,21 @@ export type AppBuildInputReport = Readonly<{
violations: readonly string[];
}>;
/**
* Template sync (af3d8e6). TechLog is this product's own domain, composed
* directly by the composition root rather than by the index generator
* (`src/features/tech-log/NOT_INSTALLED`). No context owns it, so the
* template's ownership rule refused every production bundle of this product;
* FE-GATE-012 stopped at the bundle budget before reaching it, which hid that.
*
* It is allowed in the bundle by name only. The generated indexes still may not
* import it, and every other directory marked NOT_INSTALLED (the reference and
* local-draft samples) is still refused if it reaches the bundle.
*/
export const DIRECTLY_COMPOSED_FEATURE_DIRECTORIES: readonly string[] = Object.freeze([
"tech-log",
]);
const GENERATED = [
"src/.generated/product-feature-index.ts",
"src/.generated/product-context-index.ts",
@@ -99,8 +114,9 @@ export async function inspectAppBuildInput(
}),
);
bundle = { checked: true, featureDirectories };
const composedDirectly = new Set(DIRECTLY_COMPOSED_FEATURE_DIRECTORIES);
for (const directory of featureDirectories) {
if (!owned.has(directory)) {
if (!owned.has(directory) && !composedDirectly.has(directory)) {
violations.push(`production bundle contains feature "${directory}" not owned by app ${appId}`);
}
}
@@ -6,17 +6,12 @@ import type { Asset } from "../contracts/studio/contract.ts";
import { createTechLogStudioApplication } from "../application/studio-application.ts";
import type { InstalledHttpOperationExecutor } from "../../../adapters/http/index.ts";
import { createTechLogHttpBinding } from "./http/tech-log-http-binding.ts";
import { createAssetUploadTransport } from "./http/asset-upload-transport.ts";
import { createHttpStudioAssetGateway } from "./http/http-studio-asset-gateway.ts";
import { createHttpStudioGateway } from "./http/http-studio-gateway.ts";
import type { CsrfTokenProvider } from "./http/studio-session-csrf.ts";
import { createMockStudioAssetGateway } from "./mock/mock-studio-asset-gateway.ts";
import { createMockManagementGateway } from "./mock/mock-management-gateway.ts";
import { createMockStudioState } from "./mock/mock-state.ts";
import { createMockStudioGateway } from "./mock/mock-studio-gateway.ts";
import { createHttpManagementGateway } from "./http/http-management-gateway.ts";
import { createHttpPublicContentGateway } from "./http/http-public-content-gateway.ts";
import { publicContentQueries } from "./static/public-query.ts";
import {
deferPublicContentQueries,
deferStudioGateways,
} from "./deferred-tech-log-ports.ts";
/**
* The HTTP gateway builds no headers of its own — `Idempotency-Key` comes
@@ -55,26 +50,18 @@ export function createTechLogFeatureInstalledInput(
const mockAssets = new Map<string, Asset>();
const http = createTechLogHttpBinding(context.http);
const createStudioAssetGateway = () =>
context.studioSource === "MOCK"
? createMockStudioAssetGateway(mockAssets)
: createHttpStudioAssetGateway({
http,
csrf: context.csrf,
upload: createAssetUploadTransport({
baseUrl: context.apiBaseUrl,
timeoutMs: context.requestTimeoutMs,
}),
});
// The public read source switches independently of Studio: the two are
// different services, and the combination that matters today is an authoring
// backend that is live while the public read API is not.
//
// FE-GATE-012. Both sources ship in every build (the runtime document picks
// one), so the MOCK content is loaded on its first query instead of riding
// the initial JavaScript of a production page that reads HTTP.
const publicContent =
context.publicSource === "MOCK"
? publicContentQueries
? deferPublicContentQueries(
async () => (await import("./static/public-query.ts")).publicContentQueries,
)
: createHttpPublicContentGateway({ http });
// MOCK: one in-memory Studio state per application, shared by the document
@@ -82,21 +69,28 @@ export function createTechLogFeatureInstalledInput(
// also takes it out of the document list. Management used to be HTTP even
// here, and a MOCK build (local development, the e2e and visual builds)
// asked an API that is not there for its topics and projects.
const createStudioApplication = () => {
if (context.studioSource === "MOCK") {
const state = createMockStudioState();
return createTechLogStudioApplication({
studio: createMockStudioGateway({ assets: mockAssets, state }),
assets: createStudioAssetGateway(),
management: createMockManagementGateway({ studioState: state }),
});
}
return createTechLogStudioApplication({
studio: createHttpStudioGateway({ http }),
assets: createStudioAssetGateway(),
management: createHttpManagementGateway({ http }),
});
};
//
// FE-GATE-012. Studio's gateways, MOCK or HTTP, are a chunk of their own.
// StudioProvider calls this when Studio mounts, so the chunk starts loading
// then, next to the page chunk, rather than on the first query. Each call
// still gets its own set (and, for MOCK, its own state).
const createStudioApplication = () =>
createTechLogStudioApplication(
deferStudioGateways(
async () =>
context.studioSource === "MOCK"
? (await import("./mock/mock-studio-gateways.ts")).createMockStudioGateways(
mockAssets,
)
: (await import("./http/http-studio-gateways.ts")).createHttpStudioGateways({
http,
csrf: context.csrf,
apiBaseUrl: context.apiBaseUrl,
requestTimeoutMs: context.requestTimeoutMs,
}),
{ startNow: true },
),
);
const input: TechLogFeatureInput = Object.freeze({
publicContent,
@@ -0,0 +1,39 @@
type AsyncMethods<Port> = {
readonly [Key in keyof Port]: (...args: never[]) => Promise<unknown>;
};
/**
* 모든 멤버가 Promise 를 돌려주는 포트를, 구현 모듈을 받기 전에 만든다.
*
* 부팅 그래프가 MOCK gateway·정적 공개 콘텐츠·Studio gateway 를 정적으로 가져와, 운영
* 공개 화면을 여는 사람도 그 코드를 전부 초기 JS 로 받았다(FE-GATE-012). 포트는 이미
* 비동기라, 첫 호출에서 구현을 받고 넘겨 주면 호출하는 쪽은 바뀌지 않는다.
*
* - `methods` 는 포트의 키 전부다. 타입이 빠진 키와 남는 키를 막는다.
* - 구현은 한 번만 받는다. 받기에 실패하면 잊고 다음 호출에서 다시 받는다 — 청크를 한 번
* 못 받았다고 그 세션 내내 실패하지 않는다.
*/
export function deferAsyncPort<Port extends AsyncMethods<Port>>(
load: () => Promise<Port>,
methods: Readonly<Record<keyof Port, true>>,
): Port {
let loaded: Promise<Port> | undefined;
const target = (): Promise<Port> => {
loaded ??= load().catch((error: unknown) => {
loaded = undefined;
throw error;
});
return loaded;
};
const port: Record<string, (...args: unknown[]) => Promise<unknown>> = {};
for (const name of Object.keys(methods)) {
port[name] = async (...args: unknown[]) => {
const implementation = await target();
const method = implementation[name as keyof Port] as unknown as (
...methodArgs: unknown[]
) => Promise<unknown>;
return method.apply(implementation, args);
};
}
return Object.freeze(port) as unknown as Port;
}
@@ -0,0 +1,137 @@
import type { PublicContentQueries } from "../application/ports/public-content-queries.ts";
import type { ManagementGateway } from "../application/ports/management-gateway.ts";
import type { StudioAssetGateway } from "../application/ports/studio-asset-gateway.ts";
import type { StudioGateway } from "../application/ports/studio-gateway.ts";
import { deferAsyncPort } from "./deferred-async-port.ts";
/*
포트마다 키 전부다. `Record<keyof Port, true>` 라 포트에 메서드가 늘거나 줄면 타입 검사가
여기서 실패한다.
*/
const PUBLIC_CONTENT_QUERY_METHODS = Object.freeze({
listRecords: true,
getRecord: true,
getProject: true,
getRelease: true,
getProjectRecords: true,
getProjectDecisions: true,
getProjectActivity: true,
listTopics: true,
listContacts: true,
getTopicDetail: true,
getHome: true,
listProjects: true,
listReleases: true,
listCatalog: true,
getLatestEntries: true,
getHomeFocusItems: true,
searchPublicContent: true,
} as const satisfies Record<keyof PublicContentQueries, true>);
const STUDIO_GATEWAY_METHODS = Object.freeze({
getDashboard: true,
listDocuments: true,
createDocument: true,
getDocument: true,
saveDocument: true,
validateDocument: true,
createPreview: true,
getCurrentPreview: true,
publishDocument: true,
unpublishPublication: true,
listPublications: true,
getPublicationSnapshot: true,
getCatalog: true,
} as const satisfies Record<keyof StudioGateway, true>);
const STUDIO_ASSET_GATEWAY_METHODS = Object.freeze({
listAssets: true,
uploadAsset: true,
getAsset: true,
updateAssetMetadata: true,
deleteAsset: true,
} as const satisfies Record<keyof StudioAssetGateway, true>);
const MANAGEMENT_GATEWAY_METHODS = Object.freeze({
listTopics: true,
createTopic: true,
updateTopic: true,
deleteTopic: true,
listTopicVariants: true,
createTopicVariant: true,
updateTopicVariant: true,
deleteTopicVariant: true,
listProjects: true,
listQuestions: true,
listProjectDecisions: true,
getProject: true,
createProject: true,
updateProject: true,
deleteProject: true,
publishProject: true,
unpublishProject: true,
listProjectActivities: true,
createProjectActivity: true,
updateProjectActivity: true,
deleteProjectActivity: true,
getHomeFocus: true,
updateHomeFocus: true,
listReleases: true,
getRelease: true,
createRelease: true,
updateRelease: true,
deleteRelease: true,
publishRelease: true,
archiveRelease: true,
deleteDocument: true,
deleteDecision: true,
} as const satisfies Record<keyof ManagementGateway, true>);
export function deferPublicContentQueries(
load: () => Promise<PublicContentQueries>,
): PublicContentQueries {
return deferAsyncPort(load, PUBLIC_CONTENT_QUERY_METHODS);
}
export type StudioGateways = Readonly<{
studio: StudioGateway;
assets: StudioAssetGateway;
management: ManagementGateway;
}>;
/**
* Studio gateway 셋을 한 번에 받는다. 셋이 같은 구현 묶음(MOCK 이면 같은 Studio state)을
* 써야 해서, 묶음 하나를 받고 각 포트가 그 안의 자기 gateway 로 넘긴다.
*
* `startNow` 면 첫 호출을 기다리지 않고 바로 받기 시작한다. Studio 가 마운트될 때 만들어지므로,
* 첫 조회 때 받으면 화면 청크 → 조회 → gateway 청크 → 요청으로 한 번 더 기다린다. 미리 받다
* 실패해도 여기서 삼키고, 첫 호출이 다시 받는다.
*/
export function deferStudioGateways(
load: () => Promise<StudioGateways>,
{ startNow = false }: Readonly<{ startNow?: boolean }> = {},
): StudioGateways {
let loaded: Promise<StudioGateways> | undefined;
const gateways = (): Promise<StudioGateways> => {
loaded ??= load().catch((error: unknown) => {
loaded = undefined;
throw error;
});
return loaded;
};
if (startNow) void gateways().catch(() => undefined);
return Object.freeze({
studio: deferAsyncPort(
async () => (await gateways()).studio,
STUDIO_GATEWAY_METHODS,
),
assets: deferAsyncPort(
async () => (await gateways()).assets,
STUDIO_ASSET_GATEWAY_METHODS,
),
management: deferAsyncPort(
async () => (await gateways()).management,
MANAGEMENT_GATEWAY_METHODS,
),
});
}
@@ -0,0 +1,33 @@
import { createAssetUploadTransport } from "./asset-upload-transport.ts";
import { createHttpManagementGateway } from "./http-management-gateway.ts";
import { createHttpStudioAssetGateway } from "./http-studio-asset-gateway.ts";
import { createHttpStudioGateway } from "./http-studio-gateway.ts";
import type { CsrfTokenProvider } from "./studio-session-csrf.ts";
import type { TechLogHttpBinding } from "./tech-log-http-binding.ts";
export type HttpStudioGatewaysContext = Readonly<{
http: TechLogHttpBinding;
csrf: CsrfTokenProvider;
apiBaseUrl: string;
requestTimeoutMs: number;
}>;
/**
* HTTP Studio 의 gateway 셋. Studio 에 들어갈 때 받는 청크다
* (`create-tech-log-feature-input.ts`). 공개 화면은 이 코드를 쓰지 않는다.
*/
export function createHttpStudioGateways(context: HttpStudioGatewaysContext) {
const { http } = context;
return Object.freeze({
studio: createHttpStudioGateway({ http }),
assets: createHttpStudioAssetGateway({
http,
csrf: context.csrf,
upload: createAssetUploadTransport({
baseUrl: context.apiBaseUrl,
timeoutMs: context.requestTimeoutMs,
}),
}),
management: createHttpManagementGateway({ http }),
});
}
@@ -0,0 +1,21 @@
import type { Asset } from "../../contracts/studio/contract.ts";
import { createMockManagementGateway } from "./mock-management-gateway.ts";
import { createMockStudioAssetGateway } from "./mock-studio-asset-gateway.ts";
import { createMockStudioState } from "./mock-state.ts";
import { createMockStudioGateway } from "./mock-studio-gateway.ts";
/**
* MOCK Studio 의 gateway 셋. Studio 에 들어갈 때 받는 청크다
* (`create-tech-log-feature-input.ts`).
*
* 문서 gateway 와 관리 gateway 는 Studio state 하나를 나눠 쓴다 — 관리 화면에서 작업본을
* 지우면 문서 목록에서도 빠진다. Asset 저장소는 앱 하나에 하나라 호출하는 쪽이 넘긴다.
*/
export function createMockStudioGateways(assets: Map<string, Asset>) {
const state = createMockStudioState();
return Object.freeze({
studio: createMockStudioGateway({ assets, state }),
assets: createMockStudioAssetGateway(assets),
management: createMockManagementGateway({ studioState: state }),
});
}
@@ -1,17 +1,45 @@
import {
lazy,
Suspense,
type ComponentType,
type LazyExoticComponent,
type ReactNode,
} from "react";
import { Outlet } from "react-router-dom";
import { ChunkRecoveryBoundary } from "../../../presentation/boundaries/chunk-recovery-boundary.tsx";
import { LoadingSurface } from "../../../presentation/design-system/index.ts";
import { useApplicationRecovery } from "../../../presentation/providers/application-provider.tsx";
import {
TECH_LOG_ROUTE_RUNTIME_CONTRACT,
type TechLogRouteId,
} from "../contracts/tech-log-route-contract.ts";
import { PublicShell } from "./public/public-shell.tsx";
import { StudioShell } from "./studio/studio-shell.tsx";
/*
Studio 셸은 공개 화면을 읽는 사람에게 필요 없다. 정적으로 가져오면 셸이 끌고 오는
StudioProvider·Studio 머리말·문서 server state 가 모든 첫 화면의 초기 JS 에 들어갔다
(FE-GATE-012). /studio 에 들어갈 때 받는다. 라우트 청크와 같이 청크를 못 받으면
ChunkRecoveryBoundary 가 한 번 새로 읽기를 정한다.
*/
const StudioShell = lazy(async () => {
const module = await import("./studio/studio-shell.tsx");
return { default: module.StudioShell };
});
function DeferredStudioShell({ children }: Readonly<{ children: ReactNode }>) {
const recovery = useApplicationRecovery();
return (
<ChunkRecoveryBoundary
chunkId="tech-log-studio-shell"
recover={recovery.recoverChunk}
>
<Suspense fallback={<LoadingSurface />}>
<StudioShell>{children}</StudioShell>
</Suspense>
</ChunkRecoveryBoundary>
);
}
type RouteRuntime = Readonly<{
moduleId: string;
@@ -297,8 +325,8 @@ export const TECH_LOG_ROUTE_LAYOUTS: Readonly<
</PublicShell>
),
STUDIO: (
<StudioShell>
<DeferredStudioShell>
<Outlet />
</StudioShell>
</DeferredStudioShell>
),
});
@@ -84,6 +84,24 @@ describe("app build input isolation gate", () => {
]);
});
it("accepts this product's directly composed TechLog and still refuses an uninstalled sample", async () => {
// TechLog is composed by the composition root (src/features/tech-log/NOT_INSTALLED),
// so it is in every production bundle while no context owns it. The
// reference sample is NOT_INSTALLED too, and must not ride along.
const root = path.resolve(".");
const scratch = await mkdtemp(path.join(tmpdir(), "app-build-input-product-"));
roots.push(scratch);
const bundle = await inventory(scratch, [
"src/features/tech-log/presentation/public/public-shell.tsx",
"src/features/reference-feature/feature-module.ts",
]);
const report = await inspectAppBuildInput(root, { bundleInventory: bundle });
expect(report.bundle.featureDirectories).toEqual(["reference-feature", "tech-log"]);
expect(report.violations).toEqual([
`production bundle contains feature "reference-feature" not owned by app ${report.appId}`,
]);
});
it("holds for this repository's generated indexes", async () => {
// The bundle side is gated after a fresh build (check:app-build-input:bundle).
const report = await inspectAppBuildInput(path.resolve("."), { bundleInventory: null });
+117
View File
@@ -0,0 +1,117 @@
import assert from "node:assert/strict";
import { existsSync, readFileSync } from "node:fs";
import path from "node:path";
import { parseAsync } from "@babel/core";
import { test } from "vitest";
/**
* FE-GATE-012. 첫 화면의 초기 JS 는 진입점(main.tsx), 그 정적 import, 진입점이 바로
* 동적으로 읽는 boot·render-boot-failure 와 그 정적 import 다
* (`scripts/lib/classify-vite-bundle.ts`). 공개 화면을 읽는 사람에게 필요 없는 아래 코드가
* 정적 import 하나로 이 그래프에 다시 들어오면 번들 예산을 넘는다. 빌드 없이 여기서 먼저 잡는다.
*/
const BOOT_SEEDS = [
"src/bootstrap/main.tsx",
"src/bootstrap/boot.tsx",
"src/bootstrap/render-boot-failure.tsx",
];
const DEFERRED = [
// MOCK 소스: 런타임 문서가 MOCK 을 고른 빌드(로컬·시험)에서만 쓰인다.
"src/features/tech-log/adapters/mock/",
"src/features/tech-log/adapters/static/",
// Studio: /studio 에 들어갈 때 받는다.
"src/features/tech-log/presentation/studio/",
"src/features/tech-log/adapters/http/http-studio-gateways.ts",
"src/features/tech-log/adapters/http/http-studio-gateway.ts",
"src/features/tech-log/adapters/http/http-management-gateway.ts",
"src/features/tech-log/adapters/http/http-studio-asset-gateway.ts",
"src/features/tech-log/adapters/http/asset-upload-transport.ts",
];
type Node = Readonly<Record<string, unknown> & { type: string }>;
function isTypeOnly(statement: Node): boolean {
if (statement["importKind"] === "type" || statement["exportKind"] === "type") return true;
const specifiers = statement["specifiers"] as readonly Node[] | undefined;
if (statement.type !== "ImportDeclaration" || !specifiers || specifiers.length === 0) {
return false;
}
// `import { type A, type B } from "x"` 는 컴파일 뒤 남지 않는다(verbatimModuleSyntax 없음).
return specifiers.every((specifier) => specifier["importKind"] === "type");
}
function resolveRelative(from: string, specifier: string): string | undefined {
if (!specifier.startsWith(".")) return undefined;
const target = path.posix.normalize(path.posix.join(path.posix.dirname(from), specifier));
if (!/\.tsx?$/u.test(target)) return undefined;
assert.ok(existsSync(target), `${from} 가 없는 파일을 가져온다: ${specifier}`);
return target;
}
async function staticImports(file: string): Promise<string[]> {
const plugins: ("jsx" | ["typescript", { dts: boolean }])[] = [["typescript", { dts: false }]];
if (file.endsWith(".tsx")) plugins.push("jsx");
const tree = (await parseAsync(readFileSync(file, "utf8"), {
filename: file,
babelrc: false,
configFile: false,
sourceType: "module",
parserOpts: { plugins },
})) as unknown as { program: { body: readonly Node[] } } | null;
assert.ok(tree, `cannot parse ${file}`);
const imports: string[] = [];
for (const statement of tree.program.body) {
if (
statement.type !== "ImportDeclaration" &&
statement.type !== "ExportNamedDeclaration" &&
statement.type !== "ExportAllDeclaration"
) {
continue;
}
const source = statement["source"] as Node | null | undefined;
if (!source || isTypeOnly(statement)) continue;
const resolved = resolveRelative(file, String(source["value"]));
if (resolved) imports.push(resolved);
}
return imports;
}
async function bootGraph(): Promise<Map<string, string>> {
const importedBy = new Map<string, string>(BOOT_SEEDS.map((seed) => [seed, "(seed)"]));
const pending = [...BOOT_SEEDS];
while (pending.length > 0) {
const file = pending.pop()!;
for (const imported of await staticImports(file)) {
if (importedBy.has(imported)) continue;
importedBy.set(imported, file);
pending.push(imported);
}
}
return importedBy;
}
function chain(importedBy: ReadonlyMap<string, string>, file: string): string {
const links = [file];
let current = importedBy.get(file);
while (current && current !== "(seed)") {
links.push(current);
current = importedBy.get(current);
}
return links.join(" <- ");
}
test("공개 첫 화면의 부팅 그래프에 MOCK 소스와 Studio 코드가 없다", async () => {
const graph = await bootGraph();
// 그래프를 제대로 따라갔는지: 공개 셸과 기능 입력 조립은 부팅 때 필요하다.
assert.ok(graph.has("src/features/tech-log/presentation/public/public-shell.tsx"));
assert.ok(graph.has("src/features/tech-log/adapters/create-tech-log-feature-input.ts"));
const leaked = [...graph.keys()]
.filter((file) => DEFERRED.some((prefix) => file.startsWith(prefix)))
.sort()
.map((file) => chain(graph, file));
assert.deepEqual(leaked, [], `부팅 그래프로 들어온 지연 코드:\n${leaked.join("\n")}`);
});
@@ -0,0 +1,112 @@
import assert from "node:assert/strict";
import { test } from "vitest";
import { deferAsyncPort } from "../../../src/features/tech-log/adapters/deferred-async-port.ts";
import { deferStudioGateways } from "../../../src/features/tech-log/adapters/deferred-tech-log-ports.ts";
import { createMockStudioGateways } from "../../../src/features/tech-log/adapters/mock/mock-studio-gateways.ts";
import { FIXTURE_IDS } from "../../../src/features/tech-log/adapters/mock/fixtures.ts";
import type { Asset } from "../../../src/features/tech-log/contracts/studio/contract.ts";
type Greeter = Readonly<{
greet(name: string): Promise<string>;
count(): Promise<number>;
}>;
function greeterImplementation(): Greeter {
let calls = 0;
return {
async greet(name) {
calls += 1;
return `hello ${name}`;
},
async count() {
return calls;
},
};
}
const GREETER_METHODS = { greet: true, count: true } as const;
test("구현을 첫 호출에서 한 번만 받고 모든 메서드가 같은 구현을 쓴다", async () => {
let loads = 0;
const port = deferAsyncPort(async () => {
loads += 1;
return greeterImplementation();
}, GREETER_METHODS);
assert.equal(loads, 0, "만들기만 해서는 구현을 받지 않는다");
assert.equal(await port.greet("a"), "hello a");
assert.equal(await port.greet("b"), "hello b");
assert.equal(await port.count(), 2);
assert.equal(loads, 1);
});
test("동시에 들어온 첫 호출들도 구현을 한 번만 받는다", async () => {
let loads = 0;
const port = deferAsyncPort(async () => {
loads += 1;
await Promise.resolve();
return greeterImplementation();
}, GREETER_METHODS);
await Promise.all([port.greet("a"), port.greet("b"), port.count()]);
assert.equal(loads, 1);
});
test("구현을 받지 못하면 그 호출은 실패하고 다음 호출에서 다시 받는다", async () => {
let loads = 0;
const port = deferAsyncPort(async () => {
loads += 1;
if (loads === 1) throw new TypeError("Failed to fetch dynamically imported module");
return greeterImplementation();
}, GREETER_METHODS);
await assert.rejects(port.greet("a"), /dynamically imported module/u);
assert.equal(await port.greet("b"), "hello b");
assert.equal(loads, 2);
});
test("포트는 선언한 메서드만 가진 얼린 객체다", () => {
const port = deferAsyncPort(async () => greeterImplementation(), GREETER_METHODS);
assert.deepEqual(Object.keys(port).sort(), ["count", "greet"]);
assert.equal(Object.isFrozen(port), true);
});
test("Studio gateway 셋은 구현 묶음 하나를 같이 쓴다", async () => {
let loads = 0;
const assets = new Map<string, Asset>();
const gateways = deferStudioGateways(async () => {
loads += 1;
return createMockStudioGateways(assets);
});
assert.equal(loads, 0);
const draft = (await gateways.studio.getDocument(FIXTURE_IDS.conflictCase)).document;
await gateways.management.deleteDocument("CASE", draft.id, draft.version, {
idempotencyKey: "deferred-shared-state",
});
// 관리 gateway 로 지운 작업본이 같은 묶음의 문서 gateway 에서도 사라진다.
await assert.rejects(gateways.studio.getDocument(FIXTURE_IDS.conflictCase));
await gateways.assets.listAssets({});
assert.equal(loads, 1);
});
test("startNow 면 만들 때 받기 시작하고, 그때의 실패는 첫 호출이 다시 받는다", async () => {
let loads = 0;
const assets = new Map<string, Asset>();
const gateways = deferStudioGateways(
async () => {
loads += 1;
if (loads === 1) throw new TypeError("Failed to fetch dynamically imported module");
return createMockStudioGateways(assets);
},
{ startNow: true },
);
assert.equal(loads, 1, "만들자마자 받기 시작한다");
// 미리 받기의 실패가 처리된 뒤 첫 호출이 들어온다.
await new Promise((resolve) => setTimeout(resolve, 0));
await gateways.studio.getDashboard();
assert.equal(loads, 2);
});
@@ -0,0 +1,32 @@
import { readdirSync, readFileSync } from "node:fs";
import path from "node:path";
import { describe, expect, it } from "vitest";
const DESIGN_SYSTEM = "src/presentation/design-system";
function sourceFiles(directory: string): string[] {
return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
const file = path.posix.join(directory, entry.name);
if (entry.isDirectory()) return sourceFiles(file);
return /\.tsx?$/u.test(entry.name) && !/\.stories\.tsx?$/u.test(entry.name)
? [file]
: [];
});
}
/**
* vite.config.ts 가 design-system 모듈을 side effect 없음으로 선언한다(템플릿 1101/08-08).
* 그 아래에서는 `import "x"` 처럼 효과만을 위한 import 가 모듈과 같이 빌드에서 사라진다.
* 그런 import 가 생기면 선언이 틀린 것이다.
*/
describe("design-system modules declared free of side effects", () => {
it("hold no import kept only for its effect", () => {
const files = sourceFiles(DESIGN_SYSTEM);
expect(files.length).toBeGreaterThan(0);
const effectOnly = files.filter((file) =>
/^\s*import\s+["'][^"']+["']/mu.test(readFileSync(file, "utf8")),
);
expect(effectOnly).toEqual([]);
});
});
+15
View File
@@ -138,6 +138,21 @@ export default defineConfig(({ mode }) => {
// Template sync (af3d8e6): the template's chunk groups, then TechLog's
// named route chunks, in the template's `codeSplitting` form.
rolldownOptions: {
/*
템플릿 1101/08-08(51941a54)과 같다. design-system 모듈은 컴포넌트·아이콘·토큰 목록을
선언만 하고 top-level 효과가 없다. 그렇게 선언해 두면 공개 셸이 배럴(index.ts)에서
Button 하나를 가져와도, 아무 export 도 안 쓰인 primitive 파일은 초기 청크에서
빠진다. 효과만을 위한 import 를 두면 선언 아래에서 모듈과 같이 사라지므로 이 범위에는
그런 import 가 없다. CSS 는 bootstrap/main.tsx 에서 읽는다.
*/
treeshake: {
moduleSideEffects: [
{
test: /[\\/]src[\\/]presentation[\\/]design-system[\\/].+\.tsx?$/,
sideEffects: false,
},
],
},
output: {
codeSplitting: {
groups: [