@ankhorage/paradox 0.1.3 → 0.1.5

package/dist/render/renderers/html.js

@@ -2,18 +2,8 @@
  * Renders a deterministic static HTML documentation app.
  */
 export function renderHtml({ diagrams, model, }) {
-    const navigationItems = [
-        ...model.exports.map((item) => ({
-            href: `#symbol-${toAnchorId(item.name)}`,
-            label: item.name,
-            meta: `${item.kind} • ${item.modulePath}`,
-        })),
-        ...model.components.map((component) => ({
-            href: `#component-${toAnchorId(component.name)}`,
-            label: component.name,
-            meta: `component • ${component.modulePath}`,
-        })),
-    ].sort((left, right) => left.label.localeCompare(right.label));
+    const sourceAreas = getSourceAreas(model);
+    const cliScenarios = getReadmeCliScenarios(model);
     const exportsByModule = groupBy(model.exports, (item) => item.modulePath);
     return {
         indexHtml: `<!doctype html>
@@ -33,6 +23,7 @@ export function renderHtml({ diagrams, model, }) {
       body { margin: 0; }
       a { color: #2459d3; text-decoration: none; }
       a:hover { text-decoration: underline; }
+      button { font: inherit; }
       code, pre { font-family: "SFMono-Regular", ui-monospace, SFMono-Regular, Menlo, monospace; }
       .layout {
         display: grid;
@@ -48,9 +39,7 @@ export function renderHtml({ diagrams, model, }) {
         max-height: 100vh;
         overflow: auto;
       }
-      .content {
-        padding: 2rem;
-      }
+      .content { padding: 2rem; }
       .panel, .item {
         background: #ffffff;
         border: 1px solid #d8dfec;
@@ -80,7 +69,28 @@ export function renderHtml({ diagrams, model, }) {
         padding: 0;
         margin: 0;
       }
-      .nav-list li + li { margin-top: 0.8rem; }
+      .nav-list li + li { margin-top: 0.5rem; }
+      .nav-button {
+        width: 100%;
+        display: block;
+        border: 0;
+        border-radius: 0.7rem;
+        background: transparent;
+        color: #24427a;
+        cursor: pointer;
+        padding: 0.55rem 0.7rem;
+        text-align: left;
+      }
+      .nav-button:hover, .nav-button[aria-current="page"] {
+        background: #e8eefb;
+        text-decoration: none;
+      }
+      .nav-button small {
+        display: block;
+        color: #5e6d8c;
+        margin-top: 0.15rem;
+      }
+      .view[hidden] { display: none; }
       .muted { color: #5e6d8c; }
       .chips { display: flex; flex-wrap: wrap; gap: 0.5rem; padding: 0; list-style: none; }
       .chip {
@@ -115,61 +125,64 @@ export function renderHtml({ diagrams, model, }) {
         <p class="muted">Generated with Paradox</p>
         <h1>${escapeHtml(model.packageName)}</h1>
         <p>${escapeHtml(model.description ?? 'Deterministic package documentation.')}</p>
-        <input id="search" class="search" type="search" placeholder="Search symbols, files, and metadata" />
-        <ul class="nav-list">
-          ${navigationItems
-            .map((item) => `<li><a href="${escapeAttribute(item.href)}">${escapeHtml(item.label)}</a><div class="muted">${escapeHtml(item.meta)}</div></li>`)
-            .join('')}
-        </ul>
+        <input id="search" class="search" type="search" placeholder="Search current view" />
+        <nav aria-label="Documentation sections">
+          <ul class="nav-list">
+            <li>
+              <button class="nav-button" type="button" data-target="home" aria-current="page">
+                Home
+                <small>Overview, CLI, public API, diagrams</small>
+              </button>
+            </li>
+            ${sourceAreas.map(renderSourceNavItem).join('')}
+          </ul>
+        </nav>
       </aside>
       <main class="content">
-        <section class="panel">
-          <h2>Package overview</h2>
-          <div class="summary">
-            <div><strong>${model.exports.length}</strong><span class="muted">public exports</span></div>
-            <div><strong>${model.components.length}</strong><span class="muted">components</span></div>
-            <div><strong>${model.modules.length}</strong><span class="muted">modules</span></div>
-            <div><strong>${model.entrypoints.length}</strong><span class="muted">entrypoints</span></div>
-          </div>
-          <h3>Entrypoints</h3>
-          <ul class="meta-list">
-            ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
-          </ul>
-        </section>
-        <section class="panel">
-          <h2>Modules</h2>
-          ${model.modules.map(renderModuleCard).join('')}
-        </section>
-        <section class="panel">
-          <h2>Exports by module</h2>
-          ${[...exportsByModule.entries()]
-            .map(([modulePath, exports]) => `
-                <section>
-                  <h3>${escapeHtml(modulePath)}</h3>
-                  ${exports.map((item) => renderExportCard(item)).join('')}
-                </section>`)
-            .join('')}
-        </section>
-        <section class="panel">
-          <h2>Component registry</h2>
-          ${model.components.length === 0 ? '<p class="empty">No components were detected.</p>' : model.components.map(renderComponentCard).join('')}
-        </section>
-        <section class="panel">
-          <h2>Diagrams</h2>
-          ${diagrams.map(renderDiagramCard).join('')}
+        <section id="view-home" class="view" data-view="home">
+          ${renderHomeView(model, diagrams, cliScenarios, exportsByModule)}
         </section>
+        ${sourceAreas.map(renderSourceAreaView).join('')}
       </main>
     </div>
     <script>
       const search = document.getElementById('search');
-      const items = Array.from(document.querySelectorAll('[data-search]'));
-      search?.addEventListener('input', () => {
-        const value = search.value.trim().toLowerCase();
+      const navButtons = Array.from(document.querySelectorAll('[data-target]'));
+      const views = Array.from(document.querySelectorAll('[data-view]'));
+
+      function getActiveView() {
+        return document.querySelector('[data-view]:not([hidden])');
+      }
+
+      function applySearch() {
+        const value = search?.value.trim().toLowerCase() || '';
+        const activeView = getActiveView();
+        const items = Array.from(activeView?.querySelectorAll('[data-search]') || []);
+
         for (const item of items) {
           const haystack = (item.getAttribute('data-search') || '').toLowerCase();
           item.style.display = value === '' || haystack.includes(value) ? '' : 'none';
         }
-      });
+      }
+
+      for (const button of navButtons) {
+        button.addEventListener('click', () => {
+          const target = button.getAttribute('data-target');
+
+          for (const view of views) {
+            view.hidden = view.getAttribute('data-view') !== target;
+          }
+
+          for (const item of navButtons) {
+            item.setAttribute('aria-current', item === button ? 'page' : 'false');
+          }
+
+          if (search) search.value = '';
+          applySearch();
+        });
+      }
+
+      search?.addEventListener('input', applySearch);
     </script>
     <script type="module">
       import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
@@ -180,6 +193,123 @@ export function renderHtml({ diagrams, model, }) {
 `,
     };
 }
