@ankhorage/paradox 0.0.1 → 0.0.2

package/.changeset/stable-usage-model.md

@@ -0,0 +1,5 @@
+---
+'@ankhorage/paradox': patch
+---
+
+Stabilize usage metadata, documentation model serialization, and deterministic output ordering.

package/knip.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://unpkg.com/knip@latest/schema.json",
+  "entry": ["src/index.ts", "eslint.config.mjs", ".prettierrc.js", "paradox.config.ts"],
+  "project": ["src/**/*.ts", "tests/**/*.ts"],
+  "ignore": ["tests/fixtures/**"],
+  "ignoreBinaries": ["eslint", "prettier"],
+  "ignoreUnresolved": ["bun-types"]
+}

package/package.json

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

package/paradox/paradox.json

@@ -2,6 +2,20 @@
   "packageName": "@ankhorage/paradox",
   "packageId": "@ankhorage/paradox",
   "description": "Deterministic documentation generator for TypeScript packages.",
+  "usage": {
+    "packageName": "@ankhorage/paradox",
+    "commands": [
+      {
+        "name": "paradox",
+        "command": "bunx @ankhorage/paradox"
+      }
+    ]
+  },
+  "config": {
+    "exportName": "ParadoxConfig",
+    "configFile": "paradox.config.ts",
+    "factoryName": "defineParadoxConfig"
+  },
   "exports": [
     {
       "name": "defineParadoxConfig",
@@ -14,13 +28,5 @@
       "kind": "type"
     }
   ],
-  "components": [],
-  "usage": {
-    "command": "bunx @ankhorage/paradox"
-  },
-  "config": {
-    "exportName": "ParadoxConfig",
-    "configFile": "paradox.config.ts",
-    "factoryName": "defineParadoxConfig"
-  }
+  "components": []
 }

package/src/analyze/analyze.ts

@@ -6,6 +6,7 @@ import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { createProject } from './project.js';
 import type { AnalysisResult } from './types.js';
+import { createUsageFromPackageJson, type PackageJsonModel } from './usage.js';
 
 /***
  * Runs the source analysis pipeline for a configured package.
@@ -14,11 +15,7 @@ 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 usage = createUsageFromPackageJson(pkg);
 
   const project = createProject(root);
   const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
@@ -41,16 +38,8 @@ export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
   };
 }
 
-async function readPackageJson(root: string): Promise<{
-  name: string;
-  description?: string;
-  bin?: string | Record<string, string>;
-}> {
+async function readPackageJson(root: string): Promise<PackageJsonModel> {
   const raw = await readFile(join(root, 'package.json'), 'utf-8');
 
-  return JSON.parse(raw) as {
-    name: string;
-    description?: string;
-    bin?: string | Record<string, string>;
-  };
+  return JSON.parse(raw) as PackageJsonModel;
 }

package/src/analyze/exports.ts

@@ -7,7 +7,7 @@ import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
 
-export interface AnalyzeExportsResult {
+interface AnalyzeExportsResult {
   exports: AnalysisExport[];
   config: {
     exportName: string;

package/src/analyze/types.ts

@@ -24,6 +24,16 @@ export interface AnalysisComponent {
   }[];
 }
 
+export interface AnalysisUsage {
+  packageName: string;
+  commands: AnalysisUsageCommand[];
+}
+
+export interface AnalysisUsageCommand {
+  name: string;
+  command: string;
+}
+
 /***
  * Complete analysis output used to build the documentation model.
  */
