runtypex 0.2.2 → 0.2.4

package/README.md

@@ -37,6 +37,20 @@ isUser({ id: 1, name: "Lux", active: true }); // true
 assertUser({ id: "bad" }); // throws
 ```
 
+## Runtime vs Build-Time Behavior
+
+`makeValidate<T>()` and `makeAssert<T>()` need the Vite plugin or TypeScript
+transformer to become real validation functions. `makeMapper<TDto, TDomain>()`
+also benefits from the transformer, but it still has a runtime fallback that can
+interpret the mapper spec directly.
+
+| Execution path | `makeValidate<T>()` / `makeAssert<T>()` | `makeMapper<TDto, TDomain>()` | Docs generation |
+| --- | --- | --- | --- |
+| `npm run dev` with the Vite plugin | Works. Validation usually runs. | Works with validation. | Can generate when the dev server starts. |
+| `npm run build` with the Vite plugin | Works. | Works. | Generates docs. |
+| `npm run build` + `NODE_ENV=production` + `removeInProd: true` | Replaced with no-op validation. | Mapping still works; validation is removed. | Unaffected. |
+| No Vite plugin or transformer | Placeholder runtime fallback; does not inspect `T`. | Runtime fallback mapping still works. | Not generated. |
+
 ## Vite Setup
 
 ```ts

package/dist/cjs/generator/generate-jsdoc.js

