@ankhorage/paradox 0.0.1 → 0.0.3

package/dist/model/types.d.ts

@@ -0,0 +1,42 @@
+/***
+ * 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/dist/model/types.js

@@ -0,0 +1 @@
+export {};

package/dist/render/render.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentationModel } from '../model/types.js';
+import type { RenderResult } from './types.js';
+/***
+ * Renders the documentation model into README and artifact files.
+ */
+export declare function render(model: DocumentationModel): RenderResult;

package/dist/render/render.js

@@ -0,0 +1,88 @@
+/***
+ * Renders the documentation model into README and artifact files.
+ */
+export function render(model) {
+    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) {
+    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) {
+    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) {
+    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) {
+    return value.replaceAll('|', '\\|');
+}

package/dist/render/types.d.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/dist/render/types.js

@@ -0,0 +1 @@
+export {};

package/dist/write/write.d.ts

@@ -0,0 +1,6 @@
+import type { ParadoxConfig } from '../config/types.js';
+import type { RenderResult } from '../render/types.js';
+/***
+ * Writes generated documentation artifacts to the configured output paths.
+ */
+export declare function write(result: RenderResult, config: ParadoxConfig): Promise<void>;

package/dist/write/write.js

@@ -0,0 +1,18 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/***
+ * Writes generated documentation artifacts to the configured output paths.
+ */
+export async function write(result, config) {
+    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/package.json

@@ -1,17 +1,40 @@
 {
   "name": "@ankhorage/paradox",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Deterministic documentation generator for TypeScript packages.",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
+  "homepage": "https://github.com/ankhorage/paradox#readme",
+  "bugs": {
+    "url": "https://github.com/ankhorage/paradox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ankhorage/paradox.git"
+  },
   "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "bin": {
-    "paradox": "./src/cli.ts"
+    "paradox": "./dist/cli.js"
   },
   "scripts": {
-    "build": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
     "changeset": "changeset",
     "changeset:status": "changeset status --since=origin/main",
     "docs": "bun src/cli.ts",
@@ -20,6 +43,7 @@
     "format:check": "prettier --check .",
     "lint": "eslint . --max-warnings=0",
     "lint:fix": "eslint . --fix --max-warnings=0",
+    "prepack": "bun run build",
     "test": "bun test",
     "typecheck": "bun x tsc --noEmit -p tsconfig.json",
     "version-packages": "changeset version"

package/.changeset/README.md

@@ -1,5 +0,0 @@
-# Changesets
-
-This directory stores release notes consumed by Changesets.
-
-Run `bun run changeset` to create a new changeset before publishing a package change.

package/.changeset/config.json

@@ -1,11 +0,0 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
-  "changelog": "@changesets/cli/changelog",
-  "commit": false,
-  "fixed": [],
-  "linked": [],
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": []
-}

package/.github/workflows/docs.yml

@@ -1,45 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: '1.3.11'
-
-      - name: Install dependencies
-        run: bun install --frozen-lockfile
-
-      - name: Run lint
-        run: bun run lint
-
-      - name: Check formatting
-        run: bun run format:check
-
-      - name: Run typecheck
-        run: bun run typecheck
-
-      - name: Run tests
-        run: bun run test
-
-      - name: Check changesets
-        if: github.event_name == 'pull_request'
-        run: bun run changeset:status
-
-      - name: Generate docs
-        run: bun run docs
-
-      - name: Check generated docs
-        run: git diff --exit-code

package/.prettierignore

@@ -1 +0,0 @@
-tests/__snapshots__/*.md

package/.prettierrc.js

@@ -1,5 +0,0 @@
-import { createRequire } from 'node:module';
-
-const require = createRequire(import.meta.url);
-
-export default require('@ankhorage/devtools/prettier');