@ankhorage/paradox 0.1.16 → 0.1.18

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.18
+
+### Patch Changes
+
+- eaa56ad: Render README Configuration examples from the actual tagged Paradox config file instead of synthesized boilerplate.
+
+## 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

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.1.16](./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.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)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -66,25 +66,38 @@ sequenceDiagram
 
 ## Configuration
 
-Create a `paradox.config.ts` file:
+Canonical Paradox configuration for this package.
 
 ```ts
-import { defineParadoxConfig } from '@ankhorage/paradox';
+import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
 
 export default defineParadoxConfig({
-  // ...
+  mode: 'write',
+
+  docs: {
+    title: '@ankhorage/paradox',
+    description: 'Deterministic documentation generator for TypeScript packages.',
+  },
+
+  package: {
+    entrypoints: ['src/index.ts'],
+  },
+
+  output: {
+    dir: 'paradox',
+  },
 });
 ```
 
 <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.d.ts

@@ -5,4 +5,5 @@ import type { AnalysisResult } from './types.js';
  */
 export declare function analyze(config: ParadoxConfig, runtime: {
     packageRoot: string;
+    configFilePath?: string;
 }): Promise<AnalysisResult>;

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 { analyzeReadmeConfig } from './readmeConfig.js';
 import { analyzeReadmeUsage } from './readmeUsage.js';
 import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
 import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
@@ -22,8 +23,13 @@ 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 readmeConfig = await analyzeReadmeConfig({
+        root,
+        configFilePath: runtime.configFilePath ?? null,
+    });
     const program = createTypeScriptProgram({ root, entrypoints, project });
     const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
     const components = analyzeComponents(exports, { program });
