runtypex 0.2.0 → 0.2.2

package/README.md

@@ -57,6 +57,24 @@ export default defineConfig({
 });
 ```
 
+To generate mapper documentation by convention:
+
+```ts
+export default defineConfig({
+  plugins: [
+    runtypex({
+      docs: {
+        include: "src/features/**/*.mapper.ts",
+      },
+    }),
+  ],
+});
+```
+
+The docs generator finds `defineMap<TDto, TDomainSource>()(...)` calls under the
+included files, removes the `Source` suffix, and writes generated interfaces to
+`runtypex.generated.ts` next to the mapper file.
+
 ## Feature Docs
 
 | Feature | Description |
@@ -64,7 +82,7 @@ export default defineConfig({
 | [Runtime validation](docs/runtime-validation.md) | Generate `makeValidate<T>()` and `makeAssert<T>()` implementations from TypeScript types. |
 | [Mapper](docs/mapper.md) | Convert DTO shapes into domain shapes with typed mapping specs. |
 | [Mapping policy](docs/mapping-policy.md) | Keep DTO path to domain field names consistent across multiple mappers. |
-| [JSDoc generation](docs/jsdoc-generation.md) | Generate field documentation from mapper metadata. |
+| [JSDoc generation](docs/jsdoc-generation.md) | Generate field documentation from domain JSDoc and mapper metadata. |
 | [Build integrations](docs/build-integrations.md) | Configure Vite, ts-loader, ESM exports, and build behavior. |
 
 ## Mapper Example
@@ -78,23 +96,23 @@ interface UserDto {
   status: "ACTIVE" | "INACTIVE";
 }
 
-interface User {
+interface UserSource {
+  /** User id */
   id: string;
   displayName: string;
   isActive: boolean;
 }
 
-const userMap = defineMap<UserDto, User>()({
+const userMap = defineMap<UserDto, UserSource>()({
   id: source("user_id", {
     db: "users.user_id",
-    description: "User id",
     dtoDescription: "User identifier from the user DTO.",
   }),
   displayName: source("profile.name"),
   isActive: transform("status", (value) => value === "ACTIVE"),
 });
 
-const toUser = makeMapper<UserDto, User>(userMap);
+const toUser = makeMapper<UserDto, UserSource>(userMap);
 ```
 
 ## Why runtypex?

package/dist/cjs/core/emitMapperFromSpec.d.ts

@@ -9,6 +9,7 @@ export type MapRuleInfo = {
     key: string;
     from: string;
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
 };

package/dist/cjs/generator/generate-docs.d.ts

@@ -0,0 +1,18 @@
+import ts from "typescript";
+export type RuntypexDocsOptions = boolean | {
+    include?: string | string[];
+    exclude?: string | string[];
+    sourceSuffix?: string;
+    generatedFileName?: string;
+    outDir?: "near-source";
+    policyMode?: "warn" | "error";
+};
+export type GeneratedDocsFile = {
+    fileName: string;
+    content: string;
+};
+export declare function generateDocsFromProgram(params: {
+    program: ts.Program;
+    rootDir: string;
+    docs: RuntypexDocsOptions;
+}): GeneratedDocsFile[];

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

