@ankhorage/paradox 0.0.9 → 0.0.10

package/dist/analyze/semantic/model.d.ts

@@ -0,0 +1,109 @@
+import type { Node, Project, SourceFile, Symbol, Type, TypeChecker } from 'ts-morph';
+export interface AnalyzedProgram {
+    project: Project;
+    typeChecker: TypeChecker;
+    root: string;
+    entrypoints: string[];
+    entrypointFilePaths: string[];
+}
+export interface AnalyzedFile {
+    path: string;
+    sourceFile: SourceFile;
+    isEntrypoint: boolean;
+}
+export interface AnalyzedDocBlock {
+    id: string;
+    sourcePath: string;
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+    raw: string;
+    description: string | null;
+    params: Record<string, string>;
+    returns: string | null;
+    tags: AnalyzedTag[];
+}
+export interface AnalyzedTag {
+    name: string;
+    value: string | null;
+}
+export type AnalyzedExportKind = 'function' | 'component' | 'class' | 'interface' | 'type' | 'const' | 'hook' | 'unknown';
+export interface AnalyzedExport {
+    name: string;
+    sourcePath: string;
+    exportPaths: string[];
+    kind: AnalyzedExportKind;
+    signature?: string;
+    docBlock?: AnalyzedDocBlock;
+    tags: AnalyzedTag[];
+    props?: AnalyzedProps;
+    typeMembers?: AnalyzedTypeMember[];
+    relatedTypes: string[];
+    node: Node;
+    symbol: Symbol;
+}
+export interface ResolvedTypeReference {
+    type: Type;
+    name: string | null;
+    sourcePath: string | null;
+    symbol: Symbol | null;
+}
+export interface AnalyzedProps {
+    typeName: string;
+    sourcePath: string | null;
+    members: AnalyzedProp[];
+}
+export interface AnalyzedProp {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    description?: string;
+    inheritedFrom?: string;
+}
+export interface AnalyzedTypeMember {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalyzedTypeMember[];
+}
+export interface ImportEdge {
+    fromPath: string;
+    toPath: string;
+    sourcePath: string;
+}
+export interface CallEdge {
+    fromSymbol: string;
+    toSymbol: string;
+    callExpression: string;
+    sourcePath: string;
+}
+interface TypeReferenceEdge {
+    fromSymbol: string;
+    toType: string;
+    sourcePath: string;
+}
+export interface ComponentCompositionEdge {
+    fromComponent: string;
+    toComponent: string;
+    jsxElement: string;
+    sourcePath: string;
+}
+interface AnalyzedGraphs {
+    imports: ImportEdge[];
+    calls: CallEdge[];
+    typeReferences: TypeReferenceEdge[];
+    componentComposition: ComponentCompositionEdge[];
+}
+export interface AnalyzedProject {
+    files: AnalyzedFile[];
+    exports: AnalyzedExport[];
+    docBlocks: AnalyzedDocBlock[];
+    tags: AnalyzedTag[];
+    graphs: AnalyzedGraphs;
+}
+export {};

package/dist/analyze/semantic/model.js

@@ -0,0 +1 @@
+export {};

package/dist/analyze/semantic/paradoxComment.d.ts

@@ -0,0 +1,16 @@
+import type { Node } from 'ts-morph';
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export declare function getParadoxComment(node: Node | undefined): string | null;
+interface ParsedParadoxComment {
+    description: string | null;
+    isConfig: boolean;
+    params: Record<string, string>;
+    returns: string | null;
+}
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export declare function parseParadoxComment(rawComment: string): ParsedParadoxComment;
+export {};

package/dist/analyze/semantic/paradoxComment.js

