@ankhorage/paradox 0.0.5 → 0.0.7

package/dist/analyze/types.d.ts

@@ -2,11 +2,41 @@ import type { Node } from 'ts-morph';
 /***
  * Describes one exported declaration discovered in a package.
  */
+export interface AnalysisSourceLocation {
+    filePath: string;
+    line: number;
+    column: number;
+}
+export interface AnalysisParameter {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface AnalysisSignature {
+    label: string;
+    parameters: AnalysisParameter[];
+    returnType: string | null;
+    returnDescription: string | null;
+}
+export interface AnalysisMember {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+}
 export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
     kind: 'function' | 'type' | 'unknown';
+    modulePath: string;
+    sourceLocation: AnalysisSourceLocation;
+    exportPaths: string[];
+    relatedSymbols: string[];
+    signatures: AnalysisSignature[];
+    members: AnalysisMember[];
 }
 /***
  * Describes one React component and its extracted props.
@@ -14,6 +44,9 @@ export interface AnalysisExport {
 export interface AnalysisComponent {
     name: string;
     description: string | null;
+    modulePath: string;
+    sourceLocation: AnalysisSourceLocation;
+    exportPaths: string[];
     props: {
         name: string;
         type: string;
@@ -29,6 +62,18 @@ export interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
+export interface AnalysisBadge {
+    id: string;
+    label: string;
+    value: string;
+    color: string;
+}
+export interface AnalysisModule {
+    path: string;
+    isEntrypoint: boolean;
+    dependencies: string[];
+    exports: string[];
+}
 /***
  * Complete analysis output used to build the documentation model.
  */
