@ankhorage/paradox 0.0.4 → 0.0.6

package/dist/model/buildModel.d.ts

@@ -7,10 +7,43 @@ interface BuildModelInput {
         name: string;
         description: string | null;
         kind: ExportKind;
+        modulePath: string;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+        exportPaths: string[];
+        relatedSymbols: string[];
+        signatures: {
+            label: string;
+            parameters: {
+                name: string;
+                type: string;
+                required: boolean;
+                description: string | null;
+            }[];
+            returnType: string | null;
+            returnDescription: string | null;
+        }[];
+        members: {
+            name: string;
+            kind: 'property' | 'method';
+            type: string;
+            required: boolean;
+            description: string | null;
+        }[];
     }[];
     components: {
         name: string;
         description: string | null;
+        modulePath: string;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+        exportPaths: string[];
         props: {
             name: string;
             type: string;
@@ -28,6 +61,13 @@ interface BuildModelInput {
     config: {
         exportName: string;
     } | null;
+    entrypoints: string[];
+    modules: {
+        path: string;
+        isEntrypoint: boolean;
+        dependencies: string[];
+        exports: string[];
+    }[];
 }
 /***
  * Converts analysis output into a serializable documentation model.

package/dist/model/buildModel.js

@@ -2,7 +2,8 @@
  * Converts analysis output into a serializable documentation model.
  */
 export function buildModel(analysis) {
-    const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item)]));
+    const exportNames = new Set(analysis.exports.map((item) => item.name));
+    const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item, exportNames)]));
     const exports = sortByName([...exportsByName.values()]);
     return {
         packageName: analysis.packageName,
@@ -26,21 +27,65 @@ export function buildModel(analysis) {
                 ]),
             }
             : null,
+        entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
+        modules: [...analysis.modules]
+            .map((module) => ({
+            path: module.path,
+            isEntrypoint: module.isEntrypoint,
+            dependencies: [...module.dependencies].sort((a, b) => a.localeCompare(b)),
+            exports: [...module.exports].sort((a, b) => a.localeCompare(b)),
+        }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
-        components: sortByName(analysis.components.map(mapComponent)),
+        components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
     };
 }
-function mapExport(item) {
+function mapExport(item, exportNames) {
     return {
         name: item.name,
         description: item.description,
         kind: item.kind,
+        modulePath: item.modulePath,
+        sourceLocation: {
+            filePath: item.sourceLocation.filePath,
+            line: item.sourceLocation.line,
+            column: item.sourceLocation.column,
+        },
+        exportPaths: [...item.exportPaths].sort((a, b) => a.localeCompare(b)),
+        relatedSymbols: item.relatedSymbols
+            .filter((symbol) => exportNames.has(symbol))
+            .sort((a, b) => a.localeCompare(b)),
+        signatures: item.signatures.map((signature) => ({
+            label: signature.label,
+            parameters: sortByName(signature.parameters.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+                required: parameter.required,
+                description: parameter.description,
+            }))),
+            returnType: signature.returnType,
+            returnDescription: signature.returnDescription,
+        })),
+        members: sortByName(item.members.map((member) => ({
+            name: member.name,
+            kind: member.kind,
+            type: member.type,
+            required: member.required,
+            description: member.description,
+        }))),
     };
 }
