@ankhorage/paradox 0.1.27 → 0.2.1

package/dist/render/renderers/markdown.js

@@ -8,6 +8,9 @@ export function renderMarkdown({ badges, diagrams, model, outputDir, }) {
         components: renderComponents(model),
     };
 }
+/***
+ * Renders the generated package README.
+ */
 function renderReadme(model, outputDir, badges, diagrams) {
     const lines = [
         '<!-- markdownlint-disable MD013 MD033 -->',
@@ -23,77 +26,67 @@ function renderReadme(model, outputDir, badges, diagrams) {
     }
     if (model.description)
         lines.push(model.description, '');
-    renderReadmeUsage(lines, model.readmeUsageDescription, model.readmeUsage);
-    renderReadmeCli(lines, model, outputDir, diagrams);
+    renderUsage(lines, model);
     renderConfiguration(lines, model);
     renderGeneratedDocumentation(lines, outputDir, diagrams);
     renderReadmeApi(lines, model);
     return `${lines.join('\n').trimEnd()}\n`;
 }
-function renderReadmeUsage(lines, description, entries) {
-    if (description === null && entries.length === 0)
-        return;
+/***
+ * Renders the canonical CLI-first Usage chapter.
+ */
+function renderUsage(lines, model) {
+    const readmeExample = model.usageEntries.find((entry) => entry.area === 'examples' && entry.isReadme);
     lines.push('## Usage', '');
-    if (description !== null)
-        lines.push(description, '');
-    for (const entry of entries) {
-        if (entry.title !== null)
-            lines.push(`### ${entry.title}`, '');
-        if (entry.description !== null) {
-            const [, ...rest] = entry.description.split('\n');
-            const entryDescription = rest.join('\n').trim();
-            if (entryDescription.length > 0)
-                lines.push(entryDescription, '');
-        }
-        lines.push(`Source: \`${entry.sourcePath}\``, '');
-        lines.push(`\`\`\`${entry.language}`);
-        lines.push(entry.code);
-        lines.push('```', '');
-    }
-}
-function renderReadmeCli(lines, model, outputDir, diagrams) {
-    if (model.readmeCli === null)
+    lines.push('### CLI', '');
+    lines.push('Ankhorage packages expose their command-line interface through `ankh`. Use `ankh --help` to discover available package commands, or run a package command with `--help` for package-specific usage.', '');
+    lines.push('```zsh');
+    lines.push('# Install the Ankhorage CLI');
+    lines.push('bun add --global @ankhorage/ankh', '');
+    lines.push(`# Show usage information for ${getPackageDisplayName(model.packageId)}`);
+    lines.push(model.usage.command);
+    lines.push('```', '');
+    if (readmeExample === undefined)
         return;
-    lines.push('## CLI', '');
-    if (model.readmeCli.description !== null)
-        lines.push(model.readmeCli.description, '');
-    if (model.usage !== null && model.usage.commands.length > 0) {
-        lines.push('```bash');
-        for (const command of model.usage.commands)
-            lines.push(command.command);
-        lines.push('```', '');
-    }
-    const scenarios = model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin');
-    for (const scenario of scenarios) {
-        const diagram = findScenarioDiagram(diagrams, scenario);
-        if (scenario.description === null && diagram === undefined)
-            continue;
-        lines.push('<details>');
-        lines.push(`<summary>${scenario.name}</summary>`, '');
-        if (scenario.description !== null)
-            lines.push(scenario.description, '');
-        if (diagram !== undefined) {
-            lines.push(`Diagram: [${diagram.title}](./${outputDir}/${diagram.path})`, '');
-            lines.push('```mermaid');
-            lines.push(diagram.content.trimEnd());
-            lines.push('```', '');
-        }
-        lines.push('</details>', '');
+    lines.push(`### ${readmeExample.title ?? 'Programmatic Usage'}`, '');
+    if (readmeExample.description !== null)
+        lines.push(readmeExample.description, '');
+    renderReferences(lines, readmeExample);
+    lines.push('```' + readmeExample.language);
+    lines.push(readmeExample.code);
+    lines.push('```', '');
+    if (model.exampleCount > 1) {
+        const additionalExamples = model.exampleCount - 1;
+        const label = additionalExamples === 1 ? 'example' : 'examples';
+        lines.push(`This package contains ${additionalExamples} additional ${label}. See the generated documentation for the complete set.`, '');
     }
 }
-function findScenarioDiagram(diagrams, scenario) {
-    return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
+/***
+ * Returns a human-readable package command name.
+ */
+function getPackageDisplayName(packageId) {
+    return packageId.split('/').pop() ?? packageId;
 }
+/***
+ * Renders the canonical Configuration chapter from the tagged schema plus concrete config instance.
+ */
 function renderConfiguration(lines, model) {
     const config = model.config?.isReadme ? model.config : null;
     const example = model.readmeConfig;
     if (config === null && example === null)
         return;
     lines.push('## Configuration', '');
+    if (config !== null) {
+        if (config.title !== null && config.title !== 'Configuration') {
+            lines.push(`### ${config.title}`, '');
+        }
+        if (config.description !== null)
+            lines.push(config.description, '');
+        renderReferences(lines, config);
+    }
     if (example !== null) {
-        if (example.description !== null)
-            lines.push(example.description, '');
-        lines.push(`\`\`\`${example.language}`);
+        lines.push('### Example', '');
+        lines.push('```' + example.language);
         lines.push(example.code);
         lines.push('```', '');
     }
@@ -108,15 +101,33 @@ function renderConfiguration(lines, model) {
     }
     lines.push('', '</details>', '');
 }
+/***
+ * Renders links and security evidence owned by one documented item.
+ */
+function renderReferences(lines, metadata) {
+    if (metadata.see.length > 0) {
+        lines.push(`See also: ${metadata.see.map((url) => `[${url}](${url})`).join(', ')}`, '');
+    }
+    if (metadata.security.length > 0) {
+        lines.push(`Security tests: ${metadata.security.map((reference) => `\`${reference}\``).join(', ')}`, '');
+    }
+}
+/***
+ * Renders links to generated documentation artifacts.
+ */
 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('');
 }
+/***
+ * Renders README-promoted public API entries.
+ */
 function renderReadmeApi(lines, model) {
     const groups = getReadmeGroups(model);
     if (groups.length === 0)
@@ -125,20 +136,25 @@ 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);
+            }
         }
     }
 }
+/***
+ * Renders one README-promoted component.
+ */
 function renderComponentAccordion(lines, component, exportEntry) {
     lines.push('<details>');
-    lines.push(`<summary>${component.name}</summary>`, '');
+    lines.push(`<summary>${exportEntry?.title ?? component.name}</summary>`, '');
     renderSignature(lines, exportEntry);
     if (component.description)
         lines.push(component.description, '');
-    renderExamples(lines, component.examples);
+    renderReferences(lines, component);
     if (exportEntry && exportEntry.relatedSymbols.length > 0) {
         lines.push(`Related types: ${exportEntry.relatedSymbols.map((symbol) => `\`${symbol}\``).join(', ')}`, '');
     }
@@ -154,13 +170,16 @@ function renderComponentAccordion(lines, component, exportEntry) {
     }
     lines.push('</details>', '');
 }
+/***
+ * Renders one README-promoted non-component export.
+ */
 function renderExportAccordion(lines, item) {
     lines.push('<details>');
-    lines.push(`<summary>${item.name}</summary>`, '');
+    lines.push(`<summary>${item.title ?? item.name}</summary>`, '');
     renderSignature(lines, item);
     lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+    renderReferences(lines, item);
     renderStructuredRows(lines, item);
-    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) {
@@ -168,6 +187,9 @@ function renderExportAccordion(lines, item) {
     }
     lines.push('', '</details>', '');
 }
+/***
+ * Renders the primary signature for a README public API entry.
+ */
 function renderSignature(lines, item) {
     const signature = item?.signatures[0]?.label;
     if (!signature)
@@ -176,15 +198,9 @@ function renderSignature(lines, item) {
     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('```', '');
-    }
-}
+/***
+ * Renders structured const-array rows as a Markdown table.
+ */
 function renderStructuredRows(lines, item) {
     if (item.structuredRows.length === 0)
         return;
@@ -202,6 +218,9 @@ function renderStructuredRows(lines, item) {
     }
     lines.push('');
 }
+/***
+ * Returns stable structured-row columns.
+ */
 function getStructuredColumns(item) {
     const columns = new Set();
     for (const row of item.structuredRows) {
@@ -210,9 +229,15 @@ function getStructuredColumns(item) {
     }
     return [...columns];
 }
+/***
+ * Formats one structured-row column header.
+ */
 function formatStructuredColumnHeader(column) {
     return escapeTableCell(column.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase());
 }
+/***
+ * Formats one structured-row table cell.
+ */
 function formatStructuredCell(column, value) {
     const escaped = escapeTableCell(value);
     if (column === 'syntax' || column === 'name' || column === 'handler')
@@ -223,6 +248,9 @@ function formatStructuredCell(column, value) {
         return 'no';
     return escaped;
 }
+/***
+ * Groups README-promoted API entries by presentation category.
+ */
 function getReadmeGroups(model) {
     const exportsByName = new Map(model.exports.map((entry) => [entry.name, entry]));
     const componentNames = new Set(model.components.map((component) => component.name));
@@ -244,22 +272,32 @@ function getReadmeGroups(model) {
     }
     return CATEGORY_ORDER.flatMap((title) => {
         const items = groups.get(title);
-        if (!items || items.length === 0)
-            return [];
-        return [{ title, items: sortReadmeItems(items) }];
+        return items === undefined || items.length === 0
+            ? []
+            : [{ title, items: sortReadmeItems(items) }];
     });
 }
+/***
+ * Adds one public API item to a README category.
+ */
 function addReadmeItem(groups, title, item) {
-    const existing = groups.get(title) ?? [];
-    existing.push(item);
-    groups.set(title, existing);
+    groups.set(title, [...(groups.get(title) ?? []), item]);
 }
+/***
+ * Sorts README category items by symbol name.
+ */
 function sortReadmeItems(items) {
     return [...items].sort((left, right) => getReadmeItemName(left).localeCompare(getReadmeItemName(right)));
 }
+/***
+ * Returns one README item's source symbol name.
+ */
 function getReadmeItemName(item) {
     return item.kind === 'component' ? item.component.name : item.exportEntry.name;
 }
+/***
+ * Derives a stable README public API category from a module path.
+ */
 function getReadmeCategory(modulePath, name) {
     if (modulePath.includes('/config/'))
         return 'Config';
@@ -281,24 +319,30 @@ function getReadmeCategory(modulePath, name) {
         return 'Types';
     return 'Utilities';
 }
+/***
+ * Renders the complete public API reference.
+ */
 function renderExports(model) {
     const lines = ['# Public API', ''];
     for (const item of model.exports) {
-        lines.push(`## ${item.name}`, '');
+        lines.push(`## ${item.title ?? item.name}`, '');
+        if (item.title !== null && item.title !== item.name)
+            lines.push(`Symbol: \`${item.name}\``, '');
         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)
             lines.push(item.description, '');
+        renderReferences(lines, item);
         renderStructuredRows(lines, item);
         if (item.signatures.length > 0) {
             lines.push('### Signatures', '');
             for (const signature of item.signatures) {
                 lines.push(`- \`${signature.label}\``);
                 for (const parameter of signature.parameters) {
-                    lines.push(`  - ${parameter.name}: \`${parameter.type}\`${parameter.required ? '' : ' (optional)'}${parameter.description ? ` — ${parameter.description}` : ''}`);
+                    lines.push(`  - ${parameter.name}: \`${parameter.type}\`${parameter.required ? '' : ' (optional)'}`);
                 }
-                lines.push(`  - returns: \`${signature.returnType ?? 'void'}\`${signature.returnDescription ? ` — ${signature.returnDescription}` : ''}`);
+                lines.push(`  - returns: \`${signature.returnType ?? 'void'}\``);
             }
             lines.push('');
         }
@@ -314,6 +358,9 @@ function renderExports(model) {
     }
     return `${lines.join('\n').trimEnd()}\n`;
 }
+/***
+ * Renders the complete component registry.
+ */
 function renderComponents(model) {
     const lines = ['# Components', ''];
     for (const component of model.components) {
@@ -321,6 +368,7 @@ function renderComponents(model) {
         lines.push(`Source: \`${component.sourceLocation.filePath}:${component.sourceLocation.line}:${component.sourceLocation.column}\``, '');
         if (component.description)
             lines.push(component.description, '');
+        renderReferences(lines, component);
         if (component.exportPaths.length > 0) {
             lines.push(`Export paths: ${component.exportPaths.map((path) => `\`${path}\``).join(', ')}`, '');
         }
@@ -335,12 +383,21 @@ function renderComponents(model) {
     }
     return `${lines.join('\n').trimEnd()}\n`;
 }
+/***
+ * Escapes one Markdown table cell.
+ */
 function escapeTableCell(value) {
     return value.replaceAll('|', '\\|');
 }
+/***
+ * Renders an optional default value.
+ */
 function renderDefault(value) {
     return value === undefined ? '—' : `\`${escapeTableCell(value)}\``;
 }
+/***
+ * Flattens nested configuration members into dot paths.
+ */
 function flattenConfigMembers(members, prefix = '') {
     return members.flatMap((member) => {
         const path = prefix ? `${prefix}.${member.name}` : member.name;
@@ -355,6 +412,9 @@ function flattenConfigMembers(members, prefix = '') {
         return [current, ...children];
     });
 }
+/***
+ * Returns the accessible badge label stored in a rendered badge artifact.
+ */
 function badgeLabel(model, badgePath) {
     const fileName = badgePath.split('/').pop();
     if (!fileName)
@@ -363,13 +423,6 @@ 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 = [
     'Config',
     'Documentation',

package/dist/render/toFileStem.d.ts

@@ -0,0 +1,2 @@
+/*** Convert a documentation label to the stable lowercase kebab-case file stem used by Paradox render artifacts. */
+export declare function toFileStem(value: string): string;

package/dist/render/toFileStem.js

@@ -0,0 +1,8 @@
+/*** Convert a documentation label to the stable lowercase kebab-case file stem used by Paradox render artifacts. */
+export function toFileStem(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^A-Za-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+}

package/dist/{config/types.d.ts → types/config.d.ts}

@@ -1,5 +1,7 @@
 /***
- * Configuration for running Paradox.
+ * @title Configuration
+ *
+ * Configures Paradox documentation generation for a package.
  *
  * @config
  * @readme
@@ -16,10 +18,6 @@ export interface ParadoxConfig {
     docs?: {
         title?: string;
         description?: string;
-        usage?: {
-            description?: string;
-            entrypoints?: string[];
-        };
     };
     package?: {
         root?: string;

package/dist/write/write.d.ts

@@ -1,5 +1,5 @@
-import type { ParadoxConfig } from '../config/types.js';
 import type { RenderResult } from '../render/types.js';
+import type { ParadoxConfig } from '../types/config.js';
 /***
  * Writes generated documentation artifacts to the configured output paths.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.27",
+  "version": "0.2.1",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -71,6 +71,7 @@
     "test:standalone": "bun test tests/cli.e2e.test.ts"
   },
   "dependencies": {
+    "@ankhorage/policy": "^0.2.0",
     "@ankhorage/utility": "^1.8.0",
     "ts-morph": "^28.0.0"
   },

package/dist/analyze/readmeCli.d.ts

@@ -1,9 +0,0 @@
-export interface AnalysisReadmeCli {
-    description: string | null;
-    sourcePath: string;
-}
-/***
- * Collects README CLI metadata from the canonical Ankhorage CLI entrypoint when its leading
- * Paradox comment opts into README output with @readme.
- */
-export declare function analyzeReadmeCli(root: string): Promise<AnalysisReadmeCli | null>;

package/dist/analyze/readmeCli.js

@@ -1,33 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { getLeadingParadoxComment } from './utils/getLeadingParadoxComment.js';
-const CLI_INDEX_PATH = 'src/cli/index.ts';
-/***
- * Collects README CLI metadata from the canonical Ankhorage CLI entrypoint when its leading
- * Paradox comment opts into README output with @readme.
- */
-export async function analyzeReadmeCli(root) {
-    const filePath = join(root, CLI_INDEX_PATH);
-    let source;
-    try {
-        source = await readFile(filePath, 'utf-8');
-    }
-    catch (error) {
-        if (isMissingPathError(error))
-            return null;
-        throw error;
-    }
-    const comment = getLeadingParadoxComment(source);
-    if (!comment?.parsed.isReadme)
-        return null;
-    return {
-        description: comment.parsed.description,
-        sourcePath: CLI_INDEX_PATH,
-    };
-}
-function isMissingPathError(error) {
-    return (error instanceof Error &&
-        'code' in error &&
-        typeof error.code === 'string' &&
-        error.code === 'ENOENT');
-}

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

@@ -1,10 +0,0 @@
-import { type ParsedParadoxComment } from './parseParadoxComment.js';
-export interface LeadingParadoxComment {
-    parsed: ParsedParadoxComment;
-    start: number;
-    end: number;
-}
-/***
- * Parses a leading Paradox comment from a source file.
- */
-export declare function getLeadingParadoxComment(source: string): LeadingParadoxComment | null;

package/dist/analyze/utils/getLeadingParadoxComment.js

@@ -1,16 +0,0 @@
-import { parseParadoxComment } from './parseParadoxComment.js';
-/***
- * Parses a leading Paradox comment from a source file.
- */
-export function getLeadingParadoxComment(source) {
-    const match = /^\s*(\/\*\*\*[\s\S]*?\*\/)/.exec(source);
-    const comment = match?.[1];
-    if (match === null || comment === undefined)
-        return null;
-    const start = match[0].indexOf(comment);
-    return {
-        parsed: parseParadoxComment(comment),
-        start,
-        end: start + comment.length,
-    };
-}