@ankhorage/paradox 0.0.0 → 0.0.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.0.1
+
+### Patch Changes
+
+- 17729fb: Add generated README usage and configuration sections from package metadata and `@config` doc tags.
+
 ## 0.0.0
 
 ### Initial Changes

package/README.md

@@ -2,23 +2,25 @@
 
 Deterministic documentation generator for TypeScript packages.
 
-## Package Exports
+## Usage
 
-### analyze
+```bash
+bunx @ankhorage/paradox
+```
 
-Runs the source analysis pipeline for a configured package.
+## Configuration
 
-### AnalysisComponent
+Create a `paradox.config.ts` file:
 
-Describes one React component and its extracted props.
+```ts
+import { defineParadoxConfig } from '@ankhorage/paradox';
 
-### AnalysisExport
+export default defineParadoxConfig({
+  // ...
+});
+```
 
-Describes one exported declaration discovered in a package.
-
-### AnalysisResult
-
-Complete analysis output used to build the documentation model.
+## Public API
 
 ### defineParadoxConfig
 
@@ -26,24 +28,4 @@ Defines a Paradox configuration object without changing its shape.
 
 ### ParadoxConfig
 
-Configuration for running Paradox against a TypeScript package.
-
-### buildModel
-
-Converts analysis output into a serializable documentation model.
-
-### DocumentationModel
-
-Serializable model consumed by renderers and writers.
-
-### render
-
-Renders the documentation model into README and artifact files.
-
-### RenderResult
-
-Rendered documentation files ready to be written to disk.
-
-### write
-
-Writes generated documentation artifacts to the configured output paths.
+Configuration for running Paradox.

package/package.json

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

package/paradox/exports.json

@@ -1,24 +1,4 @@
 [
-  {
-    "name": "analyze",
-    "description": "Runs the source analysis pipeline for a configured package.",
-    "kind": "function"
-  },
-  {
-    "name": "AnalysisComponent",
-    "description": "Describes one React component and its extracted props.",
-    "kind": "type"
-  },
-  {
-    "name": "AnalysisExport",
-    "description": "Describes one exported declaration discovered in a package.",
-    "kind": "type"
-  },
-  {
-    "name": "AnalysisResult",
-    "description": "Complete analysis output used to build the documentation model.",
-    "kind": "type"
-  },
   {
     "name": "defineParadoxConfig",
     "description": "Defines a Paradox configuration object without changing its shape.",
@@ -26,32 +6,7 @@
   },
   {
     "name": "ParadoxConfig",
-    "description": "Configuration for running Paradox against a TypeScript package.",
+    "description": "Configuration for running Paradox.",
     "kind": "type"
-  },
-  {
-    "name": "buildModel",
-    "description": "Converts analysis output into a serializable documentation model.",
-    "kind": "function"
-  },
-  {
-    "name": "DocumentationModel",
-    "description": "Serializable model consumed by renderers and writers.",
-    "kind": "type"
-  },
-  {
-    "name": "render",
-    "description": "Renders the documentation model into README and artifact files.",
-    "kind": "function"
-  },
-  {
-    "name": "RenderResult",
-    "description": "Rendered documentation files ready to be written to disk.",
-    "kind": "type"
-  },
-  {
-    "name": "write",
-    "description": "Writes generated documentation artifacts to the configured output paths.",
-    "kind": "function"
   }
 ]

package/paradox/exports.md

@@ -1,28 +1,4 @@
-# Package Exports
-
-## analyze
-
-Kind: `function`
-
-Runs the source analysis pipeline for a configured package.
-
-## AnalysisComponent
-
-Kind: `type`
-
-Describes one React component and its extracted props.
-
-## AnalysisExport
-
-Kind: `type`
-
-Describes one exported declaration discovered in a package.
-
-## AnalysisResult
-
-Kind: `type`
-
-Complete analysis output used to build the documentation model.
+# Public API
 
 ## defineParadoxConfig
 
@@ -34,34 +10,4 @@ Defines a Paradox configuration object without changing its shape.
 
 Kind: `type`
 
-Configuration for running Paradox against a TypeScript package.
-
-## buildModel
-
-Kind: `function`
-
-Converts analysis output into a serializable documentation model.
-
-## DocumentationModel
-
-Kind: `type`
-
-Serializable model consumed by renderers and writers.
-
-## render
-
-Kind: `function`
-
-Renders the documentation model into README and artifact files.
-
-## RenderResult
-
-Kind: `type`
-
-Rendered documentation files ready to be written to disk.
-
-## write
-
-Kind: `function`
-
-Writes generated documentation artifacts to the configured output paths.
+Configuration for running Paradox.

