runtypex 0.2.1 → 0.2.3

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,14 +96,14 @@ 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",
     dtoDescription: "User identifier from the user DTO.",
@@ -94,7 +112,7 @@ const userMap = defineMap<UserDto, User>()({
   isActive: transform("status", (value) => value === "ACTIVE"),
 });
 
-const toUser = makeMapper<UserDto, User>(userMap);
+const toUser = makeMapper<UserDto, UserSource>(userMap);
 ```
 
 ## Why runtypex?

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

@@ -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/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/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/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

@@ -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/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/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,8 +38,8 @@ 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 Sources
 
@@ -45,8 +66,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
@@ -74,11 +95,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;
 ```
@@ -95,7 +116,7 @@ generateJSDocFromSpec({
   domainType,
   specNode,
   options: {
-    policy,
+    mappingPolicy: policy,
     policyMode: "error",
   },
 });

package/package.json

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