@ankhorage/paradox 0.1.27 → 0.2.0

package/dist/render/renderers/html.js

@@ -4,7 +4,6 @@ import { slugifyAscii } from '@ankhorage/utility/string';
  */
 export function renderHtml({ diagrams, model, }) {
     const sourceAreas = getSourceAreas(model);
-    const cliScenarios = getReadmeCliScenarios(model);
     const exportsByModule = groupBy(model.exports, (item) => item.modulePath);
     return {
         indexHtml: `<!doctype html>
@@ -141,7 +140,7 @@ export function renderHtml({ diagrams, model, }) {
       </aside>
       <main class="content">
         <section id="view-home" class="view" data-view="home">
-          ${renderHomeView(model, diagrams, cliScenarios, exportsByModule)}
+          ${renderHomeView(model, diagrams, exportsByModule)}
         </section>
         ${sourceAreas.map(renderSourceAreaView).join('')}
       </main>
@@ -197,7 +196,7 @@ export function renderHtml({ diagrams, model, }) {
 /***
  * Renders the Home view that keeps public API and package-level information together.
  */
-function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
+function renderHomeView(model, diagrams, exportsByModule) {
     return `
     <section class="panel">
       <h2>Package overview</h2>
@@ -212,7 +211,8 @@ function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
         ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
       </ul>
     </section>
-    ${model.readmeCli !== null ? renderCliPanel(model, diagrams, cliScenarios) : ''}
+    ${renderUsagePanel(model)}
+    ${renderFindingsPanel(model)}
     <section class="panel">
       <h2>Modules</h2>
       ${model.modules.map(renderModuleCard).join('')}
@@ -237,36 +237,62 @@ function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
     </section>`;
 }
 /***
- * Renders the Home CLI chapter for detected bin scenarios.
+ * Renders complete CLI and programmatic usage documentation.
  */
-function renderCliPanel(model, diagrams, scenarios) {
-    const commands = model.usage?.commands ?? [];
-    const searchText = [
-        'cli',
-        model.readmeCli?.description ?? '',
-        ...commands.map((command) => command.command),
-        ...scenarios.map((scenario) => scenario.name),
-    ].join(' ');
-    return `<section class="panel" data-search="${escapeAttribute(searchText)}">
-    <h2>CLI</h2>
-    ${model.readmeCli?.description === null || model.readmeCli?.description === undefined ? '' : `<p>${escapeHtml(model.readmeCli.description)}</p>`}
-    ${commands.length === 0 ? '' : `<pre>${escapeHtml(commands.map((command) => command.command).join('\n'))}</pre>`}
-    ${scenarios
-        .map((scenario) => {
-        const diagram = findScenarioDiagram(diagrams, scenario);
-        if (scenario.description === null && diagram === undefined)
-            return '';
-        return `<article class="item" data-search="${escapeAttribute([scenario.name, scenario.description ?? ''].join(' '))}">
-          <h3>${escapeHtml(scenario.name)}</h3>
-          ${scenario.description === null ? '' : `<p>${escapeHtml(scenario.description)}</p>`}
-          ${diagram === undefined ? '' : renderDiagramCard(diagram)}
-        </article>`;
-    })
-        .join('')}
+function renderUsagePanel(model) {
+    return `<section class="panel" data-search="${escapeAttribute([
+        'usage',
+        model.usage.command,
+        ...model.usageEntries.flatMap((entry) => [
+            entry.title ?? '',
+            entry.description ?? '',
+            entry.sourcePath,
+        ]),
+    ].join(' '))}">
+    <h2>Usage</h2>
+    <article class="item">
+      <h3>CLI</h3>
+      <pre>${escapeHtml(model.usage.command)}</pre>
+    </article>
+    ${model.usageEntries.map(renderUsageEntry).join('')}
   </section>`;
 }
 /***
- * Renders one source file entry in the left navigation.
+ * Renders one source-backed usage entry in the complete documentation app.
+ */
+function renderUsageEntry(entry) {
+    return `<article class="item" data-search="${escapeAttribute([
+        entry.title ?? '',
+        entry.description ?? '',
+        entry.sourcePath,
+        ...entry.see,
+        ...entry.security,
+    ].join(' '))}">
+    <h3>${escapeHtml(entry.title ?? 'Usage')}</h3>
+    <p class="muted"><code>${escapeHtml(entry.sourcePath)}</code></p>
+    ${entry.description === null ? '' : `<p>${escapeHtml(entry.description)}</p>`}
+    ${renderReferenceMetadata(entry)}
+    <pre>${escapeHtml(entry.code)}</pre>
+  </article>`;
+}
+/***
+ * Renders policy findings so complete docs expose the same evidence consumed by Doctor.
+ */
+function renderFindingsPanel(model) {
+    if (model.findings.length === 0) {
+        return '<section class="panel"><h2>Policy</h2><p>No documentation findings.</p></section>';
+    }
+    return `<section class="panel">
+    <h2>Policy findings</h2>
+    ${model.findings
+        .map((finding) => `<article class="item" data-search="${escapeAttribute([finding.ruleId, finding.severity, finding.message, finding.sourcePath ?? ''].join(' '))}">
+          <h3>${escapeHtml(finding.ruleId)}</h3>
+          <p><strong>${escapeHtml(finding.severity)}</strong> — ${escapeHtml(finding.message)}</p>
+          ${finding.sourcePath === null ? '' : `<p class="muted"><code>${escapeHtml(finding.sourcePath)}${finding.line === null ? '' : `:${finding.line}`}</code></p>`}
+        </article>`)
+        .join('')}
+  </section>`;
+}
 /***
  * Renders one source file entry in the left navigation.
  */
@@ -293,10 +319,17 @@ function renderSourceAreaView(area) {
  * Renders one source function card in a source-area view.
  */
 function renderSourceFunctionCard(item) {
-    return `<article class="item" data-search="${escapeAttribute([item.name, item.sourceLocation.filePath, item.description ?? ''].join(' '))}">
+    return `<article class="item" data-search="${escapeAttribute([
+        item.name,
+        item.sourceLocation.filePath,
+        item.description ?? '',
+        ...item.see,
+        ...item.security,
+    ].join(' '))}">
     <h3>${escapeHtml(item.name)}</h3>
     <p class="muted"><code>${escapeHtml(item.sourceLocation.filePath)}:${item.sourceLocation.line}:${item.sourceLocation.column}</code></p>
     ${item.description === null ? '<p class="empty">No description available.</p>' : `<p>${escapeHtml(item.description)}</p>`}
+    ${renderReferenceMetadata(item)}
   </article>`;
 }
 /***
@@ -307,22 +340,6 @@ function getSourceAreas(model) {
         .map(([path, functions]) => ({ path, functions }))
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-/***
- * Selects bin scenarios that should be shown on the Home page.
- */
-function getReadmeCliScenarios(model) {
-    if (model.readmeCli === null)
-        return [];
-    return model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin');
-}
-/***
- * Finds the generated Mermaid artifact for a sequence scenario.
-/***
- * Finds the generated Mermaid artifact for a sequence scenario.
- */
-function findScenarioDiagram(diagrams, scenario) {
-    return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
-}
 /***
  * Renders module metadata on the Home page.
  */
@@ -340,15 +357,20 @@ function renderModuleCard(module) {
 function renderExportCard(item) {
     return `<article class="item" id="symbol-${slugifyAscii(item.name)}" data-search="${escapeAttribute([
         item.name,
+        item.title ?? '',
         item.kind,
         item.modulePath,
         item.description ?? '',
+        ...item.see,
+        ...item.security,
         ...item.relatedSymbols,
         ...item.signatures.map((signature) => signature.label),
     ].join(' '))}">
