@ankhorage/paradox 0.2.4 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.5
+
+### Patch Changes
+
+- 0c09385: Consume the complete Policy-owned README usage contract, including capability-aware rendering and canonical section ordering.
+
 ## 0.2.4
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.2.1](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![paradox: canonical](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.2.4](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![paradox: canonical](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 

package/dist/analyze/documentation/validateDocumentationPolicyAsync.js

@@ -44,11 +44,10 @@ function validateCommentRules(comments) {
  */
 function validateUsageRules(comments) {
     const usageComments = comments.filter((comment) => comment.parsed.isUsage);
-    if (usageComments.length === 0)
+    if (!DOCUMENTATION_POLICY.readmeUsage.required && usageComments.length === 0)
         return [];
     const findings = usageComments.flatMap((comment) => validateUsageComment(comment));
-    const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.paths.examplesRoot) &&
-        comment.parsed.isReadme);
+    const readmeExamples = usageComments.filter((comment) => isBelow(comment.sourcePath, DOCUMENTATION_POLICY.readmeUsage.root) && comment.parsed.isReadme);
     if (readmeExamples.length !== DOCUMENTATION_POLICY.readmeUsage.exactCount) {
         findings.push(createDocumentationFinding('documentation.usage.readme.unique', `Expected exactly one @usage + @readme example; found ${readmeExamples.length}.`));
     }

package/dist/render/renderers/html.js

@@ -1,3 +1,4 @@
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
 import { slugifyAscii } from '@ankhorage/utility/string';
 /***
  * Renders a deterministic static HTML documentation app.
@@ -240,10 +241,13 @@ function renderHomeView(model, diagrams, exportsByModule) {
  * Renders complete CLI and programmatic usage documentation.
  */
 function renderUsagePanel(model) {
+    if (!DOCUMENTATION_POLICY.readmeUsage.required && model.usageEntries.length === 0)
+        return '';
+    const { usageEntries } = model;
     return `<section class="panel" data-search="${escapeAttribute([
         'usage',
         model.usage.command,
-        ...model.usageEntries.flatMap((entry) => [
+        ...usageEntries.flatMap((entry) => [
             entry.title ?? '',
             entry.description ?? '',
             entry.sourcePath,
@@ -254,7 +258,7 @@ function renderUsagePanel(model) {
       <h3>CLI</h3>
       <pre>${escapeHtml(model.usage.command)}</pre>
     </article>
-    ${model.usageEntries.map(renderUsageEntry).join('')}
+    ${usageEntries.map(renderUsageEntry).join('')}
   </section>`;
 }
 /***

package/dist/render/renderers/markdown.js

@@ -1,3 +1,4 @@
+import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
 /***
  * Renders markdown artifacts from the documentation model.
  */
@@ -36,8 +37,21 @@ function renderReadme(model, outputDir, badges, diagrams) {
  * Renders the canonical CLI-first Usage chapter.
  */
 function renderUsage(lines, model) {
+    if (!DOCUMENTATION_POLICY.readmeUsage.required && model.usageEntries.length === 0)
+        return;
     const readmeExample = model.usageEntries.find((entry) => entry.area === 'examples' && entry.isReadme);
     lines.push('## Usage', '');
+    for (const section of DOCUMENTATION_POLICY.readmeUsage.sectionOrder) {
+        if (section === 'cli') {
+            renderCliUsage(lines, model);
+        }
+        else {
+            renderProgrammaticUsage(lines, model, readmeExample);
+        }
+    }
+}
+/*** Renders the canonical CLI usage section from package metadata. */
+function renderCliUsage(lines, model) {
     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');
@@ -46,6 +60,9 @@ function renderUsage(lines, model) {
     lines.push(`# Show usage information for ${getPackageDisplayName(model.packageId)}`);
     lines.push(model.usage.command);
     lines.push('```', '');
+}
+/*** Renders the single README-promoted programmatic usage declaration. */
+function renderProgrammaticUsage(lines, model, readmeExample) {
     if (readmeExample === undefined)
         return;
     lines.push(`### ${readmeExample.title ?? 'Programmatic Usage'}`, '');

package/package.json

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