@ankhorage/paradox 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.6
+
+### Patch Changes
+
+- 1a836cf: Generate a deterministic static documentation app with computed API metadata and Mermaid diagrams.
+
+  Paradox now emits an offline `paradox/index.html` documentation app, diagram artifacts, richer export metadata, function signature details, parameter and return descriptions, related symbols, and README links to the generated documentation outputs.
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -20,6 +20,124 @@ export default defineParadoxConfig({
 });
 ```
 
+## Generated documentation
+
+- [Interactive documentation app](./paradox/index.html)
+- [Public API reference](./paradox/exports.md)
+- [Component registry](./paradox/components.md)
+- [Architecture overview](./paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](./paradox/diagrams/module-relationships.mmd)
+- [Export graph](./paradox/diagrams/export-graph.mmd)
+- [Entrypoint sequence](./paradox/diagrams/entrypoint-sequence.mmd)
+
+## Architecture preview
+
+```mermaid
+graph TD
+  package__ankhorage_paradox["@ankhorage/paradox"]
+  entrypoint_src_index_ts["src/index.ts"]
+  package__ankhorage_paradox --> entrypoint_src_index_ts
+  module_src_analyze_analyze_ts["src/analyze/analyze.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_analyze_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_components_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_exports_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_modules_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_project_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_types_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
+  module_src_analyze_analyze_ts --> module_src_config_types_ts
+  module_src_analyze_components_ts["src/analyze/components.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_components_ts
+  module_src_analyze_components_ts --> module_src_analyze_types_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_getComponentPropsType_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_getPropsFromType_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_isReactComponent_ts
+  module_src_analyze_exports_ts["src/analyze/exports.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_exports_ts
+  module_src_analyze_exports_ts --> module_src_analyze_types_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_getExportMetadata_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_resolveExportSymbol_ts
+  module_src_analyze_modules_ts["src/analyze/modules.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_modules_ts
+  module_src_analyze_modules_ts --> module_src_analyze_types_ts
+  module_src_analyze_project_ts["src/analyze/project.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_project_ts
+  module_src_analyze_types_ts["src/analyze/types.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_types_ts
+  module_src_analyze_usage_ts["src/analyze/usage.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_usage_ts
+  module_src_analyze_usage_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getComponentPropsType_ts["src/analyze/utils/getComponentPropsType.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getComponentPropsType_ts
+  module_src_analyze_utils_getExportMetadata_ts["src/analyze/utils/getExportMetadata.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getExportMetadata_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_getParadoxComment_ts["src/analyze/utils/getParadoxComment.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getPropsFromType_ts["src/analyze/utils/getPropsFromType.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getPropsFromType_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_isReactComponent_ts["src/analyze/utils/isReactComponent.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_isReactComponent_ts
+  module_src_analyze_utils_parseParadoxComment_ts["src/analyze/utils/parseParadoxComment.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_resolveExportSymbol_ts["src/analyze/utils/resolveExportSymbol.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_resolveExportSymbol_ts
+  module_src_cli_ts["src/cli.ts"]
+  package__ankhorage_paradox -.-> module_src_cli_ts
+  module_src_cli_ts --> module_src_analyze_analyze_ts
+  module_src_cli_ts --> module_src_model_buildModel_ts
+  module_src_cli_ts --> module_src_paths_policy_ts
+  module_src_cli_ts --> module_src_render_render_ts
+  module_src_cli_ts --> module_src_write_write_ts
+  module_src_config_defineParadoxConfig_ts["src/config/defineParadoxConfig.ts"]
+  package__ankhorage_paradox -.-> module_src_config_defineParadoxConfig_ts
+  module_src_config_defineParadoxConfig_ts --> module_src_config_types_ts
+  module_src_config_types_ts["src/config/types.ts"]
+  package__ankhorage_paradox -.-> module_src_config_types_ts
+  module_src_index_ts["src/index.ts"]
+  module_src_model_buildModel_ts["src/model/buildModel.ts"]
+  package__ankhorage_paradox -.-> module_src_model_buildModel_ts
+  module_src_model_buildModel_ts --> module_src_model_types_ts
+  module_src_model_types_ts["src/model/types.ts"]
+  package__ankhorage_paradox -.-> module_src_model_types_ts
+  module_src_paths_policy_ts["src/paths/policy.ts"]
+  package__ankhorage_paradox -.-> module_src_paths_policy_ts
+  module_src_paths_policy_ts --> module_src_config_types_ts
+  module_src_render_render_ts["src/render/render.ts"]
+  package__ankhorage_paradox -.-> module_src_render_render_ts
+  module_src_render_render_ts --> module_src_model_types_ts
+  module_src_render_render_ts --> module_src_render_renderers_diagrams_ts
+  module_src_render_render_ts --> module_src_render_renderers_html_ts
+  module_src_render_render_ts --> module_src_render_renderers_markdown_ts
+  module_src_render_render_ts --> module_src_render_types_ts
+  module_src_render_renderers_diagrams_ts["src/render/renderers/diagrams.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_diagrams_ts
+  module_src_render_renderers_diagrams_ts --> module_src_model_types_ts
+  module_src_render_renderers_diagrams_ts --> module_src_render_types_ts
+  module_src_render_renderers_html_ts["src/render/renderers/html.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_html_ts
+  module_src_render_renderers_html_ts --> module_src_model_types_ts
+  module_src_render_renderers_html_ts --> module_src_render_types_ts
+  module_src_render_renderers_markdown_ts["src/render/renderers/markdown.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_markdown_ts
+  module_src_render_renderers_markdown_ts --> module_src_model_types_ts
+  module_src_render_renderers_markdown_ts --> module_src_render_types_ts
+  module_src_render_types_ts["src/render/types.ts"]
+  package__ankhorage_paradox -.-> module_src_render_types_ts
+  module_src_render_types_ts --> module_src_model_types_ts
+  module_src_write_write_ts["src/write/write.ts"]
+  package__ankhorage_paradox -.-> module_src_write_write_ts
+  module_src_write_write_ts --> module_src_config_types_ts
+  module_src_write_write_ts --> module_src_render_types_ts
+```
+
 ## Path resolution
 
 - Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
@@ -35,6 +153,17 @@ export default defineParadoxConfig({
 
 Defines a Paradox configuration object without changing its shape.
 
+- Kind: `function`
+- Module: `src/config/defineParadoxConfig.ts`
+- Source: `src/config/defineParadoxConfig.ts:6:1`
+- Export paths: `src/index.ts`
+- Related symbols: `ParadoxConfig`
+
 ### ParadoxConfig
 
 Configuration for running Paradox.
+
+- Kind: `type`
+- Module: `src/config/types.ts`
+- Source: `src/config/types.ts:6:1`
+- Export paths: `src/index.ts`

package/dist/analyze/analyze.js

@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
+import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
 import { createUsageFromPackageJson } from './usage.js';
 /***
@@ -18,12 +19,18 @@ export async function analyze(config, runtime) {
         entrypoints,
     });
     const components = analyzeComponents(exports);
+    const modules = analyzeModules(project, {
+        root,
+        entrypoints,
+    });
     return {
         packageName: config.docs?.title ?? pkg.name,
         packageId: pkg.name,
         description: config.docs?.description ?? pkg.description ?? null,
         exports,
         components,
+        entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
+        modules,
         usage,
         config: configMetadata,
     };

package/dist/analyze/components.js

@@ -14,6 +14,9 @@ export function analyzeComponents(exports) {
         components.push({
             name: e.name,
             description: e.description,
+            modulePath: e.modulePath,
+            sourceLocation: e.sourceLocation,
+            exportPaths: e.exportPaths,
             props,
         });
     }

package/dist/analyze/exports.js

@@ -1,4 +1,5 @@
-import { isAbsolute, join, normalize } from 'node:path';
+import { isAbsolute, join, normalize, relative } from 'node:path';
+import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
@@ -6,9 +7,10 @@ import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
  * Collects exported declarations from configured package entrypoints.
  */
 export function analyzeExports(project, options) {
-    const exports = [];
+    const exportsByName = new Map();
     let config = null;
     for (const sourceFile of getEntryPointSourceFiles(project, options)) {
+        const entrypointPath = toPosixPath(relative(options.root, sourceFile.getFilePath()));
         const exported = sourceFile.getExportSymbols();
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
@@ -16,22 +18,44 @@ export function analyzeExports(project, options) {
             const rawComment = getParadoxComment(decl);
             const parsed = rawComment
                 ? parseParadoxComment(rawComment)
-                : { description: null, isConfig: false };
+                : { description: null, isConfig: false, params: {}, returns: null };
+            const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
-                    exportName: resolved.getName(),
+                    exportName: name,
                 };
             }
-            exports.push({
-                name: resolved.getName(),
+            const metadata = getExportMetadata({
+                name,
                 node: decl,
-                description: parsed.description,
-                kind: inferKind(decl),
+                root: options.root,
+                entrypointPath,
+                symbol: resolved,
             });
+            const existing = exportsByName.get(name);
+            exportsByName.set(name, existing
+                ? {
+                    ...existing,
+                    description: existing.description ?? parsed.description,
+                    exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
+                    relatedSymbols: uniqueSorted([
+                        ...existing.relatedSymbols,
+                        ...metadata.relatedSymbols,
+                    ]),
+                    signatures: existing.signatures.length > 0 ? existing.signatures : metadata.signatures,
+                    members: existing.members.length > 0 ? existing.members : metadata.members,
+                }
+                : {
+                    name,
+                    node: decl,
+                    description: parsed.description,
+                    kind: inferKind(decl),
+                    ...metadata,
+                });
         }
     }
     return {
-        exports,
+        exports: [...exportsByName.values()],
         config,
     };
 }
@@ -50,3 +74,9 @@ function inferKind(node) {
         return 'type';
     return 'unknown';
 }
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/modules.d.ts

@@ -0,0 +1,9 @@
+import type { Project } from 'ts-morph';
+import type { AnalysisModule } from './types.js';
+/***
+ * Builds a deterministic module relationship graph for documentation renderers.
+ */
+export declare function analyzeModules(project: Project, options: {
+    root: string;
+    entrypoints: readonly string[];
+}): AnalysisModule[];

package/dist/analyze/modules.js

@@ -0,0 +1,44 @@
+import { isAbsolute, join, normalize, relative } from 'node:path';
+/***
+ * Builds a deterministic module relationship graph for documentation renderers.
+ */
+export function analyzeModules(project, options) {
+    const rootPath = normalize(options.root);
+    const entrypointPaths = new Set(options.entrypoints.map((entrypoint) => normalize(isAbsolute(entrypoint) ? entrypoint : join(options.root, entrypoint))));
+    return project
+        .getSourceFiles()
+        .filter((sourceFile) => {
+        const filePath = normalize(sourceFile.getFilePath());
+        const normalizedPath = toPosixPath(filePath);
+        return (!sourceFile.isDeclarationFile() &&
+            filePath.startsWith(rootPath) &&
+            !normalizedPath.includes('/node_modules/'));
+    })
+        .map((sourceFile) => {
+        const path = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const dependencies = sourceFile
+            .getImportDeclarations()
+            .map((declaration) => declaration.getModuleSpecifierSourceFile())
+            .filter((dependency) => dependency != null)
+            .map((dependency) => normalize(dependency.getFilePath()))
+            .filter((dependency) => dependency.startsWith(rootPath) && !toPosixPath(dependency).includes('/node_modules/'))
+            .map((dependency) => toPosixPath(relative(options.root, dependency)));
+        const exports = sourceFile
+            .getExportSymbols()
+            .map((symbol) => symbol.getName())
+            .sort((left, right) => left.localeCompare(right));
+        return {
+            path,
+            isEntrypoint: entrypointPaths.has(normalize(sourceFile.getFilePath())),
+            dependencies: uniqueSorted(dependencies),
+            exports: uniqueSorted(exports),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/types.d.ts

@@ -2,11 +2,41 @@ import type { Node } from 'ts-morph';
 /***
  * Describes one exported declaration discovered in a package.
  */
+export interface AnalysisSourceLocation {
+    filePath: string;
+    line: number;
+    column: number;
+}
+export interface AnalysisParameter {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface AnalysisSignature {
+    label: string;
+    parameters: AnalysisParameter[];
+    returnType: string | null;
+    returnDescription: string | null;
+}
+export interface AnalysisMember {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+}
 export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
     kind: 'function' | 'type' | 'unknown';
+    modulePath: string;
+    sourceLocation: AnalysisSourceLocation;
+    exportPaths: string[];
+    relatedSymbols: string[];
+    signatures: AnalysisSignature[];
+    members: AnalysisMember[];
 }
 /***
  * Describes one React component and its extracted props.
@@ -14,6 +44,9 @@ export interface AnalysisExport {
 export interface AnalysisComponent {
     name: string;
     description: string | null;
+    modulePath: string;
+    sourceLocation: AnalysisSourceLocation;
+    exportPaths: string[];
     props: {
         name: string;
         type: string;
@@ -29,6 +62,12 @@ export interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
+export interface AnalysisModule {
+    path: string;
+    isEntrypoint: boolean;
+    dependencies: string[];
+    exports: string[];
+}
 /***
  * Complete analysis output used to build the documentation model.
  */
@@ -38,6 +77,8 @@ export interface AnalysisResult {
     description: string | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];
+    entrypoints: string[];
+    modules: AnalysisModule[];
     usage: AnalysisUsage | null;
     config: {
         exportName: string;

package/dist/analyze/utils/getExportMetadata.d.ts

@@ -0,0 +1,12 @@
+import { Node, type Symbol as MorphSymbol } from 'ts-morph';
+import type { AnalysisExport } from '../types.js';
+/***
+ * Extracts computed metadata for an exported declaration.
+ */
+export declare function getExportMetadata(options: {
+    name: string;
+    node: Node;
+    root: string;
+    entrypointPath: string;
+    symbol: MorphSymbol;
+}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation'>;

package/dist/analyze/utils/getExportMetadata.js

@@ -0,0 +1,162 @@
+import { relative } from 'node:path';
+import { Node, } from 'ts-morph';
+import { getParadoxComment } from './getParadoxComment.js';
+import { parseParadoxComment } from './parseParadoxComment.js';
+/***
+ * Extracts computed metadata for an exported declaration.
+ */
+export function getExportMetadata(options) {
+    const modulePath = toPosixPath(relative(options.root, options.node.getSourceFile().getFilePath()));
+    const sourceLocation = getSourceLocation(options.node, options.root);
+    const signatures = getSignatures(options.symbol, options.node);
+    const members = getMembers(options.node);
+    const relatedSymbols = collectRelatedSymbols(options.name, signatures.flatMap((signature) => [
+        ...signature.parameters.map((parameter) => parameter.type),
+        signature.returnType,
+    ]), members.map((member) => member.type));
+    return {
+        modulePath,
+        sourceLocation,
+        exportPaths: [options.entrypointPath],
+        relatedSymbols,
+        signatures,
+        members,
+    };
+}
+function getSourceLocation(node, root) {
+    const sourceFile = node.getSourceFile();
+    const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
+    return {
+        filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+        line,
+        column,
+    };
+}
+function getSignatures(symbol, node) {
+    const parsed = readParadoxMetadata(node);
+    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns));
+    return uniqueBy(signatures.filter((signature) => signature.parameters.length > 0 ||
+        signature.returnType !== null ||
+        signature.returnDescription !== null), (signature) => signature.label);
+}
+function getSignature(declaration, params, returns) {
+    const normalizedParameters = declaration.getParameters().map((parameter) => {
+        const parameterDescription = params[parameter.getName()];
+        return {
+            name: parameter.getName(),
+            type: parameter.getType().getText(parameter),
+            required: !parameter.isOptional(),
+            description: parameterDescription ? parameterDescription.trim() : null,
+        };
+    });
+    const returnType = declaration.getReturnType().getText(declaration);
+    const parameterLabel = normalizedParameters
+        .map((parameter) => `${parameter.name}${parameter.required ? '' : '?'}: ${parameter.type}`)
+        .join(', ');
+    return {
+        label: `(${parameterLabel})${returnType === 'void' ? '' : ` => ${returnType}`}`,
+        parameters: normalizedParameters,
+        returnType,
+        returnDescription: returns,
+    };
+}
+function getMembers(node) {
+    if (getCallableNode(node) !== null)
+        return [];
+    return node
+        .getType()
+        .getProperties()
+        .map((property) => {
+        const [declaration] = property.getDeclarations();
+        const rawComment = getParadoxComment(declaration);
+        const parsed = rawComment
+            ? parseParadoxComment(rawComment)
+            : { description: null, isConfig: false, params: {}, returns: null };
+        return {
+            name: property.getName(),
+            kind: isMemberMethodDeclaration(declaration) ? 'method' : 'property',
+            type: property.getTypeAtLocation(declaration).getText(declaration),
+            required: !property.isOptional(),
+            description: parsed.description,
+        };
+    });
+}
+function getCallableDeclarations(symbol, node) {
+    const declarations = symbol
+        .getDeclarations()
+        .map((declaration) => getCallableNode(declaration))
+        .filter((declaration) => declaration !== null);
+    if (declarations.length > 0) {
+        return declarations;
+    }
+    const callableNode = getCallableNode(node);
+    return callableNode !== null ? [callableNode] : [];
+}
+function getCallableNode(node) {
+    if (Node.isFunctionDeclaration(node))
+        return node;
+    if (Node.isMethodDeclaration(node))
+        return node;
+    if (Node.isMethodSignature(node))
+        return node;
+    if (Node.isArrowFunction(node))
+        return node;
+    if (Node.isFunctionExpression(node))
+        return node;
+    if (Node.isVariableDeclaration(node)) {
+        const initializer = node.getInitializer();
+        if (initializer &&
+            (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))) {
+            return initializer;
+        }
+    }
+    return null;
+}
+function isMemberMethodDeclaration(node) {
+    return Node.isMethodDeclaration(node) || Node.isMethodSignature(node);
+}
+function readParadoxMetadata(node) {
+    const rawComment = getParadoxComment(node);
+    return rawComment
+        ? parseParadoxComment(rawComment)
+        : { description: null, isConfig: false, params: {}, returns: null };
+}
+function collectRelatedSymbols(exportName, ...values) {
+    const candidates = values.flatMap((entries) => entries).filter((entry) => entry !== null);
+    const related = new Set();
+    for (const value of candidates) {
+        for (const symbol of value.matchAll(/\b[A-Z][A-Za-z0-9_]*\b/g)) {
+            const [candidate] = symbol;
+            if (!IGNORED_RELATED_SYMBOLS.has(candidate) && candidate !== exportName) {
+                related.add(candidate);
+            }
+        }
+    }
+    return [...related].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}
+function uniqueBy(items, key) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const itemKey = key(item);
+        if (seen.has(itemKey))
+            return false;
+        seen.add(itemKey);
+        return true;
+    });
+}
+const IGNORED_RELATED_SYMBOLS = new Set([
+    'Array',
+    'Boolean',
+    'Date',
+    'Element',
+    'JSX',
+    'Map',
+    'Promise',
+    'ReadonlyArray',
+    'Record',
+    'Set',
+    'String',
+]);

package/dist/analyze/utils/getPropsFromType.js

@@ -8,7 +8,9 @@ export function getPropsFromType(type) {
         const [declaration] = property.getDeclarations();
         const propertyType = property.getTypeAtLocation(declaration);
         const rawComment = getParadoxComment(declaration);
-        const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+        const parsed = rawComment
+            ? parseParadoxComment(rawComment)
+            : { description: null, isConfig: false, params: {}, returns: null };
         return {
             name: property.getName(),
             type: propertyType.getText(declaration),

package/dist/analyze/utils/parseParadoxComment.d.ts

@@ -4,6 +4,8 @@
 interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
+    params: Record<string, string>;
+    returns: string | null;
 }
 /***
  * Parses a Paradox doc comment into structured metadata.

package/dist/analyze/utils/parseParadoxComment.js

@@ -8,12 +8,28 @@ export function parseParadoxComment(rawComment) {
         .split('\n')
         .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
     let isConfig = false;
+    const params = {};
+    let returns = null;
     const description = lines
         .filter((line) => {
-        if (line.trimStart().startsWith('@config')) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('@config')) {
             isConfig = true;
             return false;
         }
+        if (trimmed.startsWith('@param ')) {
+            const paramBody = trimmed.slice('@param '.length).trim();
+            const [name, ...descriptionParts] = paramBody.split(/\s+/);
+            if (name) {
+                params[name] = descriptionParts.join(' ').trim();
+            }
+            return false;
+        }
+        if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
+            const returnBody = trimmed.replace(/^@returns?/, '').trim();
+            returns = returnBody.length > 0 ? returnBody : null;
+            return false;
+        }
         return true;
     })
         .join('\n')
@@ -21,5 +37,7 @@ export function parseParadoxComment(rawComment) {
     return {
         description: description.length > 0 ? description : null,
         isConfig,
+        params,
+        returns,
     };
 }

package/dist/cli.js

@@ -14,10 +14,10 @@ async function main() {
     const configDir = dirname(configFilePath);
     const config = await loadParadoxConfig(configFilePath);
     const packageRoot = await resolvePackageRoot(config, configDir);
-    const { outputRoot } = resolveOutputRoot(config, packageRoot);
+    const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
     const analysis = await analyze(config, { packageRoot });
     const model = buildModel(analysis);
-    const result = render(model);
+    const result = render(model, { outputDir });
     await write(result, config, { packageRoot, outputRoot });
 }
 main().catch((error) => {