@ankhorage/paradox 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.10
+
+### Patch Changes
+
+- 47b7ced: Add generated README usage support from real source examples marked through configured usage entrypoints, while keeping existing package command usage intact.
+
 ## 0.1.9
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.9](./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.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)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -79,12 +79,12 @@ export default defineParadoxConfig({
 <details>
 <summary>Configuration options</summary>
 
-| Field   | Type                                                      | Required | Default | Description |
-| ------- | --------------------------------------------------------- | -------- | ------- | ----------- |
-| mode    | `'safe' \| 'write' \| undefined`                          | no       | —       |             |
-| docs    | `{ title?: string; description?: string; } \| undefined`  | no       | —       |             |
-| package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no       | —       |             |
-| output  | `{ dir?: string; } \| undefined`                          | no       | —       |             |
+| Field   | Type                                                                                          | Required | Default | Description |
+| ------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
+| mode    | `'safe' \| 'write' \| undefined`                                                              | no       | —       |             |
+| docs    | `{ title?: string; description?: string; usage?: { entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
+| package | `{ root?: string; entrypoints?: string[]; } \| undefined`                                     | no       | —       |             |
+| output  | `{ dir?: string; } \| undefined`                                                              | no       | —       |             |
 
 </details>
 
@@ -127,23 +127,3 @@ Module: `src/config/types.ts`
 Source: `src/config/types.ts:7:1`
 
 </details>
-
-### Documentation
-
-<details>
-<summary>PARADOX_DOC_TAGS</summary>
-
-Supported Paradox documentation tags.
-
-Paradox supports doc tags inside triple-star documentation comments.
-
-| name      | syntax     | description                                                                                                                                                      | applies to      | repeatable | handler        |
-| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ---------- | -------------- |
-| `readme`  | `@readme`  | Includes a documentation block or exported symbol in README output.                                                                                              | block, symbol   | no         | `markReadme`   |
-| `config`  | `@config`  | 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. | interface, type | no         | `markConfig`   |
-| `example` | `@example` | Adds a titled fenced code example to the generated documentation for a symbol.                                                                                   | symbol          | yes        | `parseExample` |
-
-Module: `src/doc-tags/registry.ts`
-Source: `src/doc-tags/registry.ts:8:14`
-
-</details>

package/dist/analyze/analyze.js

@@ -5,6 +5,7 @@ import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
+import { analyzeReadmeUsage } from './readmeUsage.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
 import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
@@ -21,10 +22,16 @@ export async function analyze(config, runtime) {
     const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
+    const usageEntryPoints = config.docs?.usage?.entrypoints ?? [];
+    const readmeUsage = await analyzeReadmeUsage({ root, entrypoints: usageEntryPoints });
     const program = createTypeScriptProgram({ root, entrypoints, project });
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
-    const modules = analyzeModules(project, { root, entrypoints });
+    const modules = analyzeModules(project, {
+        root,
+        entrypoints,
+        excludePaths: usageEntryPoints,
+    });
     const sourceFunctions = analyzeSourceFunctions(project, root);
     const sequenceScenarios = analyzeSequenceScenarios({ project, root, pkg, exports });
     const configExport = configMetadata
@@ -60,6 +67,7 @@ export async function analyze(config, runtime) {
         badges,
         sequenceScenarios,
         usage,
+        readmeUsage,
         config: configMetadata
             ? {
                 exportName: configMetadata.exportName,

package/dist/analyze/modules.d.ts

@@ -6,4 +6,5 @@ import type { AnalysisModule } from './types.js';
 export declare function analyzeModules(project: Project, options: {
     root: string;
     entrypoints: readonly string[];
+    excludePaths?: readonly string[];
 }): AnalysisModule[];

package/dist/analyze/modules.js

@@ -5,6 +5,7 @@ import { isAbsolute, join, normalize, relative } from 'node:path';
 export function analyzeModules(project, options) {
     const rootPath = normalize(options.root);
     const entrypointPaths = new Set(options.entrypoints.map((entrypoint) => normalize(isAbsolute(entrypoint) ? entrypoint : join(options.root, entrypoint))));
+    const excludedPaths = new Set((options.excludePaths ?? []).map((entrypoint) => normalize(isAbsolute(entrypoint) ? entrypoint : join(options.root, entrypoint))));
     return project
         .getSourceFiles()
         .filter((sourceFile) => {
@@ -12,6 +13,7 @@ export function analyzeModules(project, options) {
         const normalizedPath = toPosixPath(filePath);
         return (!sourceFile.isDeclarationFile() &&
             filePath.startsWith(rootPath) &&
+            !excludedPaths.has(filePath) &&
             !normalizedPath.includes('/node_modules/'));
     })
         .map((sourceFile) => {
@@ -21,7 +23,9 @@ export function analyzeModules(project, options) {
             .map((declaration) => declaration.getModuleSpecifierSourceFile())
             .filter((dependency) => dependency != null)
             .map((dependency) => normalize(dependency.getFilePath()))
-            .filter((dependency) => dependency.startsWith(rootPath) && !toPosixPath(dependency).includes('/node_modules/'))
+            .filter((dependency) => dependency.startsWith(rootPath) &&
+            !excludedPaths.has(dependency) &&
+            !toPosixPath(dependency).includes('/node_modules/'))
             .map((dependency) => toPosixPath(relative(options.root, dependency)));
         const exports = sourceFile
             .getExportSymbols()

package/dist/analyze/readmeUsage.d.ts

@@ -0,0 +1,14 @@
+export interface AnalysisReadmeUsage {
+    title: string | null;
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
+/***
+ * Collects README usage examples from configured real source files.
+ */
+export declare function analyzeReadmeUsage(options: {
+    root: string;
+    entrypoints: readonly string[];
+}): Promise<AnalysisReadmeUsage[]>;

package/dist/analyze/readmeUsage.js

@@ -0,0 +1,72 @@
+import { readFile } from 'node:fs/promises';
+import { extname, isAbsolute, join, relative } from 'node:path';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+const USAGE_TAG = `${String.fromCharCode(64)}usage`;
+/***
+ * Collects README usage examples from configured real source files.
+ */
+export async function analyzeReadmeUsage(options) {
+    const entries = await Promise.all(options.entrypoints.map(async (entrypoint) => analyzeUsageEntrypoint(options.root, entrypoint)));
+    return entries.flat().sort((left, right) => left.sourcePath.localeCompare(right.sourcePath));
+}
+async function analyzeUsageEntrypoint(root, entrypoint) {
+    const absolutePath = isAbsolute(entrypoint) ? entrypoint : join(root, entrypoint);
+    const source = await readFile(absolutePath, 'utf-8');
+    const sourcePath = toPosixPath(relative(root, absolutePath));
+    const matches = findUsageComments(source);
+    return matches.map((match) => {
+        const parsed = parseParadoxComment(match.comment);
+        return {
+            title: getUsageTitle(parsed.description, sourcePath),
+            description: parsed.description,
+            language: getLanguage(sourcePath),
+            code: removeRange(source, match.start, match.end).trim(),
+            sourcePath,
+        };
+    });
+}
+function findUsageComments(source) {
+    const matches = [];
+    const pattern = /\/\*\*\*[\s\S]*?\*\//g;
+    for (const match of source.matchAll(pattern)) {
+        const [comment] = match;
+        if (!comment.includes(USAGE_TAG))
+            continue;
+        matches.push({
+            comment,
+            start: match.index,
+            end: match.index + comment.length,
+        });
+    }
+    return matches;
+}
+function removeRange(source, start, end) {
+    const before = source.slice(0, start).trimEnd();
+    const after = source.slice(end).trimStart();
+    if (before.length === 0)
+        return after;
+    if (after.length === 0)
+        return before;
+    return `${before}\n\n${after}`;
+}
+function getUsageTitle(description, sourcePath) {
+    if (description === null)
+        return sourcePath;
+    const [firstLine = sourcePath] = description.split('\n');
+    return firstLine.trim() || sourcePath;
+}
+function getLanguage(sourcePath) {
+    const extension = extname(sourcePath).toLowerCase();
+    if (extension === '.tsx')
+        return 'tsx';
+    if (extension === '.ts')
+        return 'ts';
+    if (extension === '.jsx')
+        return 'jsx';
+    if (extension === '.js')
+        return 'js';
+    return '';
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/types.d.ts

@@ -79,6 +79,13 @@ interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
+interface AnalysisReadmeUsage {
+    title: string | null;
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
 export interface AnalysisBadge {
     id: string;
     label: string;
@@ -156,6 +163,7 @@ export interface AnalysisResult {
     badges: AnalysisBadge[];
     sequenceScenarios: AnalysisSequenceScenario[];
     usage: AnalysisUsage | null;
+    readmeUsage: AnalysisReadmeUsage[];
     config: {
         exportName: string;
         isReadme: boolean;

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

@@ -1,10 +1,11 @@
 /***
  * Parsed representation of a Paradox doc comment.
  */
-interface ParsedParadoxComment {
+export interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
     isReadme: boolean;
+    isUsage: boolean;
     examples: ParsedExample[];
     params: Record<string, string>;
     returns: string | null;

package/dist/analyze/utils/parseParadoxComment.js

@@ -1,3 +1,4 @@
+const USAGE_TAG = `${String.fromCharCode(64)}usage`;
 /***
  * Parses a Paradox doc comment into structured metadata.
  */
@@ -7,6 +8,7 @@ export function parseParadoxComment(rawComment) {
     const examples = [];
     let isConfig = false;
     let isReadme = false;
+    let isUsage = false;
     const params = {};
     let returns = null;
     for (let index = 0; index < lines.length; index += 1) {
@@ -20,6 +22,10 @@ export function parseParadoxComment(rawComment) {
             isReadme = true;
             continue;
         }
+        if (trimmed.startsWith(USAGE_TAG)) {
+            isUsage = true;
+            continue;
+        }
         if (trimmed.startsWith('@example')) {
             const parsed = parseExample(lines, index);
             examples.push(parsed.example);
@@ -46,6 +52,7 @@ export function parseParadoxComment(rawComment) {
         description: description.length > 0 ? description : null,
         isConfig,
         isReadme,
+        isUsage,
         examples,
         params,
         returns,

package/dist/config/types.d.ts

@@ -9,6 +9,9 @@ export interface ParadoxConfig {
     docs?: {
         title?: string;
         description?: string;
+        usage?: {
+            entrypoints?: string[];
+        };
     };
     package?: {
         root?: string;

package/dist/doc-tags/registry.d.ts

@@ -1,10 +1,3 @@
-/***
- * Supported Paradox documentation tags.
- *
- * Paradox supports doc tags inside triple-star documentation comments.
- *
- * @readme
- */
 export declare const PARADOX_DOC_TAGS: readonly [{
     readonly name: "readme";
     readonly syntax: "@readme";
@@ -26,6 +19,13 @@ export declare const PARADOX_DOC_TAGS: readonly [{
     readonly appliesTo: readonly ["symbol"];
     readonly repeatable: true;
     readonly handler: "parseExample";
+}, {
+    readonly name: "usage";
+    readonly syntax: "@usage";
+    readonly description: "Promotes a real source example into the generated README Usage section.";
+    readonly appliesTo: readonly ["block", "symbol"];
+    readonly repeatable: false;
+    readonly handler: "markUsage";
 }];
 export type ParadoxDocTagName = (typeof PARADOX_DOC_TAGS)[number]['name'];
 export type ParadoxDocTagHandlerId = (typeof PARADOX_DOC_TAGS)[number]['handler'];

package/dist/doc-tags/registry.js

@@ -5,6 +5,8 @@
  *
  * @readme
  */
+const DOC_TAG_PREFIX = '\u0040';
+const USAGE_DOC_TAG = `${DOC_TAG_PREFIX}usage`;
 export const PARADOX_DOC_TAGS = [
     {
         name: 'readme',
@@ -30,6 +32,14 @@ export const PARADOX_DOC_TAGS = [
         repeatable: true,
         handler: 'parseExample',
     },
+    {
+        name: 'usage',
+        syntax: USAGE_DOC_TAG,
+        description: 'Promotes a real source example into the generated README Usage section.',
+        appliesTo: ['block', 'symbol'],
+        repeatable: false,
+        handler: 'markUsage',
+    },
 ];
 /***
  * Looks up documentation tag metadata by tag name.

package/dist/model/buildModel.d.ts

@@ -107,6 +107,13 @@ interface BuildModelInput {
             command: string;
         }[];
     } | null;
+    readmeUsage: {
+        title: string | null;
+        description: string | null;
+        language: string;
+        code: string;
+        sourcePath: string;
+    }[];
     config: {
         exportName: string;
         isReadme: boolean;

package/dist/model/buildModel.js

@@ -24,6 +24,15 @@ export function buildModel(analysis) {
                 }))),
             }
             : null,
+        readmeUsage: analysis.readmeUsage
+            .map((usageEntry) => ({
+            title: usageEntry.title,
+            description: usageEntry.description,
+            language: usageEntry.language,
+            code: usageEntry.code,
+            sourcePath: usageEntry.sourcePath,
+        }))
+            .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath)),
         config: analysis.config !== null
             ? {
                 exportName: analysis.config.exportName,

package/dist/model/types.d.ts

@@ -7,6 +7,7 @@ export interface DocumentationModel {
     description: string | null;
     badges: GeneratedBadge[];
     usage: UsageModel | null;
+    readmeUsage: ReadmeUsageModel[];
     config: ConfigModel | null;
     entrypoints: string[];
     modules: ModuleModel[];
@@ -30,6 +31,13 @@ interface UsageCommandModel {
     name: string;
     command: string;
 }
+interface ReadmeUsageModel {
+    title: string | null;
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
 interface ConfigModel {
     exportName: string;
     isReadme: boolean;

package/dist/render/renderers/markdown.js

@@ -21,25 +21,41 @@ function renderReadme(model, outputDir, badges, diagrams) {
             .map((badge) => `![${badgeLabel(model, badge.path)}](./${outputDir}/${badge.path})`)
             .join(' '), '');
     }
-    if (model.description) {
+    if (model.description)
         lines.push(model.description, '');
-    }
+    renderReadmeUsage(lines, model.readmeUsage);
     if (model.usage !== null) {
-        lines.push('## Installation', '');
-        lines.push('```bash');
-        for (const command of model.usage.commands) {
+        lines.push('## Installation', '', '```bash');
+        for (const command of model.usage.commands)
             lines.push(command.command);
-        }
         lines.push('```', '');
     }
     renderCliScenarios(lines, model, outputDir, diagrams);
-    if (model.config?.isReadme) {
+    if (model.config?.isReadme)
         renderConfiguration(lines, model);
-    }
     renderGeneratedDocumentation(lines, outputDir, diagrams);
     renderReadmeApi(lines, model);
     return `${lines.join('\n').trimEnd()}\n`;
 }