+/***
+ * Renders the Home view that keeps public API and package-level information together.
+ */
+function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
+    return `
+    <section class="panel">
+      <h2>Package overview</h2>
+      <div class="summary">
+        <div><strong>${model.exports.length}</strong><span class="muted">public exports</span></div>
+        <div><strong>${model.components.length}</strong><span class="muted">components</span></div>
+        <div><strong>${model.modules.length}</strong><span class="muted">modules</span></div>
+        <div><strong>${model.entrypoints.length}</strong><span class="muted">entrypoints</span></div>
+      </div>
+      <h3>Entrypoints</h3>
+      <ul class="meta-list">
+        ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
+      </ul>
+    </section>
+    ${cliScenarios.length > 0 ? renderCliPanel(model, diagrams, cliScenarios) : ''}
+    <section class="panel">
+      <h2>Modules</h2>
+      ${model.modules.map(renderModuleCard).join('')}
+    </section>
+    <section class="panel">
+      <h2>Public API</h2>
+      ${[...exportsByModule.entries()]
+        .map(([modulePath, exports]) => `
+            <section>
+              <h3>${escapeHtml(modulePath)}</h3>
+              ${exports.map((item) => renderExportCard(item)).join('')}
+            </section>`)
+        .join('')}
+    </section>
+    <section class="panel">
+      <h2>Component registry</h2>
+      ${model.components.length === 0 ? '<p class="empty">No components were detected.</p>' : model.components.map(renderComponentCard).join('')}
+    </section>
+    <section class="panel">
+      <h2>Diagrams</h2>
+      ${diagrams.map(renderDiagramCard).join('')}
+    </section>`;
+}
+/***
+ * Renders the Home CLI chapter for detected bin scenarios.
+ */
+function renderCliPanel(model, diagrams, scenarios) {
+    return `<section class="panel" data-search="cli ${scenarios.map((scenario) => scenario.name).join(' ')}">
+    <h2>CLI</h2>
+    ${scenarios
+        .map((scenario) => {
+        const command = model.usage?.commands.find((item) => item.name === scenario.name);
+        const diagram = findScenarioDiagram(diagrams, scenario);
+        return `<article class="item" data-search="${escapeAttribute([scenario.name, scenario.description ?? '', command?.command ?? ''].join(' '))}">
+          <h3>${escapeHtml(scenario.name)}</h3>
+          ${scenario.description === null ? '' : `<p>${escapeHtml(scenario.description)}</p>`}
+          ${command === undefined ? '' : `<pre>${escapeHtml(command.command)}</pre>`}
+          ${diagram === undefined ? '' : renderDiagramCard(diagram)}
+        </article>`;
+    })
+        .join('')}
+  </section>`;
+}
+/***
+ * Renders one source file entry in the left navigation.
+ */
+function renderSourceNavItem(area) {
+    return `<li>
+    <button class="nav-button" type="button" data-target="${escapeAttribute(area.path)}">
+      ${escapeHtml(area.path)}
+      <small>${area.functions.length} function${area.functions.length === 1 ? '' : 's'}</small>
+    </button>
+  </li>`;
+}
+/***
+ * Renders the right-hand source area view for a selected file.
+ */
+function renderSourceAreaView(area) {
+    return `<section id="view-${toAnchorId(area.path)}" class="view" data-view="${escapeAttribute(area.path)}" hidden>
+    <section class="panel">
+      <h2>${escapeHtml(area.path)}</h2>
+      ${area.functions.map(renderSourceFunctionCard).join('')}
+    </section>
+  </section>`;
+}
+/***
+ * 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(' '))}">
+    <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>`}
+  </article>`;
+}
+/***
+ * Groups analyzed source functions by their source file path.
+ */
+function getSourceAreas(model) {
+    return [...groupBy(model.sourceFunctions, (item) => item.sourceLocation.filePath).entries()]
+        .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) {
+    return model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
+}
+/***
+ * 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.
+ */
 function renderModuleCard(module) {
     return `<article class="item" data-search="${escapeAttribute([module.path, ...module.dependencies, ...module.exports].join(' '))}">
     <h3>${escapeHtml(module.path)}</h3>
@@ -188,6 +318,9 @@ function renderModuleCard(module) {
     <p><strong>Exports:</strong> ${renderInlineCodeList(module.exports)}</p>
   </article>`;
 }
