@ankhorage/paradox 0.0.0

package/eslint.config.mjs

@@ -0,0 +1,12 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createConfig } from '@ankhorage/devtools/eslint';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default createConfig({
+  tsconfigRootDir: __dirname,
+  project: ['./tsconfig.eslint.json'],
+  files: ['src/**/*.ts', 'tests/*.ts', 'paradox.config.ts'],
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@ankhorage/paradox",
+  "version": "0.0.0",
+  "description": "Deterministic documentation generator for TypeScript packages.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "paradox": "./src/cli.ts"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "changeset": "changeset",
+    "changeset:status": "changeset status --since=origin/main",
+    "docs": "bun src/cli.ts",
+    "docs:bunx": "bunx @ankhorage/paradox",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "eslint . --max-warnings=0",
+    "lint:fix": "eslint . --fix --max-warnings=0",
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit -p tsconfig.json",
+    "version-packages": "changeset version"
+  },
+  "dependencies": {
+    "ts-morph": "^24.0.0"
+  },
+  "devDependencies": {
+    "@ankhorage/devtools": "^1.0.0",
+    "@changesets/cli": "^2.31.0",
+    "@types/bun": "^1.1.14",
+    "typescript": "^5.6.3"
+  }
+}

package/paradox/components.md

@@ -0,0 +1 @@
+# Components

package/paradox/exports.json