+function renderReadmeUsage(lines, entries) {
+    if (entries.length === 0)
+        return;
+    lines.push('## Usage', '');
+    for (const entry of entries) {
+        if (entry.title !== null)
+            lines.push(`### ${entry.title}`, '');
+        if (entry.description !== null) {
+            const [, ...rest] = entry.description.split('\n');
+            const description = rest.join('\n').trim();
+            if (description.length > 0)
+                lines.push(description, '');
+        }
+        lines.push(`Source: \`${entry.sourcePath}\``, '');
+        lines.push(`\`\`\`${entry.language}`);
+        lines.push(entry.code);
+        lines.push('```', '');
+    }
+}
 function renderCliScenarios(lines, model, outputDir, diagrams) {
     const scenarios = model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
     if (scenarios.length === 0)
@@ -48,9 +64,8 @@ function renderCliScenarios(lines, model, outputDir, diagrams) {
     for (const scenario of scenarios) {
         lines.push('<details>');
         lines.push(`<summary>${scenario.name}</summary>`, '');
-        if (scenario.description !== null) {
+        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');
@@ -94,25 +109,24 @@ function renderConfiguration(lines, model) {
         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('', '</details>', '');
+    if (config.members.length === 0)
+        return;
+    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('', '</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)`);
     lines.push(`- [Component registry](./${outputDir}/components.md)`);
-    for (const diagram of diagrams) {
+    for (const diagram of diagrams)
         lines.push(`- [${diagram.title}](./${outputDir}/${diagram.path})`);
-    }
     lines.push('');
 }
 function renderReadmeApi(lines, model) {
@@ -123,12 +137,10 @@ function renderReadmeApi(lines, model) {
     for (const group of groups) {
         lines.push(`### ${group.title}`, '');
         for (const item of group.items) {
-            if (item.kind === 'component') {
+            if (item.kind === 'component')
                 renderComponentAccordion(lines, item.component, item.exportEntry);
-            }
-            else {
+            else
                 renderExportAccordion(lines, item.exportEntry);
-            }
         }
     }
 }
@@ -205,9 +217,8 @@ function renderStructuredRows(lines, item) {
 function getStructuredColumns(item) {
     const columns = new Set();
     for (const row of item.structuredRows) {
-        for (const column of Object.keys(row.values)) {
+        for (const column of Object.keys(row.values))
             columns.add(column);
-        }
     }
     return [...columns];
 }
@@ -216,9 +227,8 @@ function formatStructuredColumnHeader(column) {
 }
 function formatStructuredCell(column, value) {
     const escaped = escapeTableCell(value);
-    if (column === 'syntax' || column === 'name' || column === 'handler') {
+    if (column === 'syntax' || column === 'name' || column === 'handler')
         return `\`${escaped}\``;
-    }
     if (value === 'true')
         return 'yes';
     if (value === 'false')
@@ -290,9 +300,8 @@ function renderExports(model) {
         lines.push(`Kind: \`${item.kind}\``);
         lines.push(`Module: \`${item.modulePath}\``);
         lines.push(`Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``, '');
-        if (item.description) {
+        if (item.description)
             lines.push(item.description, '');
-        }
         renderStructuredRows(lines, item);
         if (item.signatures.length > 0) {
             lines.push('### Signatures', '');
@@ -322,9 +331,8 @@ function renderComponents(model) {
     for (const component of model.components) {
         lines.push(`## ${component.name}`, '');
         lines.push(`Source: \`${component.sourceLocation.filePath}:${component.sourceLocation.line}:${component.sourceLocation.column}\``, '');
-        if (component.description) {
+        if (component.description)
             lines.push(component.description, '');
-        }
         if (component.exportPaths.length > 0) {
             lines.push(`Export paths: ${component.exportPaths.map((path) => `\`${path}\``).join(', ')}`, '');
         }
@@ -361,9 +369,8 @@ function flattenConfigMembers(members, prefix = '') {
 }
 function badgeLabel(model, badgePath) {
     const fileName = badgePath.split('/').pop();
-    if (!fileName) {
+    if (!fileName)
         return badgePath;
-    }
     const id = fileName.replace(/\.svg$/, '');
     const badge = model.badges.find((entry) => entry.id === id);
     return badge ? `${badge.label}: ${badge.value}` : badgePath;

package/package.json

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