@ankhorage/paradox 0.1.18 → 0.1.19

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.19
+
+### Patch Changes
+
+- 5f6a40f: Generate the README CLI chapter from the canonical `src/cli/index.ts` `@readme` opt-in, keep executable commands under CLI instead of Installation, and declare the required Node.js types dependency.
+
 ## 0.1.18
 
 ### Patch Changes

package/README.md

@@ -3,18 +3,18 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.18](./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) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.19](./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) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
-## Installation
+## CLI
+
+Generates deterministic documentation for a package through the Paradox CLI.
 
 ```bash
 bunx @ankhorage/paradox
 ```
 
-## CLI
-
 <details>
 <summary>paradox</summary>
 
@@ -24,10 +24,6 @@ The command discovers the nearest Paradox config, resolves the package and outpu
 analyzes the package, builds the documentation model, renders all documentation artifacts,
 and writes them to the configured output directory.
 
-```bash
-bunx @ankhorage/paradox
-```
-
 Diagram: [paradox sequence](./paradox/diagrams/sequences/paradox.mmd)
 
 ```mermaid

package/dist/analyze/analyze.js

@@ -5,6 +5,7 @@ import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
+import { analyzeReadmeCli } from './readmeCli.js';
 import { analyzeReadmeConfig } from './readmeConfig.js';
 import { analyzeReadmeUsage } from './readmeUsage.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
@@ -26,6 +27,7 @@ export async function analyze(config, runtime) {
     const readmeUsageDescription = config.docs?.usage?.description ?? null;
     const usageEntryPoints = config.docs?.usage?.entrypoints ?? [];
     const readmeUsage = await analyzeReadmeUsage({ root, entrypoints: usageEntryPoints });
+    const readmeCli = await analyzeReadmeCli(root);
     const readmeConfig = await analyzeReadmeConfig({
         root,
         configFilePath: runtime.configFilePath ?? null,
@@ -75,6 +77,7 @@ export async function analyze(config, runtime) {
         usage,
         readmeUsageDescription,
         readmeUsage,
+        readmeCli,
         readmeConfig,
         config: configMetadata
             ? {

package/dist/analyze/readmeCli.d.ts

@@ -0,0 +1,9 @@
+export interface AnalysisReadmeCli {
+    description: string | null;
+    sourcePath: string;
+}
+/***
+ * Collects README CLI metadata from the canonical Ankhorage CLI entrypoint when its leading
+ * Paradox comment opts into README output with @readme.
+ */
+export declare function analyzeReadmeCli(root: string): Promise<AnalysisReadmeCli | null>;

package/dist/analyze/readmeCli.js

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getLeadingParadoxComment } from './utils/getLeadingParadoxComment.js';
+const CLI_INDEX_PATH = 'src/cli/index.ts';
+/***
+ * Collects README CLI metadata from the canonical Ankhorage CLI entrypoint when its leading
+ * Paradox comment opts into README output with @readme.
+ */
+export async function analyzeReadmeCli(root) {
+    const filePath = join(root, CLI_INDEX_PATH);
+    let source;
+    try {
+        source = await readFile(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return null;
+        throw error;
+    }
+    const comment = getLeadingParadoxComment(source);
+    if (!comment?.parsed.isReadme)
+        return null;
+    return {
+        description: comment.parsed.description,
+        sourcePath: CLI_INDEX_PATH,
+    };
+}
+function isMissingPathError(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code === 'ENOENT');
+}

package/dist/analyze/readmeConfig.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { extname, relative } from 'node:path';
-import { parseParadoxComment } from './utils/parseParadoxComment.js';
+import { getLeadingParadoxComment } from './utils/getLeadingParadoxComment.js';
 /***
  * Collects a README configuration example from the actual Paradox config file when its
  * leading Paradox comment is marked with both @config and @readme.
@@ -9,32 +9,19 @@ export async function analyzeReadmeConfig(options) {
     if (options.configFilePath === null)
         return null;
     const source = await readFile(options.configFilePath, 'utf-8');
-    const match = findLeadingParadoxComment(source);
-    if (match === null)
+    const comment = getLeadingParadoxComment(source);
+    if (comment === null)
         return null;
-    const parsed = parseParadoxComment(match.comment);
-    if (!parsed.isConfig || !parsed.isReadme)
+    if (!comment.parsed.isConfig || !comment.parsed.isReadme)
         return null;
     const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
     return {
-        description: parsed.description,
+        description: comment.parsed.description,
         language: getLanguage(sourcePath),
-        code: removeRange(source, match.start, match.end).trim(),
+        code: removeRange(source, comment.start, comment.end).trim(),
         sourcePath,
     };
 }
-function findLeadingParadoxComment(source) {
-    const match = /^\s*(\/\*\*\*[\s\S]*?\*\/)/.exec(source);
-    const comment = match?.[1];
-    if (match === null || comment === undefined)
-        return null;
-    const start = match[0].indexOf(comment);
-    return {
-        comment,
-        start,
-        end: start + comment.length,
-    };
-}
 function removeRange(source, start, end) {
     const before = source.slice(0, start).trimEnd();
     const after = source.slice(end).trimStart();

package/dist/analyze/types.d.ts

@@ -86,6 +86,10 @@ interface AnalysisReadmeUsage {
     code: string;
     sourcePath: string;
 }
+interface AnalysisReadmeCli {
+    description: string | null;
+    sourcePath: string;
+}
 interface AnalysisReadmeConfig {
     description: string | null;
     language: string;
@@ -171,6 +175,7 @@ export interface AnalysisResult {
     usage: AnalysisUsage | null;
     readmeUsageDescription: string | null;
     readmeUsage: AnalysisReadmeUsage[];
+    readmeCli: AnalysisReadmeCli | null;
     readmeConfig: AnalysisReadmeConfig | null;
     config: {
         exportName: string;

package/dist/analyze/usage.d.ts

@@ -11,6 +11,6 @@ export interface PackageJsonModel {
     prettier?: unknown;
 }
 /***
- * Builds installation and executable usage commands from package metadata.
+ * Builds executable CLI commands from package metadata.
  */
 export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

package/dist/analyze/usage.js

@@ -1,5 +1,5 @@
 /***
- * Builds installation and executable usage commands from package metadata.
+ * Builds executable CLI commands from package metadata.
  */
 export function createUsageFromPackageJson(pkg) {
     if (pkg.bin == null)

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

@@ -0,0 +1,10 @@
+import { type ParsedParadoxComment } from './parseParadoxComment.js';
+export interface LeadingParadoxComment {
+    parsed: ParsedParadoxComment;
+    start: number;
+    end: number;
+}
+/***
+ * Parses a leading Paradox comment from a source file.
+ */
+export declare function getLeadingParadoxComment(source: string): LeadingParadoxComment | null;

package/dist/analyze/utils/getLeadingParadoxComment.js

@@ -0,0 +1,16 @@
+import { parseParadoxComment } from './parseParadoxComment.js';
+/***
+ * Parses a leading Paradox comment from a source file.
+ */
+export function getLeadingParadoxComment(source) {
+    const match = /^\s*(\/\*\*\*[\s\S]*?\*\/)/.exec(source);
+    const comment = match?.[1];
+    if (match === null || comment === undefined)
+        return null;
+    const start = match[0].indexOf(comment);
+    return {
+        parsed: parseParadoxComment(comment),
+        start,
+        end: start + comment.length,
+    };
+}

package/dist/cli/index.d.ts

@@ -1 +1,6 @@
+/***
+ * Generates deterministic documentation for a package through the Paradox CLI.
+ *
+ * @readme
+ */
 export { default } from '../docsSurface.js';

package/dist/cli/index.js

@@ -1 +1,6 @@
+/***
+ * Generates deterministic documentation for a package through the Paradox CLI.
+ *
+ * @readme
+ */
 export { default } from '../docsSurface.js';

package/dist/cli/standalone.js

@@ -11,8 +11,6 @@ import { write } from '../write/write.js';
  * The command discovers the nearest Paradox config, resolves the package and output roots,
  * analyzes the package, builds the documentation model, renders all documentation artifacts,
  * and writes them to the configured output directory.
- *
- * @readme
  */
 async function main() {
     const cwd = process.cwd();

package/dist/model/buildModel.d.ts

@@ -115,6 +115,10 @@ interface BuildModelInput {
         code: string;
         sourcePath: string;
     }[];
+    readmeCli: {
+        description: string | null;
+        sourcePath: string;
+    } | null;
     readmeConfig: {
         description: string | null;
         language: string;

package/dist/model/buildModel.js

@@ -34,6 +34,12 @@ export function buildModel(analysis) {
             sourcePath: usageEntry.sourcePath,
         }))
             .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,

package/dist/model/types.d.ts

@@ -9,6 +9,7 @@ export interface DocumentationModel {
     usage: UsageModel | null;
     readmeUsageDescription: string | null;
     readmeUsage: ReadmeUsageModel[];
+    readmeCli: ReadmeCliModel | null;
     readmeConfig: ReadmeConfigModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
@@ -40,6 +41,10 @@ interface ReadmeUsageModel {
     code: string;
     sourcePath: string;
 }
+interface ReadmeCliModel {
+    description: string | null;
+    sourcePath: string;
+}
 interface ReadmeConfigModel {
     description: string | null;
     language: string;
@@ -89,6 +94,12 @@ export interface SequenceScenarioModel {
     description: string | null;
     isReadme: boolean;
 }
+export interface ModuleModel {
+    path: string;
+    isEntrypoint: boolean;
+    dependencies: string[];
+    exports: string[];
+}
 interface ExampleModel {
     title: string | null;
     language: string | null;
@@ -121,15 +132,6 @@ interface MemberModel {
     inheritedFrom?: string;
     children?: MemberModel[];
 }
-interface StructuredRowModel {
-    values: Record<string, string>;
-}
-export interface ModuleModel {
-    path: string;
-    isEntrypoint: boolean;
-    dependencies: string[];
-    exports: string[];
-}
 interface PropModel {
     name: string;
     type: string;
@@ -137,6 +139,9 @@ interface PropModel {
     defaultValue?: string;
     description: string | null;
 }
+interface StructuredRowModel {
+    values: Record<string, string>;
+}
 interface ConfigMemberModel {
     name: string;
     type: string;

package/dist/render/renderers/html.js

@@ -211,7 +211,7 @@ function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
         ${model.entrypoints.map((entrypoint) => `<li><code>${escapeHtml(entrypoint)}</code></li>`).join('')}
       </ul>
     </section>
-    ${cliScenarios.length > 0 ? renderCliPanel(model, diagrams, cliScenarios) : ''}
+    ${model.readmeCli !== null ? renderCliPanel(model, diagrams, cliScenarios) : ''}
     <section class="panel">
       <h2>Modules</h2>
       ${model.modules.map(renderModuleCard).join('')}
@@ -239,22 +239,33 @@ function renderHomeView(model, diagrams, cliScenarios, exportsByModule) {
  * 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(' ')}">
+    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 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(' '))}">
+        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>`}
-          ${command === undefined ? '' : `<pre>${escapeHtml(command.command)}</pre>`}
           ${diagram === undefined ? '' : renderDiagramCard(diagram)}
         </article>`;
     })
         .join('')}
   </section>`;
 }