@@ -35,9 +45,7 @@ export interface AnalysisResult {
   exports: AnalysisExport[];
   components: AnalysisComponent[];
 
-  usage: {
-    command: string;
-  } | null;
+  usage: AnalysisUsage | null;
 
   config: {
     exportName: string;

package/src/analyze/usage.ts

@@ -0,0 +1,53 @@
+import type { AnalysisUsage } from './types.js';
+
+export interface PackageJsonModel {
+  name: string;
+  description?: string;
+  bin?: string | Record<string, string>;
+}
+
+export function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null {
+  if (pkg.bin == null) return null;
+
+  if (typeof pkg.bin === 'string') {
+    return {
+      packageName: pkg.name,
+      commands: [
+        {
+          name: getPackageBaseName(pkg.name),
+          command: `bunx ${pkg.name}`,
+        },
+      ],
+    };
+  }
+
+  const entries = Object.keys(pkg.bin).sort((a, b) => a.localeCompare(b));
+
+  if (entries.length === 0) return null;
+
+  if (entries.length === 1) {
+    const [name] = entries;
+
+    return {
+      packageName: pkg.name,
+      commands: [
+        {
+          name,
+          command: `bunx ${pkg.name}`,
+        },
+      ],
+    };
+  }
+
+  return {
+    packageName: pkg.name,
+    commands: entries.map((name) => ({
+      name,
+      command: `bunx ${pkg.name} ${name}`,
+    })),
+  };
+}
+
+function getPackageBaseName(packageName: string): string {
+  return packageName.split('/').pop() ?? packageName;
+}

package/src/analyze/utils/parseParadoxComment.ts

@@ -1,7 +1,7 @@
 /***
  * Parsed representation of a Paradox doc comment.
  */
-export interface ParsedParadoxComment {
+interface ParsedParadoxComment {
   description: string | null;
   isConfig: boolean;
 }

package/src/model/buildModel.ts

@@ -1,38 +1,94 @@
-import type { AnalysisResult } from '../analyze/types.js';
-import type { DocumentationModel } from './types.js';
+import type { ComponentModel, DocumentationModel, ExportKind, ExportModel } from './types.js';
+
+interface BuildModelInput {
+  packageName: string;
+  packageId: string;
+  description: string | null;
+  exports: {
+    name: string;
+    description: string | null;
+    kind: ExportKind;
+  }[];
+  components: {
+    name: string;
+    description: string | null;
+    props: {
+      name: string;
+      type: string;
+      required: boolean;
+      description: string | null;
+    }[];
+  }[];
+  usage: {
+    packageName: string;
+    commands: {
+      name: string;
+      command: string;
+    }[];
+  } | null;
+  config: {
+    exportName: string;
+  } | null;
+}
 
 /***
  * Converts analysis output into a serializable documentation model.
  */
-export function buildModel(analysis: AnalysisResult): DocumentationModel {
-  const exportsByName = new Map(
-    analysis.exports.map((item) => [
-      item.name,
-      {
-        name: item.name,
-        description: item.description,
-        kind: item.kind,
-      },
-    ]),
-  );
+export function buildModel(analysis: BuildModelInput): DocumentationModel {
+  const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item)]));
+  const exports = sortByName([...exportsByName.values()]);
 
   return {
     packageName: analysis.packageName,
     packageId: analysis.packageId,
     description: analysis.description,
-    exports: [...exportsByName.values()],
-    components: analysis.components,
-    usage: analysis.usage,
+    usage:
+      analysis.usage !== null
+        ? {
+            packageName: analysis.usage.packageName,
+            commands: sortByName(
+              analysis.usage.commands.map((command) => ({
+                name: command.name,
+                command: command.command,
+              })),
+            ),
+          }
+        : null,
     config:
       analysis.config !== null
         ? {
             exportName: analysis.config.exportName,
-            configFile: `${analysis.packageId.split('/').pop()}.config.ts`,
+            configFile: getDefaultConfigFileName(analysis.packageId),
             factoryName: findConfigFactoryName(analysis.config.exportName, [
               ...exportsByName.keys(),
             ]),
           }
         : null,
+    exports,
+    components: sortByName(analysis.components.map(mapComponent)),
+  };
+}
+
+function mapExport(item: BuildModelInput['exports'][number]): ExportModel {
+  return {
+    name: item.name,
+    description: item.description,
+    kind: item.kind,
+  };
+}
+
+function mapComponent(component: BuildModelInput['components'][number]): ComponentModel {
+  return {
+    name: component.name,
+    description: component.description,
+    props: sortByName(
+      component.props.map((prop) => ({
+        name: prop.name,
+        type: prop.type,
+        required: prop.required,
+        description: prop.description,
+      })),
+    ),
   };
 }
 