@@ -38,6 +83,9 @@ export interface AnalysisResult {
     description: string | null;
     exports: AnalysisExport[];
     components: AnalysisComponent[];
+    entrypoints: string[];
+    modules: AnalysisModule[];
+    badges: AnalysisBadge[];
     usage: AnalysisUsage | null;
     config: {
         exportName: string;

package/dist/analyze/usage.d.ts

@@ -2,6 +2,12 @@ import type { AnalysisUsage } from './types.js';
 export interface PackageJsonModel {
     name: string;
     description?: string;
+    version?: string;
+    license?: string;
+    packageManager?: string;
     bin?: string | Record<string, string>;
+    scripts?: Record<string, string>;
+    eslintConfig?: unknown;
+    prettier?: unknown;
 }
 export declare function createUsageFromPackageJson(pkg: PackageJsonModel): AnalysisUsage | null;

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

@@ -0,0 +1,12 @@
+import { Node, type Symbol as MorphSymbol } from 'ts-morph';
+import type { AnalysisExport } from '../types.js';
+/***
+ * Extracts computed metadata for an exported declaration.
+ */
+export declare function getExportMetadata(options: {
+    name: string;
+    node: Node;
+    root: string;
+    entrypointPath: string;
+    symbol: MorphSymbol;
+}): Pick<AnalysisExport, 'exportPaths' | 'members' | 'modulePath' | 'relatedSymbols' | 'signatures' | 'sourceLocation'>;

package/dist/analyze/utils/getExportMetadata.js

@@ -0,0 +1,162 @@
+import { relative } from 'node:path';
+import { Node, } from 'ts-morph';
+import { getParadoxComment } from './getParadoxComment.js';
+import { parseParadoxComment } from './parseParadoxComment.js';
+/***
+ * Extracts computed metadata for an exported declaration.
+ */
+export function getExportMetadata(options) {
+    const modulePath = toPosixPath(relative(options.root, options.node.getSourceFile().getFilePath()));
+    const sourceLocation = getSourceLocation(options.node, options.root);
+    const signatures = getSignatures(options.symbol, options.node);
+    const members = getMembers(options.node);
+    const relatedSymbols = collectRelatedSymbols(options.name, signatures.flatMap((signature) => [
+        ...signature.parameters.map((parameter) => parameter.type),
+        signature.returnType,
+    ]), members.map((member) => member.type));
+    return {
+        modulePath,
+        sourceLocation,
+        exportPaths: [options.entrypointPath],
+        relatedSymbols,
+        signatures,
+        members,
+    };
+}
+function getSourceLocation(node, root) {
+    const sourceFile = node.getSourceFile();
+    const { column, line } = sourceFile.getLineAndColumnAtPos(node.getStart(false));
+    return {
+        filePath: toPosixPath(relative(root, sourceFile.getFilePath())),
+        line,
+        column,
+    };
+}
+function getSignatures(symbol, node) {
+    const parsed = readParadoxMetadata(node);
+    const signatures = getCallableDeclarations(symbol, node).map((declaration) => getSignature(declaration, parsed.params, parsed.returns));
+    return uniqueBy(signatures.filter((signature) => signature.parameters.length > 0 ||
+        signature.returnType !== null ||
+        signature.returnDescription !== null), (signature) => signature.label);
+}
+function getSignature(declaration, params, returns) {
+    const normalizedParameters = declaration.getParameters().map((parameter) => {
+        const parameterDescription = params[parameter.getName()];
+        return {
+            name: parameter.getName(),
+            type: parameter.getType().getText(parameter),
+            required: !parameter.isOptional(),
+            description: parameterDescription ? parameterDescription.trim() : null,
+        };
+    });
+    const returnType = declaration.getReturnType().getText(declaration);
+    const parameterLabel = normalizedParameters
+        .map((parameter) => `${parameter.name}${parameter.required ? '' : '?'}: ${parameter.type}`)
+        .join(', ');
+    return {
+        label: `(${parameterLabel})${returnType === 'void' ? '' : ` => ${returnType}`}`,
+        parameters: normalizedParameters,
+        returnType,
+        returnDescription: returns,
+    };
+}
+function getMembers(node) {
+    if (getCallableNode(node) !== null)
+        return [];
+    return node
+        .getType()
+        .getProperties()
+        .map((property) => {
+        const [declaration] = property.getDeclarations();
+        const rawComment = getParadoxComment(declaration);
+        const parsed = rawComment
+            ? parseParadoxComment(rawComment)
+            : { description: null, isConfig: false, params: {}, returns: null };
+        return {
+            name: property.getName(),
+            kind: isMemberMethodDeclaration(declaration) ? 'method' : 'property',
+            type: property.getTypeAtLocation(declaration).getText(declaration),
+            required: !property.isOptional(),
+            description: parsed.description,
+        };
+    });
+}
+function getCallableDeclarations(symbol, node) {
+    const declarations = symbol
+        .getDeclarations()
+        .map((declaration) => getCallableNode(declaration))
+        .filter((declaration) => declaration !== null);
+    if (declarations.length > 0) {
+        return declarations;
+    }
+    const callableNode = getCallableNode(node);
+    return callableNode !== null ? [callableNode] : [];
+}
+function getCallableNode(node) {
+    if (Node.isFunctionDeclaration(node))
+        return node;
+    if (Node.isMethodDeclaration(node))
+        return node;
+    if (Node.isMethodSignature(node))
+        return node;
+    if (Node.isArrowFunction(node))
+        return node;
+    if (Node.isFunctionExpression(node))
+        return node;
+    if (Node.isVariableDeclaration(node)) {
+        const initializer = node.getInitializer();
+        if (initializer &&
+            (Node.isArrowFunction(initializer) || Node.isFunctionExpression(initializer))) {
+            return initializer;
+        }
+    }
+    return null;
+}
+function isMemberMethodDeclaration(node) {
+    return Node.isMethodDeclaration(node) || Node.isMethodSignature(node);
+}
+function readParadoxMetadata(node) {
+    const rawComment = getParadoxComment(node);
+    return rawComment
+        ? parseParadoxComment(rawComment)
+        : { description: null, isConfig: false, params: {}, returns: null };
+}
+function collectRelatedSymbols(exportName, ...values) {
+    const candidates = values.flatMap((entries) => entries).filter((entry) => entry !== null);
+    const related = new Set();
+    for (const value of candidates) {
+        for (const symbol of value.matchAll(/\b[A-Z][A-Za-z0-9_]*\b/g)) {
+            const [candidate] = symbol;
+            if (!IGNORED_RELATED_SYMBOLS.has(candidate) && candidate !== exportName) {
+                related.add(candidate);
+            }
+        }
+    }
+    return [...related].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}
+function uniqueBy(items, key) {
+    const seen = new Set();
+    return items.filter((item) => {
+        const itemKey = key(item);
+        if (seen.has(itemKey))
+            return false;
+        seen.add(itemKey);
+        return true;
+    });
+}
+const IGNORED_RELATED_SYMBOLS = new Set([
+    'Array',
+    'Boolean',
+    'Date',
+    'Element',
+    'JSX',
+    'Map',
+    'Promise',
+    'ReadonlyArray',
+    'Record',
+    'Set',
+    'String',
+]);

package/dist/analyze/utils/getPropsFromType.js

@@ -8,7 +8,9 @@ export function getPropsFromType(type) {
         const [declaration] = property.getDeclarations();
         const propertyType = property.getTypeAtLocation(declaration);
         const rawComment = getParadoxComment(declaration);
-        const parsed = rawComment ? parseParadoxComment(rawComment) : { description: null };
+        const parsed = rawComment
+            ? parseParadoxComment(rawComment)
+            : { description: null, isConfig: false, params: {}, returns: null };
         return {
             name: property.getName(),
             type: propertyType.getText(declaration),

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

@@ -4,6 +4,8 @@
 interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
+    params: Record<string, string>;
+    returns: string | null;
 }
 /***
  * Parses a Paradox doc comment into structured metadata.

package/dist/analyze/utils/parseParadoxComment.js

@@ -8,12 +8,28 @@ export function parseParadoxComment(rawComment) {
         .split('\n')
         .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
     let isConfig = false;
+    const params = {};
+    let returns = null;
     const description = lines
         .filter((line) => {
-        if (line.trimStart().startsWith('@config')) {
+        const trimmed = line.trimStart();
+        if (trimmed.startsWith('@config')) {
             isConfig = true;
             return false;
         }
+        if (trimmed.startsWith('@param ')) {
+            const paramBody = trimmed.slice('@param '.length).trim();
+            const [name, ...descriptionParts] = paramBody.split(/\s+/);
+            if (name) {
+                params[name] = descriptionParts.join(' ').trim();
+            }
+            return false;
+        }
+        if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
+            const returnBody = trimmed.replace(/^@returns?/, '').trim();
+            returns = returnBody.length > 0 ? returnBody : null;
+            return false;
+        }
         return true;
     })
         .join('\n')
@@ -21,5 +37,7 @@ export function parseParadoxComment(rawComment) {
     return {
         description: description.length > 0 ? description : null,
         isConfig,
+        params,
+        returns,
     };
 }

package/dist/cli.js

@@ -14,10 +14,10 @@ async function main() {
     const configDir = dirname(configFilePath);
     const config = await loadParadoxConfig(configFilePath);
     const packageRoot = await resolvePackageRoot(config, configDir);
-    const { outputRoot } = resolveOutputRoot(config, packageRoot);
+    const { outputDir, outputRoot } = resolveOutputRoot(config, packageRoot);
     const analysis = await analyze(config, { packageRoot });
     const model = buildModel(analysis);
-    const result = render(model);
+    const result = render(model, { outputDir });
     await write(result, config, { packageRoot, outputRoot });
 }
 main().catch((error) => {

package/dist/model/buildModel.d.ts

@@ -3,14 +3,53 @@ interface BuildModelInput {
     packageName: string;
     packageId: string;
     description: string | null;
+    badges: {
+        id: string;
+        label: string;
+        value: string;
+        color: string;
+    }[];
     exports: {
         name: string;
         description: string | null;
         kind: ExportKind;
+        modulePath: string;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+        exportPaths: string[];
+        relatedSymbols: string[];
+        signatures: {
+            label: string;
+            parameters: {
+                name: string;
+                type: string;
+                required: boolean;
+                description: string | null;
+            }[];
+            returnType: string | null;
+            returnDescription: string | null;
+        }[];
+        members: {
+            name: string;
+            kind: 'property' | 'method';
+            type: string;
+            required: boolean;
+            description: string | null;
+        }[];
     }[];
     components: {
         name: string;
         description: string | null;
+        modulePath: string;
+        sourceLocation: {
+            filePath: string;
+            line: number;
+            column: number;
+        };
+        exportPaths: string[];
         props: {
             name: string;
             type: string;
@@ -28,6 +67,13 @@ interface BuildModelInput {
     config: {
         exportName: string;
     } | null;
+    entrypoints: string[];
+    modules: {
+        path: string;
+        isEntrypoint: boolean;
+        dependencies: string[];
+        exports: string[];
+    }[];
 }
 /***
  * Converts analysis output into a serializable documentation model.

package/dist/model/buildModel.js

@@ -2,12 +2,19 @@
  * 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 exportNames = new Set(analysis.exports.map((item) => item.name));
+    const exportsByName = new Map(analysis.exports.map((item) => [item.name, mapExport(item, exportNames)]));
     const exports = sortByName([...exportsByName.values()]);
     return {
         packageName: analysis.packageName,
         packageId: analysis.packageId,
         description: analysis.description,
+        badges: analysis.badges.map((badge) => ({
+            id: badge.id,
+            label: badge.label,
+            value: badge.value,
+            color: badge.color,
+        })),
         usage: analysis.usage !== null
             ? {
                 packageName: analysis.usage.packageName,
@@ -26,21 +33,65 @@ export function buildModel(analysis) {
                 ]),
             }
             : null,
+        entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
+        modules: [...analysis.modules]
+            .map((module) => ({
+            path: module.path,
+            isEntrypoint: module.isEntrypoint,
+            dependencies: [...module.dependencies].sort((a, b) => a.localeCompare(b)),
+            exports: [...module.exports].sort((a, b) => a.localeCompare(b)),
+        }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
-        components: sortByName(analysis.components.map(mapComponent)),
+        components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
     };
 }
-function mapExport(item) {
+function mapExport(item, exportNames) {
     return {
         name: item.name,
         description: item.description,
         kind: item.kind,
+        modulePath: item.modulePath,
+        sourceLocation: {
+            filePath: item.sourceLocation.filePath,
+            line: item.sourceLocation.line,
+            column: item.sourceLocation.column,
+        },
+        exportPaths: [...item.exportPaths].sort((a, b) => a.localeCompare(b)),
+        relatedSymbols: item.relatedSymbols
+            .filter((symbol) => exportNames.has(symbol))
+            .sort((a, b) => a.localeCompare(b)),
+        signatures: item.signatures.map((signature) => ({
+            label: signature.label,
+            parameters: sortByName(signature.parameters.map((parameter) => ({
+                name: parameter.name,
+                type: parameter.type,
+                required: parameter.required,
+                description: parameter.description,
+            }))),
+            returnType: signature.returnType,
+            returnDescription: signature.returnDescription,
+        })),
+        members: sortByName(item.members.map((member) => ({
+            name: member.name,
+            kind: member.kind,
+            type: member.type,
+            required: member.required,
+            description: member.description,
+        }))),
     };
 }
-function mapComponent(component) {
+function mapComponent(component, exportModel) {
     return {
         name: component.name,
         description: component.description,
+        modulePath: component.modulePath,
+        sourceLocation: {
+            filePath: component.sourceLocation.filePath,
+            line: component.sourceLocation.line,
+            column: component.sourceLocation.column,
+        },
+        exportPaths: exportModel?.exportPaths ?? [...component.exportPaths].sort((a, b) => a.localeCompare(b)),
         props: sortByName(component.props.map((prop) => ({
             name: prop.name,
             type: prop.type,

package/dist/model/types.d.ts

@@ -5,11 +5,20 @@ export interface DocumentationModel {
     packageName: string;
     packageId: string;
     description: string | null;
+    badges: GeneratedBadge[];
     usage: UsageModel | null;
     config: ConfigModel | null;
+    entrypoints: string[];
+    modules: ModuleModel[];
     exports: ExportModel[];
     components: ComponentModel[];
 }
+export interface GeneratedBadge {
+    id: string;
+    label: string;
+    value: string;
+    color: string;
+}
 export interface UsageModel {
     packageName: string;
     commands: UsageCommandModel[];
@@ -27,13 +36,52 @@ export interface ExportModel {
     name: string;
     description: string | null;
     kind: ExportKind;
+    modulePath: string;
+    sourceLocation: SourceLocationModel;
+    exportPaths: string[];
+    relatedSymbols: string[];
+    signatures: SignatureModel[];
+    members: MemberModel[];
 }
 export type ExportKind = 'function' | 'type' | 'unknown';
 export interface ComponentModel {
     name: string;
     description: string | null;
+    modulePath: string;
+    sourceLocation: SourceLocationModel;
+    exportPaths: string[];
     props: PropModel[];
 }
+export interface SourceLocationModel {
+    filePath: string;
+    line: number;
+    column: number;
+}
+export interface SignatureModel {
+    label: string;
+    parameters: ParameterModel[];
+    returnType: string | null;
+    returnDescription: string | null;
+}
+export interface ParameterModel {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface MemberModel {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+}
+export interface ModuleModel {
+    path: string;
+    isEntrypoint: boolean;
+    dependencies: string[];
+    exports: string[];
+}
 export interface PropModel {
     name: string;
     type: string;

package/dist/render/render.d.ts

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