+/***
+ * Renders one source file entry in the left navigation.
 /***
  * Renders one source file entry in the left navigation.
  */
@@ -299,8 +310,12 @@ function getSourceAreas(model) {
  * Selects bin scenarios that should be shown on the Home page.
  */
 function getReadmeCliScenarios(model) {
-    return model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
+    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.
  */

package/dist/render/renderers/markdown.js

@@ -24,13 +24,7 @@ function renderReadme(model, outputDir, badges, diagrams) {
     if (model.description)
         lines.push(model.description, '');
     renderReadmeUsage(lines, model.readmeUsageDescription, model.readmeUsage);
-    if (model.usage !== null) {
-        lines.push('## Installation', '', '```bash');
-        for (const command of model.usage.commands)
-            lines.push(command.command);
-        lines.push('```', '');
-    }
-    renderCliScenarios(lines, model, outputDir, diagrams);
+    renderReadmeCli(lines, model, outputDir, diagrams);
     renderConfiguration(lines, model);
     renderGeneratedDocumentation(lines, outputDir, diagrams);
     renderReadmeApi(lines, model);
@@ -57,23 +51,27 @@ function renderReadmeUsage(lines, description, entries) {
         lines.push('```', '');
     }
 }
-function renderCliScenarios(lines, model, outputDir, diagrams) {
-    const scenarios = model.sequenceScenarios.filter((scenario) => scenario.kind === 'bin' && scenario.isReadme);
-    if (scenarios.length === 0)
+function renderReadmeCli(lines, model, outputDir, diagrams) {
+    if (model.readmeCli === null)
         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, '');
-        const command = model.usage?.commands.find((item) => item.name === scenario.name);
-        if (command !== undefined) {
-            lines.push('```bash');
-            lines.push(command.command);
-            lines.push('```', '');
-        }
-        const diagram = findScenarioDiagram(diagrams, scenario);
         if (diagram !== undefined) {
             lines.push(`Diagram: [${diagram.title}](./${outputDir}/${diagram.path})`, '');
             lines.push('```mermaid');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.18",
+  "version": "0.1.19",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -75,7 +75,8 @@
     "@ankhorage/devtools": "^1.0.6",
     "@changesets/cli": "^2.31.0",
     "@types/bun": "^1.3.13",
-    "typescript": "^5.6.3"
+    "typescript": "^5.6.3",
+    "@types/node": "^25.6.0"
   },
   "packageManager": "bun@1.3.13"
 }