@@ -0,0 +1,64 @@
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export function getParadoxComment(node) {
+    if (!node)
+        return null;
+    const sourceFile = node.getSourceFile();
+    const text = sourceFile.getFullText();
+    const nodeStart = node.getStart(false);
+    const beforeNode = text.slice(0, nodeStart);
+    const commentStart = beforeNode.lastIndexOf('/***');
+    if (commentStart === -1)
+        return null;
+    const commentEnd = text.indexOf('*/', commentStart);
+    if (commentEnd === -1 || commentEnd > nodeStart)
+        return null;
+    const between = text.slice(commentEnd + 2, nodeStart);
+    if (!/^[\s;]*(export\s+)?(default\s+)?$/.test(between))
+        return null;
+    return text.slice(commentStart, commentEnd + 2);
+}
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export function parseParadoxComment(rawComment) {
+    const lines = rawComment
+        .replace(/^\/\*\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+    let isConfig = false;
+    const params = {};
+    let returns = null;
+    const description = lines
+        .filter((line) => {
+        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')
+        .trim();
+    return {
+        description: description.length > 0 ? description : null,
+        isConfig,
+        params,
+        returns,
+    };
+}

package/dist/analyze/semantic/tagRegistry.d.ts

@@ -0,0 +1,2 @@
+export type TagRegistry = ReadonlySet<string>;
+export declare const defaultTagRegistry: TagRegistry;

package/dist/analyze/semantic/tagRegistry.js

@@ -0,0 +1 @@
+export const defaultTagRegistry = new Set(['readme', 'config']);

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

@@ -0,0 +1,4 @@
+export declare function toPosixPath(path: string): string;
+export declare function relativeToRoot(root: string, filePath: string): string;
+export declare function isPathInsideRoot(root: string, filePath: string): boolean;
+export declare function isNodeModulePath(filePath: string): boolean;

package/dist/analyze/semantic/utils.js

@@ -0,0 +1,13 @@
+import { normalize, relative } from 'node:path';
+export function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}
+export function relativeToRoot(root, filePath) {
+    return toPosixPath(relative(root, filePath));
+}
+export function isPathInsideRoot(root, filePath) {
+    return normalize(filePath).startsWith(normalize(root));
+}
+export function isNodeModulePath(filePath) {
+    return toPosixPath(filePath).includes('/node_modules/');
+}

package/dist/analyze/types.d.ts

@@ -25,6 +25,9 @@ export interface AnalysisMember {
     type: string;
     required: boolean;
     description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalysisMember[];
 }
 export interface AnalysisExport {
     name: string;
@@ -58,7 +61,7 @@ export interface AnalysisUsage {
     packageName: string;
     commands: AnalysisUsageCommand[];
 }
-export interface AnalysisUsageCommand {
+interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
@@ -74,6 +77,43 @@ export interface AnalysisModule {
     dependencies: string[];
     exports: string[];
 }
+interface AnalysisTypeMember {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalysisTypeMember[];
+}
+interface ImportEdge {
+    fromPath: string;
+    toPath: string;
+    sourcePath: string;
+}
+interface CallEdge {
+    fromSymbol: string;
+    toSymbol: string;
+    callExpression: string;
+    sourcePath: string;
+}
+interface TypeReferenceEdge {
+    fromSymbol: string;
+    toType: string;
+    sourcePath: string;
+}
+interface ComponentCompositionEdge {
+    fromComponent: string;
+    toComponent: string;
+    jsxElement: string;
+    sourcePath: string;
+}
+interface AnalysisGraphs {
+    imports: ImportEdge[];
+    calls: CallEdge[];
+    typeReferences: TypeReferenceEdge[];
+    componentComposition: ComponentCompositionEdge[];
+}
 /***
  * Complete analysis output used to build the documentation model.
  */
@@ -89,5 +129,8 @@ export interface AnalysisResult {
     usage: AnalysisUsage | null;
     config: {
         exportName: string;
+        members: AnalysisTypeMember[];
     } | null;
+    graphs: AnalysisGraphs;
 }
+export {};

package/dist/model/buildModel.d.ts

@@ -1,4 +1,23 @@
 import type { DocumentationModel, ExportKind } from './types.js';
+interface ExportMemberInput {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: ExportMemberInput[];
+}
+interface ConfigMemberInput {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: ConfigMemberInput[];
+}
 interface BuildModelInput {
     packageName: string;
     packageId: string;
@@ -32,13 +51,7 @@ interface BuildModelInput {
             returnType: string | null;
             returnDescription: string | null;
         }[];
-        members: {
-            name: string;
-            kind: 'property' | 'method';
-            type: string;
-            required: boolean;
-            description: string | null;
-        }[];
+        members: ExportMemberInput[];
     }[];
     components: {
         name: string;
@@ -66,6 +79,7 @@ interface BuildModelInput {
     } | null;
     config: {
         exportName: string;
+        members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];
     modules: {
@@ -74,6 +88,30 @@ interface BuildModelInput {
         dependencies: string[];
         exports: string[];
     }[];
+    graphs: {
+        imports: {
+            fromPath: string;
+            toPath: string;
+            sourcePath: string;
+        }[];
+        calls: {
+            fromSymbol: string;
+            toSymbol: string;
+            callExpression: string;
+            sourcePath: string;
+        }[];
+        typeReferences: {
+            fromSymbol: string;
+            toType: string;
+            sourcePath: string;
+        }[];
+        componentComposition: {
+            fromComponent: string;
+            toComponent: string;
+            jsxElement: string;
+            sourcePath: string;
+        }[];
+    };
 }
 /***
  * Converts analysis output into a serializable documentation model.

package/dist/model/buildModel.js

@@ -31,6 +31,7 @@ export function buildModel(analysis) {
                 factoryName: findConfigFactoryName(analysis.config.exportName, [
                     ...exportsByName.keys(),
                 ]),
+                members: analysis.config.members,
             }
             : null,
         entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
@@ -44,6 +45,12 @@ 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)))),
+        graphs: {
+            imports: [...analysis.graphs.imports],
+            calls: [...analysis.graphs.calls],
+            typeReferences: [...analysis.graphs.typeReferences],
+            componentComposition: [...analysis.graphs.componentComposition],
+        },
     };
 }
 function mapExport(item, exportNames) {
@@ -78,6 +85,9 @@ function mapExport(item, exportNames) {
             type: member.type,
             required: member.required,
             description: member.description,
+            defaultValue: member.defaultValue,
+            inheritedFrom: member.inheritedFrom,
+            children: member.children,
         }))),
     };
 }

package/dist/model/types.d.ts

@@ -12,6 +12,7 @@ export interface DocumentationModel {
     modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
+    graphs: GraphModel;
 }
 export interface GeneratedBadge {
     id: string;
@@ -19,18 +20,19 @@ export interface GeneratedBadge {
     value: string;
     color: string;
 }
-export interface UsageModel {
+interface UsageModel {
     packageName: string;
     commands: UsageCommandModel[];
 }
-export interface UsageCommandModel {
+interface UsageCommandModel {
     name: string;
     command: string;
 }
-export interface ConfigModel {
+interface ConfigModel {
     exportName: string;
     configFile: string;
     factoryName: string | null;
+    members: ConfigMemberModel[];
 }
 export interface ExportModel {
     name: string;
@@ -52,29 +54,32 @@ export interface ComponentModel {
     exportPaths: string[];
     props: PropModel[];
 }
-export interface SourceLocationModel {
+interface SourceLocationModel {
     filePath: string;
     line: number;
     column: number;
 }
-export interface SignatureModel {
+interface SignatureModel {
     label: string;
     parameters: ParameterModel[];
     returnType: string | null;
     returnDescription: string | null;
 }
-export interface ParameterModel {
+interface ParameterModel {
     name: string;
     type: string;
     required: boolean;
     description: string | null;
 }
-export interface MemberModel {
+interface MemberModel {
     name: string;
     kind: 'property' | 'method';
     type: string;
     required: boolean;
     description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: MemberModel[];
 }
 export interface ModuleModel {
     path: string;
@@ -82,9 +87,47 @@ export interface ModuleModel {
     dependencies: string[];
     exports: string[];
 }
-export interface PropModel {
+interface PropModel {
     name: string;
     type: string;
     required: boolean;
     description: string | null;
 }
+interface ConfigMemberModel {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: ConfigMemberModel[];
+}
+interface GraphModel {
+    imports: ImportEdgeModel[];
+    calls: CallEdgeModel[];
+    typeReferences: TypeReferenceEdgeModel[];
+    componentComposition: ComponentCompositionEdgeModel[];
+}
+interface ImportEdgeModel {
+    fromPath: string;
+    toPath: string;
+    sourcePath: string;
+}
+interface CallEdgeModel {
+    fromSymbol: string;
+    toSymbol: string;
+    callExpression: string;
+    sourcePath: string;
+}
+interface TypeReferenceEdgeModel {
+    fromSymbol: string;
+    toType: string;
+    sourcePath: string;
+}
+interface ComponentCompositionEdgeModel {
+    fromComponent: string;
+    toComponent: string;
+    jsxElement: string;
+    sourcePath: string;
+}
+export {};

package/dist/paths/policy.d.ts

@@ -1,12 +1,4 @@
 import type { ParadoxConfig } from '../config/types.js';
-export interface ResolvedRuntimePaths {
-    cwd: string;
-    configFilePath: string;
-    configDir: string;
-    packageRoot: string;
-    outputDir: string;
-    outputRoot: string;
-}
 export declare function findParadoxConfigFile(startDir: string): Promise<string | null>;
 export declare function loadParadoxConfig(configFilePath: string): Promise<ParadoxConfig>;
 export declare function resolvePackageRoot(config: ParadoxConfig, configDir: string): Promise<string>;
@@ -14,10 +6,3 @@ export declare function resolveOutputRoot(config: ParadoxConfig, packageRoot: st
     outputDir: string;
     outputRoot: string;
 };
-export declare function resolveWriteTargets(packageRoot: string, outputRoot: string): {
-    exportsMarkdown: string;
-    componentsMarkdown: string;
-    exportsJson: string;
-    paradoxJson: string;
-    readme: string;
-};

package/dist/paths/policy.js

@@ -48,15 +48,6 @@ export function resolveOutputRoot(config, packageRoot) {
     assertWithinRoot(outputRoot, packageRoot, `Resolved output directory escapes package root: ${outputRoot}`);
     return { outputDir, outputRoot };
 }
-export function resolveWriteTargets(packageRoot, outputRoot) {
-    return {
-        exportsMarkdown: join(outputRoot, 'exports.md'),
-        componentsMarkdown: join(outputRoot, 'components.md'),
-        exportsJson: join(outputRoot, 'exports.json'),
-        paradoxJson: join(outputRoot, 'paradox.json'),
-        readme: join(packageRoot, 'README.md'),
-    };
-}
 async function pathExists(path) {
     try {
         await access(path);

package/dist/render/renderers/diagrams.js

@@ -73,6 +73,17 @@ function renderExportGraph(model) {
 }
 function renderEntrypointSequence(model) {
     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 participants = new Map();
     for (const module of model.modules) {
         participants.set(module.path, `participant ${toMermaidId(`participant-${module.path}`)} as ${module.path}`);

package/dist/render/renderers/markdown.js

@@ -26,27 +26,37 @@ function renderReadme(model, outputDir, badges, diagrams) {
         }
         lines.push('```', '');
     }
-    if (model.config !== null) {
+    const { config } = model;
+    if (config !== null) {
         lines.push('## Configuration', '');
-        lines.push(`Create a \`${model.config.configFile}\` file:`, '');
+        lines.push(`Create a \`${config.configFile}\` file:`, '');
         lines.push('```ts');
-        if (model.config.factoryName !== null) {
-            lines.push(`import { ${model.config.factoryName} } from '${model.packageId}';`);
+        if (config.factoryName !== null) {
+            lines.push(`import { ${config.factoryName} } from '${model.packageId}';`);
             lines.push('');
-            lines.push(`export default ${model.config.factoryName}({`);
+            lines.push(`export default ${config.factoryName}({`);
             lines.push('  // ...');
             lines.push('});');
         }
         else {
-            lines.push(`import type { ${model.config.exportName} } from '${model.packageId}';`);
+            lines.push(`import type { ${config.exportName} } from '${model.packageId}';`);
             lines.push('');
             lines.push('const config = {');
             lines.push('  // ...');
-            lines.push(`} satisfies ${model.config.exportName};`);
+            lines.push(`} satisfies ${config.exportName};`);
             lines.push('');
             lines.push('export default config;');
         }
         lines.push('```', '');
+        if (config.members.length > 0) {
+            lines.push('### Configuration options', '');
+            lines.push('| Field | Type | Required | Default | Description |');
+            lines.push('| --- | --- | --- | --- | --- |');
+            for (const configMember of flattenConfigMembers(config.members)) {
+                lines.push(`| ${escapeTableCell(configMember.path)} | \`${escapeTableCell(configMember.type)}\` | ${configMember.required ? 'yes' : 'no'} | ${escapeTableCell(configMember.defaultValue ?? '')} | ${escapeTableCell(configMember.description ?? '')} |`);
+            }
+            lines.push('');
+        }
     }
     lines.push('## Generated documentation', '');
     lines.push(`- [Interactive documentation app](./${outputDir}/index.html)`);
@@ -144,6 +154,20 @@ function renderComponents(model) {
 function escapeTableCell(value) {
     return value.replaceAll('|', '\\|');
 }
+function flattenConfigMembers(members, prefix = '') {
+    return members.flatMap((member) => {
+        const path = prefix ? `${prefix}.${member.name}` : member.name;
+        const current = {
+            path,
+            type: member.type,
+            required: member.required,
+            description: member.description,
+            defaultValue: member.defaultValue,
+        };
+        const children = member.children ? flattenConfigMembers(member.children, path) : [];
+        return [current, ...children];
+    });
+}
 function badgeLabel(model, badgePath) {
     const fileName = badgePath.split('/').pop();
     if (!fileName) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -14,6 +14,14 @@
     "type": "git",
     "url": "git+https://github.com/ankhorage/paradox.git"
   },
+  "keywords": [
+    "typescript",
+    "documentation",
+    "readme-generator",
+    "static-analysis",
+    "ts-morph",
+    "developer-tools"
+  ],
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -39,10 +47,11 @@
     "changeset:status": "changeset status --since=origin/main",
     "docs": "bun src/cli.ts",
     "docs:bunx": "bunx @ankhorage/paradox",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
-    "lint": "eslint . --max-warnings=0",
-    "lint:fix": "eslint . --fix --max-warnings=0",
+    "format": "ankhorage-prettier --write .",
+    "format:check": "ankhorage-prettier --check .",
+    "knip": "ankhorage-knip",
+    "lint": "ankhorage-eslint . --max-warnings=0",
+    "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
     "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
@@ -52,7 +61,7 @@
     "ts-morph": "^24.0.0"
   },
   "devDependencies": {
-    "@ankhorage/devtools": "^1.0.0",
+    "@ankhorage/devtools": "^1.0.5",
     "@changesets/cli": "^2.31.0",
     "@types/bun": "^1.3.13",
     "typescript": "^5.6.3"