@@ -30,14 +30,14 @@ function generateJSDocFromSpec(params) {
             _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        _pushJSDocBulletField(lines, "DTO", _formatCodeSpan(`${dtoName}.${rule.from}`));
         if (rule.dtoDescription) {
-            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+            _pushJSDocBulletField(lines, "DTO description", _escapeComment(rule.dtoDescription));
         }
-        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
+        _pushJSDocBulletField(lines, "DTO type", _formatCodeSpan(dtoPathType ? checker.typeToString(dtoPathType) : "unknown"));
         if (rule.db)
-            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
-        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
+            _pushJSDocBulletField(lines, "Origin", _formatCodeSpan(rule.db));
+        _pushJSDocBulletField(lines, "Domain type", _formatCodeSpan(checker.typeToString(domainType)));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -75,8 +75,8 @@ function _getDomainDescription(checker, prop) {
     const description = typescript_1.default.displayPartsToString(prop.getDocumentationComment(checker)).trim();
     return description || null;
 }
-function _pushJSDocField(lines, label, value) {
-    _pushJSDocText(lines, `${label}: ${value}`, "", " ".repeat(label.length + 2));
+function _pushJSDocBulletField(lines, label, value) {
+    _pushJSDocText(lines, `- ${label}: ${value}`, "", "  ");
 }
 function _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
     for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
@@ -101,3 +101,9 @@ function _wrapJSDocText(text, firstIndent, continuationIndent) {
     lines.push(current.trimEnd());
     return lines;
 }
+function _formatCodeSpan(value) {
+    return `\`${_escapeMarkdownCode(_escapeComment(value))}\``;
+}
+function _escapeMarkdownCode(value) {
+    return value.replace(/`/g, "\\`");
+}

package/dist/esm/generator/generate-jsdoc.js

@@ -24,14 +24,14 @@ export function generateJSDocFromSpec(params) {
             _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        _pushJSDocBulletField(lines, "DTO", _formatCodeSpan(`${dtoName}.${rule.from}`));
         if (rule.dtoDescription) {
-            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+            _pushJSDocBulletField(lines, "DTO description", _escapeComment(rule.dtoDescription));
         }
-        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
+        _pushJSDocBulletField(lines, "DTO type", _formatCodeSpan(dtoPathType ? checker.typeToString(dtoPathType) : "unknown"));
         if (rule.db)
-            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
-        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
+            _pushJSDocBulletField(lines, "Origin", _formatCodeSpan(rule.db));
+        _pushJSDocBulletField(lines, "Domain type", _formatCodeSpan(checker.typeToString(domainType)));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -69,8 +69,8 @@ function _getDomainDescription(checker, prop) {
     const description = ts.displayPartsToString(prop.getDocumentationComment(checker)).trim();
     return description || null;
 }
-function _pushJSDocField(lines, label, value) {
-    _pushJSDocText(lines, `${label}: ${value}`, "", " ".repeat(label.length + 2));
+function _pushJSDocBulletField(lines, label, value) {
+    _pushJSDocText(lines, `- ${label}: ${value}`, "", "  ");
 }
 function _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
     for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
@@ -95,3 +95,9 @@ function _wrapJSDocText(text, firstIndent, continuationIndent) {
     lines.push(current.trimEnd());
     return lines;
 }
+function _formatCodeSpan(value) {
+    return `\`${_escapeMarkdownCode(_escapeComment(value))}\``;
+}
+function _escapeMarkdownCode(value) {
+    return value.replace(/`/g, "\\`");
+}

package/docs/build-integrations.md

@@ -53,6 +53,10 @@ export const addressMap = defineMap<
 It generates `SearchAddressDomain` by removing the `Source` suffix and writes
 all generated interfaces for the same folder to `runtypex.generated.ts`.
 
+Unlike `makeValidate<T>()`, `makeAssert<T>()`, and `makeMapper<TDto, TDomain>()`,
+docs generation does create a file. When `docs` is not configured, no
+`runtypex.generated.ts` file is written.
+
 Docs options:
 
 | Option | Default | Description |

package/docs/jsdoc-generation.md

@@ -25,6 +25,57 @@ The plugin finds `defineMap<TDto, TDomainSource>()(...)` calls in included mappe
 files, removes the `Source` suffix from `TDomainSource`, and writes generated
 interfaces to `runtypex.generated.ts` next to the mapper file.
 
+## Build-Time vs No Build Integration
+
+Docs generation runs from the Vite plugin `buildStart` hook. It is not a runtime
+API and it does not change application code.
+
+With `docs.include` configured, each matching mapper file is scanned during the
+build:
+
+```ts
+// src/features/address/address.mapper.ts
+export interface SearchAddressDomainSource {
+  /** Address id */
+  id: string;
+}
+
+export const addressMap = defineMap<
+  SearchAddressDto,
+  SearchAddressDomainSource
+>()({
+  id: source("RESULT.ID", {
+    db: "address.id",
+    dtoDescription: "Address identifier from the API response.",
+  }),
+});
+```
+
+The plugin writes a generated file next to the mapper file:
+
+```ts
+// src/features/address/runtypex.generated.ts
+export interface SearchAddressDomain {
+  /**
+   * Address id
+   *
+   * - DTO: `SearchAddressDto.RESULT.ID`
+   * - DTO description: Address identifier from the API response.
+   * - DTO type: `string`
+   * - Origin: `address.id`
+   * - Domain type: `string`
+   */
+  id: string;
+}
+```
+
+No application runtime code is emitted for docs generation. The only output is
+the generated `.ts` documentation file.
+
+Without `docs` configured, or without running the Vite plugin, no docs file is
+created. Mapper files remain unchanged, and `generateJSDocFromSpec()` is only
+available as a manual build-tool API.
+
 ## Manual API
 
 ```ts
@@ -66,8 +117,8 @@ Field meanings:
 | Field | Meaning |
 | --- | --- |
 | Domain property JSDoc | Domain field description. Usually used as the first JSDoc sentence. |
-| `dtoDescription` | Optional explanation shown below the DTO path line. |
-| `db` | Optional database table and column reference. |
+| `dtoDescription` | Optional explanation shown as the `DTO description` bullet. |
+| `db` | Optional origin field shown as the `Origin` bullet. |
 
 For older mapper specs, `description` is still read as a fallback when the
 domain property has no JSDoc. New code should prefer domain property JSDoc so
@@ -95,11 +146,11 @@ the generated documentation can look like this:
 /**
  * User id
  *
- * DTO: UserDto.user_id
- *      Identifier returned by the user API.
- * DTO type: string
- * DB: users.user_id
- * Domain type: string
+ * - DTO: `UserDto.user_id`
+ * - DTO description: Identifier returned by the user API.
+ * - DTO type: `string`
+ * - Origin: `users.user_id`
+ * - Domain type: `string`
  */
 id: string;
 ```

package/docs/ko/build-integrations.md

@@ -0,0 +1,186 @@
+
+# 빌드 연동
+
+`runtypex`는 TypeScript 컴파일러 API를 사용해 타입 정보를 분석하고, 이를 바탕으로 검증 함수와 매퍼 코드를 생성합니다.
+
+가장 좋은 사용 방식은 **빌드 과정에서 TypeScript 트랜스포머를 실행하는 것**입니다. 이렇게 하면 타입 정보를 온전히 활용할 수 있어 `runtypex`의 기능을 제대로 사용할 수 있습니다.
+
+<br/>
+
+## Vite에서 사용하기
+
+Vite 프로젝트에서는 `runtypex`의 Vite 플러그인을 등록하면 됩니다.
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { vitePlugin as runtypex } from "runtypex";
+
+export default defineConfig({
+  plugins: [runtypex()],
+});
+```
+
+Vite 플러그인은 TypeScript 파일을 분석하면서 다음 호출을 찾습니다.
+
+* `makeValidate<T>()`
+* `makeAssert<T>()`
+* `makeMapper<TDto, TDomain>()`
+
+대상 호출을 찾으면 플러그인은 다음 순서로 동작합니다.
+
+1. 해당 파일에서 가장 가까운 `tsconfig.json`을 찾습니다.
+2. TypeScript 프로그램을 생성합니다.
+3. `runtypex` 트랜스포머를 실행합니다.
+4. 변환된 코드를 Vite에 반환합니다.
+
+즉, 개발자는 위 함수들을 선언적으로 작성하고, 실제 검증 및 매핑 코드는 빌드 과정에서 자동으로 생성됩니다.
+
+<br/>
+
+## Vite에서 매퍼 문서 생성하기
+
+Vite 플러그인은 매퍼 파일을 분석해, 컨벤션 기반으로 타입 문서 파일을 생성할 수도 있습니다.
+
+```ts
+export default defineConfig({
+  plugins: [
+    runtypex({
+      docs: {
+        include: "src/features/**/*.mapper.ts",
+      },
+    }),
+  ],
+});
+```
+
+위 설정을 추가하면 `runtypex`는 지정된 매퍼 파일을 스캔합니다.
+
+예를 들어 다음과 같은 매퍼 선언이 있다고 가정합니다.
+
+```ts
+export const addressMap = defineMap<
+  SearchAddressDto,
+  SearchAddressDomainSource
+>()({
+  id: source("RESULT.ID"),
+});
+```
+
+`runtypex`는 두 번째 타입 인자인 `SearchAddressDomainSource`를 기준으로 생성할 도메인 타입 이름을 결정합니다.
+
+기본 설정에서는 `Source` 접미사를 제거하므로, 생성되는 인터페이스 이름은 다음과 같습니다.
+
+```ts
+SearchAddressDomain
+```
+
+생성된 인터페이스들은 각 매퍼 파일과 같은 폴더의 `runtypex.generated.ts` 파일에 기록됩니다.
+
+> `makeValidate<T>()`, `makeAssert<T>()`, `makeMapper<TDto, TDomain>()`은 빌드 중 코드를 변환하지만,
+> `docs` 옵션은 실제 파일인 `runtypex.generated.ts`를 생성합니다.
+
+`docs` 옵션을 설정하지 않으면 `runtypex.generated.ts` 파일은 생성되지 않습니다.
+
+<br/>
+
+## 문서 생성 옵션
+
+| 옵션                  | 기본값                                 | 설명                                                          |
+| ------------------- | ----------------------------------- | ----------------------------------------------------------- |
+| `include`           | `**/*.mapper.ts`, `**/*.mapper.tsx` | Vite 루트 기준으로 스캔할 매퍼 파일 패턴입니다.                               |
+| `exclude`           | generated file name                 | 스캔에서 제외할 파일 패턴입니다.                                          |
+| `sourceSuffix`      | `Source`                            | 생성 인터페이스 이름을 만들 때 제거할 도메인 타입 접미사입니다.                        |
+| `generatedFileName` | `runtypex.generated.ts`             | 각 매퍼 파일 옆에 생성할 파일 이름입니다.                                    |
+| `outDir`            | `near-source`                       | 생성 파일 위치입니다. 현재는 소스 파일 근처 생성만 지원합니다.                        |
+| `policyMode`        | `warn`                              | 매퍼가 문서 생성 컨벤션을 어겼을 때의 처리 방식입니다. `error`로 설정하면 빌드 실패로 처리합니다. |
+
+<br/>
+
+## ts-loader에서 사용하기
+
+webpack에서 `ts-loader`를 사용하는 경우, `getCustomTransformers` 옵션에 `runtypex` 트랜스포머를 등록합니다.
+
+```js
+// webpack.config.js
+const { tsTransformer } = require("runtypex");
+
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        loader: "ts-loader",
+        options: {
+          getCustomTransformers: (program) => ({
+            before: [tsTransformer({ program })],
+          }),
+        },
+      },
+    ],
+  },
+};
+```
+
+이 설정은 TypeScript 컴파일 전에 `runtypex` 트랜스포머를 실행합니다.
+
+<br/>
+
+## 트랜스포머 옵션
+
+`tsTransformer`에는 다음 옵션을 전달할 수 있습니다.
+
+```ts
+tsTransformer({
+  program,
+  removeInProd: true,
+  validateDto: true,
+  validateDomain: true,
+});
+```
+
+| 옵션               | 기본값      | 설명                                           |
+| ---------------- | -------- | -------------------------------------------- |
+| `program`        | required | 타입 해석에 사용할 TypeScript 프로그램입니다. 반드시 전달해야 합니다. |
+| `removeInProd`   | `false`  | 프로덕션 빌드에서 생성된 검증 코드를 no-op 함수로 대체합니다.        |
+| `validateDto`    | `true`   | 생성 매퍼에서 DTO 입력값 검증을 활성화합니다.                  |
+| `validateDomain` | `true`   | 생성 매퍼에서 도메인 출력값 검증을 활성화합니다.                  |
+
+<br/>
+
+## 패키지 진입점
+
+필요한 기능에 따라 다음 경로에서 가져올 수 있습니다.
+
+```ts
+import { makeValidate } from "runtypex";
+import { makeMapper } from "runtypex/mapper";
+import { generateJSDocFromSpec } from "runtypex/generator";
+import { tsTransformer } from "runtypex/transformer";
+import { vitePlugin } from "runtypex/transformer/vite-plugin";
+```
+
+패키지는 ESM과 CommonJS 빌드를 모두 제공합니다.
+
+* ESM: `dist/esm`
+* CommonJS: `dist/cjs`
+
+<br/>
+
+## 로컬 검증
+
+빌드와 테스트가 정상적으로 동작하는지 확인하려면 다음 명령을 사용할 수 있습니다.
+
+```bash
+npm run build
+npx jest --runInBand --watchman=false
+npm run test:esm
+```
+
+각 명령의 용도는 다음과 같습니다.
+
+| 명령                                      | 용도                            |
+| --------------------------------------- | ----------------------------- |
+| `npm run build`                         | 패키지를 빌드합니다.                   |
+| `npx jest --runInBand --watchman=false` | Jest 테스트를 단일 프로세스로 실행합니다.     |
+| `npm run test:esm`                      | ESM 환경에서 패키지가 정상 동작하는지 확인합니다. |

package/docs/ko/jsdoc-generation.md

@@ -0,0 +1,276 @@
+
+
+# JSDoc 생성
+
+`runtypex`는 매퍼 메타데이터를 바탕으로 도메인 인터페이스용 JSDoc 문서를 생성할 수 있습니다.
+
+생성된 JSDoc은 에디터에서 도메인 필드를 볼 때 다음 정보를 함께 확인할 수 있도록 돕습니다.
+
+* 도메인 필드의 설명
+* 해당 필드가 참조하는 DTO 경로
+* DTO 필드 설명
+* DTO 타입
+* 원본 데이터 출처
+* 도메인 타입
+
+즉, 매퍼를 통해 만들어진 도메인 필드가 **어떤 DTO 또는 원본 필드에서 왔는지**를 코드 안에서 바로 확인할 수 있습니다.
+
+
+<br/>
+
+## Vite에서 자동 생성하기
+
+Vite 프로젝트에서는 `runtypex` 플러그인의 `docs` 옵션을 설정하면 JSDoc 문서 파일을 자동으로 생성할 수 있습니다.
+
+```ts
+import { defineConfig } from "vite";
+import { vitePlugin as runtypex } from "runtypex";
+
+export default defineConfig({
+  plugins: [
+    runtypex({
+      docs: {
+        include: "src/features/**/*.mapper.ts",
+      },
+    }),
+  ],
+});
+```
+
+플러그인은 `docs.include`에 포함된 매퍼 파일을 스캔하고, 다음 형태의 호출을 찾습니다.
+
+```ts
+defineMap<TDto, TDomainSource>()(...)
+```
+
+그런 다음 두 번째 타입 인자인 `TDomainSource`를 기준으로 생성할 인터페이스 이름을 결정합니다.
+
+기본 설정에서는 `Source` 접미사를 제거합니다.
+
+예를 들어 다음 타입은:
+
+```ts
+SearchAddressDomainSource
+```
+
+다음 인터페이스 이름으로 생성됩니다.
+
+```ts
+SearchAddressDomain
+```
+
+생성된 인터페이스는 매퍼 파일과 같은 폴더의 `runtypex.generated.ts` 파일에 기록됩니다.
+
+
+<br/>
+
+## 생성 예시
+
+다음과 같은 매퍼 파일이 있다고 가정합니다.
+
+```ts
+// src/features/address/address.mapper.ts
+export interface SearchAddressDomainSource {
+  /** Address id */
+  id: string;
+}
+
+export const addressMap = defineMap<
+  SearchAddressDto,
+  SearchAddressDomainSource
+>()({
+  id: source("RESULT.ID", {
+    db: "address.id",
+    dtoDescription: "Address identifier from the API response.",
+  }),
+});
+```
+
+`runtypex`는 매퍼 파일 옆에 다음과 같은 생성 파일을 기록합니다.
+
+```ts
+// src/features/address/runtypex.generated.ts
+export interface SearchAddressDomain {
+  /**
+   * Address id
+   *
+   * - DTO: `SearchAddressDto.RESULT.ID`
+   * - DTO description: Address identifier from the API response.
+   * - DTO type: `string`
+   * - Origin: `address.id`
+   * - Domain type: `string`
+   */
+  id: string;
+}
+```
+
+이 문서는 런타임 코드가 아니라, 타입과 에디터 경험을 위한 `.ts` 문서 파일입니다.
+
+
+<br/>
+
+## 문서 생성 시점
+
+JSDoc 문서 생성은 Vite 플러그인의 `buildStart` 훅에서 실행됩니다.
+
+따라서 다음 조건을 만족할 때만 문서 파일이 생성됩니다.
+
+1. Vite 플러그인을 사용합니다.
+2. `docs` 옵션을 설정합니다.
+3. `docs.include`에 해당하는 매퍼 파일이 있습니다.
+4. 해당 파일 안에 `defineMap<TDto, TDomainSource>()(...)` 호출이 있습니다.
+
+반대로 다음 경우에는 `runtypex.generated.ts` 파일이 생성되지 않습니다.
+
+* `docs` 옵션을 설정하지 않은 경우
+* Vite 플러그인을 실행하지 않은 경우
+* 포함 조건에 맞는 매퍼 파일이 없는 경우
+* 매퍼 파일이 문서 생성 컨벤션을 따르지 않는 경우
+
+문서 생성은 애플리케이션 런타임 코드를 변경하지 않습니다. 매퍼 파일도 그대로 유지되며, 출력 결과는 생성된 `.ts` 문서 파일뿐입니다.
+
+
+<br/>
+
+## 수동 API 사용하기
+
+Vite 플러그인을 사용하지 않고, 자체 빌드 도구에서 JSDoc 생성을 직접 실행할 수도 있습니다.
+
+```ts
+import { generateJSDocFromSpec } from "runtypex/generator";
+
+const source = generateJSDocFromSpec({
+  checker,
+  dtoType,
+  domainType,
+  specNode,
+});
+```
+
+`generateJSDocFromSpec()`은 저수준 API입니다.
+
+이 API는 다음 값에 이미 접근할 수 있는 빌드 도구를 위한 기능입니다.
+
+* TypeScript 프로그램
+* TypeScript checker
+* DTO 타입
+* 도메인 타입
+* 매퍼 명세 노드
+
+일반적인 Vite 프로젝트에서는 직접 호출하기보다 `docs` 옵션을 사용하는 것을 권장합니다.
+
+
+<br/>
+
+## 메타데이터 작성 위치
+
+도메인 필드의 기본 설명은 도메인 타입에 작성하는 것이 좋습니다.
+
+```ts
+interface User {
+  /** User id */
+  id: string;
+}
+```
+
+매퍼 메타데이터에는 DTO 또는 원본 데이터에 특화된 설명을 작성할 수 있습니다.
+
+```ts
+source("user_id", {
+  db: "users.user_id",
+  dtoDescription: "Identifier returned by the user API.",
+});
+```
+
+각 필드는 생성된 JSDoc에서 다음과 같이 사용됩니다.
+
+| 필드                    | 설명                                       |
+| --------------------- | ---------------------------------------- |
+| Domain property JSDoc | 도메인 필드 설명입니다. 일반적으로 JSDoc의 첫 문장으로 사용됩니다. |
+| `dtoDescription`      | `DTO description` 항목에 표시되는 선택 설명입니다.     |
+| `db`                  | `Origin` 항목에 표시되는 선택 원본 필드입니다.           |
+
+
+<br/>
+
+## `description` 폴백
+
+이전 매퍼 명세와의 호환성을 위해, 도메인 프로퍼티에 JSDoc이 없으면 매퍼 메타데이터의 `description` 값을 폴백으로 사용합니다.
+
+다만 새 코드에서는 도메인 프로퍼티 JSDoc을 우선 사용하는 것이 좋습니다.
+
+```ts
+interface User {
+  /** User id */
+  id: string;
+}
+```
+
+이 방식은 도메인 필드의 의미를 타입 정의에 한 번만 작성할 수 있게 해줍니다. 같은 도메인 필드를 여러 DTO 매핑에서 사용할 때도 설명을 반복하지 않아도 됩니다.
+
+
+<br/>
+
+## 생성 결과 예시
+
+다음 도메인 타입과 매핑이 있다고 가정합니다.
+
+```ts
+interface User {
+  /** User id */
+  id: string;
+}
+```
+
+```ts
+id: source("user_id", {
+  db: "users.user_id",
+  dtoDescription: "Identifier returned by the user API.",
+});
+```
+
+생성되는 JSDoc은 다음과 같은 형태가 됩니다.
+
+```ts
+/**
+ * User id
+ *
+ * - DTO: `UserDto.user_id`
+ * - DTO description: Identifier returned by the user API.
+ * - DTO type: `string`
+ * - Origin: `users.user_id`
+ * - Domain type: `string`
+ */
+id: string;
+```
+
+
+<br/>
+
+## 정책 옵션 연동
+
+JSDoc 생성은 매퍼 정책 옵션과 함께 사용할 수 있습니다.
+
+정책 옵션을 설정하면 매퍼 명세가 표준 DTO 경로 명명 규칙을 위반했을 때 경고를 출력하거나, 문서 생성 자체를 실패시킬 수 있습니다.
+
+```ts
+generateJSDocFromSpec({
+  checker,
+  dtoType,
+  domainType,
+  specNode,
+  options: {
+    mappingPolicy: policy,
+    policyMode: "error",
+  },
+});
+```
+
+`policyMode`는 정책 위반을 어떻게 처리할지 결정합니다.
+
+| 값       | 동작                             |
+| ------- | ------------------------------ |
+| `warn`  | 정책 위반을 경고로 처리합니다.              |
+| `error` | 정책 위반을 오류로 처리하고 문서 생성을 실패시킵니다. |
+
+이 옵션은 생성 문서가 런타임 매퍼 및 빌드 시점 매퍼 생성과 같은 명명 규칙을 따르도록 만들고 싶을 때 유용합니다.