+/***
+ * Renders one public API export card on the Home page.
+ */
 function renderExportCard(item) {
     return `<article class="item" id="symbol-${toAnchorId(item.name)}" data-search="${escapeAttribute([
         item.name,
@@ -206,6 +339,9 @@ function renderExportCard(item) {
     ${item.members.length > 0 ? renderMemberTable(item) : ''}
   </article>`;
 }
+/***
+ * Renders all call signatures for a public API export.
+ */
 function renderSignatureBlock(item) {
     return item.signatures
         .map((signature) => `<div>
@@ -230,6 +366,9 @@ function renderSignatureBlock(item) {
       </div>`)
         .join('');
 }
+/***
+ * Renders the members table for a type-like public API export.
+ */
 function renderMemberTable(item) {
     return `<table>
     <thead><tr><th>Member</th><th>Kind</th><th>Type</th><th>Required</th><th>Description</th></tr></thead>
@@ -246,6 +385,9 @@ function renderMemberTable(item) {
     </tbody>
   </table>`;
 }
+/***
+ * Renders one detected component card on the Home page.
+ */
 function renderComponentCard(component) {
     return `<article class="item" id="component-${toAnchorId(component.name)}" data-search="${escapeAttribute([
         component.name,
@@ -272,6 +414,9 @@ function renderComponentCard(component) {
     </table>
   </article>`;
 }