-function mapComponent(component) {
+function mapComponent(component, exportModel) {
     return {
         name: component.name,
         description: component.description,
+        modulePath: component.modulePath,
+        sourceLocation: {
+            filePath: component.sourceLocation.filePath,
+            line: component.sourceLocation.line,
+            column: component.sourceLocation.column,
+        },
+        exportPaths: exportModel?.exportPaths ?? [...component.exportPaths].sort((a, b) => a.localeCompare(b)),
         props: sortByName(component.props.map((prop) => ({
             name: prop.name,
             type: prop.type,

package/dist/model/types.d.ts

@@ -7,6 +7,8 @@ export interface DocumentationModel {
     description: string | null;
     usage: UsageModel | null;
     config: ConfigModel | null;
+    entrypoints: string[];
+    modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
 }
@@ -27,13 +29,52 @@ export interface ExportModel {
     name: string;
     description: string | null;
     kind: ExportKind;
+    modulePath: string;
+    sourceLocation: SourceLocationModel;
+    exportPaths: string[];
+    relatedSymbols: string[];
+    signatures: SignatureModel[];
+    members: MemberModel[];
 }
 export type ExportKind = 'function' | 'type' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
+    modulePath: string;
+    sourceLocation: SourceLocationModel;
+    exportPaths: string[];
     props: PropModel[];
 }
+export interface SourceLocationModel {
+    filePath: string;
+    line: number;
+    column: number;
+}
+export interface SignatureModel {
+    label: string;
+    parameters: ParameterModel[];
+    returnType: string | null;
+    returnDescription: string | null;
+}
+export interface ParameterModel {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface MemberModel {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface ModuleModel {
+    path: string;
+    isEntrypoint: boolean;
+    dependencies: string[];
+    exports: string[];
+}
 export interface PropModel {
     name: string;
     type: string;

package/dist/render/render.d.ts

@@ -3,4 +3,6 @@ import type { RenderResult } from './types.js';
 /***
  * Renders the documentation model into README and artifact files.
  */
-export declare function render(model: DocumentationModel): RenderResult;
+export declare function render(model: DocumentationModel, options?: {
+    outputDir?: string;
+}): RenderResult;

package/dist/render/render.js

@@ -1,95 +1,29 @@
+import { renderDiagramArtifacts } from './renderers/diagrams.js';
+import { renderHtml } from './renderers/html.js';
+import { renderMarkdown } from './renderers/markdown.js';
 /***
  * Renders the documentation model into README and artifact files.
  */
-export function render(model) {
-    return {
-        readme: renderReadme(model),
-        exportsMarkdown: renderExports(model),
-        components: renderComponents(model),
+export function render(model, options = {}) {
+    const diagrams = renderDiagramArtifacts(model);
+    const outputDir = options.outputDir ?? 'paradox';
+    const result = {
+        readme: '',
+        exportsMarkdown: '',
+        components: '',
         exportsJson: `${JSON.stringify(model.exports, null, 2)}\n`,
         paradoxJson: `${JSON.stringify(model, null, 2)}\n`,
+        indexHtml: '',
+        diagrams,
     };
-}
-function renderReadme(model) {
-    const lines = [`# ${model.packageName}`, ''];
-    if (model.description) {
-        lines.push(model.description, '');
-    }
-    if (model.usage !== null) {
-        lines.push('## Usage', '');
-        lines.push('```bash');
-        for (const command of model.usage.commands) {
-            lines.push(command.command);
-        }
-        lines.push('```', '');
-    }
-    if (model.config !== null) {
-        lines.push('## Configuration', '');
-        lines.push(`Create a \`${model.config.configFile}\` file:`, '');
-        lines.push('```ts');
-        if (model.config.factoryName !== null) {
-            lines.push(`import { ${model.config.factoryName} } from '${model.packageId}';`);
-            lines.push('');
-            lines.push(`export default ${model.config.factoryName}({`);
-            lines.push('  // ...');
-            lines.push('});');
-        }
-        else {
-            lines.push(`import type { ${model.config.exportName} } from '${model.packageId}';`);
-            lines.push('');
-            lines.push('const config = {');
-            lines.push('  // ...');
-            lines.push(`} satisfies ${model.config.exportName};`);
-            lines.push('');
-            lines.push('export default config;');
-        }
-        lines.push('```', '');
-    }
-    lines.push('## Path resolution', '');
-    lines.push('- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).');
-    lines.push('- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.');
-    lines.push('- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.');
-    lines.push('- Modes:');
-    lines.push('  - `safe`: writes generated artifacts only under the output directory');
-    lines.push('  - `write`: additionally updates `<packageRoot>/README.md`', '');
-    if (model.exports.length > 0) {
-        lines.push('## Public API', '');
-        for (const item of model.exports) {
-            lines.push(`### ${item.name}`, '');
-            lines.push(item.description ?? `\`${item.kind}\` export.`, '');
-        }
-    }
-    return `${lines.join('\n').trimEnd()}\n`;
-}
-function renderExports(model) {
-    const lines = ['# Public API', ''];
-    for (const item of model.exports) {
-        lines.push(`## ${item.name}`, '');
-        lines.push(`Kind: \`${item.kind}\``, '');
-        if (item.description) {
-            lines.push(item.description, '');
-        }
-    }
-    return `${lines.join('\n').trimEnd()}\n`;
-}
-function renderComponents(model) {
-    const lines = ['# Components', ''];
-    for (const component of model.components) {
-        lines.push(`## ${component.name}`, '');
-        if (component.description) {
-            lines.push(component.description, '');
-        }
-        if (component.props.length > 0) {
-            lines.push('| Prop | Type | Required | Description |');
-            lines.push('| --- | --- | --- | --- |');
-            for (const prop of component.props) {
-                lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${escapeTableCell(prop.description ?? '')} |`);
-            }
-            lines.push('');
-        }
+    const context = {
+        model,
+        outputDir,
+        diagrams,
+        result,
+    };
+    for (const renderer of [renderMarkdown, renderHtml]) {
+        Object.assign(result, renderer(context));
     }
-    return `${lines.join('\n').trimEnd()}\n`;
-}
-function escapeTableCell(value) {
-    return value.replaceAll('|', '\\|');
+    return result;
 }

package/dist/render/renderers/diagrams.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentationModel } from '../../model/types.js';
+import type { DiagramArtifact } from '../types.js';
+/***
+ * Generates deterministic Mermaid diagrams for the documentation app.
+ */
+export declare function renderDiagramArtifacts(model: DocumentationModel): DiagramArtifact[];

package/dist/render/renderers/diagrams.js

@@ -0,0 +1,106 @@
+/***
+ * Generates deterministic Mermaid diagrams for the documentation app.
+ */
+export function renderDiagramArtifacts(model) {
+    return [
+        {
+            path: 'diagrams/architecture-overview.mmd',
+            title: 'Architecture overview',
+            content: renderArchitectureOverview(model),
+        },
+        {
+            path: 'diagrams/module-relationships.mmd',
+            title: 'Module relationships',
+            content: renderModuleRelationships(model),
+        },
+        {
+            path: 'diagrams/export-graph.mmd',
+            title: 'Export graph',
+            content: renderExportGraph(model),
+        },
+        {
+            path: 'diagrams/entrypoint-sequence.mmd',
+            title: 'Entrypoint sequence',
+            content: renderEntrypointSequence(model),
+        },
+    ];
+}
+function renderArchitectureOverview(model) {
+    const lines = ['graph TD'];
+    const packageId = toMermaidId(`package-${model.packageId}`);
+    lines.push(`  ${packageId}["${escapeLabel(model.packageName)}"]`);
+    for (const entrypoint of model.entrypoints) {
+        const entrypointId = toMermaidId(`entrypoint-${entrypoint}`);
+        lines.push(`  ${entrypointId}["${escapeLabel(entrypoint)}"]`);
+        lines.push(`  ${packageId} --> ${entrypointId}`);
+    }
+    for (const module of model.modules) {
+        const moduleId = toMermaidId(`module-${module.path}`);
+        lines.push(`  ${moduleId}["${escapeLabel(module.path)}"]`);
+        if (!module.isEntrypoint) {
+            lines.push(`  ${packageId} -.-> ${moduleId}`);
+        }
+        for (const dependency of module.dependencies) {
+            lines.push(`  ${moduleId} --> ${toMermaidId(`module-${dependency}`)}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderModuleRelationships(model) {
+    const lines = ['graph LR'];
+    for (const module of model.modules) {
+        lines.push(`  ${toMermaidId(`module-${module.path}`)}["${escapeLabel(module.path)}"]`);
+    }
+    const edges = model.modules.flatMap((module) => module.dependencies.map((dependency) => `  ${toMermaidId(`module-${module.path}`)} --> ${toMermaidId(`module-${dependency}`)}`));
+    lines.push(...(edges.length > 0 ? edges : renderFallbackEdge(model.modules, 'module')));
+    return `${lines.join('\n')}\n`;
+}
+function renderExportGraph(model) {
+    const lines = ['graph LR'];
+    const exportedNames = new Set(model.exports.map((item) => item.name));
+    for (const module of model.modules) {
+        lines.push(`  ${toMermaidId(`module-${module.path}`)}["${escapeLabel(module.path)}"]`);
+    }
+    for (const item of model.exports) {
+        const exportId = toMermaidId(`export-${item.name}`);
+        lines.push(`  ${exportId}["${escapeLabel(item.name)}"]`);
+        lines.push(`  ${toMermaidId(`module-${item.modulePath}`)} --> ${exportId}`);
+        for (const relatedSymbol of item.relatedSymbols.filter((symbol) => exportedNames.has(symbol))) {
+            lines.push(`  ${exportId} -.-> ${toMermaidId(`export-${relatedSymbol}`)}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderEntrypointSequence(model) {
+    const lines = ['sequenceDiagram'];
+    const participants = new Map();
+    for (const module of model.modules) {
+        participants.set(module.path, `participant ${toMermaidId(`participant-${module.path}`)} as ${module.path}`);
+    }
+    lines.push(...participants.values());
+    const interactions = model.modules.flatMap((module) => module.dependencies.map((dependency) => `  ${toMermaidId(`participant-${module.path}`)}->>${toMermaidId(`participant-${dependency}`)}: imports`));
+    if (interactions.length === 0) {
+        const packageId = toMermaidId(`participant-${model.packageId}`);
+        lines.push(`  participant ${packageId} as ${model.packageName}`);
+        lines.push(`  Note over ${packageId}: No internal module relationships detected.`);
+    }
+    else {
+        lines.push(...interactions);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function renderFallbackEdge(modules, prefix) {
+    if (modules.length === 0) {
+        return ['  empty["No modules analyzed"]'];
+    }
+    return modules.slice(1).map((module, index) => {
+        const previous = modules[index];
+        return `  ${toMermaidId(`${prefix}-${previous.path}`)} -.-> ${toMermaidId(`${prefix}-${module.path}`)}`;
+    });
+}
+function toMermaidId(value) {
+    return value.replace(/[^A-Za-z0-9_]/g, '_');
+}
+function escapeLabel(value) {
+    return value.replaceAll('"', '"');
+}

package/dist/render/renderers/html.d.ts

@@ -0,0 +1,5 @@
+import type { RenderContext } from '../types.js';
+/***
+ * Renders a deterministic static HTML documentation app.
+ */
+export declare function renderHtml({ diagrams, model, }: RenderContext): Pick<RenderContext['result'], 'indexHtml'>;