@ankhorage/paradox 0.0.9 → 0.1.0

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,22 +20,26 @@ 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;
+    isReadme: boolean;
     configFile: string;
     factoryName: string | null;
+    members: ConfigMemberModel[];
 }
 export interface ExportModel {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: ExampleModel[];
     kind: ExportKind;
     modulePath: string;
     sourceLocation: SourceLocationModel;
@@ -47,34 +52,44 @@ 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 SourceLocationModel {
+interface ExampleModel {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
+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 +97,48 @@ export interface ModuleModel {
     dependencies: string[];
     exports: string[];
 }
-export interface PropModel {
+interface PropModel {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    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

@@ -9,7 +9,13 @@ export function renderMarkdown({ badges, diagrams, model, outputDir, }) {
     };
 }
 function renderReadme(model, outputDir, badges, diagrams) {
-    const lines = [`# ${model.packageName}`, ''];
+    const lines = [
+        '<!-- markdownlint-disable MD013 MD033 -->',
+        '<!-- This file is generated by Paradox. Do not edit manually. -->',
+        '',
+        `# ${model.packageName}`,
+        '',
+    ];
     if (badges.length > 0) {
         lines.push(badges
             .map((badge) => `![${badgeLabel(model, badge.path)}](./${outputDir}/${badge.path})`)
@@ -19,35 +25,68 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push(model.description, '');
     }
     if (model.usage !== null) {
-        lines.push('## Usage', '');
+        lines.push('## Installation', '');
         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;');
+    renderDocumentationTags(lines);
+    if (model.config?.isReadme) {
+        renderConfiguration(lines, model);
+    }
+    renderGeneratedDocumentation(lines, outputDir, diagrams);
+    renderArchitecturePreview(lines, diagrams);
+    renderPathResolution(lines);
+    renderReadmeApi(lines, model);
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderDocumentationTags(lines) {
+    lines.push('## Documentation Tags', '');
+    for (const tag of DOCUMENTATION_TAGS) {
+        lines.push('<details>');
+        lines.push(`<summary>@${tag.name}</summary>`, '');
+        lines.push(tag.description, '');
+        lines.push('</details>', '');
+    }
+}
+function renderConfiguration(lines, model) {
+    const { config } = model;
+    if (config === null)
+        return;
+    lines.push('## Configuration', '');
+    lines.push(`Create a \`${config.configFile}\` file:`, '');
+    lines.push('```ts');
+    if (config.factoryName !== null) {
+        lines.push(`import { ${config.factoryName} } from '${model.packageId}';`);
+        lines.push('');
+        lines.push(`export default ${config.factoryName}({`);
+        lines.push('  // ...');
+        lines.push('});');
+    }
+    else {
+        lines.push(`import type { ${config.exportName} } from '${model.packageId}';`);
+        lines.push('');
+        lines.push('const config = {');
+        lines.push('  // ...');
+        lines.push(`} satisfies ${config.exportName};`);
+        lines.push('');
+        lines.push('export default config;');
+    }
+    lines.push('```', '');
+    if (config.members.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Configuration options</summary>', '');
+        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'} | ${renderDefault(configMember.defaultValue)} | ${escapeTableCell(configMember.description ?? '')} |`);
         }
-        lines.push('```', '');
+        lines.push('', '</details>', '');
     }
+}
+function renderGeneratedDocumentation(lines, outputDir, diagrams) {
     lines.push('## Generated documentation', '');
     lines.push(`- [Interactive documentation app](./${outputDir}/index.html)`);
     lines.push(`- [Public API reference](./${outputDir}/exports.md)`);
@@ -56,12 +95,19 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push(`- [${diagram.title}](./${outputDir}/${diagram.path})`);
     }
     lines.push('');
+}
+function renderArchitecturePreview(lines, diagrams) {
     lines.push('## Architecture preview', '');
     if (diagrams.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Architecture overview</summary>', '');
         lines.push('```mermaid');
-        lines.push(diagrams[0].content.trimEnd());
+        lines.push(diagrams[0]?.content.trimEnd() ?? '');
         lines.push('```', '');
+        lines.push('</details>', '');
     }
+}
+function renderPathResolution(lines) {
     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.');
@@ -69,22 +115,131 @@ function renderReadme(model, outputDir, badges, diagrams) {
     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.`, '');
-            lines.push(`- Kind: \`${item.kind}\``);
-            lines.push(`- Module: \`${item.modulePath}\``);
-            lines.push(`- Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
-            lines.push(`- Export paths: ${item.exportPaths.map((path) => `\`${path}\``).join(', ')}`);
-            if (item.relatedSymbols.length > 0) {
-                lines.push(`- Related symbols: ${item.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`);
+}
+function renderReadmeApi(lines, model) {
+    const groups = getReadmeGroups(model);
+    if (groups.length === 0)
+        return;
+    lines.push('## Public API', '');
+    for (const group of groups) {
+        lines.push(`### ${group.title}`, '');
+        for (const item of group.items) {
+            if (item.kind === 'component') {
+                renderComponentAccordion(lines, item.component, item.exportEntry);
+            }
+            else {
+                renderExportAccordion(lines, item.exportEntry);
             }
-            lines.push('');
         }
     }
-    return `${lines.join('\n').trimEnd()}\n`;
+}
+function renderComponentAccordion(lines, component, exportEntry) {
+    lines.push('<details>');
+    lines.push(`<summary>${component.name}</summary>`, '');
+    renderSignature(lines, exportEntry);
+    if (component.description)
+        lines.push(component.description, '');
+    renderExamples(lines, component.examples);
+    if (exportEntry && exportEntry.relatedSymbols.length > 0) {
+        lines.push(`Related types: ${exportEntry.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`, '');
+    }
+    if (component.props.length > 0) {
+        lines.push('<details>');
+        lines.push('<summary>Props</summary>', '');
+        lines.push('| Prop | Type | Required | Default | Description |');
+        lines.push('| --- | --- | --- | --- | --- |');
+        for (const prop of component.props) {
+            lines.push(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${renderDefault(prop.defaultValue)} | ${escapeTableCell(prop.description ?? '')} |`);
+        }
+        lines.push('', '</details>', '');
+    }
+    lines.push('</details>', '');
+}
+function renderExportAccordion(lines, item) {
+    lines.push('<details>');
+    lines.push(`<summary>${item.name}</summary>`, '');
+    renderSignature(lines, item);
+    lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+    renderExamples(lines, item.examples);
+    lines.push(`Module: \`${item.modulePath}\``);
+    lines.push(`Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
+    if (item.relatedSymbols.length > 0) {
+        lines.push(`Related symbols: ${item.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`);
+    }
+    lines.push('', '</details>', '');
+}
+function renderSignature(lines, item) {
+    const signature = item?.signatures[0]?.label;
+    if (!signature)
+        return;
+    lines.push('```ts');
+    lines.push(`${item.name}${signature}`);
+    lines.push('```', '');
+}
+function renderExamples(lines, examples) {
+    for (const example of examples) {
+        if (example.title)
+            lines.push(`#### ${example.title}`, '');
+        lines.push(`\`\`\`${example.language ?? ''}`);
+        lines.push(example.code);
+        lines.push('```', '');
+    }
+}
+function getReadmeGroups(model) {
+    const exportsByName = new Map(model.exports.map((entry) => [entry.name, entry]));
+    const componentNames = new Set(model.components.map((component) => component.name));
+    const groups = new Map();
+    for (const component of model.components.filter((entry) => entry.isReadme)) {
+        addReadmeItem(groups, getReadmeCategory(component.modulePath, component.name), {
+            kind: 'component',
+            component,
+            exportEntry: exportsByName.get(component.name),
+        });
+    }
+    for (const item of model.exports.filter((entry) => entry.isReadme)) {
+        if (componentNames.has(item.name))
+            continue;
+        addReadmeItem(groups, getReadmeCategory(item.modulePath, item.name), {
+            kind: 'export',
+            exportEntry: item,
+        });
+    }
+    return CATEGORY_ORDER.flatMap((title) => {
+        const items = groups.get(title);
+        if (!items || items.length === 0)
+            return [];
+        return [{ title, items: sortReadmeItems(items) }];
+    });
+}
+function addReadmeItem(groups, title, item) {
+    const existing = groups.get(title) ?? [];
+    existing.push(item);
+    groups.set(title, existing);
+}
+function sortReadmeItems(items) {
+    return [...items].sort((left, right) => getReadmeItemName(left).localeCompare(getReadmeItemName(right)));
+}
+function getReadmeItemName(item) {
+    return item.kind === 'component' ? item.component.name : item.exportEntry.name;
+}
+function getReadmeCategory(modulePath, name) {
+    if (modulePath.includes('/config/'))
+        return 'Configuration';
+    if (modulePath.includes('/primitives/'))
+        return 'Primitives';
+    if (modulePath.includes('/components/'))
+        return 'Components';
+    if (modulePath.includes('/patterns/'))
+        return 'Patterns';
+    if (modulePath.includes('/layout/'))
+        return 'Layout';
+    if (modulePath.includes('/hooks/') || /^use[A-Z]/.test(name))
+        return 'Hooks';
+    if (modulePath.includes('/utils/'))
+        return 'Utilities';
+    if (modulePath.endsWith('types.ts') || modulePath.includes('/types/'))
+        return 'Types';
+    return 'Utilities';
 }
 function renderExports(model) {
     const lines = ['# Public API', ''];
@@ -131,10 +286,10 @@ function renderComponents(model) {
             lines.push(`Export paths: ${component.exportPaths.map((path) => `\`${path}\``).join(', ')}`, '');
         }
         if (component.props.length > 0) {
-            lines.push('| Prop | Type | Required | Description |');
-            lines.push('| --- | --- | --- | --- |');
+            lines.push('| Prop | Type | Required | Default | 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(`| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${prop.required ? 'yes' : 'no'} | ${renderDefault(prop.defaultValue)} | ${escapeTableCell(prop.description ?? '')} |`);
             }
             lines.push('');
         }
@@ -144,6 +299,23 @@ function renderComponents(model) {
 function escapeTableCell(value) {
     return value.replaceAll('|', '\\|');
 }
+function renderDefault(value) {
+    return value === undefined ? '—' : `\`${escapeTableCell(value)}\``;
+}
+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) {
@@ -153,3 +325,27 @@ function badgeLabel(model, badgePath) {
     const badge = model.badges.find((entry) => entry.id === id);
     return badge ? `${badge.label}: ${badge.value}` : badgePath;
 }
+const CATEGORY_ORDER = [
+    'Configuration',
+    'Primitives',
+    'Components',
+    'Patterns',
+    'Layout',
+    'Hooks',
+    'Utilities',
+    'Types',
+];
+const DOCUMENTATION_TAGS = [
+    {
+        name: 'readme',
+        description: 'Includes a documentation block or exported symbol in README output.',
+    },
+    {
+        name: 'config',
+        description: 'Marks a type or interface as part of the Paradox configuration model. `@config` alone does not imply README inclusion; use `@config` plus `@readme` for README output.',
+    },
+    {
+        name: 'example',
+        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.9",
+  "version": "0.1.0",
   "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"