+/***
+ * Renders one Mermaid diagram card.
+ */
 function renderDiagramCard(diagram) {
     return `<article class="item" data-search="${escapeAttribute(`${diagram.title} ${diagram.path}`)}">
     <h3>${escapeHtml(diagram.title)}</h3>
@@ -283,17 +428,26 @@ function renderDiagramCard(diagram) {
     </details>
   </article>`;
 }
+/***
+ * Renders an inline comma-separated list of code values.
+ */
 function renderInlineCodeList(values) {
     if (values.length === 0) {
         return '<span class="empty">None</span>';
     }
     return values.map((value) => `<code>${escapeHtml(value)}</code>`).join(', ');
 }
+/***
+ * Renders a compact chip list for related symbols.
+ */
 function renderChipList(values) {
     return `<ul class="chips">${values
         .map((value) => `<li class="chip">${escapeHtml(value)}</li>`)
         .join('')}</ul>`;
 }
+/***
+ * Groups items by a string key and returns deterministic key order.
+ */
 function groupBy(items, key) {
     const groups = new Map();
     for (const item of items) {
@@ -308,12 +462,28 @@ function groupBy(items, key) {
     }
     return new Map([...groups.entries()].sort(([left], [right]) => left.localeCompare(right)));
 }
+/***
+ * Converts a label to a stable HTML anchor id fragment.
+ */
 function toAnchorId(value) {
     return value
         .toLowerCase()
         .replace(/[^a-z0-9]+/g, '-')
         .replace(/^-|-$/g, '');
 }
+/***
+ * 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.
+ */
 function escapeHtml(value) {
     return value
         .replaceAll('&', '&amp;')
@@ -322,6 +492,9 @@ function escapeHtml(value) {
         .replaceAll('"', '&quot;')
         .replaceAll("'", '&#39;');
 }
+/***
+ * Escapes text for use inside HTML attribute values.
+ */
 function escapeAttribute(value) {
     return escapeHtml(value).replaceAll('\n', '&#10;');
 }

package/dist/render/renderers/markdown.js

@@ -33,7 +33,6 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push('```', '');
     }
     renderCliScenarios(lines, model, outputDir, diagrams);
-    renderDocumentationTags(lines);
     if (model.config?.isReadme) {
         renderConfiguration(lines, model);
     }
@@ -73,15 +72,6 @@ function renderCliScenarios(lines, model, outputDir, diagrams) {
 function findScenarioDiagram(diagrams, scenario) {
     return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
 }
-function renderDocumentationTags(lines) {
-    lines.push('## Documentation Tags', '');
-    for (const tag of DOCUMENTATION_TAGS) {
-        lines.push('<details>');
-        lines.push(`<summary>@${tag.name}</summary>`, '');
-        lines.push(tag.description, '');
-        lines.push('</details>', '');
-    }
-}
 function renderConfiguration(lines, model) {
     const { config } = model;
     if (config === null)
@@ -191,6 +181,7 @@ function renderExportAccordion(lines, item) {
     lines.push(`<summary>${item.name}</summary>`, '');
     renderSignature(lines, item);
     lines.push(item.description ?? `\`${item.kind}\` export.`, '');
+    renderStructuredRows(lines, item);
     renderExamples(lines, item.examples);
     lines.push(`Module: \`${item.modulePath}\``);
     lines.push(`Source: \`${item.sourceLocation.filePath}:${item.sourceLocation.line}:${item.sourceLocation.column}\``);
@@ -216,6 +207,46 @@ function renderExamples(lines, examples) {
         lines.push('```', '');
     }
 }
+function renderStructuredRows(lines, item) {
+    if (item.structuredRows.length === 0)
+        return;
+    const columns = getStructuredColumns(item);
+    if (columns.length === 0)
+        return;
+    lines.push('| ' + columns.map(formatStructuredColumnHeader).join(' | ') + ' |');
+    lines.push('| ' + columns.map(() => '---').join(' | ') + ' |');
+    for (const row of item.structuredRows) {
+        lines.push('| ' +
+            columns
+                .map((column) => formatStructuredCell(column, row.values[column] ?? ''))
+                .join(' | ') +
+            ' |');
+    }
+    lines.push('');
+}
+function getStructuredColumns(item) {
+    const columns = new Set();
+    for (const row of item.structuredRows) {
+        for (const column of Object.keys(row.values)) {
+            columns.add(column);
+        }
+    }
+    return [...columns];
+}
+function formatStructuredColumnHeader(column) {
+    return escapeTableCell(column.replace(/([a-z])([A-Z])/g, '$1 $2').toLowerCase());
+}
+function formatStructuredCell(column, value) {
+    const escaped = escapeTableCell(value);
+    if (column === 'syntax' || column === 'name' || column === 'handler') {
+        return `\`${escaped}\``;
+    }
+    if (value === 'true')
+        return 'yes';
+    if (value === 'false')
+        return 'no';
+    return escaped;
+}
 function getReadmeGroups(model) {
     const exportsByName = new Map(model.exports.map((entry) => [entry.name, entry]));
     const componentNames = new Set(model.components.map((component) => component.name));
@@ -255,7 +286,9 @@ function getReadmeItemName(item) {
 }
 function getReadmeCategory(modulePath, name) {
     if (modulePath.includes('/config/'))
-        return 'Configuration';
+        return 'Config';
+    if (modulePath.includes('/doc-tags/'))
+        return 'Documentation';
     if (modulePath.includes('/primitives/'))
         return 'Primitives';
     if (modulePath.includes('/components/'))
@@ -282,6 +315,7 @@ function renderExports(model) {
         if (item.description) {
             lines.push(item.description, '');
         }
+        renderStructuredRows(lines, item);
         if (item.signatures.length > 0) {
             lines.push('### Signatures', '');
             for (const signature of item.signatures) {
@@ -364,7 +398,8 @@ function toFileStem(value) {
         .toLowerCase();
 }
 const CATEGORY_ORDER = [
-    'Configuration',
+    'Config',
+    'Documentation',
     'Primitives',
     'Components',
     'Patterns',
@@ -373,17 +408,3 @@ const CATEGORY_ORDER = [
     'Utilities',
     'Types',
 ];
-const DOCUMENTATION_TAGS = [
-    {
-        name: 'readme',
-        description: 'Includes a documentation block or exported symbol in README output.',
-    },
-    {
-        name: 'config',
-        description: 'Marks a type or interface as part of the Paradox configuration model. `@config` alone does not imply README inclusion; use `@config` plus `@readme` for README output.',
-    },
-    {
-        name: 'example',
-        description: 'Adds a titled fenced code example to the generated documentation for a symbol.',
-    },
-];

package/package.json

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