@ankhorage/paradox 0.1.15 → 0.1.17

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.17
+
+### Patch Changes
+
+- 8eac93d: Support section-level README Usage prose through `docs.usage.description` without requiring a source-backed usage example.
+
+## 0.1.16
+
+### Patch Changes
+
+- 5bbc16a: Move the standalone executable into the canonical `src/cli/` folder while keeping the provider export at `src/cli/index.ts`.
+
 ## 0.1.15
 
 ### Patch Changes

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.15](./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.17](./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.
 
@@ -79,12 +79,12 @@ export default defineParadoxConfig({
 <details>
 <summary>Configuration options</summary>
 
-| Field   | Type                                                                                          | Required | Default | Description |
-| ------- | --------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
-| mode    | `'safe' \| 'write' \| undefined`                                                              | no       | —       |             |
-| docs    | `{ title?: string; description?: string; usage?: { entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
-| package | `{ root?: string; entrypoints?: string[]; } \| undefined`                                     | no       | —       |             |
-| output  | `{ dir?: string; } \| undefined`                                                              | no       | —       |             |
+| Field   | Type                                                                                                                | Required | Default | Description |
+| ------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ------- | ----------- |
+| mode    | `'safe' \| 'write' \| undefined`                                                                                    | no       | —       |             |
+| docs    | `{ title?: string; description?: string; usage?: { description?: string; entrypoints?: string[]; }; } \| undefined` | no       | —       |             |
+| package | `{ root?: string; entrypoints?: string[]; } \| undefined`                                                           | no       | —       |             |
+| output  | `{ dir?: string; } \| undefined`                                                                                    | no       | —       |             |
 
 </details>
 

package/dist/analyze/analyze.js

@@ -22,6 +22,7 @@ export async function analyze(config, runtime) {
     const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
+    const readmeUsageDescription = config.docs?.usage?.description ?? null;
     const usageEntryPoints = config.docs?.usage?.entrypoints ?? [];
     const readmeUsage = await analyzeReadmeUsage({ root, entrypoints: usageEntryPoints });
     const program = createTypeScriptProgram({ root, entrypoints, project });
@@ -67,6 +68,7 @@ export async function analyze(config, runtime) {
         badges,
         sequenceScenarios,
         usage,
+        readmeUsageDescription,
         readmeUsage,
         config: configMetadata
             ? {

package/dist/analyze/types.d.ts

@@ -163,6 +163,7 @@ export interface AnalysisResult {
     badges: AnalysisBadge[];
     sequenceScenarios: AnalysisSequenceScenario[];
     usage: AnalysisUsage | null;
+    readmeUsageDescription: string | null;
     readmeUsage: AnalysisReadmeUsage[];
     config: {
         exportName: string;

package/dist/{cli.js → cli/standalone.js}

@@ -1,10 +1,10 @@
 #!/usr/bin/env bun
 import { dirname } from 'node:path';
-import { analyze } from './analyze/analyze.js';
-import { buildModel } from './model/buildModel.js';
-import { findParadoxConfigFile, loadParadoxConfig, resolveOutputRoot, resolvePackageRoot, } from './paths/policy.js';
-import { render } from './render/render.js';
-import { write } from './write/write.js';
+import { analyze } from '../analyze/analyze.js';
+import { buildModel } from '../model/buildModel.js';
+import { findParadoxConfigFile, loadParadoxConfig, resolveOutputRoot, resolvePackageRoot, } from '../paths/policy.js';
+import { render } from '../render/render.js';
+import { write } from '../write/write.js';
 /***
  * Runs the Paradox CLI.
  *

package/dist/config/types.d.ts

@@ -10,6 +10,7 @@ export interface ParadoxConfig {
         title?: string;
         description?: string;
         usage?: {
+            description?: string;
             entrypoints?: string[];
         };
     };

package/dist/model/buildModel.d.ts

@@ -107,6 +107,7 @@ interface BuildModelInput {
             command: string;
         }[];
     } | null;
+    readmeUsageDescription: string | null;
     readmeUsage: {
         title: string | null;
         description: string | null;

package/dist/model/buildModel.js

@@ -24,6 +24,7 @@ export function buildModel(analysis) {
                 }))),
             }
             : null,
+        readmeUsageDescription: analysis.readmeUsageDescription,
         readmeUsage: analysis.readmeUsage
             .map((usageEntry) => ({
             title: usageEntry.title,

package/dist/model/types.d.ts

@@ -7,6 +7,7 @@ export interface DocumentationModel {
     description: string | null;
     badges: GeneratedBadge[];
     usage: UsageModel | null;
+    readmeUsageDescription: string | null;
     readmeUsage: ReadmeUsageModel[];
     config: ConfigModel | null;
     entrypoints: string[];

package/dist/render/renderers/markdown.js

@@ -23,7 +23,7 @@ function renderReadme(model, outputDir, badges, diagrams) {
     }
     if (model.description)
         lines.push(model.description, '');
-    renderReadmeUsage(lines, model.readmeUsage);
+    renderReadmeUsage(lines, model.readmeUsageDescription, model.readmeUsage);
     if (model.usage !== null) {
         lines.push('## Installation', '', '```bash');
         for (const command of model.usage.commands)
@@ -37,18 +37,20 @@ function renderReadme(model, outputDir, badges, diagrams) {
     renderReadmeApi(lines, model);
     return `${lines.join('\n').trimEnd()}\n`;
 }
-function renderReadmeUsage(lines, entries) {
-    if (entries.length === 0)
+function renderReadmeUsage(lines, description, entries) {
+    if (description === null && entries.length === 0)
         return;
     lines.push('## Usage', '');
+    if (description !== null)
+        lines.push(description, '');
     for (const entry of entries) {
         if (entry.title !== null)
             lines.push(`### ${entry.title}`, '');
         if (entry.description !== null) {
             const [, ...rest] = entry.description.split('\n');
-            const description = rest.join('\n').trim();
-            if (description.length > 0)
-                lines.push(description, '');
+            const entryDescription = rest.join('\n').trim();
+            if (entryDescription.length > 0)
+                lines.push(entryDescription, '');
         }
         lines.push(`Source: \`${entry.sourcePath}\``, '');
         lines.push(`\`\`\`${entry.language}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
@@ -43,7 +43,7 @@
     "LICENSE"
   ],
   "bin": {
-    "paradox": "./dist/cli.js"
+    "paradox": "./dist/cli/standalone.js"
   },
   "ankh": {
     "category": "docs",
@@ -56,7 +56,7 @@
     "build": "tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:status": "changeset status --since=origin/main",
-    "docs": "bun src/cli.ts",
+    "docs": "bun src/cli/standalone.ts",
     "docs:bunx": "bunx @ankhorage/paradox",
     "format": "ankhorage-prettier --write .",
     "format:check": "ankhorage-prettier --check .",