package/paradox/paradox.json

@@ -1,27 +1,8 @@
 {
   "packageName": "@ankhorage/paradox",
+  "packageId": "@ankhorage/paradox",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "exports": [
-    {
-      "name": "analyze",
-      "description": "Runs the source analysis pipeline for a configured package.",
-      "kind": "function"
-    },
-    {
-      "name": "AnalysisComponent",
-      "description": "Describes one React component and its extracted props.",
-      "kind": "type"
-    },
-    {
-      "name": "AnalysisExport",
-      "description": "Describes one exported declaration discovered in a package.",
-      "kind": "type"
-    },
-    {
-      "name": "AnalysisResult",
-      "description": "Complete analysis output used to build the documentation model.",
-      "kind": "type"
-    },
     {
       "name": "defineParadoxConfig",
       "description": "Defines a Paradox configuration object without changing its shape.",
@@ -29,34 +10,17 @@
     },
     {
       "name": "ParadoxConfig",
-      "description": "Configuration for running Paradox against a TypeScript package.",
+      "description": "Configuration for running Paradox.",
       "kind": "type"
-    },
-    {
-      "name": "buildModel",
-      "description": "Converts analysis output into a serializable documentation model.",
-      "kind": "function"
-    },
-    {
-      "name": "DocumentationModel",
-      "description": "Serializable model consumed by renderers and writers.",
-      "kind": "type"
-    },
-    {
-      "name": "render",
-      "description": "Renders the documentation model into README and artifact files.",
-      "kind": "function"
-    },
-    {
-      "name": "RenderResult",
-      "description": "Rendered documentation files ready to be written to disk.",
-      "kind": "type"
-    },
-    {
-      "name": "write",
-      "description": "Writes generated documentation artifacts to the configured output paths.",
-      "kind": "function"
     }
   ],
-  "components": []
+  "components": [],
+  "usage": {
+    "command": "bunx @ankhorage/paradox"
+  },
+  "config": {
+    "exportName": "ParadoxConfig",
+    "configFile": "paradox.config.ts",
+    "factoryName": "defineParadoxConfig"
+  }
 }

package/src/analyze/analyze.ts

@@ -14,11 +14,16 @@ export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
   const root = config.package?.root ?? process.cwd();
 
   const pkg = await readPackageJson(root);
+  const usage = pkg.bin
+    ? {
+        command: `bunx ${pkg.name}`,
+      }
+    : null;
 
   const project = createProject(root);
   const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
 
