@ankhorage/paradox 0.0.2 → 0.0.4

package/eslint.config.mjs

@@ -1,12 +0,0 @@
-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/knip.json

@@ -1,8 +0,0 @@
-{
-  "$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/paradox/components.md

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

package/paradox/exports.json

@@ -1,12 +0,0 @@
-[
-  {
-    "name": "defineParadoxConfig",
-    "description": "Defines a Paradox configuration object without changing its shape.",
-    "kind": "function"
-  },
-  {
-    "name": "ParadoxConfig",
-    "description": "Configuration for running Paradox.",
-    "kind": "type"
-  }
-]

package/paradox/exports.md

@@ -1,13 +0,0 @@
-# Public API
-
-## defineParadoxConfig
-
-Kind: `function`
-
-Defines a Paradox configuration object without changing its shape.
-
-## ParadoxConfig
-
-Kind: `type`
-
-Configuration for running Paradox.

package/paradox/paradox.json

@@ -1,32 +0,0 @@
-{
-  "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",
-      "description": "Defines a Paradox configuration object without changing its shape.",
-      "kind": "function"
-    },
-    {
-      "name": "ParadoxConfig",
-      "description": "Configuration for running Paradox.",
-      "kind": "type"
-    }
-  ],
-  "components": []
-}

package/paradox.config.ts

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

@@ -1,45 +0,0 @@
-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';
-import { createUsageFromPackageJson, type PackageJsonModel } from './usage.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 usage = createUsageFromPackageJson(pkg);
-
-  const project = createProject(root);
-  const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
-
-  const { config: configMetadata, exports } = analyzeExports(project, {
-    root,
-    entrypoints,
-  });
-  const components = analyzeComponents(exports);
-
-  return {
-    packageName: config.docs?.title ?? pkg.name,
-    packageId: pkg.name,
-    description: config.docs?.description ?? pkg.description ?? null,
-
-    exports,
-    components,
-    usage,
-    config: configMetadata,
-  };
-}
-
-async function readPackageJson(root: string): Promise<PackageJsonModel> {
-  const raw = await readFile(join(root, 'package.json'), 'utf-8');
-
-  return JSON.parse(raw) as PackageJsonModel;
-}

package/src/analyze/components.ts

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

@@ -1,87 +0,0 @@
-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';
-
-interface AnalyzeExportsResult {
-  exports: AnalysisExport[];
-  config: {
-    exportName: string;
-  } | null;
-}
-
-/***
- * Collects exported declarations from configured package entrypoints.
- */
-export function analyzeExports(
-  project: Project,
-  options: {
-    root: string;
-    entrypoints: readonly string[];
-  },
-): AnalyzeExportsResult {
-  const exports: AnalysisExport[] = [];
-  let config: AnalyzeExportsResult['config'] = null;
-
-  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, isConfig: false };
-
-      if (parsed.isConfig) {
-        config = {
-          exportName: resolved.getName(),
-        };
-      }
-
-      exports.push({
-        name: resolved.getName(),
-        node: decl,
-        description: parsed.description,
-        kind: inferKind(decl),
-      });
-    }
-  }
-
-  return {
-    exports,
-    config,
-  };
-}
-
-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

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

@@ -1,53 +0,0 @@
-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;
-  }[];
-}
-
-export interface AnalysisUsage {
-  packageName: string;
-  commands: AnalysisUsageCommand[];
-}
-
-export interface AnalysisUsageCommand {
-  name: string;
-  command: string;
-}
-
-/***
- * Complete analysis output used to build the documentation model.
- */
-export interface AnalysisResult {
-  packageName: string;
-  packageId: string;
-  description: string | null;
-
-  exports: AnalysisExport[];
-  components: AnalysisComponent[];
-
-  usage: AnalysisUsage | null;
-
-  config: {
-    exportName: string;
-  } | null;
-}

package/src/analyze/usage.ts

@@ -1,53 +0,0 @@
-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/getComponentPropsType.ts

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

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

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

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

@@ -1,37 +0,0 @@
-/***
- * Parsed representation of a Paradox doc comment.
- */
-interface ParsedParadoxComment {
-  description: string | null;
-  isConfig: boolean;
-}
-
-/***
- * Parses a Paradox doc comment into structured metadata.
- */
-export function parseParadoxComment(rawComment: string): ParsedParadoxComment {
-  const lines = rawComment
-    .replace(/^\/\*\*\*/, '')
-    .replace(/\*\/$/, '')
-    .split('\n')
-    .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
-
-  let isConfig = false;
-
-  const description = lines
-    .filter((line) => {
-      if (line.trimStart().startsWith('@config')) {
-        isConfig = true;
-        return false;
-      }
-
-      return true;
-    })
-    .join('\n')
-    .trim();
-
-  return {
-    description: description.length > 0 ? description : null,
-    isConfig,
-  };
-}

package/src/cli.ts

@@ -1,30 +0,0 @@
-#!/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/types.ts

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