@@ -44,3 +100,13 @@ function findConfigFactoryName(configExportName: string, exportNames: string[]):
 
   return exportNames.includes(expectedFactoryName) ? expectedFactoryName : null;
 }
+
+function getDefaultConfigFileName(packageId: string): string {
+  const packageBaseName = packageId.split('/').pop() ?? packageId;
+
+  return `${packageBaseName}.config.ts`;
+}
+
+function sortByName<T extends { name: string }>(items: readonly T[]): T[] {
+  return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/model/types.ts

@@ -1,5 +1,3 @@
-import type { AnalysisComponent, AnalysisResult } from '../analyze/types.js';
-
 /***
  * Serializable model consumed by renderers and writers.
  */
@@ -7,22 +5,45 @@ export interface DocumentationModel {
   packageName: string;
   packageId: string;
   description: string | null;
-  exports: {
-    name: string;
-    description: string | null;
-    kind: string;
-  }[];
-  components: AnalysisComponent[];
-  usage: {
-    command: string;
-  } | null;
-  config: {
-    exportName: string;
-    configFile: string;
-    factoryName: string | null;
-  } | null;
+  usage: UsageModel | null;
+  config: ConfigModel | null;
+  exports: ExportModel[];
+  components: ComponentModel[];
 }
 
-export type SerializableAnalysisResult = Omit<AnalysisResult, 'exports'> & {
-  exports: DocumentationModel['exports'];
-};
+export interface UsageModel {
+  packageName: string;
+  commands: UsageCommandModel[];
+}
+
+export interface UsageCommandModel {
+  name: string;
+  command: string;
+}
+
+export interface ConfigModel {
+  exportName: string;
+  configFile: string;
+  factoryName: string | null;
+}
+
+export interface ExportModel {
+  name: string;
+  description: string | null;
+  kind: ExportKind;
+}
+
+export type ExportKind = 'function' | 'type' | 'unknown';
+
+export interface ComponentModel {
+  name: string;
+  description: string | null;
+  props: PropModel[];
+}
+
+export interface PropModel {
+  name: string;
+  type: string;
+  required: boolean;
+  description: string | null;
+}

package/src/render/render.ts

@@ -24,7 +24,9 @@ function renderReadme(model: DocumentationModel): string {
   if (model.usage !== null) {
     lines.push('## Usage', '');
     lines.push('```bash');
-    lines.push(model.usage.command);
+    for (const command of model.usage.commands) {
+      lines.push(command.command);
+    }
     lines.push('```', '');
   }
 

package/tests/__snapshots__/basic.components.md

@@ -6,5 +6,5 @@ Renders the fixture button component.
 
 | Prop | Type | Required | Description |
 | --- | --- | --- | --- |
-| label | `string` | yes | Visible button label. |
 | disabled | `boolean \| undefined` | no | Optional disabled state. |
+| label | `string` | yes | Visible button label. |

package/tests/__snapshots__/basic.exports.md

@@ -6,14 +6,14 @@ Kind: `function`
 
 Renders the fixture button component.
 
-## ToolConfig
+## ButtonProps
 
 Kind: `type`
 
-Configuration for the fixture package.
+Props accepted by the fixture button.
 
-## ButtonProps
+## ToolConfig
 
 Kind: `type`
 
-Props accepted by the fixture button.
+Configuration for the fixture package.

package/tests/__snapshots__/basic.readme.md

@@ -28,10 +28,10 @@ export default config;
 
 Renders the fixture button component.
 
-### ToolConfig
-
-Configuration for the fixture package.
-
 ### ButtonProps
 
 Props accepted by the fixture button.
+
+### ToolConfig
+
+Configuration for the fixture package.

package/tests/__snapshots__/multi-bin.readme.md

@@ -0,0 +1,16 @@
+# Multi Bin Fixture
+
+Fixture docs for multiple binaries.
+
+## Usage
+
+```bash
+bunx fixture-multi-bin alpha
+bunx fixture-multi-bin beta
+```
+
+## Public API
+
+### example
+
+Example public function.

package/tests/analyze.test.ts

@@ -4,10 +4,12 @@ import { join } from 'node:path';
 import { describe, expect, test } from 'bun:test';
 
 import { analyze } from '../src/analyze/analyze.js';
+import { createUsageFromPackageJson } from '../src/analyze/usage.js';
 import { buildModel } from '../src/model/buildModel.js';
 import { render } from '../src/render/render.js';
 
 const fixtureRoot = join(import.meta.dir, 'fixtures/basic');
+const multiBinFixtureRoot = join(import.meta.dir, 'fixtures/multi-bin');
 const snapshotRoot = join(import.meta.dir, '__snapshots__');
 
 describe('analyze', () => {
@@ -30,7 +32,13 @@ describe('analyze', () => {
     ]);
     expect(analysis.exports.map((item) => item.name)).not.toContain('internalHelper');
     expect(analysis.usage).toEqual({
-      command: 'bunx @fixture/basic',
+      packageName: '@fixture/basic',
+      commands: [
+        {
+          name: 'fixture-basic',
+          command: 'bunx @fixture/basic',
+        },
+      ],
     });
     expect(analysis.config).toEqual({
       exportName: 'ToolConfig',
@@ -63,6 +71,79 @@ describe('analyze', () => {
     await expectSnapshot('basic.exports.md', output.exportsMarkdown);
     await expectSnapshot('basic.components.md', output.components);
   });
+
+  test('renders multiple bin commands deterministically', async () => {
+    const analysis = await analyze({
+      docs: {
+        title: 'Multi Bin Fixture',
+        description: 'Fixture docs for multiple binaries.',
+      },
+      package: {
+        root: multiBinFixtureRoot,
+        entrypoints: ['src/index.ts'],
+      },
+    });
+
+    expect(analysis.usage).toEqual({
+      packageName: 'fixture-multi-bin',
+      commands: [
+        {
+          name: 'alpha',
+          command: 'bunx fixture-multi-bin alpha',
+        },
+        {
+          name: 'beta',
+          command: 'bunx fixture-multi-bin beta',
+        },
+      ],
+    });
+
+    const output = render(buildModel(analysis));
+
+    await expectSnapshot('multi-bin.readme.md', output.readme);
+  });
+
+  test('normalizes string bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: 'fixture-string-bin',
+        bin: './src/cli.ts',
+      }),
+    ).toEqual({
+      packageName: 'fixture-string-bin',
+      commands: [
+        {
+          name: 'fixture-string-bin',
+          command: 'bunx fixture-string-bin',
+        },
+      ],
+    });
+  });
+
+  test('normalizes missing bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: 'fixture-no-bin',
+      }),
+    ).toBeNull();
+  });
+
+  test('normalizes scoped string bin usage', () => {
+    expect(
+      createUsageFromPackageJson({
+        name: '@fixture/string-bin',
+        bin: './src/cli.ts',
+      }),
+    ).toEqual({
+      packageName: '@fixture/string-bin',
+      commands: [
+        {
+          name: 'string-bin',
+          command: 'bunx @fixture/string-bin',
+        },
+      ],
+    });
+  });
 });
 
 async function expectSnapshot(name: string, actual: string): Promise<void> {

package/tests/fixtures/multi-bin/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "fixture-multi-bin",
+  "description": "Fixture package with multiple binaries.",
+  "type": "module",
+  "bin": {
+    "beta": "./src/beta.ts",
+    "alpha": "./src/alpha.ts"
+  }
+}

package/tests/fixtures/multi-bin/src/alpha.ts

@@ -0,0 +1 @@
+export function alpha(): void {}

package/tests/fixtures/multi-bin/src/beta.ts

@@ -0,0 +1 @@
+export function beta(): void {}

package/tests/fixtures/multi-bin/src/index.ts

@@ -0,0 +1,4 @@
+/***
+ * Example public function.
+ */
+export function example(): void {}

package/tests/fixtures/multi-bin/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src/**/*.ts"]
+}