-  const exports = analyzeExports(project, {
+  const { config: configMetadata, exports } = analyzeExports(project, {
     root,
     entrypoints,
   });
@@ -26,21 +31,26 @@ export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
 
   return {
     packageName: config.docs?.title ?? pkg.name,
+    packageId: pkg.name,
     description: config.docs?.description ?? pkg.description ?? null,
 
     exports,
     components,
+    usage,
+    config: configMetadata,
   };
 }
 
 async function readPackageJson(root: string): Promise<{
   name: string;
   description?: string;
+  bin?: string | Record<string, string>;
 }> {
   const raw = await readFile(join(root, 'package.json'), 'utf-8');
 
   return JSON.parse(raw) as {
     name: string;
     description?: string;
+    bin?: string | Record<string, string>;
   };
 }

package/src/analyze/exports.ts

@@ -7,6 +7,13 @@ import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
 
+export interface AnalyzeExportsResult {
+  exports: AnalysisExport[];
+  config: {
+    exportName: string;
+  } | null;
+}
+
 /***
  * Collects exported declarations from configured package entrypoints.
  */
@@ -16,8 +23,9 @@ export function analyzeExports(
     root: string;
     entrypoints: readonly string[];
   },
-): AnalysisExport[] {
+): AnalyzeExportsResult {
   const exports: AnalysisExport[] = [];
+  let config: AnalyzeExportsResult['config'] = null;
 
   for (const sourceFile of getEntryPointSourceFiles(project, options)) {
     const exported = sourceFile.getExportSymbols();
@@ -27,7 +35,15 @@ export function analyzeExports(
       const [decl] = resolved.getDeclarations();
 
       const rawComment = getParadoxComment(decl);
-      const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+      const parsed = rawComment
+        ? parseParadoxComment(rawComment)
+        : { description: null, isConfig: false };
+
+      if (parsed.isConfig) {
+        config = {
+          exportName: resolved.getName(),
+        };
+      }
 
       exports.push({
         name: resolved.getName(),
@@ -38,7 +54,10 @@ export function analyzeExports(
     }
   }
 
-  return exports;
+  return {
+    exports,
+    config,
+  };
 }
 
 function getEntryPointSourceFiles(

package/src/analyze/types.ts

@@ -29,8 +29,17 @@ export interface AnalysisComponent {
  */
 export interface AnalysisResult {
   packageName: string;
+  packageId: string;
   description: string | null;
 
   exports: AnalysisExport[];
   components: AnalysisComponent[];
+
+  usage: {
+    command: string;
+  } | null;
+
+  config: {
+    exportName: string;
+  } | null;
 }

package/src/analyze/utils/parseParadoxComment.ts

@@ -3,21 +3,35 @@
  */
 export interface ParsedParadoxComment {
   description: string | null;
+  isConfig: boolean;
 }
 
 /***
  * Parses a Paradox doc comment into structured metadata.
  */
 export function parseParadoxComment(rawComment: string): ParsedParadoxComment {
-  const body = rawComment
+  const lines = rawComment
     .replace(/^\/\*\*\*/, '')
     .replace(/\*\/$/, '')
     .split('\n')
-    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd())
+    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+
+  let isConfig = false;
+
+  const description = lines
+    .filter((line) => {
+      if (line.trimStart().startsWith('@config')) {
+        isConfig = true;
+        return false;
+      }
+
+      return true;
+    })
     .join('\n')
     .trim();
 
   return {
-    description: body.length > 0 ? body : null,
+    description: description.length > 0 ? description : null,
+    isConfig,
   };
 }

package/src/config/types.ts

@@ -1,5 +1,7 @@
 /***
- * Configuration for running Paradox against a TypeScript package.
+ * Configuration for running Paradox.
+ *
+ * @config
  */
 export interface ParadoxConfig {
   mode?: 'safe' | 'write';

package/src/index.ts

@@ -1,9 +1,2 @@
-export { analyze } from './analyze/analyze.js';
-export type { AnalysisComponent, AnalysisExport, AnalysisResult } from './analyze/types.js';
 export { defineParadoxConfig } from './config/defineParadoxConfig.js';
 export type { ParadoxConfig } from './config/types.js';
-export { buildModel } from './model/buildModel.js';
-export type { DocumentationModel } from './model/types.js';
-export { render } from './render/render.js';
-export type { RenderResult } from './render/types.js';
-export { write } from './write/write.js';

package/src/model/buildModel.ts

@@ -18,8 +18,29 @@ export function buildModel(analysis: AnalysisResult): DocumentationModel {
 
   return {
     packageName: analysis.packageName,
+    packageId: analysis.packageId,
     description: analysis.description,
     exports: [...exportsByName.values()],
     components: analysis.components,
+    usage: analysis.usage,
+    config:
+      analysis.config !== null
+        ? {
+            exportName: analysis.config.exportName,
+            configFile: `${analysis.packageId.split('/').pop()}.config.ts`,
+            factoryName: findConfigFactoryName(analysis.config.exportName, [
+              ...exportsByName.keys(),
+            ]),
+          }
+        : null,
   };
 }
+
+function findConfigFactoryName(configExportName: string, exportNames: string[]): string | null {
+  const prefix = configExportName.endsWith('Config')
+    ? configExportName.slice(0, -'Config'.length)
+    : configExportName;
+  const expectedFactoryName = `define${prefix}Config`;
+
+  return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
+}

package/src/model/types.ts

@@ -5,6 +5,7 @@ import type { AnalysisComponent, AnalysisResult } from '../analyze/types.js';
  */
 export interface DocumentationModel {
   packageName: string;
+  packageId: string;
   description: string | null;
   exports: {
     name: string;
@@ -12,6 +13,14 @@ export interface DocumentationModel {
     kind: string;
   }[];
   components: AnalysisComponent[];
+  usage: {
+    command: string;
+  } | null;
+  config: {
+    exportName: string;
+    configFile: string;
+    factoryName: string | null;
+  } | null;
 }
 
 export type SerializableAnalysisResult = Omit<AnalysisResult, 'exports'> & {

package/src/render/render.ts

@@ -21,8 +21,39 @@ function renderReadme(model: DocumentationModel): string {
     lines.push(model.description, '');
   }
 
+  if (model.usage !== null) {
+    lines.push('## Usage', '');
+    lines.push('```bash');
+    lines.push(model.usage.command);
+    lines.push('```', '');
+  }
+
+  if (model.config !== null) {
+    lines.push('## Configuration', '');
+    lines.push(`Create a \`${model.config.configFile}\` file:`, '');
+    lines.push('```ts');
+
+    if (model.config.factoryName !== null) {
+      lines.push(`import { ${model.config.factoryName} } from '${model.packageId}';`);
+      lines.push('');
+      lines.push(`export default ${model.config.factoryName}({`);
+      lines.push('  // ...');
+      lines.push('});');
+    } else {
+      lines.push(`import type { ${model.config.exportName} } from '${model.packageId}';`);
+      lines.push('');
+      lines.push('const config = {');
+      lines.push('  // ...');
+      lines.push(`} satisfies ${model.config.exportName};`);
+      lines.push('');
+      lines.push('export default config;');
+    }
+
+    lines.push('```', '');
+  }
+
   if (model.exports.length > 0) {
-    lines.push('## Package Exports', '');
+    lines.push('## Public API', '');
 
     for (const item of model.exports) {
       lines.push(`### ${item.name}`, '');
@@ -34,7 +65,7 @@ function renderReadme(model: DocumentationModel): string {
 }
 
 function renderExports(model: DocumentationModel): string {
-  const lines = ['# Package Exports', ''];
+  const lines = ['# Public API', ''];
 
   for (const item of model.exports) {
     lines.push(`## ${item.name}`, '');

package/tests/__snapshots__/basic.exports.md

@@ -1,4 +1,4 @@
-# Package Exports
+# Public API
 
 ## Button
 
@@ -6,6 +6,12 @@ Kind: `function`
 
 Renders the fixture button component.
 
+## ToolConfig
+
+Kind: `type`
+
+Configuration for the fixture package.
+
 ## ButtonProps
 
 Kind: `type`

package/tests/__snapshots__/basic.readme.md

@@ -2,12 +2,36 @@
 
 Generated fixture docs.
 
-## Package Exports
+## Usage
+
+```bash
+bunx @fixture/basic
+```
+
+## Configuration
+
+Create a `basic.config.ts` file:
+
+```ts
+import type { ToolConfig } from '@fixture/basic';
+
+const config = {
+  // ...
+} satisfies ToolConfig;
+
+export default config;
+```
+
+## Public API
 
 ### Button
 
 Renders the fixture button component.
 
+### ToolConfig
+
+Configuration for the fixture package.
+
 ### ButtonProps
 
 Props accepted by the fixture button.

package/tests/analyze.test.ts

@@ -3,7 +3,9 @@ import { join } from 'node:path';
 
 import { describe, expect, test } from 'bun:test';
 
-import { analyze, buildModel, render } from '../src/index.js';
+import { analyze } from '../src/analyze/analyze.js';
+import { buildModel } from '../src/model/buildModel.js';
+import { render } from '../src/render/render.js';
 
 const fixtureRoot = join(import.meta.dir, 'fixtures/basic');
 const snapshotRoot = join(import.meta.dir, '__snapshots__');
@@ -21,8 +23,18 @@ describe('analyze', () => {
       },
     });
 
-    expect(analysis.exports.map((item) => item.name)).toEqual(['Button', 'ButtonProps']);
+    expect(analysis.exports.map((item) => item.name)).toEqual([
+      'Button',
+      'ToolConfig',
+      'ButtonProps',
+    ]);
     expect(analysis.exports.map((item) => item.name)).not.toContain('internalHelper');
+    expect(analysis.usage).toEqual({
+      command: 'bunx @fixture/basic',
+    });
+    expect(analysis.config).toEqual({
+      exportName: 'ToolConfig',
+    });
 
     expect(analysis.components).toEqual([
       {

package/tests/fixtures/basic/package.json

@@ -1,5 +1,8 @@
 {
   "name": "@fixture/basic",
   "description": "Fixture package for Paradox tests.",
-  "type": "module"
+  "type": "module",
+  "bin": {
+    "fixture-basic": "./src/index.ts"
+  }
 }

package/tests/fixtures/basic/src/config.ts

@@ -0,0 +1,8 @@
+/***
+ * Configuration for the fixture package.
+ *
+ * @config
+ */
+export interface ToolConfig {
+  enabled: boolean;
+}

package/tests/fixtures/basic/src/index.ts

@@ -1,2 +1,3 @@
 export { Button } from './ui.js';
+export type { ToolConfig } from './config.js';
 export type { ButtonProps } from './ui.js';