@ankhorage/paradox 0.0.2 → 0.0.4

package/src/model/buildModel.ts

@@ -1,112 +0,0 @@
-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: 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,
-    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: 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,
-      })),
-    ),
-  };
-}
-
-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;
-}
-
-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,49 +0,0 @@
-/***
- * Serializable model consumed by renderers and writers.
- */
-export interface DocumentationModel {
-  packageName: string;
-  packageId: string;
-  description: string | null;
-  usage: UsageModel | null;
-  config: ConfigModel | null;
-  exports: ExportModel[];
-  components: ComponentModel[];
-}
-
-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

@@ -1,115 +0,0 @@
-import type { DocumentationModel } from '../model/types.js';
-import type { RenderResult } from './types.js';
-
-/***
- * Renders the documentation model into README and artifact files.
- */
-export function render(model: DocumentationModel): RenderResult {
-  return {
-    readme: renderReadme(model),
-    exportsMarkdown: renderExports(model),
-    components: renderComponents(model),
-    exportsJson: `${JSON.stringify(model.exports, null, 2)}\n`,
-    paradoxJson: `${JSON.stringify(model, null, 2)}\n`,
-  };
-}
-
-function renderReadme(model: DocumentationModel): string {
-  const lines = [`# ${model.packageName}`, ''];
-
-  if (model.description) {
-    lines.push(model.description, '');
-  }
-
-  if (model.usage !== null) {
-    lines.push('## Usage', '');
-    lines.push('```bash');
-    for (const command of model.usage.commands) {
-      lines.push(command.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('## Public API', '');
-
-    for (const item of model.exports) {
-      lines.push(`### ${item.name}`, '');
-      lines.push(item.description ?? `\`${item.kind}\` export.`, '');
-    }
-  }
-
-  return `${lines.join('\n').trimEnd()}\n`;
-}
-
-function renderExports(model: DocumentationModel): string {
-  const lines = ['# Public API', ''];
-
-  for (const item of model.exports) {
-    lines.push(`## ${item.name}`, '');
-    lines.push(`Kind: \`${item.kind}\``, '');
-
-    if (item.description) {
-      lines.push(item.description, '');
-    }
-  }
-
-  return `${lines.join('\n').trimEnd()}\n`;
-}
-
-function renderComponents(model: DocumentationModel): string {
-  const lines = ['# Components', ''];
-
-  for (const component of model.components) {
-    lines.push(`## ${component.name}`, '');
-
-    if (component.description) {
-      lines.push(component.description, '');
-    }
-
-    if (component.props.length > 0) {
-      lines.push('| Prop | Type | Required | Description |');
-      lines.push('| --- | --- | --- | --- |');
-
-      for (const prop of component.props) {
-        lines.push(
-          `| ${escapeTableCell(prop.name)} | \`${escapeTableCell(prop.type)}\` | ${
-            prop.required ? 'yes' : 'no'
-          } | ${escapeTableCell(prop.description ?? '')} |`,
-        );
-      }
-
-      lines.push('');
-    }
-  }
-
-  return `${lines.join('\n').trimEnd()}\n`;
-}
-
-function escapeTableCell(value: string): string {
-  return value.replaceAll('|', '\\|');
-}

package/src/render/types.ts

@@ -1,10 +0,0 @@
-/***
- * Rendered documentation files ready to be written to disk.
- */
-export interface RenderResult {
-  readme: string;
-  exportsMarkdown: string;
-  components: string;
-  exportsJson: string;
-  paradoxJson: string;
-}

package/src/write/write.ts

@@ -1,25 +0,0 @@
-import { mkdir, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-
-import type { ParadoxConfig } from '../config/types.js';
-import type { RenderResult } from '../render/types.js';
-
-/***
- * Writes generated documentation artifacts to the configured output paths.
- */
-export async function write(result: RenderResult, config: ParadoxConfig): Promise<void> {
-  const root = config.package?.root ?? process.cwd();
-  const outputDir = config.output?.dir ?? 'paradox';
-  const mode = config.mode ?? 'safe';
-
-  await mkdir(join(root, outputDir), { recursive: true });
-
-  await writeFile(join(root, outputDir, 'exports.md'), result.exportsMarkdown);
-  await writeFile(join(root, outputDir, 'components.md'), result.components);
-  await writeFile(join(root, outputDir, 'exports.json'), result.exportsJson);
-  await writeFile(join(root, outputDir, 'paradox.json'), result.paradoxJson);
-
-  if (mode === 'write') {
-    await writeFile(join(root, 'README.md'), result.readme);
-  }
-}

package/tests/__snapshots__/basic.components.md

@@ -1,10 +0,0 @@
-# Components
-
-## Button
-
-Renders the fixture button component.
-
-| Prop | Type | Required | Description |
-| --- | --- | --- | --- |
-| disabled | `boolean \| undefined` | no | Optional disabled state. |
-| label | `string` | yes | Visible button label. |

package/tests/__snapshots__/basic.exports.md

@@ -1,19 +0,0 @@
-# Public API
-
-## Button
-
-Kind: `function`
-
-Renders the fixture button component.
-
-## ButtonProps
-
-Kind: `type`
-
-Props accepted by the fixture button.
-
-## ToolConfig
-
-Kind: `type`
-
-Configuration for the fixture package.

package/tests/__snapshots__/basic.readme.md

@@ -1,37 +0,0 @@
-# Fixture Docs
-
-Generated fixture docs.
-
-## 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.
-
-### ButtonProps
-
-Props accepted by the fixture button.
-
-### ToolConfig
-
-Configuration for the fixture package.

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

@@ -1,16 +0,0 @@
-# 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

@@ -1,153 +0,0 @@
-import { readFile } from 'node:fs/promises';
-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', () => {
-  test('builds documentation from package entrypoints', async () => {
-    const analysis = await analyze({
-      docs: {
-        title: 'Fixture Docs',
-        description: 'Generated fixture docs.',
-      },
-      package: {
-        root: fixtureRoot,
-        entrypoints: ['src/index.ts'],
-      },
-    });
-
-    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({
-      packageName: '@fixture/basic',
-      commands: [
-        {
-          name: 'fixture-basic',
-          command: 'bunx @fixture/basic',
-        },
-      ],
-    });
-    expect(analysis.config).toEqual({
-      exportName: 'ToolConfig',
-    });
-
-    expect(analysis.components).toEqual([
-      {
-        name: 'Button',
-        description: 'Renders the fixture button component.',
-        props: [
-          {
-            name: 'label',
-            type: 'string',
-            required: true,
-            description: 'Visible button label.',
-          },
-          {
-            name: 'disabled',
-            type: 'boolean | undefined',
-            required: false,
-            description: 'Optional disabled state.',
-          },
-        ],
-      },
-    ]);
-
-    const output = render(buildModel(analysis));
-
-    await expectSnapshot('basic.readme.md', output.readme);
-    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> {
-  const expected = await readFile(join(snapshotRoot, name), 'utf-8');
-
-  expect(actual.trimEnd()).toBe(expected.trimEnd());
-}

package/tests/fixtures/basic/package.json

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

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

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

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

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

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

@@ -1,6 +0,0 @@
-/***
- * Internal helper that must not appear in package exports.
- */
-export function internalHelper(): string {
-  return 'internal';
-}

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

@@ -1,29 +0,0 @@
-declare namespace JSX {
-  interface Element {
-    readonly type: string;
-  }
-}
-
-/***
- * Props accepted by the fixture button.
- */
-export interface ButtonProps {
-  /***
-   * Visible button label.
-   */
-  label: string;
-
-  /***
-   * Optional disabled state.
-   */
-  disabled?: boolean;
-}
-
-/***
- * Renders the fixture button component.
- */
-export function Button(props: ButtonProps): JSX.Element {
-  return {
-    type: props.disabled ? 'disabled-button' : 'button',
-  };
-}

package/tests/fixtures/basic/tsconfig.json

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

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

@@ -1,9 +0,0 @@
-{
-  "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

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

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

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

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

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

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

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

package/tsconfig.eslint.json

@@ -1,16 +0,0 @@
-{
-  "$schema": "https://json.schemastore.org/tsconfig",
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": ".",
-    "noEmit": true
-  },
-  "include": [
-    "src/**/*.ts",
-    "tests/**/*.ts",
-    "paradox.config.ts",
-    "eslint.config.mjs",
-    ".prettierrc.js"
-  ],
-  "exclude": ["dist", "node_modules"]
-}