@ankhorage/paradox 0.2.3 → 0.2.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- 77bf26a: Reuse the fixed canonical portable-path conversion from @ankhorage/utility and require Utility 1.8.1 or newer.
+
 ## 0.2.3
 
 ### 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/analyze.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolvePolicyStatus } from '@ankhorage/policy/status';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { validateCollaborators } from '../config/utils/validateCollaborators.js';
 import { validateDonationAccount } from '../config/utils/validateDonationAccount.js';
 import { analyzeBadges } from './badges.js';
@@ -72,7 +73,7 @@ export async function analyze(config, runtime) {
         exports,
         components,
         sourceFunctions,
-        entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
+        entrypoints: entrypoints.map(toPortablePath).sort(),
         modules,
         badges,
         sequenceScenarios,

package/dist/analyze/documentation/collectDocumentationCommentsAsync.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { extname, join, relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { parseParadoxComment } from '../utils/parseParadoxComment.js';
 const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.json5']);
 const SCANNED_ROOTS = ['src', 'examples'];
@@ -47,7 +48,7 @@ async function collectRootSourceFilesAsync(root) {
  */
 async function collectFileCommentsAsync(root, filePath) {
     const source = await readFile(filePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(root, filePath));
+    const sourcePath = toPortablePath(relative(root, filePath));
     return [...source.matchAll(COMMENT_PATTERN)].map((match) => {
         const [raw] = match;
         return {
@@ -64,9 +65,3 @@ async function collectFileCommentsAsync(root, filePath) {
 function isMissingPathError(error) {
     return error instanceof Error && 'code' in error && error.code === 'ENOENT';
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

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/analyze/exports.js

@@ -1,5 +1,6 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node } from 'ts-morph';
 import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
@@ -12,7 +13,7 @@ export function analyzeExports(project, options) {
     const exportsByName = new Map();
     let config = null;
     for (const sourceFile of getEntryPointSourceFiles(project, options)) {
-        const entrypointPath = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const entrypointPath = toPortablePath(relative(options.root, sourceFile.getFilePath()));
         const exported = sourceFile.getExportSymbols();
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
@@ -107,12 +108,6 @@ function inferKind(node) {
         return 'value';
     return 'unknown';
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
 /***
  * Creates empty documentation metadata for exports without Paradox comments.
  */

package/dist/analyze/modules.js

@@ -1,5 +1,6 @@
 import { isAbsolute, join, normalize, relative } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Builds a deterministic module relationship graph for documentation renderers.
  */
@@ -11,14 +12,14 @@ export function analyzeModules(project, options) {
         .getSourceFiles()
         .filter((sourceFile) => {
         const filePath = normalize(sourceFile.getFilePath());
-        const normalizedPath = toPosixPath(filePath);
+        const normalizedPath = toPortablePath(filePath);
         return (!sourceFile.isDeclarationFile() &&
             filePath.startsWith(rootPath) &&
             !excludedPaths.has(filePath) &&
             !normalizedPath.includes('/node_modules/'));
     })
         .map((sourceFile) => {
-        const path = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const path = toPortablePath(relative(options.root, sourceFile.getFilePath()));
         const dependencies = sourceFile
             .getImportDeclarations()
             .map((declaration) => declaration.getModuleSpecifierSourceFile())
@@ -26,8 +27,8 @@ export function analyzeModules(project, options) {
             .map((dependency) => normalize(dependency.getFilePath()))
             .filter((dependency) => dependency.startsWith(rootPath) &&
             !excludedPaths.has(dependency) &&
-            !toPosixPath(dependency).includes('/node_modules/'))
-            .map((dependency) => toPosixPath(relative(options.root, dependency)));
+            !toPortablePath(dependency).includes('/node_modules/'))
+            .map((dependency) => toPortablePath(relative(options.root, dependency)));
         const exports = sourceFile
             .getExportSymbols()
             .map((symbol) => symbol.getName())
@@ -41,9 +42,3 @@ export function analyzeModules(project, options) {
     })
         .sort((left, right) => left.path.localeCompare(right.path));
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/readmeConfig.js

@@ -1,5 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { extname, relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Collects the concrete Paradox configuration instance as a README configuration example.
  */
@@ -7,7 +8,7 @@ export async function analyzeReadmeConfig(options) {
     if (options.configFilePath === null)
         return null;
     const source = await readFile(options.configFilePath, 'utf-8');
-    const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
+    const sourcePath = toPortablePath(relative(options.root, options.configFilePath));
     return {
         language: getLanguage(sourcePath),
         code: source.trim(),
@@ -25,9 +26,3 @@ function getLanguage(sourcePath) {
         return 'js';
     return '';
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/readmeUsage.js

@@ -1,6 +1,7 @@
 import { readdir } from 'node:fs/promises';
 import { extname, join, relative } from 'node:path';
 import { DOCUMENTATION_POLICY } from '@ankhorage/policy/documentation';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Project } from 'ts-morph';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -41,7 +42,7 @@ async function collectSourceFilesAsync(root) {
  */
 function analyzeUsageFile(root, project, filePath) {
     const sourceFile = project.getSourceFile(filePath) ?? project.addSourceFileAtPath(filePath);
-    const sourcePath = toPosixPath(relative(root, filePath));
+    const sourcePath = toPortablePath(relative(root, filePath));
     return sourceFile.getStatements().flatMap((statement) => {
         const comment = getParadoxComment(statement);
         if (comment === null)
@@ -140,9 +141,3 @@ function isMissingPathError(error) {
         typeof error.code === 'string' &&
         error.code === 'ENOENT');
 }
-/***
- * Normalizes filesystem separators for stable documentation paths.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/semantic/createTypeScriptProgram.js

@@ -1,6 +1,6 @@
 import { isAbsolute, join, normalize } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Project } from 'ts-morph';
-import { toPosixPath } from './utils.js';
 /***
  * Creates or reuses a ts-morph project for analysis.
  */
@@ -17,7 +17,7 @@ export function createTypeScriptProgram(options) {
         project,
         typeChecker: project.getTypeChecker(),
         root,
-        entrypoints: entrypoints.map((entrypoint) => toPosixPath(entrypoint)),
+        entrypoints: entrypoints.map((entrypoint) => toPortablePath(entrypoint)),
         entrypointFilePaths,
     };
 }

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

@@ -1,4 +1,3 @@
-export declare function toPosixPath(path: string): string;
 export declare function relativeToRoot(root: string, filePath: string): string;
 export declare function isPathInsideRoot(root: string, filePath: string): boolean;
 export declare function isNodeModulePath(filePath: string): boolean;

package/dist/analyze/semantic/utils.js

@@ -1,13 +1,11 @@
 import { normalize, relative } from 'node:path';
-export function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
+import { toPortablePath } from '@ankhorage/utility/node/path';
 export function relativeToRoot(root, filePath) {
-    return toPosixPath(relative(root, filePath));
+    return toPortablePath(relative(root, filePath));
 }
 export function isPathInsideRoot(root, filePath) {
     return normalize(filePath).startsWith(normalize(root));
 }
 export function isNodeModulePath(filePath) {
-    return toPosixPath(filePath).includes('/node_modules/');
+    return toPortablePath(filePath).includes('/node_modules/');
 }

package/dist/analyze/sequenceScenarios.js

@@ -1,7 +1,8 @@
 import { isAbsolute, join, normalize } from 'node:path';
 import { uniqueSortedStrings } from '@ankhorage/utility/array';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node as MorphNode, } from 'ts-morph';
-import { relativeToRoot, toPosixPath } from './semantic/utils.js';
+import { relativeToRoot } from './semantic/utils.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 /***
@@ -73,7 +74,7 @@ function resolveBinSourceFile(project, root, targetPath) {
     return null;
 }
 function getBinSourceCandidates(targetPath) {
-    const normalized = toPosixPath(targetPath).replace(/^\.\//, '');
+    const normalized = toPortablePath(targetPath).replace(/^\.\//, '');
     const candidates = [];
     if (/^src\/.*\.tsx?$/.test(normalized)) {
         candidates.push(normalized);

package/dist/analyze/sourceFunctions.js

@@ -1,4 +1,5 @@
 import { relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node } from 'ts-morph';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
@@ -11,7 +12,7 @@ export function analyzeSourceFunctions(project, root) {
         .flatMap((sourceFile) => {
         if (sourceFile.isDeclarationFile())
             return [];
-        const filePath = toPosixPath(relative(root, sourceFile.getFilePath()));
+        const filePath = toPortablePath(relative(root, sourceFile.getFilePath()));
         if (!filePath.startsWith('src/'))
             return [];
         return sourceFile.getDescendants().flatMap((node) => {
@@ -50,15 +51,9 @@ function createSourceFunction(name, node, root) {
         see: parsedComment?.see ?? [],
         security: parsedComment?.security ?? [],
         sourceLocation: {
-            filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+            filePath: toPortablePath(relative(root, sourceFile.getFilePath())),
             line,
             column,
         },
     };
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}

package/dist/analyze/utils/getExportMetadata.js

@@ -1,4 +1,5 @@
 import { relative } from 'node:path';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 import { Node, } from 'ts-morph';
 import { getParadoxComment } from './getParadoxComment.js';
 import { normalizeTypeText } from './normalizeTypeText.js';
@@ -7,7 +8,7 @@ import { parseParadoxComment } from './parseParadoxComment.js';
  * Extracts computed metadata for an exported declaration.
  */
 export function getExportMetadata(options) {
-    const modulePath = toPosixPath(relative(options.root, options.node.getSourceFile().getFilePath()));
+    const modulePath = toPortablePath(relative(options.root, options.node.getSourceFile().getFilePath()));
     const sourceLocation = getSourceLocation(options.node, options.root);
     const signatures = getSignatures(options.symbol, options.node, options.root);
     const members = getMembers(options.node, options.root);
@@ -33,7 +34,7 @@ function getSourceLocation(node, root) {
     const sourceFile = node.getSourceFile();
     const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
     return {
-        filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+        filePath: toPortablePath(relative(root, sourceFile.getFilePath())),
         line,
         column,
     };
@@ -259,12 +260,6 @@ function collectRelatedSymbols(exportName, ...values) {
     }
     return [...related].sort((left, right) => left.localeCompare(right));
 }
-/***
- * Normalizes platform-specific path separators for generated documentation output.
- */
-function toPosixPath(path) {
-    return path.replaceAll('\\', '/');
-}
 /***
  * Returns unique items by a caller-provided key while preserving first occurrence order.
  */

package/dist/analyze/utils/normalizeTypeText.js

@@ -1,3 +1,4 @@
+import { toPortablePath } from '@ankhorage/utility/node/path';
 /***
  * Removes machine-specific absolute paths from TypeScript import type text.
  */
@@ -13,7 +14,7 @@ export function normalizeTypeText(typeText, packageRoot) {
     return normalized + typeText.slice(cursor);
 }
 function normalizeImportPath(importPath, packageRoot) {
-    const normalizedPath = toPosixPath(importPath);
+    const normalizedPath = toPortablePath(importPath);
     const nodeModulesMarker = '/node_modules/';
     const nodeModulesIndex = normalizedPath.lastIndexOf(nodeModulesMarker);
     if (nodeModulesIndex >= 0) {
@@ -22,12 +23,9 @@ function normalizeImportPath(importPath, packageRoot) {
     if (normalizedPath.startsWith('node_modules/')) {
         return normalizedPath.slice('node_modules/'.length);
     }
-    const normalizedRoot = packageRoot ? toPosixPath(packageRoot).replace(/\/$/, '') : null;
+    const normalizedRoot = packageRoot ? toPortablePath(packageRoot).replace(/\/$/, '') : null;
     if (normalizedRoot && normalizedPath.startsWith(`${normalizedRoot}/`)) {
         return `./${normalizedPath.slice(normalizedRoot.length + 1)}`;
     }
     return normalizedPath;
 }
-function toPosixPath(value) {
-    return value.replaceAll('\\', '/');
-}

package/dist/paths/policy.js

@@ -1,6 +1,7 @@
 import { access } from 'node:fs/promises';
 import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { toPortablePath } from '@ankhorage/utility/node/path';
 const CONFIG_FILENAMES = [
     'paradox.config.ts',
     'paradox.config.js',
@@ -105,7 +106,7 @@ function validateOutputDir(outputDir) {
  * Splits a configured path into normalized non-empty path segments.
  */
 function splitPathSegments(path) {
-    const normalized = path.replaceAll('\\', '/');
+    const normalized = toPortablePath(path);
     return normalized.split('/').filter((segment) => segment.length > 0 && segment !== '.');
 }
 /***

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.3",
+  "version": "0.2.5",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -71,8 +71,8 @@
     "test:standalone": "bun test tests/cli.e2e.test.ts"
   },
   "dependencies": {
-    "@ankhorage/policy": "^0.3.1",
-    "@ankhorage/utility": "^1.8.0",
+    "@ankhorage/policy": "^0.5.0",
+    "@ankhorage/utility": "^1.8.1",
     "ts-morph": "^28.0.0"
   },
   "devDependencies": {