@@ -0,0 +1,202 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocsFromProgram = generateDocsFromProgram;
+const node_path_1 = __importDefault(require("node:path"));
+const typescript_1 = __importDefault(require("typescript"));
+const generate_jsdoc_js_1 = require("./generate-jsdoc.js");
+function generateDocsFromProgram(params) {
+    const options = _normalizeDocsOptions(params.docs);
+    if (!options)
+        return [];
+    const checker = params.program.getTypeChecker();
+    const groups = new Map();
+    const sourceFiles = params.program
+        .getSourceFiles()
+        .filter((sourceFile) => !sourceFile.isDeclarationFile && _isIncluded(sourceFile.fileName, params.rootDir, options))
+        .sort((a, b) => _toPosix(a.fileName).localeCompare(_toPosix(b.fileName)));
+    for (const sourceFile of sourceFiles) {
+        for (const doc of _findMapperDocs(checker, sourceFile, options)) {
+            const fileName = node_path_1.default.join(node_path_1.default.dirname(sourceFile.fileName), options.generatedFileName);
+            const docs = groups.get(fileName) ?? [];
+            docs.push(doc);
+            groups.set(fileName, docs);
+        }
+    }
+    return Array.from(groups.entries())
+        .sort(([a], [b]) => _toPosix(a).localeCompare(_toPosix(b)))
+        .map(([fileName, docs]) => ({
+        fileName,
+        content: _generateFileContent(checker, fileName, docs, options),
+    }));
+}
+function _normalizeDocsOptions(options) {
+    if (!options)
+        return null;
+    const object = typeof options === "object" ? options : {};
+    if (object.outDir && object.outDir !== "near-source") {
+        throw new Error('[runtypex/docs] docs.outDir currently supports only "near-source".');
+    }
+    const generatedFileName = object.generatedFileName ?? "runtypex.generated.ts";
+    return {
+        include: _array(object.include ?? ["**/*.mapper.ts", "**/*.mapper.tsx"]),
+        exclude: [..._array(object.exclude), `**/${generatedFileName}`],
+        sourceSuffix: object.sourceSuffix ?? "Source",
+        generatedFileName,
+        policyMode: object.policyMode ?? "warn",
+    };
+}
+function _isIncluded(fileName, rootDir, options) {
+    return (_matchesAny(fileName, rootDir, options.include) &&
+        !_matchesAny(fileName, rootDir, options.exclude));
+}
+function _findMapperDocs(checker, sourceFile, options) {
+    const docs = [];
+    const visit = (node) => {
+        if (typescript_1.default.isVariableDeclaration(node) && typescript_1.default.isIdentifier(node.name) && node.initializer) {
+            const map = _readDefineMapCall(node.initializer);
+            if (map) {
+                const domainType = checker.getTypeFromTypeNode(map.domainTypeNode);
+                const domainName = _typeName(checker, domainType, map.domainTypeNode, sourceFile);
+                const generatedName = _generatedName(domainName, options.sourceSuffix);
+                if (generatedName) {
+                    docs.push({
+                        generatedName,
+                        dtoType: checker.getTypeFromTypeNode(map.dtoTypeNode),
+                        domainType,
+                        specNode: map.specNode,
+                    });
+                }
+                else {
+                    _handleConventionIssue(`[runtypex/docs] Skipping ${node.name.text}: ${_generatedNameIssue(domainName, options.sourceSuffix)}.`, options.policyMode);
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return docs;
+}
+function _readDefineMapCall(node) {
+    const specCall = _skip(node);
+    if (!typescript_1.default.isCallExpression(specCall) || !specCall.arguments[0])
+        return null;
+    const factoryCall = _skip(specCall.expression);
+    if (!typescript_1.default.isCallExpression(factoryCall) || factoryCall.typeArguments?.length !== 2)
+        return null;
+    if (!_isDefineMapExpression(_skip(factoryCall.expression)))
+        return null;
+    return {
+        dtoTypeNode: factoryCall.typeArguments[0],
+        domainTypeNode: factoryCall.typeArguments[1],
+        specNode: specCall,
+    };
+}
+function _isDefineMapExpression(node) {
+    return ((typescript_1.default.isIdentifier(node) && node.text === "defineMap") ||
+        (typescript_1.default.isPropertyAccessExpression(node) && node.name.text === "defineMap"));
+}
+function _generateFileContent(checker, fileName, docs, options) {
+    const names = new Set();
+    const interfaces = [];
+    for (const doc of docs) {
+        if (names.has(doc.generatedName)) {
+            throw new Error(`[runtypex/docs] Generated interface "${doc.generatedName}" conflicts in ${fileName}.`);
+        }
+        names.add(doc.generatedName);
+        interfaces.push((0, generate_jsdoc_js_1.generateJSDocFromSpec)({
+            checker,
+            dtoType: doc.dtoType,
+            domainType: doc.domainType,
+            specNode: doc.specNode,
+            options: { name: doc.generatedName, policyMode: options.policyMode },
+        }));
+    }
+    return `${interfaces.join("\n\n")}\n`;
+}
+function _generatedName(domainName, sourceSuffix) {
+    if (!sourceSuffix)
+        return domainName;
+    if (!domainName.endsWith(sourceSuffix))
+        return null;
+    const generatedName = domainName.slice(0, -sourceSuffix.length);
+    return generatedName || null;
+}
+function _generatedNameIssue(domainName, sourceSuffix) {
+    if (!sourceSuffix)
+        return `domain type "${domainName}" does not produce a generated interface name`;
+    if (!domainName.endsWith(sourceSuffix)) {
+        return `domain type "${domainName}" does not end with "${sourceSuffix}"`;
+    }
+    return `domain type "${domainName}" would produce an empty generated interface name`;
+}
+function _typeName(checker, type, typeNode, sourceFile) {
+    return (type.aliasSymbol?.name ??
+        type.symbol?.name ??
+        checker.typeToString(type, typeNode) ??
+        typeNode.getText(sourceFile));
+}
+function _handleConventionIssue(message, mode) {
+    if (mode === "error")
+        throw new Error(message);
+    console.warn(message);
+}
+function _matchesAny(fileName, rootDir, patterns) {
+    const absolute = _toPosix(node_path_1.default.resolve(fileName));
+    const relative = _toPosix(node_path_1.default.relative(rootDir, fileName));
+    return patterns.some((pattern) => {
+        const normalized = _toPosix(pattern);
+        const target = node_path_1.default.isAbsolute(pattern) ? absolute : relative;
+        return _globToRegExp(normalized).test(target);
+    });
+}
+function _globToRegExp(pattern) {
+    let regex = "^";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        const next = pattern[i + 1];
+        if (char === "*") {
+            if (next === "*") {
+                const after = pattern[i + 2];
+                if (after === "/") {
+                    regex += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    regex += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                regex += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            regex += "[^/]";
+            continue;
+        }
+        regex += _escapeRegex(char);
+    }
+    return new RegExp(`${regex}$`);
+}
+function _escapeRegex(value) {
+    return /[\\^$+?.()|[\]{}]/.test(value) ? `\\${value}` : value;
+}
+function _skip(node) {
+    let expr = node;
+    while (typescript_1.default.isParenthesizedExpression(expr) || typescript_1.default.isAsExpression(expr) || typescript_1.default.isTypeAssertionExpression(expr)) {
+        expr = expr.expression;
+    }
+    return expr;
+}
+function _array(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function _toPosix(value) {
+    return value.replace(/\\/g, "/");
+}

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

@@ -7,6 +7,7 @@ exports.generateJSDocFromSpec = generateJSDocFromSpec;
 const typescript_1 = __importDefault(require("typescript"));
 const path_js_1 = require("../core/path.js");
 const emitMapperFromSpec_js_1 = require("../core/emitMapperFromSpec.js");
+const JSDOC_CONTENT_WIDTH = 76;
 function generateJSDocFromSpec(params) {
     const checker = params.checker;
     const dtoName = params.dtoType.symbol?.name ?? "Dto";
@@ -22,18 +23,21 @@ function generateJSDocFromSpec(params) {
         const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
         const domainType = declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : checker.getAnyType();
         const dtoPathType = _getTypeAtPath(checker, params.dtoType, rule.from);
+        const description = _getDomainDescription(checker, prop) ?? rule.description;
         const optional = (prop.getFlags() & typescript_1.default.SymbolFlags.Optional) !== 0 ? "?" : "";
         lines.push("  /**");
-        if (rule.description) {
-            lines.push(`   * ${_escapeComment(rule.description)}`);
+        if (description) {
+            _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        const dtoDescription = rule.dtoDescription ? ` ${_escapeComment(rule.dtoDescription)}` : "";
-        lines.push(`   * DTO: ${dtoName}.${rule.from}${dtoDescription}`);
-        lines.push(`   * DTO type: ${dtoPathType ? checker.typeToString(dtoPathType) : "unknown"}`);
+        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        if (rule.dtoDescription) {
+            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+        }
+        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
         if (rule.db)
-            lines.push(`   * DB: ${_escapeComment(rule.db)}`);
-        lines.push(`   * Domain type: ${checker.typeToString(domainType)}`);
+            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
+        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -67,3 +71,33 @@ function _propertyName(name) {
 function _escapeComment(value) {
     return value.replace(/\*\//g, "* /");
 }
+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 _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
+    for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
+        lines.push(`   * ${line}`);
+    }
+}
+function _wrapJSDocText(text, firstIndent, continuationIndent) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    if (!words.length)
+        return [firstIndent.trimEnd()];
+    const lines = [];
+    let current = firstIndent;
+    for (const word of words) {
+        const candidate = current.trim().length ? `${current} ${word}` : `${current}${word}`;
+        if (candidate.length <= JSDOC_CONTENT_WIDTH || !current.trim().length) {
+            current = candidate;
+            continue;
+        }
+        lines.push(current.trimEnd());
+        current = `${continuationIndent}${word}`;
+    }
+    lines.push(current.trimEnd());
+    return lines;
+}

package/dist/cjs/generator/index.d.ts

@@ -1 +1,2 @@
 export * from "./generate-jsdoc.js";
+export * from "./generate-docs.js";

package/dist/cjs/generator/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./generate-jsdoc.js"), exports);
+__exportStar(require("./generate-docs.js"), exports);

package/dist/cjs/index.d.ts

@@ -1,4 +1,4 @@
 export { makeValidate, makeAssert, type ValidateFn, type AssertFn } from "./runtime/validate.js";
 export { defineMap, defineMappingPolicy, mapperHelpers, makeMapper, source, transform, type DefinedMap, type Mapper, type MapperOptions, type MapperMetadata, type MapRule, type MapSpec, type MappingPolicy, type MappingPolicyMode, type PathOf, } from "./runtime/mapper.js";
-export { default as vitePlugin } from "./transformer/vite-plugin.js";
+export { default as vitePlugin, type RuntypexVitePluginOptions } from "./transformer/vite-plugin.js";
 export { default as tsTransformer } from "./transformer/ts-transformer.js";

package/dist/cjs/runtime/mapper.d.ts

@@ -5,6 +5,7 @@ export type PathOf<T> = T extends Primitive ? never : T extends readonly (infer
 export type Mapper<TDto, TDomain> = (dto: TDto) => TDomain;
 export type MapperMetadata<TValue = never> = {
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
     default?: TValue;

package/dist/cjs/transformer/index.d.ts

@@ -1,3 +1,3 @@
 export { default } from "./ts-transformer.js";
 export { default as tsTransformer } from "./ts-transformer.js";
-export { default as vitePlugin } from "./vite-plugin.js";
+export { default as vitePlugin, type RuntypexVitePluginOptions } from "./vite-plugin.js";

package/dist/cjs/transformer/vite-plugin.d.ts

@@ -1,4 +1,9 @@
 import type { Plugin } from "vite";
+import { type RuntypexDocsOptions } from "../generator/generate-docs.js";
+export type RuntypexVitePluginOptions = {
+    removeInProd?: boolean;
+    docs?: RuntypexDocsOptions;
+};
 /**
  * 🧩 vitePluginRuntypex
  * A Vite plugin that performs build-time type → runtime validation transformation.
@@ -13,6 +18,4 @@ import type { Plugin } from "vite";
  *  - Optional: remove validation code in production (`removeInProd`)
  *  - Compatible with Rollup / Webpack (via Vite plugin API)
  */
-export default function vitePluginRuntypex(options?: {
-    removeInProd?: boolean;
-}): Plugin;
+export default function vitePluginRuntypex(options?: RuntypexVitePluginOptions): Plugin;

package/dist/cjs/transformer/vite-plugin.js

@@ -6,6 +6,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.default = vitePluginRuntypex;
 const typescript_1 = __importDefault(require("typescript"));
 const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const generate_docs_js_1 = require("../generator/generate-docs.js");
 const ts_transformer_js_1 = __importDefault(require("./ts-transformer.js"));
 /**
  * 🧩 vitePluginRuntypex
@@ -23,9 +25,24 @@ const ts_transformer_js_1 = __importDefault(require("./ts-transformer.js"));
  */
 function vitePluginRuntypex(options) {
     const removeInProd = !!options?.removeInProd;
+    let root = process.cwd();
     return {
         name: "vite-plugin-runtypex",
         enforce: "pre",
+        configResolved(config) {
+            root = config.root;
+        },
+        buildStart() {
+            if (!options?.docs)
+                return;
+            const { program } = _createProgramForRoot(root);
+            for (const file of (0, generate_docs_js_1.generateDocsFromProgram)({ program, rootDir: root, docs: options.docs })) {
+                node_fs_1.default.mkdirSync(node_path_1.default.dirname(file.fileName), { recursive: true });
+                if (typescript_1.default.sys.fileExists(file.fileName) && typescript_1.default.sys.readFile(file.fileName) === file.content)
+                    continue;
+                node_fs_1.default.writeFileSync(file.fileName, file.content);
+            }
+        },
         transform(code, id) {
             const isTS = id.endsWith(".ts") || id.endsWith(".tsx");
             const isTargetFunction = /make(?:Validate|Assert|Mapper)</.test(code);
@@ -46,7 +63,10 @@ function vitePluginRuntypex(options) {
 // ① createProgram & TypeChecker
 // ──────────────────────────────────────────────
 function _createProgramFor(file) {
-    const tsconfig = _findNearestTsconfig(node_path_1.default.dirname(file));
+    return _createProgramForRoot(node_path_1.default.dirname(file));
+}
+function _createProgramForRoot(root) {
+    const tsconfig = _findNearestTsconfig(root);
     const cfg = typescript_1.default.readConfigFile(tsconfig, typescript_1.default.sys.readFile);
     if (cfg.error)
         throw new Error(typescript_1.default.flattenDiagnosticMessageText(cfg.error.messageText, "\n"));

package/dist/esm/core/emitMapperFromSpec.d.ts

@@ -9,6 +9,7 @@ export type MapRuleInfo = {
     key: string;
     from: string;
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
 };

package/dist/esm/generator/generate-docs.d.ts

@@ -0,0 +1,18 @@
+import ts from "typescript";
+export type RuntypexDocsOptions = boolean | {
+    include?: string | string[];
+    exclude?: string | string[];
+    sourceSuffix?: string;
+    generatedFileName?: string;
+    outDir?: "near-source";
+    policyMode?: "warn" | "error";
+};
+export type GeneratedDocsFile = {
+    fileName: string;
+    content: string;
+};
+export declare function generateDocsFromProgram(params: {
+    program: ts.Program;
+    rootDir: string;
+    docs: RuntypexDocsOptions;
+}): GeneratedDocsFile[];

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

@@ -0,0 +1,196 @@
+import path from "node:path";
+import ts from "typescript";
+import { generateJSDocFromSpec } from "./generate-jsdoc.js";
+export function generateDocsFromProgram(params) {
+    const options = _normalizeDocsOptions(params.docs);
+    if (!options)
+        return [];
+    const checker = params.program.getTypeChecker();
+    const groups = new Map();
+    const sourceFiles = params.program
+        .getSourceFiles()
+        .filter((sourceFile) => !sourceFile.isDeclarationFile && _isIncluded(sourceFile.fileName, params.rootDir, options))
+        .sort((a, b) => _toPosix(a.fileName).localeCompare(_toPosix(b.fileName)));
+    for (const sourceFile of sourceFiles) {
+        for (const doc of _findMapperDocs(checker, sourceFile, options)) {
+            const fileName = path.join(path.dirname(sourceFile.fileName), options.generatedFileName);
+            const docs = groups.get(fileName) ?? [];
+            docs.push(doc);
+            groups.set(fileName, docs);
+        }
+    }
+    return Array.from(groups.entries())
+        .sort(([a], [b]) => _toPosix(a).localeCompare(_toPosix(b)))
+        .map(([fileName, docs]) => ({
+        fileName,
+        content: _generateFileContent(checker, fileName, docs, options),
+    }));
+}
+function _normalizeDocsOptions(options) {
+    if (!options)
+        return null;
+    const object = typeof options === "object" ? options : {};
+    if (object.outDir && object.outDir !== "near-source") {
+        throw new Error('[runtypex/docs] docs.outDir currently supports only "near-source".');
+    }
+    const generatedFileName = object.generatedFileName ?? "runtypex.generated.ts";
+    return {
+        include: _array(object.include ?? ["**/*.mapper.ts", "**/*.mapper.tsx"]),
+        exclude: [..._array(object.exclude), `**/${generatedFileName}`],
+        sourceSuffix: object.sourceSuffix ?? "Source",
+        generatedFileName,
+        policyMode: object.policyMode ?? "warn",
+    };
+}
+function _isIncluded(fileName, rootDir, options) {
+    return (_matchesAny(fileName, rootDir, options.include) &&
+        !_matchesAny(fileName, rootDir, options.exclude));
+}
+function _findMapperDocs(checker, sourceFile, options) {
+    const docs = [];
+    const visit = (node) => {
+        if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
+            const map = _readDefineMapCall(node.initializer);
+            if (map) {
+                const domainType = checker.getTypeFromTypeNode(map.domainTypeNode);
+                const domainName = _typeName(checker, domainType, map.domainTypeNode, sourceFile);
+                const generatedName = _generatedName(domainName, options.sourceSuffix);
+                if (generatedName) {
+                    docs.push({
+                        generatedName,
+                        dtoType: checker.getTypeFromTypeNode(map.dtoTypeNode),
+                        domainType,
+                        specNode: map.specNode,
+                    });
+                }
+                else {
+                    _handleConventionIssue(`[runtypex/docs] Skipping ${node.name.text}: ${_generatedNameIssue(domainName, options.sourceSuffix)}.`, options.policyMode);
+                }
+            }
+        }
+        node.forEachChild(visit);
+    };
+    visit(sourceFile);
+    return docs;
+}
+function _readDefineMapCall(node) {
+    const specCall = _skip(node);
+    if (!ts.isCallExpression(specCall) || !specCall.arguments[0])
+        return null;
+    const factoryCall = _skip(specCall.expression);
+    if (!ts.isCallExpression(factoryCall) || factoryCall.typeArguments?.length !== 2)
+        return null;
+    if (!_isDefineMapExpression(_skip(factoryCall.expression)))
+        return null;
+    return {
+        dtoTypeNode: factoryCall.typeArguments[0],
+        domainTypeNode: factoryCall.typeArguments[1],
+        specNode: specCall,
+    };
+}
+function _isDefineMapExpression(node) {
+    return ((ts.isIdentifier(node) && node.text === "defineMap") ||
+        (ts.isPropertyAccessExpression(node) && node.name.text === "defineMap"));
+}
+function _generateFileContent(checker, fileName, docs, options) {
+    const names = new Set();
+    const interfaces = [];
+    for (const doc of docs) {
+        if (names.has(doc.generatedName)) {
+            throw new Error(`[runtypex/docs] Generated interface "${doc.generatedName}" conflicts in ${fileName}.`);
+        }
+        names.add(doc.generatedName);
+        interfaces.push(generateJSDocFromSpec({
+            checker,
+            dtoType: doc.dtoType,
+            domainType: doc.domainType,
+            specNode: doc.specNode,
+            options: { name: doc.generatedName, policyMode: options.policyMode },
+        }));
+    }
+    return `${interfaces.join("\n\n")}\n`;
+}
+function _generatedName(domainName, sourceSuffix) {
+    if (!sourceSuffix)
+        return domainName;
+    if (!domainName.endsWith(sourceSuffix))
+        return null;
+    const generatedName = domainName.slice(0, -sourceSuffix.length);
+    return generatedName || null;
+}
+function _generatedNameIssue(domainName, sourceSuffix) {
+    if (!sourceSuffix)
+        return `domain type "${domainName}" does not produce a generated interface name`;
+    if (!domainName.endsWith(sourceSuffix)) {
+        return `domain type "${domainName}" does not end with "${sourceSuffix}"`;
+    }
+    return `domain type "${domainName}" would produce an empty generated interface name`;
+}
+function _typeName(checker, type, typeNode, sourceFile) {
+    return (type.aliasSymbol?.name ??
+        type.symbol?.name ??
+        checker.typeToString(type, typeNode) ??
+        typeNode.getText(sourceFile));
+}
+function _handleConventionIssue(message, mode) {
+    if (mode === "error")
+        throw new Error(message);
+    console.warn(message);
+}
+function _matchesAny(fileName, rootDir, patterns) {
+    const absolute = _toPosix(path.resolve(fileName));
+    const relative = _toPosix(path.relative(rootDir, fileName));
+    return patterns.some((pattern) => {
+        const normalized = _toPosix(pattern);
+        const target = path.isAbsolute(pattern) ? absolute : relative;
+        return _globToRegExp(normalized).test(target);
+    });
+}
+function _globToRegExp(pattern) {
+    let regex = "^";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const char = pattern[i];
+        const next = pattern[i + 1];
+        if (char === "*") {
+            if (next === "*") {
+                const after = pattern[i + 2];
+                if (after === "/") {
+                    regex += "(?:.*/)?";
+                    i += 2;
+                }
+                else {
+                    regex += ".*";
+                    i += 1;
+                }
+            }
+            else {
+                regex += "[^/]*";
+            }
+            continue;
+        }
+        if (char === "?") {
+            regex += "[^/]";
+            continue;
+        }
+        regex += _escapeRegex(char);
+    }
+    return new RegExp(`${regex}$`);
+}
+function _escapeRegex(value) {
+    return /[\\^$+?.()|[\]{}]/.test(value) ? `\\${value}` : value;
+}
+function _skip(node) {
+    let expr = node;
+    while (ts.isParenthesizedExpression(expr) || ts.isAsExpression(expr) || ts.isTypeAssertionExpression(expr)) {
+        expr = expr.expression;
+    }
+    return expr;
+}
+function _array(value) {
+    if (value === undefined)
+        return [];
+    return Array.isArray(value) ? value : [value];
+}
+function _toPosix(value) {
+    return value.replace(/\\/g, "/");
+}

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

@@ -1,6 +1,7 @@
 import ts from "typescript";
 import { parsePath } from "../core/path.js";
 import { findMapPolicyViolations, handleMapPolicyViolations, readMapRules } from "../core/emitMapperFromSpec.js";
+const JSDOC_CONTENT_WIDTH = 76;
 export function generateJSDocFromSpec(params) {
     const checker = params.checker;
     const dtoName = params.dtoType.symbol?.name ?? "Dto";
@@ -16,18 +17,21 @@ export function generateJSDocFromSpec(params) {
         const declaration = prop.valueDeclaration ?? prop.declarations?.[0];
         const domainType = declaration ? checker.getTypeOfSymbolAtLocation(prop, declaration) : checker.getAnyType();
         const dtoPathType = _getTypeAtPath(checker, params.dtoType, rule.from);
+        const description = _getDomainDescription(checker, prop) ?? rule.description;
         const optional = (prop.getFlags() & ts.SymbolFlags.Optional) !== 0 ? "?" : "";
         lines.push("  /**");
-        if (rule.description) {
-            lines.push(`   * ${_escapeComment(rule.description)}`);
+        if (description) {
+            _pushJSDocText(lines, _escapeComment(description));
             lines.push("   *");
         }
-        const dtoDescription = rule.dtoDescription ? ` ${_escapeComment(rule.dtoDescription)}` : "";
-        lines.push(`   * DTO: ${dtoName}.${rule.from}${dtoDescription}`);
-        lines.push(`   * DTO type: ${dtoPathType ? checker.typeToString(dtoPathType) : "unknown"}`);
+        _pushJSDocField(lines, "DTO", `${dtoName}.${rule.from}`);
+        if (rule.dtoDescription) {
+            _pushJSDocText(lines, _escapeComment(rule.dtoDescription), "     ");
+        }
+        _pushJSDocField(lines, "DTO type", dtoPathType ? checker.typeToString(dtoPathType) : "unknown");
         if (rule.db)
-            lines.push(`   * DB: ${_escapeComment(rule.db)}`);
-        lines.push(`   * Domain type: ${checker.typeToString(domainType)}`);
+            _pushJSDocField(lines, "DB", _escapeComment(rule.db));
+        _pushJSDocField(lines, "Domain type", checker.typeToString(domainType));
         lines.push("   */");
         lines.push(`  ${_propertyName(prop.name)}${optional}: ${checker.typeToString(domainType)};`);
         lines.push("");
@@ -61,3 +65,33 @@ function _propertyName(name) {
 function _escapeComment(value) {
     return value.replace(/\*\//g, "* /");
 }
+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 _pushJSDocText(lines, text, firstIndent = "", continuationIndent = firstIndent) {
+    for (const line of _wrapJSDocText(text, firstIndent, continuationIndent)) {
+        lines.push(`   * ${line}`);
+    }
+}
+function _wrapJSDocText(text, firstIndent, continuationIndent) {
+    const words = text.replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+    if (!words.length)
+        return [firstIndent.trimEnd()];
+    const lines = [];
+    let current = firstIndent;
+    for (const word of words) {
+        const candidate = current.trim().length ? `${current} ${word}` : `${current}${word}`;
+        if (candidate.length <= JSDOC_CONTENT_WIDTH || !current.trim().length) {
+            current = candidate;
+            continue;
+        }
+        lines.push(current.trimEnd());
+        current = `${continuationIndent}${word}`;
+    }
+    lines.push(current.trimEnd());
+    return lines;
+}

package/dist/esm/generator/index.d.ts

@@ -1 +1,2 @@
 export * from "./generate-jsdoc.js";
+export * from "./generate-docs.js";

package/dist/esm/generator/index.js

@@ -1 +1,2 @@
 export * from "./generate-jsdoc.js";
+export * from "./generate-docs.js";

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
 export { makeValidate, makeAssert, type ValidateFn, type AssertFn } from "./runtime/validate.js";
 export { defineMap, defineMappingPolicy, mapperHelpers, makeMapper, source, transform, type DefinedMap, type Mapper, type MapperOptions, type MapperMetadata, type MapRule, type MapSpec, type MappingPolicy, type MappingPolicyMode, type PathOf, } from "./runtime/mapper.js";
-export { default as vitePlugin } from "./transformer/vite-plugin.js";
+export { default as vitePlugin, type RuntypexVitePluginOptions } from "./transformer/vite-plugin.js";
 export { default as tsTransformer } from "./transformer/ts-transformer.js";

package/dist/esm/runtime/mapper.d.ts

@@ -5,6 +5,7 @@ export type PathOf<T> = T extends Primitive ? never : T extends readonly (infer
 export type Mapper<TDto, TDomain> = (dto: TDto) => TDomain;
 export type MapperMetadata<TValue = never> = {
     db?: string;
+    /** @deprecated Prefer domain property JSDoc for domain field descriptions. */
     description?: string;
     dtoDescription?: string;
     default?: TValue;

package/dist/esm/transformer/index.d.ts

@@ -1,3 +1,3 @@
 export { default } from "./ts-transformer.js";
 export { default as tsTransformer } from "./ts-transformer.js";
-export { default as vitePlugin } from "./vite-plugin.js";
+export { default as vitePlugin, type RuntypexVitePluginOptions } from "./vite-plugin.js";

package/dist/esm/transformer/vite-plugin.d.ts

@@ -1,4 +1,9 @@
 import type { Plugin } from "vite";
+import { type RuntypexDocsOptions } from "../generator/generate-docs.js";
+export type RuntypexVitePluginOptions = {
+    removeInProd?: boolean;
+    docs?: RuntypexDocsOptions;
+};
 /**
  * 🧩 vitePluginRuntypex
  * A Vite plugin that performs build-time type → runtime validation transformation.
@@ -13,6 +18,4 @@ import type { Plugin } from "vite";
  *  - Optional: remove validation code in production (`removeInProd`)
  *  - Compatible with Rollup / Webpack (via Vite plugin API)
  */
-export default function vitePluginRuntypex(options?: {
-    removeInProd?: boolean;
-}): Plugin;
+export default function vitePluginRuntypex(options?: RuntypexVitePluginOptions): Plugin;

package/dist/esm/transformer/vite-plugin.js

@@ -1,5 +1,7 @@
 import ts from "typescript";
 import path from "node:path";
+import fs from "node:fs";
+import { generateDocsFromProgram } from "../generator/generate-docs.js";
 import tsTransformer from "./ts-transformer.js";
 /**
  * 🧩 vitePluginRuntypex
@@ -17,9 +19,24 @@ import tsTransformer from "./ts-transformer.js";
  */
 export default function vitePluginRuntypex(options) {
     const removeInProd = !!options?.removeInProd;
+    let root = process.cwd();
     return {
         name: "vite-plugin-runtypex",
         enforce: "pre",
+        configResolved(config) {
+            root = config.root;
+        },
+        buildStart() {
+            if (!options?.docs)
+                return;
+            const { program } = _createProgramForRoot(root);
+            for (const file of generateDocsFromProgram({ program, rootDir: root, docs: options.docs })) {
+                fs.mkdirSync(path.dirname(file.fileName), { recursive: true });
+                if (ts.sys.fileExists(file.fileName) && ts.sys.readFile(file.fileName) === file.content)
+                    continue;
+                fs.writeFileSync(file.fileName, file.content);
+            }
+        },
         transform(code, id) {
             const isTS = id.endsWith(".ts") || id.endsWith(".tsx");
             const isTargetFunction = /make(?:Validate|Assert|Mapper)</.test(code);
@@ -40,7 +57,10 @@ export default function vitePluginRuntypex(options) {
 // ① createProgram & TypeChecker
 // ──────────────────────────────────────────────
 function _createProgramFor(file) {
-    const tsconfig = _findNearestTsconfig(path.dirname(file));
+    return _createProgramForRoot(path.dirname(file));
+}
+function _createProgramForRoot(root) {
+    const tsconfig = _findNearestTsconfig(root);
     const cfg = ts.readConfigFile(tsconfig, ts.sys.readFile);
     if (cfg.error)
         throw new Error(ts.flattenDiagnosticMessageText(cfg.error.messageText, "\n"));

package/docs/build-integrations.md

@@ -25,6 +25,45 @@ When a target call is found, the plugin creates a TypeScript program for the
 nearest `tsconfig.json`, runs the transformer, and returns the transformed code
 to Vite.
 
+The Vite plugin can also generate mapper documentation by convention:
+
+```ts
+export default defineConfig({
+  plugins: [
+    runtypex({
+      docs: {
+        include: "src/features/**/*.mapper.ts",
+      },
+    }),
+  ],
+});
+```
+
+For each included mapper file, runtypex finds declarations like:
+
+```ts
+export const addressMap = defineMap<
+  SearchAddressDto,
+  SearchAddressDomainSource
+>()({
+  id: source("RESULT.ID"),
+});
+```
+
+It generates `SearchAddressDomain` by removing the `Source` suffix and writes
+all generated interfaces for the same folder to `runtypex.generated.ts`.
+
+Docs options:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `include` | `**/*.mapper.ts`, `**/*.mapper.tsx` | Mapper files to scan, relative to the Vite root. |
+| `exclude` | generated file name | Files to skip. |
+| `sourceSuffix` | `Source` | Domain type suffix removed for the generated interface name. |
+| `generatedFileName` | `runtypex.generated.ts` | File written next to each mapper file. |
+| `outDir` | `near-source` | Currently only near-source generation is supported. |
+| `policyMode` | `warn` | Use `error` to fail when a mapper violates docs conventions. |
+
 ## ts-loader
 
 ```js

package/docs/jsdoc-generation.md

@@ -4,7 +4,28 @@ JSDoc generation creates interface documentation from mapper metadata. It helps
 editors show where a domain field came from and which DTO or database field it
 represents.
 
-## API
+## Vite Convention
+
+```ts
+import { defineConfig } from "vite";
+import { vitePlugin as runtypex } from "runtypex";
+
+export default defineConfig({
+  plugins: [
+    runtypex({
+      docs: {
+        include: "src/features/**/*.mapper.ts",
+      },
+    }),
+  ],
+});
+```
+
+The plugin finds `defineMap<TDto, TDomainSource>()(...)` calls in included mapper
+files, removes the `Source` suffix from `TDomainSource`, and writes generated
+interfaces to `runtypex.generated.ts` next to the mapper file.
+
+## Manual API
 
 ```ts
 import { generateJSDocFromSpec } from "runtypex/generator";
@@ -17,17 +38,25 @@ const source = generateJSDocFromSpec({
 });
 ```
 
-This API is intended for build tooling that already has access to the TypeScript
-program, checker, DTO type, domain type, and mapper spec node.
+This lower-level API is intended for build tooling that already has access to
+the TypeScript program, checker, DTO type, domain type, and mapper spec node.
 
-## Metadata Fields
+## Metadata Sources
 
-Mapper metadata can include:
+Domain field descriptions should live on the domain type:
+
+```ts
+interface User {
+  /** User id */
+  id: string;
+}
+```
+
+Mapper metadata can include source-specific details:
 
 ```ts
 source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
@@ -36,18 +65,26 @@ Field meanings:
 
 | Field | Meaning |
 | --- | --- |
-| `description` | Domain field description. Usually used as the first JSDoc sentence. |
-| `dtoDescription` | Optional explanation attached to the DTO path line. |
+| 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. |
 
+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
+the domain description is not duplicated per DTO mapping.
+
 ## Generated Output
 
-Given this domain field:
+Given this domain field and mapping:
 
 ```ts
+interface User {
+  /** User id */
+  id: string;
+}
+
 id: source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
@@ -58,7 +95,8 @@ the generated documentation can look like this:
 /**
  * User id
  *
- * DTO: UserDto.user_id Identifier returned by the user API.
+ * DTO: UserDto.user_id
+ *      Identifier returned by the user API.
  * DTO type: string
  * DB: users.user_id
  * Domain type: string
@@ -78,7 +116,7 @@ generateJSDocFromSpec({
   domainType,
   specNode,
   options: {
-    policy,
+    mappingPolicy: policy,
     policyMode: "error",
   },
 });

package/docs/mapper.md

@@ -77,13 +77,13 @@ Mapping rules can include metadata:
 ```ts
 id: source("user_id", {
   db: "users.user_id",
-  description: "User id",
   dtoDescription: "Identifier returned by the user API.",
 });
 ```
 
 Metadata is not required for mapping. It is mainly used by JSDoc generation and
-documentation tooling.
+documentation tooling. Keep domain field descriptions on the domain type JSDoc;
+mapper metadata should describe DTO/database-specific details.
 
 ## Typed Helpers
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runtypex",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Runtime type guards compiled from TypeScript types.",
   "license": "MIT",
   "author": "KumJungMin",