@ankhorage/paradox 0.1.27 → 0.2.1

package/dist/model/buildModel.js

@@ -4,87 +4,45 @@
 export function buildModel(analysis) {
     const exportNames = new Set(analysis.exports.map((item) => item.name));
     const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item, exportNames)]));
-    const exports = sortByName([...exportsByName.values()]);
     return {
         packageName: analysis.packageName,
         packageId: analysis.packageId,
         description: analysis.description,
         collaborators: analysis.collaborators,
         donation: analysis.donation === null ? null : { account: analysis.donation.account },
-        badges: analysis.badges.map((badge) => ({
-            id: badge.id,
-            label: badge.label,
-            value: badge.value,
-            color: badge.color,
-        })),
-        usage: analysis.usage !== null
-            ? {
-                packageName: analysis.usage.packageName,
-                commands: sortByName(analysis.usage.commands.map((command) => ({
-                    name: command.name,
-                    command: command.command,
-                }))),
-            }
-            : null,
-        readmeUsageDescription: analysis.readmeUsageDescription,
-        readmeUsage: analysis.readmeUsage
-            .map((usageEntry) => ({
-            title: usageEntry.title,
-            description: usageEntry.description,
-            language: usageEntry.language,
-            code: usageEntry.code,
-            sourcePath: usageEntry.sourcePath,
-        }))
+        badges: analysis.badges.map((badge) => ({ ...badge })),
+        usage: { ...analysis.usage },
+        usageEntries: analysis.usageEntries
+            .map((entry) => ({ ...entry, see: [...entry.see], security: [...entry.security] }))
             .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath)),
-        readmeCli: analysis.readmeCli !== null
-            ? {
-                description: analysis.readmeCli.description,
-                sourcePath: analysis.readmeCli.sourcePath,
-            }
-            : null,
-        readmeConfig: analysis.readmeConfig !== null
-            ? {
-                description: analysis.readmeConfig.description,
-                language: analysis.readmeConfig.language,
-                code: analysis.readmeConfig.code,
-                sourcePath: analysis.readmeConfig.sourcePath,
-            }
-            : null,
-        config: analysis.config !== null
-            ? {
-                exportName: analysis.config.exportName,
-                isReadme: analysis.config.isReadme,
+        exampleCount: analysis.exampleCount,
+        findings: analysis.findings.map((finding) => ({ ...finding })),
+        readmeConfig: analysis.readmeConfig === null ? null : { ...analysis.readmeConfig },
+        config: analysis.config === null
+            ? null
+            : {
+                ...analysis.config,
+                see: [...analysis.config.see],
+                security: [...analysis.config.security],
                 members: analysis.config.members,
-            }
-            : null,
+            },
         entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
         modules: [...analysis.modules]
             .map((module) => ({
-            path: module.path,
-            isEntrypoint: module.isEntrypoint,
+            ...module,
             dependencies: [...module.dependencies].sort((a, b) => a.localeCompare(b)),
             exports: [...module.exports].sort((a, b) => a.localeCompare(b)),
         }))
             .sort((left, right) => left.path.localeCompare(right.path)),
-        exports,
+        exports: sortByName([...exportsByName.values()]),
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
         sourceFunctions: analysis.sourceFunctions.map((sourceFunction) => ({
-            name: sourceFunction.name,
-            description: sourceFunction.description,
-            sourceLocation: {
-                filePath: sourceFunction.sourceLocation.filePath,
-                line: sourceFunction.sourceLocation.line,
-                column: sourceFunction.sourceLocation.column,
-            },
+            ...sourceFunction,
+            see: [...sourceFunction.see],
+            security: [...sourceFunction.security],
+            sourceLocation: { ...sourceFunction.sourceLocation },
         })),
