@ankhorage/paradox 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.2
+
+### Patch Changes
+
+- 9dc0fd2: Add sequence diagram of bin script to README.md
+
+## 0.1.1
+
+### Patch Changes
+
+- 3a7c982: Render sequence diagrams from call flow instead of import topology.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.10](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.1](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -13,6 +13,59 @@ Deterministic documentation generator for TypeScript packages.
 bunx @ankhorage/paradox
 ```
 
+## CLI
+
+### paradox
+
+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.
+
+```bash
+bunx @ankhorage/paradox
+```
+
+<details>
+<summary>paradox sequence</summary>
+
+Diagram: [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
+
+```mermaid
+sequenceDiagram
+  participant participant_analyze as analyze
+  participant participant_buildModel as buildModel
+  participant participant_dirname as dirname
+  participant participant_findParadoxConfigFile as findParadoxConfigFile
+  participant participant_loadParadoxConfig as loadParadoxConfig
+  participant participant_main as main
+  participant participant_render as render
+  participant participant_resolveOutputRoot as resolveOutputRoot
+  participant participant_resolvePackageRoot as resolvePackageRoot
+  participant participant_write as write
+  participant_main->>participant_findParadoxConfigFile: findParadoxConfigFile()
+  participant_findParadoxConfigFile-->>participant_main: return
+  participant_main->>participant_dirname: dirname()
+  participant_dirname-->>participant_main: return
+  participant_main->>participant_loadParadoxConfig: loadParadoxConfig()
+  participant_loadParadoxConfig-->>participant_main: return
+  participant_main->>participant_resolvePackageRoot: resolvePackageRoot()
+  participant_resolvePackageRoot-->>participant_main: return
+  participant_main->>participant_resolveOutputRoot: resolveOutputRoot()
+  participant_resolveOutputRoot-->>participant_main: return
+  participant_main->>participant_analyze: analyze()
+  participant_analyze-->>participant_main: return
+  participant_main->>participant_buildModel: buildModel()
+  participant_buildModel-->>participant_main: return
+  participant_main->>participant_render: render()
+  participant_render-->>participant_main: return
+  participant_main->>participant_write: write()
+  participant_write-->>participant_main: return
+```
+
+</details>
+
 ## Documentation Tags
 
 <details>
@@ -68,7 +121,7 @@ export default defineParadoxConfig({
 - [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)
+- [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
 
 ## Architecture preview
 
@@ -90,6 +143,7 @@ graph TD
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_createTypeScriptProgram_ts
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_exports_ts
   module_src_analyze_analyze_ts --> module_src_analyze_semantic_graphs_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_sequenceScenarios_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
@@ -165,6 +219,13 @@ graph TD
   package__ankhorage_paradox -.-> module_src_analyze_semantic_tagRegistry_ts
   module_src_analyze_semantic_utils_ts["src/analyze/semantic/utils.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_semantic_utils_ts
+  module_src_analyze_sequenceScenarios_ts["src/analyze/sequenceScenarios.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_sequenceScenarios_ts
+  module_src_analyze_sequenceScenarios_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_sequenceScenarios_ts --> module_src_analyze_types_ts
+  module_src_analyze_sequenceScenarios_ts --> module_src_analyze_usage_ts
+  module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_sequenceScenarios_ts --> module_src_analyze_utils_parseParadoxComment_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/dist/analyze/analyze.js

@@ -8,6 +8,7 @@ import { createProject } from './project.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
+import { analyzeSequenceScenarios } from './sequenceScenarios.js';
 import { createUsageFromPackageJson } from './usage.js';
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
@@ -20,6 +21,7 @@ export async function analyze(config, runtime) {
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
     const modules = analyzeModules(project, { root, entrypoints });
+    const sequenceScenarios = analyzeSequenceScenarios({ project, root, pkg, exports });
     const configExport = configMetadata
         ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
         : null;
@@ -50,6 +52,7 @@ export async function analyze(config, runtime) {
         entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
         modules,
         badges,
+        sequenceScenarios,
         usage,
         config: configMetadata
             ? {

package/dist/analyze/sequenceScenarios.d.ts

@@ -0,0 +1,14 @@
+import { type Project } from 'ts-morph';
+import type { AnalysisExport, AnalysisSequenceScenario } from './types.js';
+import type { PackageJsonModel } from './usage.js';
+interface AnalyzeSequenceScenariosOptions {
+    project: Project;
+    root: string;
+    pkg: PackageJsonModel;
+    exports: readonly AnalysisExport[];
+}
+/***
+ * Finds scenario roots that can be rendered as sequence diagrams.
+ */
+export declare function analyzeSequenceScenarios({ project, root, pkg, exports, }: AnalyzeSequenceScenariosOptions): AnalysisSequenceScenario[];
+export {};

package/dist/analyze/sequenceScenarios.js

@@ -0,0 +1,174 @@
+import { isAbsolute, join, normalize } from 'node:path';
+import { Node as MorphNode, } from 'ts-morph';
+import { relativeToRoot, toPosixPath } from './semantic/utils.js';
+import { getParadoxComment } from './utils/getParadoxComment.js';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+/***
+ * Finds scenario roots that can be rendered as sequence diagrams.
+ */
+export function analyzeSequenceScenarios({ project, root, pkg, exports, }) {
+    return uniqueScenarios([
+        ...analyzeBinSequenceScenarios(project, root, pkg),
+        ...analyzeExportSequenceScenarios(exports),
+    ]);
+}
+function analyzeBinSequenceScenarios(project, root, pkg) {
+    return getBinEntries(pkg).flatMap((entry) => {
+        const sourceFile = resolveBinSourceFile(project, root, entry.targetPath);
+        if (!sourceFile)
+            return [];
+        const callableRoot = findTopLevelInvokedLocalCallable(sourceFile);
+        if (callableRoot === null)
+            return [];
+        return [
+            {
+                kind: 'bin',
+                name: entry.name,
+                sourcePath: relativeToRoot(root, sourceFile.getFilePath()),
+                symbolName: callableRoot.symbolName,
+                description: callableRoot.description,
+                isReadme: callableRoot.isReadme,
+            },
+        ];
+    });
+}
+function analyzeExportSequenceScenarios(exports) {
+    return exports.flatMap((entry) => {
+        if (entry.signatures.length === 0)
+            return [];
+        return [
+            {
+                kind: 'export',
+                name: entry.name,
+                sourcePath: entry.modulePath,
+                symbolName: entry.name,
+                description: entry.description,
+                isReadme: entry.isReadme,
+            },
+        ];
+    });
+}
+function getBinEntries(pkg) {
+    if (pkg.bin == null)
+        return [];
+    if (typeof pkg.bin === 'string') {
+        return [
+            {
+                name: getPackageBaseName(pkg.name),
+                targetPath: pkg.bin,
+            },
+        ];
+    }
+    return Object.entries(pkg.bin)
+        .map(([name, targetPath]) => ({ name, targetPath }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
+function resolveBinSourceFile(project, root, targetPath) {
+    for (const candidate of getBinSourceCandidates(targetPath)) {
+        const sourceFile = getSourceFileByRelativePath(project, root, candidate);
+        if (sourceFile)
+            return sourceFile;
+    }
+    return null;
+}
+function getBinSourceCandidates(targetPath) {
+    const normalized = toPosixPath(targetPath).replace(/^\.\//, '');
+    const candidates = [];
+    if (/^src\/.*\.tsx?$/.test(normalized)) {
+        candidates.push(normalized);
+    }
+    if (/^dist\/.*\.jsx?$/.test(normalized)) {
+        candidates.push(normalized.replace(/^dist\//, 'src/').replace(/\.jsx?$/, '.ts'));
+        candidates.push(normalized.replace(/^dist\//, 'src/').replace(/\.jsx?$/, '.tsx'));
+    }
+    if (/\.jsx?$/.test(normalized)) {
+        candidates.push(normalized.replace(/\.jsx?$/, '.ts'));
+        candidates.push(normalized.replace(/\.jsx?$/, '.tsx'));
+    }
+    return uniqueSorted(candidates);
+}
+function getSourceFileByRelativePath(project, root, relativePath) {
+    const absolutePath = normalize(isAbsolute(relativePath) ? relativePath : join(root, relativePath));
+    return project.getSourceFile(absolutePath) ?? null;
+}
+function findTopLevelInvokedLocalCallable(sourceFile) {
+    const candidates = [];
+    sourceFile.forEachDescendant((node) => {
+        if (!MorphNode.isCallExpression(node))
+            return;
+        if (isInsideCallable(node))
+            return;
+        const callableDeclaration = getLocalFunctionDeclarationForCall(sourceFile, node);
+        if (callableDeclaration !== null) {
+            candidates.push(callableDeclaration);
+        }
+    });
+    const uniqueCandidates = uniqueByFunctionName(candidates);
+    const declaration = uniqueCandidates.length === 1 ? uniqueCandidates[0] : undefined;
+    if (declaration === undefined)
+        return null;
+    const parsedComment = getParsedParadoxComment(declaration);
+    return {
+        symbolName: declaration.getName() ?? 'main',
+        description: parsedComment.description,
+        isReadme: parsedComment.isReadme,
+    };
+}
+function getParsedParadoxComment(declaration) {
+    const comment = getParadoxComment(declaration);
+    if (comment === null) {
+        return { description: null, isReadme: false };
+    }
+    const parsed = parseParadoxComment(comment);
+    return {
+        description: parsed.description,
+        isReadme: parsed.isReadme,
+    };
+}
+function getLocalFunctionDeclarationForCall(sourceFile, node) {
+    const expression = node.getExpression();
+    const symbol = expression.getSymbol() ?? expression.getType().getSymbol();
+    if (!symbol)
+        return null;
+    for (const declaration of symbol.getDeclarations()) {
+        if (declaration.getSourceFile().getFilePath() !== sourceFile.getFilePath())
+            continue;
+        if (!MorphNode.isFunctionDeclaration(declaration))
+            continue;
+        return declaration;
+    }
+    return null;
+}
+function isInsideCallable(node) {
+    return Boolean(node.getFirstAncestor((candidate) => MorphNode.isFunctionDeclaration(candidate) ||
+        MorphNode.isMethodDeclaration(candidate) ||
+        MorphNode.isFunctionExpression(candidate) ||
+        MorphNode.isArrowFunction(candidate) ||
+        MorphNode.isClassDeclaration(candidate)));
+}
+function getPackageBaseName(packageName) {
+    return packageName.split('/').pop() ?? packageName;
+}
+function uniqueScenarios(scenarios) {
+    const seen = new Set();
+    return scenarios.filter((scenario) => {
+        const key = `${scenario.kind}:${scenario.name}:${scenario.sourcePath}:${scenario.symbolName}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+function uniqueByFunctionName(declarations) {
+    const seen = new Set();
+    return declarations.filter((declaration) => {
+        const name = declaration.getName();
+        if (name === undefined || seen.has(name))
+            return false;
+        seen.add(name);
+        return true;
+    });
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}

package/dist/analyze/types.d.ts

@@ -87,6 +87,14 @@ export interface AnalysisModule {
     dependencies: string[];
     exports: string[];
 }
+export interface AnalysisSequenceScenario {
+    kind: 'bin' | 'export';
+    name: string;
+    sourcePath: string;
+    symbolName: string;
+    description: string | null;
+    isReadme: boolean;
+}
 interface AnalysisTypeMember {
     name: string;
     type: string;
@@ -136,6 +144,7 @@ export interface AnalysisResult {
     entrypoints: string[];
     modules: AnalysisModule[];
     badges: AnalysisBadge[];
+    sequenceScenarios: AnalysisSequenceScenario[];
     usage: AnalysisUsage | null;
     config: {
         exportName: string;

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/model/buildModel.d.ts

@@ -80,6 +80,14 @@ interface BuildModelInput {
             description: string | null;
         }[];
     }[];
+    sequenceScenarios: {
+        kind: 'bin' | 'export';
+        name: string;
+        sourcePath: string;
+        symbolName: string;
+        description: string | null;
+        isReadme: boolean;
+    }[];
     usage: {
         packageName: string;
         commands: {

package/dist/model/buildModel.js

@@ -46,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],

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 {
@@ -59,6 +60,14 @@ export interface ComponentModel {
     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;

package/dist/render/renderers/diagrams.js

@@ -1,3 +1,6 @@
+const MAX_SEQUENCE_CALL_EDGES = 12;
+const MAX_SEQUENCE_PARTICIPANTS = 8;
+const MAX_BIN_SEQUENCE_PARTICIPANTS = 12;
 /***
  * Generates deterministic Mermaid diagrams for the documentation app.
  */
@@ -18,11 +21,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,35 +70,117 @@ 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) {
+    if (scenario.kind === 'bin') {
+        return renderBinSequenceScenario(model, scenario);
+    }
+    return renderNestedSequenceScenario(model, scenario);
+}
+function renderBinSequenceScenario(model, scenario) {
+    const callEdges = collectDirectCallEdges(model.graphs.calls, scenario.symbolName);
+    const participants = collectSequenceParticipants(callEdges);
+    if (callEdges.length === 0)
+        return null;
+    if (participants.length > MAX_BIN_SEQUENCE_PARTICIPANTS)
+        return null;
     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`;
+    for (const participant of participants) {
+        lines.push(`  participant ${toMermaidId(`participant-${participant}`)} as ${escapeLabel(participant)}`);
     }
-    const participants = new Map();
-    for (const module of model.modules) {
-        participants.set(module.path, `participant ${toMermaidId(`participant-${module.path}`)} as ${module.path}`);
+    for (const edge of callEdges) {
+        const fromId = toMermaidId(`participant-${edge.fromSymbol}`);
+        const toId = toMermaidId(`participant-${edge.toSymbol}`);
+        lines.push(`  ${fromId}->>${toId}: ${formatCallLabel(edge.callExpression)}`);
+        lines.push(`  ${toId}-->>${fromId}: return`);
     }
-    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.`);
+    return `${lines.join('\n')}\n`;
+}
+function renderNestedSequenceScenario(model, scenario) {
+    const lines = ['sequenceDiagram'];
+    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;
     }
-    else {
-        lines.push(...interactions);
+    for (const participant of participants) {
+        lines.push(`  participant ${toMermaidId(`participant-${participant}`)} as ${escapeLabel(participant)}`);
     }
+    renderCallFlow(lines, reachableEdges, scenario.symbolName);
     return `${lines.join('\n')}\n`;
 }
+function collectDirectCallEdges(callEdges, root) {
+    return callEdges.filter((edge) => edge.fromSymbol === root);
+}
+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);
+    }
+}
+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`);
+    }
+}
+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) {
         return ['  empty["No modules analyzed"]'];
@@ -109,6 +190,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, '_');
 }

package/dist/render/renderers/markdown.js

@@ -32,6 +32,7 @@ function renderReadme(model, outputDir, badges, diagrams) {
         }
         lines.push('```', '');
     }