@@ -0,0 +1,57 @@
+[
+  {
+    "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.",
+    "kind": "function"
+  },
+  {
+    "name": "ParadoxConfig",
+    "description": "Configuration for running Paradox against a TypeScript package.",
+    "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

@@ -0,0 +1,67 @@
+# 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.
+
+## defineParadoxConfig
+
+Kind: `function`
+
+Defines a Paradox configuration object without changing its shape.
+
+## ParadoxConfig
+
+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.

package/paradox/paradox.json

@@ -0,0 +1,62 @@
+{
+  "packageName": "@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.",
+      "kind": "function"
+    },
+    {
+      "name": "ParadoxConfig",
+      "description": "Configuration for running Paradox against a TypeScript package.",
+      "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": []
+}

package/paradox.config.ts

@@ -0,0 +1,18 @@
+import { defineParadoxConfig } from './src/config/defineParadoxConfig.js';
+
+export default defineParadoxConfig({
+  mode: 'write',
+
+  docs: {
+    title: '@ankhorage/paradox',
+    description: 'Deterministic documentation generator for TypeScript packages.',
+  },
+
+  package: {
+    entrypoints: ['src/index.ts'],
+  },
+
+  output: {
+    dir: 'paradox',
+  },
+});

package/src/analyze/analyze.ts

@@ -0,0 +1,46 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type { ParadoxConfig } from '../config/types.js';
+import { analyzeComponents } from './components.js';
+import { analyzeExports } from './exports.js';
+import { createProject } from './project.js';
+import type { AnalysisResult } from './types.js';
+
+/***
+ * Runs the source analysis pipeline for a configured package.
+ */
+export async function analyze(config: ParadoxConfig): Promise<AnalysisResult> {
+  const root = config.package?.root ?? process.cwd();
+
+  const pkg = await readPackageJson(root);
+
+  const project = createProject(root);
+  const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
+
+  const exports = analyzeExports(project, {
+    root,
+    entrypoints,
+  });
+  const components = analyzeComponents(exports);
+
+  return {
+    packageName: config.docs?.title ?? pkg.name,
+    description: config.docs?.description ?? pkg.description ?? null,
+
+    exports,
+    components,
+  };
+}
+
+async function readPackageJson(root: string): Promise<{
+  name: string;
+  description?: string;
+}> {
+  const raw = await readFile(join(root, 'package.json'), 'utf-8');
+
+  return JSON.parse(raw) as {
+    name: string;
+    description?: string;
+  };
+}

package/src/analyze/components.ts

@@ -0,0 +1,27 @@
+import type { AnalysisComponent, AnalysisExport } from './types.js';
+import { getComponentPropsType } from './utils/getComponentPropsType.js';
+import { getPropsFromType } from './utils/getPropsFromType.js';
+import { isReactComponent } from './utils/isReactComponent.js';
+
+/***
+ * Extracts React components and their props from analyzed exports.
+ */
+export function analyzeComponents(exports: readonly AnalysisExport[]): AnalysisComponent[] {
+  const components: AnalysisComponent[] = [];
+
+  for (const e of exports) {
+    if (!isReactComponent(e.node)) continue;
+
+    const propsType = getComponentPropsType(e.node);
+
+    const props = propsType != null ? getPropsFromType(propsType) : [];
+
+    components.push({
+      name: e.name,
+      description: e.description,
+      props,
+    });
+  }
+
+  return components;
+}

package/src/analyze/exports.ts

@@ -0,0 +1,68 @@
+import { isAbsolute, join, normalize } from 'node:path';
+
+import type { Node, Project } from 'ts-morph';
+
+import type { AnalysisExport } from './types.js';
+import { getParadoxComment } from './utils/getParadoxComment.js';
+import { parseParadoxComment } from './utils/parseParadoxComment.js';
+import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
+
+/***
+ * Collects exported declarations from configured package entrypoints.
+ */
+export function analyzeExports(
+  project: Project,
+  options: {
+    root: string;
+    entrypoints: readonly string[];
+  },
+): AnalysisExport[] {
+  const exports: AnalysisExport[] = [];
+
+  for (const sourceFile of getEntryPointSourceFiles(project, options)) {
+    const exported = sourceFile.getExportSymbols();
+
+    for (const symbol of exported) {
+      const resolved = resolveExportSymbol(symbol);
+      const [decl] = resolved.getDeclarations();
+
+      const rawComment = getParadoxComment(decl);
+      const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+
+      exports.push({
+        name: resolved.getName(),
+        node: decl,
+        description: parsed.description,
+        kind: inferKind(decl),
+      });
+    }
+  }
+
+  return exports;
+}
+
+function getEntryPointSourceFiles(
+  project: Project,
+  options: {
+    root: string;
+    entrypoints: readonly string[];
+  },
+) {
+  return options.entrypoints
+    .map((entrypoint) => {
+      const absolutePath = normalize(
+        isAbsolute(entrypoint) ? entrypoint : join(options.root, entrypoint),
+      );
+
+      return project.getSourceFile(
+        (sourceFile) => normalize(sourceFile.getFilePath()) === absolutePath,
+      );
+    })
+    .filter((sourceFile) => sourceFile != null);
+}
+
+function inferKind(node: Node): AnalysisExport['kind'] {
+  if ('getParameters' in node) return 'function';
+  if ('getProperties' in node || 'getMembers' in node) return 'type';
+  return 'unknown';
+}

package/src/analyze/project.ts

@@ -0,0 +1,11 @@
+import { Project } from 'ts-morph';
+
+/***
+ * Creates the ts-morph project used by the analyzer.
+ */
+export function createProject(root: string): Project {
+  return new Project({
+    tsConfigFilePath: `${root}/tsconfig.json`,
+    skipAddingFilesFromTsConfig: false,
+  });
+}

package/src/analyze/types.ts

@@ -0,0 +1,36 @@
+import type { Node } from 'ts-morph';
+
+/***
+ * Describes one exported declaration discovered in a package.
+ */
+export interface AnalysisExport {
+  name: string;
+  node: Node;
+  description: string | null;
+  kind: 'function' | 'type' | 'unknown';
+}
+
+/***
+ * Describes one React component and its extracted props.
+ */
+export interface AnalysisComponent {
+  name: string;
+  description: string | null;
+  props: {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+  }[];
+}
+
+/***
+ * Complete analysis output used to build the documentation model.
+ */
+export interface AnalysisResult {
+  packageName: string;
+  description: string | null;
+
+  exports: AnalysisExport[];
+  components: AnalysisComponent[];
+}

package/src/analyze/utils/getComponentPropsType.ts

@@ -0,0 +1,26 @@
+import { Node, type Type } from 'ts-morph';
+
+/***
+ * Returns the first parameter type for a React component declaration.
+ */
+export function getComponentPropsType(node: Node): Type | null {
+  const callSignature = getCallSignature(node);
+  const firstParam = callSignature?.getParameters()[0];
+  const firstDecl = firstParam?.getDeclarations()[0];
+
+  if (firstDecl) return firstParam.getTypeAtLocation(firstDecl);
+
+  return null;
+}
+
+function getCallSignature(node: Node) {
+  if (Node.isFunctionDeclaration(node)) {
+    return node.getType().getCallSignatures()[0] ?? null;
+  }
+
+  if (Node.isVariableDeclaration(node)) {
+    return node.getType().getCallSignatures()[0] ?? null;
+  }
+
+  return null;
+}

package/src/analyze/utils/getParadoxComment.ts

@@ -0,0 +1,24 @@
+import type { Node } from 'ts-morph';
+
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export function getParadoxComment(node: Node): string | null {
+  const sourceFile = node.getSourceFile();
+  const text = sourceFile.getFullText();
+  const nodeStart = node.getStart(false);
+  const beforeNode = text.slice(0, nodeStart);
+  const commentStart = beforeNode.lastIndexOf('/***');
+
+  if (commentStart === -1) return null;
+
+  const commentEnd = text.indexOf('*/', commentStart);
+
+  if (commentEnd === -1 || commentEnd > nodeStart) return null;
+
+  const between = text.slice(commentEnd + 2, nodeStart);
+
+  if (!/^[\s;]*(export\s+)?(default\s+)?$/.test(between)) return null;
+
+  return text.slice(commentStart, commentEnd + 2);
+}

package/src/analyze/utils/getPropsFromType.ts

@@ -0,0 +1,24 @@
+import type { Type } from 'ts-morph';
+
+import type { AnalysisComponent } from '../types.js';
+import { getParadoxComment } from './getParadoxComment.js';
+import { parseParadoxComment } from './parseParadoxComment.js';
+
+/***
+ * Extracts prop names, types, required flags, and descriptions from a type.
+ */
+export function getPropsFromType(type: Type): AnalysisComponent['props'] {
+  return type.getProperties().map((property) => {
+    const [declaration] = property.getDeclarations();
+    const propertyType = property.getTypeAtLocation(declaration);
+    const rawComment = getParadoxComment(declaration);
+    const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+
+    return {
+      name: property.getName(),
+      type: propertyType.getText(declaration),
+      required: !property.isOptional(),
+      description: parsed.description,
+    };
+  });
+}

package/src/analyze/utils/isReactComponent.ts

@@ -0,0 +1,35 @@
+import { Node } from 'ts-morph';
+
+/***
+ * Detects simple React component declarations by name and return type.
+ */
+export function isReactComponent(node: Node): boolean {
+  const name = getDeclarationName(node);
+
+  if (!name || !/^[A-Z]/.test(name)) return false;
+
+  const callSignature = getCallSignature(node);
+  const returnType = callSignature?.getReturnType().getText() ?? null;
+
+  if (returnType == null) return false;
+
+  return /JSX\.Element|ReactElement|ReactNode|Element/.test(returnType);
+}
+
+function getDeclarationName(node: Node): string | null {
+  if (Node.isFunctionDeclaration(node)) return node.getName() ?? null;
+  if (Node.isVariableDeclaration(node)) return node.getName();
+  return null;
+}
+
+function getCallSignature(node: Node) {
+  if (Node.isFunctionDeclaration(node)) {
+    return node.getType().getCallSignatures()[0] ?? null;
+  }
+
+  if (Node.isVariableDeclaration(node)) {
+    return node.getType().getCallSignatures()[0] ?? null;
+  }
+
+  return null;
+}

package/src/analyze/utils/parseParadoxComment.ts

@@ -0,0 +1,23 @@
+/***
+ * Parsed representation of a Paradox doc comment.
+ */
+export interface ParsedParadoxComment {
+  description: string | null;
+}
+
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export function parseParadoxComment(rawComment: string): ParsedParadoxComment {
+  const body = rawComment
+    .replace(/^\/\*\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd())
+    .join('\n')
+    .trim();
+
+  return {
+    description: body.length > 0 ? body : null,
+  };
+}

package/src/analyze/utils/resolveExportSymbol.ts

@@ -0,0 +1,8 @@
+import type { Symbol } from 'ts-morph';
+
+/***
+ * Resolves aliased export symbols to their underlying declarations.
+ */
+export function resolveExportSymbol(symbol: Symbol): Symbol {
+  return symbol.getAliasedSymbol() ?? symbol;
+}

package/src/cli.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { analyze } from './analyze/analyze.js';
+import type { ParadoxConfig } from './config/types.js';
+import { buildModel } from './model/buildModel.js';
+import { render } from './render/render.js';
+import { write } from './write/write.js';
+
+async function main(): Promise<void> {
+  const config = await loadConfig(process.cwd());
+  const analysis = await analyze(config);
+  const model = buildModel(analysis);
+  const result = render(model);
+
+  await write(result, config);
+}
+
+async function loadConfig(root: string): Promise<ParadoxConfig> {
+  const configUrl = pathToFileURL(join(root, 'paradox.config.ts')).href;
+  const mod = (await import(configUrl)) as { default?: ParadoxConfig };
+
+  return mod.default ?? {};
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/config/defineParadoxConfig.ts

@@ -0,0 +1,8 @@
+import type { ParadoxConfig } from './types.js';
+
+/***
+ * Defines a Paradox configuration object without changing its shape.
+ */
+export function defineParadoxConfig(config: ParadoxConfig): ParadoxConfig {
+  return config;
+}

package/src/config/types.ts

@@ -0,0 +1,20 @@
+/***
+ * Configuration for running Paradox against a TypeScript package.
+ */
+export interface ParadoxConfig {
+  mode?: 'safe' | 'write';
+
+  docs?: {
+    title?: string;
+    description?: string;
+  };
+
+  package?: {
+    root?: string;
+    entrypoints?: string[];
+  };
+
+  output?: {
+    dir?: string;
+  };
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+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';