-        sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({
-            kind: scenario.kind,
-            name: scenario.name,
-            sourcePath: scenario.sourcePath,
-            symbolName: scenario.symbolName,
-            description: scenario.description,
-            isReadme: scenario.isReadme,
-        }))),
+        sequenceScenarios: sortByName(analysis.sequenceScenarios.map((scenario) => ({ ...scenario }))),
         graphs: {
             imports: [...analysis.graphs.imports],
             calls: [...analysis.graphs.calls],
@@ -99,39 +57,24 @@ export function buildModel(analysis) {
 function mapExport(item, exportNames) {
     return {
         name: item.name,
+        title: item.title,
         description: item.description,
         isReadme: item.isReadme,
-        examples: item.examples.map((example) => ({ ...example })),
+        see: [...item.see],
+        security: [...item.security],
         kind: item.kind,
         modulePath: item.modulePath,
-        sourceLocation: {
-            filePath: item.sourceLocation.filePath,
-            line: item.sourceLocation.line,
-            column: item.sourceLocation.column,
-        },
+        sourceLocation: { ...item.sourceLocation },
         exportPaths: [...item.exportPaths].sort((a, b) => a.localeCompare(b)),
         relatedSymbols: item.relatedSymbols
             .filter((symbol) => exportNames.has(symbol))
             .sort((a, b) => a.localeCompare(b)),
         signatures: item.signatures.map((signature) => ({
-            label: signature.label,
-            parameters: sortByName(signature.parameters.map((parameter) => ({
-                name: parameter.name,
-                type: parameter.type,
-                required: parameter.required,
-                description: parameter.description,
-            }))),
-            returnType: signature.returnType,
-            returnDescription: signature.returnDescription,
+            ...signature,
+            parameters: sortByName(signature.parameters.map((parameter) => ({ ...parameter }))),
         })),
         members: sortByName(item.members.map((member) => ({
-            name: member.name,
-            kind: member.kind,
-            type: member.type,
-            required: member.required,
-            description: member.description,
-            defaultValue: member.defaultValue,
-            inheritedFrom: member.inheritedFrom,
+            ...member,
             children: member.children,
         }))),
         structuredRows: item.structuredRows.map((row) => ({ values: { ...row.values } })),
@@ -145,25 +88,16 @@ function mapComponent(component, exportModel) {
         name: component.name,
         description: component.description,
         isReadme: component.isReadme,
-        examples: component.examples.map((example) => ({ ...example })),
+        see: [...component.see],
+        security: [...component.security],
         modulePath: component.modulePath,
-        sourceLocation: {
-            filePath: component.sourceLocation.filePath,
-            line: component.sourceLocation.line,
-            column: component.sourceLocation.column,
-        },
+        sourceLocation: { ...component.sourceLocation },
         exportPaths: exportModel?.exportPaths ?? [...component.exportPaths].sort((a, b) => a.localeCompare(b)),
-        props: sortByName(component.props.map((prop) => ({
-            name: prop.name,
-            type: prop.type,
-            required: prop.required,
-            defaultValue: prop.defaultValue,
-            description: prop.description,
-        }))),
+        props: sortByName(component.props.map((prop) => ({ ...prop }))),
     };
 }
 /***
- * Returns a copy of items sorted by their `name` property.
+ * Returns a copy of items sorted by their name property.
  */
 function sortByName(items) {
     return [...items].sort((a, b) => a.name.localeCompare(b.name));

package/dist/model/types.d.ts

@@ -1,3 +1,4 @@
+import type { PolicySeverity } from '@ankhorage/policy/status';
 /***
  * Serializable model consumed by renderers and writers.
  */
@@ -8,10 +9,10 @@ export interface DocumentationModel {
     collaborators: true | null;
     donation: DonationModel | null;
     badges: GeneratedBadge[];
-    usage: UsageModel | null;
-    readmeUsageDescription: string | null;
-    readmeUsage: ReadmeUsageModel[];
-    readmeCli: ReadmeCliModel | null;
+    usage: UsageModel;
+    usageEntries: UsageEntryModel[];
+    exampleCount: number;
+    findings: DocumentationFindingModel[];
     readmeConfig: ReadmeConfigModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
@@ -33,39 +34,47 @@ export interface GeneratedBadge {
 }
 interface UsageModel {
     packageName: string;
-    commands: UsageCommandModel[];
-}
-interface UsageCommandModel {
-    name: string;
     command: string;
 }
-interface ReadmeUsageModel {
+interface UsageEntryModel {
+    area: 'cli' | 'examples';
     title: string | null;
     description: string | null;
     language: string;
     code: string;
     sourcePath: string;
+    isReadme: boolean;
+    see: string[];
+    security: string[];
 }
-interface ReadmeCliModel {
-    description: string | null;
-    sourcePath: string;
+interface DocumentationFindingModel {
+    ruleId: string;
+    severity: PolicySeverity;
+    message: string;
+    sourcePath: string | null;
+    line: number | null;
 }
 interface ReadmeConfigModel {
-    description: string | null;
     language: string;
     code: string;
     sourcePath: string;
 }
 interface ConfigModel {
     exportName: string;
+    title: string | null;
+    description: string | null;
     isReadme: boolean;
+    see: string[];
+    security: string[];
     members: ConfigMemberModel[];
 }
 export interface ExportModel {
     name: string;
+    title: string | null;
     description: string | null;
     isReadme: boolean;
-    examples: ExampleModel[];
+    see: string[];
+    security: string[];
     kind: ExportKind;
     modulePath: string;
     sourceLocation: SourceLocationModel;
@@ -80,7 +89,8 @@ export interface ComponentModel {
     name: string;
     description: string | null;
     isReadme: boolean;
-    examples: ExampleModel[];
+    see: string[];
+    security: string[];
     modulePath: string;
     sourceLocation: SourceLocationModel;
     exportPaths: string[];
@@ -89,6 +99,8 @@ export interface ComponentModel {
 interface SourceFunctionModel {
     name: string;
     description: string | null;
+    see: string[];
+    security: string[];
     sourceLocation: SourceLocationModel;
 }
 export interface SequenceScenarioModel {
@@ -105,11 +117,6 @@ export interface ModuleModel {
     dependencies: string[];
     exports: string[];
 }
-interface ExampleModel {
-    title: string | null;
-    language: string | null;
-    code: string;
-}
 interface SourceLocationModel {
     filePath: string;
     line: number;

package/dist/paths/policy.d.ts

@@ -1,4 +1,4 @@
-import type { ParadoxConfig } from '../config/types.js';
+import type { ParadoxConfig } from '../types/config.js';
 /***
  * Searches upward from a start directory until it finds a supported Paradox config file.
  */

package/dist/render/renderers/diagrams.js

@@ -1,3 +1,5 @@
+import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toFileStem } from '../toFileStem.js';
 const MAX_SEQUENCE_CALL_EDGES = 12;
 const MAX_SEQUENCE_PARTICIPANTS = 8;
 const MAX_BIN_SEQUENCE_PARTICIPANTS = 12;
@@ -173,7 +175,7 @@ function groupCallsBySource(callEdges) {
     return grouped;
 }
 function collectSequenceParticipants(callEdges) {
-    return uniqueSorted(callEdges.flatMap((edge) => [edge.fromSymbol, edge.toSymbol]));
+    return uniqueSortedStrings(callEdges.flatMap((edge) => [edge.fromSymbol, edge.toSymbol]));
 }
 function getCallEdgeKey(edge) {
     return `${edge.fromSymbol}->${edge.toSymbol}@${edge.sourcePath}:${edge.callExpression}`;
@@ -190,16 +192,6 @@ function renderFallbackEdge(modules, prefix) {
         return `  ${toMermaidId(`${prefix}-${previous.path}`)} -.-> ${toMermaidId(`${prefix}-${module.path}`)}`;
     });
 }
-function uniqueSorted(values) {
-    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
-}
-function toFileStem(value) {
-    return value
-        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
-        .replace(/[^A-Za-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .toLowerCase();
-}
 function toMermaidId(value) {
     return value.replace(/[^A-Za-z0-9_]/g, '_');
 }

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.
  */