@@ -67,7 +73,9 @@ export async function analyze(config, runtime) {
         badges,
         sequenceScenarios,
         usage,
+        readmeUsageDescription,
         readmeUsage,
+        readmeConfig,
         config: configMetadata
             ? {
                 exportName: configMetadata.exportName,

package/dist/analyze/readmeConfig.d.ts

@@ -0,0 +1,14 @@
+export interface AnalysisReadmeConfig {
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
+/***
+ * Collects a README configuration example from the actual Paradox config file when its
+ * leading Paradox comment is marked with both @config and @readme.
+ */
+export declare function analyzeReadmeConfig(options: {
+    root: string;
+    configFilePath: string | null;
+}): Promise<AnalysisReadmeConfig | null>;

package/dist/analyze/readmeConfig.js

@@ -0,0 +1,57 @@
+import { readFile } from 'node:fs/promises';
+import { extname, relative } from 'node:path';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+/***
+ * Collects a README configuration example from the actual Paradox config file when its
+ * leading Paradox comment is marked with both @config and @readme.
+ */
+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)
+        return null;
+    const parsed = parseParadoxComment(match.comment);
+    if (!parsed.isConfig || !parsed.isReadme)
+        return null;
+    const sourcePath = toPosixPath(relative(options.root, options.configFilePath));
+    return {
+        description: parsed.description,
+        language: getLanguage(sourcePath),
+        code: removeRange(source, match.start, match.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();
+    if (before.length === 0)
+        return after;
+    if (after.length === 0)
+        return before;
+    return `${before}\n\n${after}`;
+}
+function getLanguage(sourcePath) {
+    const extension = extname(sourcePath).toLowerCase();
+    if (extension === '.ts')
+        return 'ts';
+    if (extension === '.js' || extension === '.mjs' || extension === '.cjs')
+        return 'js';
+    return '';
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/types.d.ts

@@ -86,6 +86,12 @@ interface AnalysisReadmeUsage {
     code: string;
     sourcePath: string;
 }
+interface AnalysisReadmeConfig {
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
 export interface AnalysisBadge {
     id: string;
     label: string;
@@ -163,7 +169,9 @@ export interface AnalysisResult {
     badges: AnalysisBadge[];
     sequenceScenarios: AnalysisSequenceScenario[];
     usage: AnalysisUsage | null;
+    readmeUsageDescription: string | null;
     readmeUsage: AnalysisReadmeUsage[];
+    readmeConfig: AnalysisReadmeConfig | null;
     config: {
         exportName: string;
         isReadme: boolean;

package/dist/cli/standalone.js

@@ -24,7 +24,7 @@ async function main() {
     const config = await loadParadoxConfig(configFilePath);
     const packageRoot = await resolvePackageRoot(config, configDir);
     const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
-    const analysis = await analyze(config, { packageRoot });
+    const analysis = await analyze(config, { packageRoot, configFilePath });
     const model = buildModel(analysis);
     const result = render(model, { outputDir });
     await write(result, config, { packageRoot, outputRoot });

package/dist/config/types.d.ts

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

package/dist/doc-tags/registry.d.ts

@@ -8,8 +8,8 @@ export declare const PARADOX_DOC_TAGS: readonly [{
 }, {
     readonly name: "config";
     readonly syntax: "@config";
-    readonly 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.";
-    readonly appliesTo: readonly ["interface", "type"];
+    readonly description: "Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.";
+    readonly appliesTo: readonly ["block", "interface", "type"];
     readonly repeatable: false;
     readonly handler: "markConfig";
 }, {

package/dist/doc-tags/registry.js

@@ -19,8 +19,8 @@ export const PARADOX_DOC_TAGS = [
     {
         name: 'config',
         syntax: '@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.',
-        appliesTo: ['interface', 'type'],
+        description: 'Marks a configuration type, interface, or source block. Pair with @readme to include the schema or actual config source in README Configuration output.',
+        appliesTo: ['block', 'interface', 'type'],
         repeatable: false,
         handler: 'markConfig',
     },

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;
@@ -114,6 +115,12 @@ interface BuildModelInput {
         code: string;
         sourcePath: string;
     }[];
+    readmeConfig: {
+        description: string | null;
+        language: string;
+        code: string;
+        sourcePath: string;
+    } | null;
     config: {
         exportName: string;
         isReadme: boolean;

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,
@@ -33,14 +34,18 @@ export function buildModel(analysis) {
             sourcePath: usageEntry.sourcePath,
         }))
             .sort((left, right) => left.sourcePath.localeCompare(right.sourcePath)),
+        readmeConfig: analysis.readmeConfig !== null
+            ? {
+                description: analysis.readmeConfig.description,
+                language: analysis.readmeConfig.language,
+                code: analysis.readmeConfig.code,
+                sourcePath: analysis.readmeConfig.sourcePath,
+            }
+            : null,
         config: analysis.config !== null
             ? {
                 exportName: analysis.config.exportName,
                 isReadme: analysis.config.isReadme,
-                configFile: getDefaultConfigFileName(analysis.packageId),
-                factoryName: findConfigFactoryName(analysis.config.exportName, [
-                    ...exportsByName.keys(),
-                ]),
                 members: analysis.config.members,
             }
             : null,
@@ -149,23 +154,6 @@ function mapComponent(component, exportModel) {
         }))),
     };
 }
-/***
- * Finds the conventional config factory export for a config type when present.
- */
-function findConfigFactoryName(configExportName, exportNames) {
-    const prefix = configExportName.endsWith('Config')
-        ? configExportName.slice(0, -'Config'.length)
-        : configExportName;
-    const expectedFactoryName = `define${prefix}Config`;
-    return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
-}
-/***
- * Derives the default config file name from a package id.
- */
-function getDefaultConfigFileName(packageId) {
-    const packageBaseName = packageId.split('/').pop() ?? packageId;
-    return `${packageBaseName}.config.ts`;
-}
 /***
  * Returns a copy of items sorted by their `name` property.
  */

package/dist/model/types.d.ts

@@ -7,7 +7,9 @@ export interface DocumentationModel {
     description: string | null;
     badges: GeneratedBadge[];
     usage: UsageModel | null;
+    readmeUsageDescription: string | null;
     readmeUsage: ReadmeUsageModel[];
+    readmeConfig: ReadmeConfigModel | null;
     config: ConfigModel | null;
     entrypoints: string[];
     modules: ModuleModel[];
@@ -38,11 +40,15 @@ interface ReadmeUsageModel {
     code: string;
     sourcePath: string;
 }
+interface ReadmeConfigModel {
+    description: string | null;
+    language: string;
+    code: string;
+    sourcePath: string;
+}
 interface ConfigModel {
     exportName: string;
     isReadme: boolean;
-    configFile: string;
-    factoryName: string | null;
     members: ConfigMemberModel[];
 }
 export interface ExportModel {

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)
@@ -31,24 +31,25 @@ function renderReadme(model, outputDir, badges, diagrams) {
         lines.push('```', '');
     }
     renderCliScenarios(lines, model, outputDir, diagrams);
-    if (model.config?.isReadme)
-        renderConfiguration(lines, model);
+    renderConfiguration(lines, model);
     renderGeneratedDocumentation(lines, outputDir, 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}`);
@@ -86,30 +87,19 @@ function findScenarioDiagram(diagrams, scenario) {
     return diagrams.find((diagram) => diagram.path === `diagrams/sequences/${toFileStem(scenario.name)}.mmd`);
 }
 function renderConfiguration(lines, model) {
-    const { config } = model;
-    if (config === null)
+    const config = model.config?.isReadme ? model.config : null;
+    const example = model.readmeConfig;
+    if (config === null && example === null)
         return;
     lines.push('## Configuration', '');
-    lines.push(`Create a \`${config.configFile}\` file:`, '');
-    lines.push('```ts');
-    if (config.factoryName !== null) {
-        lines.push(`import { ${config.factoryName} } from '${model.packageId}';`);
-        lines.push('');
-        lines.push(`export default ${config.factoryName}({`);
-        lines.push('  // ...');
-        lines.push('});');
-    }
-    else {
-        lines.push(`import type { ${config.exportName} } from '${model.packageId}';`);
-        lines.push('');
-        lines.push('const config = {');
-        lines.push('  // ...');
-        lines.push(`} satisfies ${config.exportName};`);
-        lines.push('');
-        lines.push('export default config;');
+    if (example !== null) {
+        if (example.description !== null)
+            lines.push(example.description, '');
+        lines.push(`\`\`\`${example.language}`);
+        lines.push(example.code);
+        lines.push('```', '');
     }
-    lines.push('```', '');
-    if (config.members.length === 0)
+    if (config === null || config.members.length === 0)
         return;
     lines.push('<details>');
     lines.push('<summary>Configuration options</summary>', '');

package/package.json

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