@ankhorage/paradox 0.0.0

package/src/model/buildModel.ts

@@ -0,0 +1,25 @@
+import type { AnalysisResult } from '../analyze/types.js';
+import type { DocumentationModel } from './types.js';
+
+/***
+ * 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,
+      },
+    ]),
+  );
+
+  return {
+    packageName: analysis.packageName,
+    description: analysis.description,
+    exports: [...exportsByName.values()],
+    components: analysis.components,
+  };
+}

package/src/model/types.ts

@@ -0,0 +1,19 @@
+import type { AnalysisComponent, AnalysisResult } from '../analyze/types.js';
+
+/***
+ * Serializable model consumed by renderers and writers.
+ */
+export interface DocumentationModel {
+  packageName: string;
+  description: string | null;
+  exports: {
+    name: string;
+    description: string | null;
+    kind: string;
+  }[];
+  components: AnalysisComponent[];
+}
+
+export type SerializableAnalysisResult = Omit<AnalysisResult, 'exports'> & {
+  exports: DocumentationModel['exports'];
+};

package/src/render/render.ts

@@ -0,0 +1,82 @@
+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.exports.length > 0) {
+    lines.push('## Package Exports', '');
+
+    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 = ['# Package Exports', ''];
+
+  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

@@ -0,0 +1,10 @@
+/***
+ * 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

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

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

package/tests/__snapshots__/basic.exports.md

@@ -0,0 +1,13 @@
+# Package Exports
+
+## Button
+
+Kind: `function`
+
+Renders the fixture button component.
+
+## ButtonProps
+
+Kind: `type`
+
+Props accepted by the fixture button.

package/tests/__snapshots__/basic.readme.md

@@ -0,0 +1,13 @@
+# Fixture Docs
+
+Generated fixture docs.
+
+## Package Exports
+
+### Button
+
+Renders the fixture button component.
+
+### ButtonProps
+
+Props accepted by the fixture button.

package/tests/analyze.test.ts

@@ -0,0 +1,60 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { describe, expect, test } from 'bun:test';
+
+import { analyze, buildModel, render } from '../src/index.js';
+
+const fixtureRoot = join(import.meta.dir, 'fixtures/basic');
+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', 'ButtonProps']);
+    expect(analysis.exports.map((item) => item.name)).not.toContain('internalHelper');
+
+    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);
+  });
+});
+
+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

@@ -0,0 +1,5 @@
+{
+  "name": "@fixture/basic",
+  "description": "Fixture package for Paradox tests.",
+  "type": "module"
+}

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

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

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

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

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

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

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

package/tsconfig.eslint.json

@@ -0,0 +1,16 @@
+{
+  "$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"]
+}

package/tsconfig.json

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