-    <h4>${escapeHtml(item.name)}</h4>
+    <h4>${escapeHtml(item.title ?? item.name)}</h4>
+    ${item.title === null || item.title === item.name ? '' : `<p class="muted">Symbol: <code>${escapeHtml(item.name)}</code></p>`}
     <p class="muted">${escapeHtml(item.kind)} • <code>${escapeHtml(item.sourceLocation.filePath)}:${item.sourceLocation.line}:${item.sourceLocation.column}</code></p>
     ${item.description ? `<p>${escapeHtml(item.description)}</p>` : ''}
+    ${renderReferenceMetadata(item)}
     <p><strong>Export paths:</strong> ${renderInlineCodeList(item.exportPaths)}</p>
     <div><strong>Related symbols:</strong> ${item.relatedSymbols.length > 0 ? renderChipList(item.relatedSymbols) : '<span class="empty">None</span>'}</div>
     ${item.signatures.length > 0 ? renderSignatureBlock(item) : ''}
@@ -409,11 +431,14 @@ function renderComponentCard(component) {
         component.name,
         component.modulePath,
         component.description ?? '',
+        ...component.see,
+        ...component.security,
         ...component.props.map((prop) => `${prop.name} ${prop.type}`),
     ].join(' '))}">
     <h3>${escapeHtml(component.name)}</h3>
     <p class="muted"><code>${escapeHtml(component.sourceLocation.filePath)}:${component.sourceLocation.line}:${component.sourceLocation.column}</code></p>
     ${component.description ? `<p>${escapeHtml(component.description)}</p>` : ''}
+    ${renderReferenceMetadata(component)}
     <p><strong>Export paths:</strong> ${renderInlineCodeList(component.exportPaths)}</p>
     <table>
       <thead><tr><th>Prop</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
@@ -444,6 +469,22 @@ function renderDiagramCard(diagram) {
     </details>
   </article>`;
 }
+/***
+ * Renders validated external references and security-test evidence.
+ */
+function renderReferenceMetadata(metadata) {
+    const see = metadata.see.length === 0
+        ? ''
+        : `<p><strong>See also:</strong> ${metadata.see
+            .map((url) => `<a href="${escapeAttribute(url)}" rel="noreferrer">${escapeHtml(url)}</a>`)
+            .join(', ')}</p>`;
+    const security = metadata.security.length === 0
+        ? ''
+        : `<p><strong>Security tests:</strong> ${metadata.security
+            .map((reference) => `<code>${escapeHtml(reference)}</code>`)
+            .join(', ')}</p>`;
+    return `${see}${security}`;
+}
 /***
  * Renders an inline comma-separated list of code values.
  */
@@ -478,16 +519,6 @@ function groupBy(items, key) {
     }
     return new Map([...groups.entries()].sort(([left], [right]) => left.localeCompare(right)));
 }
-/***
- * Converts a scenario name to the generated Mermaid file stem.
- */
-function toFileStem(value) {
-    return value
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .replace(/[^A-Za-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .toLowerCase();
-}
 /***
  * Escapes user-controlled text for safe HTML rendering.
  */

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();
+}