+    renderCliScenarios(lines, model, outputDir, diagrams);
     renderDocumentationTags(lines);
     if (model.config?.isReadme) {
         renderConfiguration(lines, model);
@@ -42,6 +43,37 @@ function renderReadme(model, outputDir, badges, diagrams) {
     renderReadmeApi(lines, model);
     return `${lines.join('\n').trimEnd()}\n`;
 }
+function renderCliScenarios(lines, model, outputDir, diagrams) {
+    const scenarios = model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
+    if (scenarios.length === 0)
+        return;
+    lines.push('## CLI', '');
+    for (const scenario of scenarios) {
+        lines.push(`### ${scenario.name}`, '');
+        if (scenario.description !== null) {
+            lines.push(scenario.description, '');
+        }
+        const command = model.usage?.commands.find((item) => item.name === scenario.name);
+        if (command !== undefined) {
+            lines.push('```bash');
+            lines.push(command.command);
+            lines.push('```', '');
+        }
+        const diagram = findScenarioDiagram(diagrams, scenario);
+        if (diagram !== undefined) {
+            lines.push('<details>');
+            lines.push(`<summary>${scenario.name} sequence</summary>`, '');
+            lines.push(`Diagram: [${diagram.title}](./${outputDir}/${diagram.path})`, '');
+            lines.push('```mermaid');
+            lines.push(diagram.content.trimEnd());
+            lines.push('```', '');
+            lines.push('</details>', '');
+        }
+    }
+}
+function findScenarioDiagram(diagrams, scenario) {
+    return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
+}
 function renderDocumentationTags(lines) {
     lines.push('## Documentation Tags', '');
     for (const tag of DOCUMENTATION_TAGS) {
@@ -325,6 +357,13 @@ function badgeLabel(model, badgePath) {
     const badge = model.badges.find((entry) => entry.id === id);
     return badge ? `${badge.label}: ${badge.value}` : badgePath;
 }
+function toFileStem(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}
 const CATEGORY_ORDER = [
     'Configuration',
     'Primitives',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {