@ankhorage/paradox 0.0.10 → 0.1.1

package/dist/cli.js

@@ -5,6 +5,15 @@ import { buildModel } from './model/buildModel.js';
 import { findParadoxConfigFile, loadParadoxConfig, resolveOutputRoot, resolvePackageRoot, } from './paths/policy.js';
 import { render } from './render/render.js';
 import { write } from './write/write.js';
+/***
+ * Runs the Paradox CLI.
+ *
+ * The command discovers the nearest Paradox config, resolves the package and output roots,
+ * analyzes the package, builds the documentation model, renders all documentation artifacts,
+ * and writes them to the configured output directory.
+ *
+ * @readme
+ */
 async function main() {
     const cwd = process.cwd();
     const configFilePath = await findParadoxConfigFile(cwd);

package/dist/config/defineParadoxConfig.d.ts

@@ -1,5 +1,7 @@
 import type { ParadoxConfig } from './types.js';
 /***
  * Defines a Paradox configuration object without changing its shape.
+ *
+ * @readme
  */
 export declare function defineParadoxConfig(config: ParadoxConfig): ParadoxConfig;

package/dist/config/defineParadoxConfig.js

@@ -1,5 +1,7 @@
 /***
  * Defines a Paradox configuration object without changing its shape.
+ *
+ * @readme
  */
 export function defineParadoxConfig(config) {
     return config;

package/dist/config/types.d.ts

@@ -2,6 +2,7 @@
  * Configuration for running Paradox.
  *
  * @config
+ * @readme
  */
 export interface ParadoxConfig {
     mode?: 'safe' | 'write';

package/dist/model/buildModel.d.ts

@@ -1,4 +1,9 @@
 import type { DocumentationModel, ExportKind } from './types.js';
+interface ExampleInput {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 interface ExportMemberInput {
     name: string;
     kind: 'property' | 'method';
@@ -31,6 +36,8 @@ interface BuildModelInput {
     exports: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         kind: ExportKind;
         modulePath: string;
         sourceLocation: {
@@ -56,6 +63,8 @@ interface BuildModelInput {
     components: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         modulePath: string;
         sourceLocation: {
             filePath: string;
@@ -67,9 +76,18 @@ interface BuildModelInput {
             name: string;
             type: string;
             required: boolean;
+            defaultValue?: string;
             description: string | null;
         }[];
     }[];
+    sequenceScenarios: {
+        kind: 'bin' | 'export';
+        name: string;
+        sourcePath: string;
+        symbolName: string;
+        description: string | null;
+        isReadme: boolean;
+    }[];
     usage: {
         packageName: string;
         commands: {
@@ -79,6 +97,7 @@ interface BuildModelInput {
     } | null;
     config: {
         exportName: string;
+        isReadme: boolean;
         members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];

package/dist/model/buildModel.js

@@ -27,6 +27,7 @@ export function buildModel(analysis) {
         config: analysis.config !== null
             ? {
                 exportName: analysis.config.exportName,
+                isReadme: analysis.config.isReadme,
                 configFile: getDefaultConfigFileName(analysis.packageId),
                 factoryName: findConfigFactoryName(analysis.config.exportName, [
                     ...exportsByName.keys(),
@@ -45,6 +46,14 @@ export function buildModel(analysis) {
             .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
+        sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({
+            kind: scenario.kind,
+            name: scenario.name,
+            sourcePath: scenario.sourcePath,
+            symbolName: scenario.symbolName,
+            description: scenario.description,
+            isReadme: scenario.isReadme,
+        }))),
         graphs: {
             imports: [...analysis.graphs.imports],
             calls: [...analysis.graphs.calls],
@@ -57,6 +66,8 @@ function mapExport(item, exportNames) {
     return {
         name: item.name,
         description: item.description,
+        isReadme: item.isReadme,
+        examples: item.examples.map((example) => ({ ...example })),
         kind: item.kind,
         modulePath: item.modulePath,
         sourceLocation: {
@@ -95,6 +106,8 @@ function mapComponent(component, exportModel) {
     return {
         name: component.name,
         description: component.description,
+        isReadme: component.isReadme,
+        examples: component.examples.map((example) => ({ ...example })),
         modulePath: component.modulePath,
         sourceLocation: {
             filePath: component.sourceLocation.filePath,
@@ -106,6 +119,7 @@ function mapComponent(component, exportModel) {
             name: prop.name,
             type: prop.type,
             required: prop.required,
+            defaultValue: prop.defaultValue,
             description: prop.description,
         }))),
     };

package/dist/model/types.d.ts

@@ -12,6 +12,7 @@ export interface DocumentationModel {
     modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
+    sequenceScenarios: SequenceScenarioModel[];
     graphs: GraphModel;
 }
 export interface GeneratedBadge {
@@ -30,6 +31,7 @@ interface UsageCommandModel {
 }
 interface ConfigModel {
     exportName: string;
+    isReadme: boolean;
     configFile: string;
     factoryName: string | null;
     members: ConfigMemberModel[];
@@ -37,6 +39,8 @@ interface ConfigModel {
 export interface ExportModel {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: ExampleModel[];
     kind: ExportKind;
     modulePath: string;
     sourceLocation: SourceLocationModel;
@@ -49,11 +53,26 @@ export type ExportKind = 'function' | 'type' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: ExampleModel[];
     modulePath: string;
     sourceLocation: SourceLocationModel;
     exportPaths: string[];
     props: PropModel[];
 }
+export interface SequenceScenarioModel {
+    kind: 'bin' | 'export';
+    name: string;
+    sourcePath: string;
+    symbolName: string;
+    description: string | null;
+    isReadme: boolean;
+}
+interface ExampleModel {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 interface SourceLocationModel {
     filePath: string;
     line: number;
@@ -91,6 +110,7 @@ interface PropModel {
     name: string;
     type: string;
     required: boolean;
+    defaultValue?: string;
     description: string | null;
 }
 interface ConfigMemberModel {

package/dist/render/renderers/diagrams.js

@@ -1,3 +1,5 @@
+const MAX_SEQUENCE_CALL_EDGES = 12;
+const MAX_SEQUENCE_PARTICIPANTS = 8;
 /***
  * Generates deterministic Mermaid diagrams for the documentation app.
  */
@@ -18,11 +20,7 @@ export function renderDiagramArtifacts(model) {
             title: 'Export graph',
             content: renderExportGraph(model),
         },
-        {
-            path: 'diagrams/entrypoint-sequence.mmd',
-            title: 'Entrypoint sequence',
-            content: renderEntrypointSequence(model),
-        },
+        ...renderSequenceArtifacts(model),
     ];
 }
 function renderArchitectureOverview(model) {
@@ -71,34 +69,88 @@ function renderExportGraph(model) {
     }
     return `${lines.join('\n')}\n`;
 }
-function renderEntrypointSequence(model) {
+function renderSequenceArtifacts(model) {
+    return model.sequenceScenarios.flatMap((scenario) => {
+        const content = renderSequenceScenario(model, scenario);
+        if (content === null)
+            return [];
+        return [
+            {
+                path: `diagrams/sequences/${toFileStem(scenario.name)}.mmd`,
+                title: `${scenario.name} sequence`,
+                content,
+            },
+        ];
+    });
+}
+function renderSequenceScenario(model, scenario) {
     const lines = ['sequenceDiagram'];
-    const callEdges = model.graphs.calls;
-    if (callEdges.length > 0) {
-        const participants = new Map();
-        for (const edge of callEdges) {
-            participants.set(edge.fromSymbol, `participant ${toMermaidId(`participant-${edge.fromSymbol}`)} as ${edge.fromSymbol}`);
-            participants.set(edge.toSymbol, `participant ${toMermaidId(`participant-${edge.toSymbol}`)} as ${edge.toSymbol}`);
-        }
-        lines.push(...participants.values());
-        lines.push(...callEdges.map((edge) => `  ${toMermaidId(`participant-${edge.fromSymbol}`)}->>${toMermaidId(`participant-${edge.toSymbol}`)}: ${edge.callExpression}`));
-        return `${lines.join('\n')}\n`;
+    const reachableEdges = collectReachableCallEdges(model.graphs.calls, scenario.symbolName);
+    const participants = collectSequenceParticipants(reachableEdges);
+    if (reachableEdges.length === 0)
+        return null;
+    if (reachableEdges.length > MAX_SEQUENCE_CALL_EDGES ||
+        participants.length > MAX_SEQUENCE_PARTICIPANTS) {
+        return null;
     }
-    const participants = new Map();
-    for (const module of model.modules) {
-        participants.set(module.path, `participant ${toMermaidId(`participant-${module.path}`)} as ${module.path}`);
+    for (const participant of participants) {
+        lines.push(`  participant ${toMermaidId(`participant-${participant}`)} as ${escapeLabel(participant)}`);
     }
-    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.`);
+    renderCallFlow(lines, reachableEdges, scenario.symbolName);
+    return `${lines.join('\n')}\n`;
+}
+function collectReachableCallEdges(callEdges, root) {
+    const outgoing = groupCallsBySource(callEdges);
+    const visited = new Set();
+    const ordered = [];
+    visitCallEdges(root, outgoing, visited, ordered);
+    return ordered;
+}
+function visitCallEdges(fromSymbol, outgoing, visited, ordered) {
+    for (const edge of outgoing.get(fromSymbol) ?? []) {
+        const key = getCallEdgeKey(edge);
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        ordered.push(edge);
+        visitCallEdges(edge.toSymbol, outgoing, visited, ordered);
     }
-    else {
-        lines.push(...interactions);
+}
+function renderCallFlow(lines, callEdges, root) {
+    const outgoing = groupCallsBySource(callEdges);
+    const visited = new Set();
+    renderNestedCalls(lines, root, outgoing, visited);
+}
+function renderNestedCalls(lines, fromSymbol, outgoing, visited) {
+    for (const edge of outgoing.get(fromSymbol) ?? []) {
+        const key = getCallEdgeKey(edge);
+        if (visited.has(key))
+            continue;
+        visited.add(key);
+        const fromId = toMermaidId(`participant-${edge.fromSymbol}`);
+        const toId = toMermaidId(`participant-${edge.toSymbol}`);
+        lines.push(`  ${fromId}->>${toId}: ${formatCallLabel(edge.callExpression)}`);
+        renderNestedCalls(lines, edge.toSymbol, outgoing, visited);
+        lines.push(`  ${toId}-->>${fromId}: return`);
     }
-    return `${lines.join('\n')}\n`;
+}
+function groupCallsBySource(callEdges) {
+    const grouped = new Map();
+    for (const edge of callEdges) {
+        const existing = grouped.get(edge.fromSymbol) ?? [];
+        existing.push(edge);
+        grouped.set(edge.fromSymbol, existing);
+    }
+    return grouped;
+}
+function collectSequenceParticipants(callEdges) {
+    return uniqueSorted(callEdges.flatMap((edge) => [edge.fromSymbol, edge.toSymbol]));
+}
+function getCallEdgeKey(edge) {
+    return `${edge.fromSymbol}->${edge.toSymbol}@${edge.sourcePath}:${edge.callExpression}`;
+}
+function formatCallLabel(callExpression) {
+    return callExpression.endsWith(')') ? callExpression : `${callExpression}()`;
 }
 function renderFallbackEdge(modules, prefix) {
     if (modules.length === 0) {
@@ -109,6 +161,16 @@ function renderFallbackEdge(modules, prefix) {
         return `  ${toMermaidId(`${prefix}-${previous.path}`)} -.-> ${toMermaidId(`${prefix}-${module.path}`)}`;
     });
 }
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function toFileStem(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
 function toMermaidId(value) {
     return value.replace(/[^A-Za-z0-9_]/g, '_');
 }