@ankhorage/paradox 0.0.2 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.0.4
+
+### Patch Changes
+
+- f5b89ce: Stabilize Paradox config discovery and output path resolution so generated artifacts are written under the resolved package output directory.
+
+## 0.0.3
+
+### Patch Changes
+
+- d9fb959: Stabilize usage metadata, documentation model serialization, deterministic output ordering, and package entrypoint exports.
+
 ## 0.0.1
 
 ### Patch Changes

package/README.md

@@ -20,6 +20,15 @@ export default defineParadoxConfig({
 });
 ```
 
+## Path resolution
+
+- Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
+- Package root: defaults to the directory containing `paradox.config.*`; `package.root` (when relative) resolves relative to that directory.
+- Output directory: defaults to `paradox/`; `output.dir` (when relative) resolves relative to the resolved package root and must stay inside it.
+- Modes:
+  - `safe`: writes generated artifacts only under the output directory
+  - `write`: additionally updates `<packageRoot>/README.md`
+
 ## Public API
 
 ### defineParadoxConfig

package/dist/analyze/analyze.d.ts

@@ -0,0 +1,8 @@
+import type { ParadoxConfig } from '../config/types.js';
+import type { AnalysisResult } from './types.js';
+/***
+ * Runs the source analysis pipeline for a configured package.
+ */
+export declare function analyze(config: ParadoxConfig, runtime: {
+    packageRoot: string;
+}): Promise<AnalysisResult>;

package/dist/analyze/analyze.js

@@ -0,0 +1,34 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { analyzeComponents } from './components.js';
+import { analyzeExports } from './exports.js';
+import { createProject } from './project.js';
+import { createUsageFromPackageJson } from './usage.js';
+/***
+ * Runs the source analysis pipeline for a configured package.
+ */
+export async function analyze(config, runtime) {
+    const root = runtime.packageRoot;
+    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) {
+    const raw = await readFile(join(root, 'package.json'), 'utf-8');
+    return JSON.parse(raw);
+}

package/dist/analyze/components.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisComponent, AnalysisExport } from './types.js';
+/***
+ * Extracts React components and their props from analyzed exports.
+ */
+export declare function analyzeComponents(exports: readonly AnalysisExport[]): AnalysisComponent[];

package/dist/analyze/components.js

@@ -0,0 +1,21 @@
+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) {
+    const components = [];
+    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/dist/analyze/exports.d.ts

@@ -0,0 +1,16 @@
+import type { Project } from 'ts-morph';
+import type { AnalysisExport } from './types.js';
+interface AnalyzeExportsResult {
+    exports: AnalysisExport[];
+    config: {
+        exportName: string;
+    } | null;
+}
+/***
+ * Collects exported declarations from configured package entrypoints.
+ */
+export declare function analyzeExports(project: Project, options: {
+    root: string;
+    entrypoints: readonly string[];
+}): AnalyzeExportsResult;
+export {};

package/dist/analyze/exports.js

@@ -0,0 +1,52 @@
+import { isAbsolute, join, normalize } from 'node:path';
+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, options) {
+    const exports = [];
+    let 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, options) {
+    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) {
+    if ('getParameters' in node)
+        return 'function';
+    if ('getProperties' in node || 'getMembers' in node)
+        return 'type';
+    return 'unknown';
+}

package/dist/analyze/project.d.ts

@@ -0,0 +1,5 @@
+import { Project } from 'ts-morph';
+/***
+ * Creates the ts-morph project used by the analyzer.
+ */
+export declare function createProject(root: string): Project;

package/dist/analyze/project.js

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

package/dist/analyze/types.d.ts

@@ -0,0 +1,45 @@
+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/dist/analyze/types.js

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

package/dist/analyze/usage.d.ts

@@ -0,0 +1,7 @@
+import type { AnalysisUsage } from './types.js';
+export interface PackageJsonModel {
+    name: string;
+    description?: string;
+    bin?: string | Record<string, string>;
+}
+export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

package/dist/analyze/usage.js

@@ -0,0 +1,40 @@
+export function createUsageFromPackageJson(pkg) {
+    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) {
+    return packageName.split('/').pop() ?? packageName;
+}

package/dist/analyze/utils/getComponentPropsType.d.ts

@@ -0,0 +1,5 @@
+import { Node, type Type } from 'ts-morph';
+/***
+ * Returns the first parameter type for a React component declaration.
+ */
+export declare function getComponentPropsType(node: Node): Type | null;

package/dist/analyze/utils/getComponentPropsType.js

@@ -0,0 +1,21 @@
+import { Node } from 'ts-morph';
+/***
+ * Returns the first parameter type for a React component declaration.
+ */
+export function getComponentPropsType(node) {
+    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) {
+    if (Node.isFunctionDeclaration(node)) {
+        return node.getType().getCallSignatures()[0] ?? null;
+    }
+    if (Node.isVariableDeclaration(node)) {
+        return node.getType().getCallSignatures()[0] ?? null;
+    }
+    return null;
+}

package/dist/analyze/utils/getParadoxComment.d.ts

@@ -0,0 +1,5 @@
+import type { Node } from 'ts-morph';
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export declare function getParadoxComment(node: Node): string | null;

package/dist/analyze/utils/getParadoxComment.js

@@ -0,0 +1,19 @@
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export function getParadoxComment(node) {
+    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/dist/analyze/utils/getPropsFromType.d.ts

@@ -0,0 +1,6 @@
+import type { Type } from 'ts-morph';
+import type { AnalysisComponent } from '../types.js';
+/***
+ * Extracts prop names, types, required flags, and descriptions from a type.
+ */
+export declare function getPropsFromType(type: Type): AnalysisComponent['props'];

package/dist/analyze/utils/getPropsFromType.js

@@ -0,0 +1,19 @@
+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) {
+    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/dist/analyze/utils/isReactComponent.d.ts

@@ -0,0 +1,5 @@
+import { Node } from 'ts-morph';
+/***
+ * Detects simple React component declarations by name and return type.
+ */
+export declare function isReactComponent(node: Node): boolean;

package/dist/analyze/utils/isReactComponent.js

@@ -0,0 +1,30 @@
+import { Node } from 'ts-morph';
+/***
+ * Detects simple React component declarations by name and return type.
+ */
+export function isReactComponent(node) {
+    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) {
+    if (Node.isFunctionDeclaration(node))
+        return node.getName() ?? null;
+    if (Node.isVariableDeclaration(node))
+        return node.getName();
+    return null;
+}
+function getCallSignature(node) {
+    if (Node.isFunctionDeclaration(node)) {
+        return node.getType().getCallSignatures()[0] ?? null;
+    }
+    if (Node.isVariableDeclaration(node)) {
+        return node.getType().getCallSignatures()[0] ?? null;
+    }
+    return null;
+}

package/dist/analyze/utils/parseParadoxComment.d.ts

@@ -0,0 +1,12 @@
+/***
+ * Parsed representation of a Paradox doc comment.
+ */
+interface ParsedParadoxComment {
+    description: string | null;
+    isConfig: boolean;
+}
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export declare function parseParadoxComment(rawComment: string): ParsedParadoxComment;
+export {};

package/dist/analyze/utils/parseParadoxComment.js

@@ -0,0 +1,25 @@
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export function parseParadoxComment(rawComment) {
+    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/analyze/utils/resolveExportSymbol.ts → dist/analyze/utils/resolveExportSymbol.d.ts}

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

package/dist/analyze/utils/resolveExportSymbol.js

@@ -0,0 +1,6 @@
+/***
+ * Resolves aliased export symbols to their underlying declarations.
+ */
+export function resolveExportSymbol(symbol) {
+    return symbol.getAliasedSymbol() ?? symbol;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+import { dirname } from 'node:path';
+import { analyze } from './analyze/analyze.js';
+import { buildModel } from './model/buildModel.js';
+import { findParadoxConfigFile, loadParadoxConfig, resolveOutputRoot, resolvePackageRoot, } from './paths/policy.js';
+import { render } from './render/render.js';
+import { write } from './write/write.js';
+async function main() {
+    const cwd = process.cwd();
+    const configFilePath = await findParadoxConfigFile(cwd);
+    if (!configFilePath) {
+        throw new Error(`Unable to find Paradox config. Looked for paradox.config.{ts,js,mjs,cjs} by searching upward from: ${cwd}`);
+    }
+    const configDir = dirname(configFilePath);
+    const config = await loadParadoxConfig(configFilePath);
+    const packageRoot = await resolvePackageRoot(config, configDir);
+    const { outputRoot } = resolveOutputRoot(config, packageRoot);
+    const analysis = await analyze(config, { packageRoot });
+    const model = buildModel(analysis);
+    const result = render(model);
+    await write(result, config, { packageRoot, outputRoot });
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/{src/config/defineParadoxConfig.ts → dist/config/defineParadoxConfig.d.ts}

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

package/dist/config/defineParadoxConfig.js

@@ -0,0 +1,6 @@
+/***
+ * Defines a Paradox configuration object without changing its shape.
+ */
+export function defineParadoxConfig(config) {
+    return config;
+}

package/dist/config/types.d.ts

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

package/dist/config/types.js

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

package/dist/index.js

@@ -0,0 +1 @@
+export { defineParadoxConfig } from './config/defineParadoxConfig.js';

package/dist/model/buildModel.d.ts

@@ -0,0 +1,36 @@
+import type { DocumentationModel, ExportKind } 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 declare function buildModel(analysis: BuildModelInput): DocumentationModel;
+export {};

package/dist/model/buildModel.js

@@ -0,0 +1,65 @@
+/***
+ * Converts analysis output into a serializable documentation model.
+ */
+export function buildModel(analysis) {
+    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) {
+    return {
+        name: item.name,
+        description: item.description,
+        kind: item.kind,
+    };
+}
+function mapComponent(component) {
+    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, exportNames) {
+    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) {
+    const packageBaseName = packageId.split('/').pop() ?? packageId;
+    return `${packageBaseName}.config.ts`;
+}
+function sortByName(items) {
+    return [...items].sort((a, b) => a.name.localeCompare(b.name));
+}