@ankhorage/paradox 0.0.9 → 0.1.0

package/dist/analyze/semantic/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/semantic/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/semantic/model.d.ts

@@ -0,0 +1,109 @@
+import type { Node, Project, SourceFile, Symbol, Type, TypeChecker } from 'ts-morph';
+export interface AnalyzedProgram {
+    project: Project;
+    typeChecker: TypeChecker;
+    root: string;
+    entrypoints: string[];
+    entrypointFilePaths: string[];
+}
+export interface AnalyzedFile {
+    path: string;
+    sourceFile: SourceFile;
+    isEntrypoint: boolean;
+}
+export interface AnalyzedDocBlock {
+    id: string;
+    sourcePath: string;
+    start: number;
+    end: number;
+    line: number;
+    column: number;
+    raw: string;
+    description: string | null;
+    params: Record<string, string>;
+    returns: string | null;
+    tags: AnalyzedTag[];
+}
+export interface AnalyzedTag {
+    name: string;
+    value: string | null;
+}
+export type AnalyzedExportKind = 'function' | 'component' | 'class' | 'interface' | 'type' | 'const' | 'hook' | 'unknown';
+export interface AnalyzedExport {
+    name: string;
+    sourcePath: string;
+    exportPaths: string[];
+    kind: AnalyzedExportKind;
+    signature?: string;
+    docBlock?: AnalyzedDocBlock;
+    tags: AnalyzedTag[];
+    props?: AnalyzedProps;
+    typeMembers?: AnalyzedTypeMember[];
+    relatedTypes: string[];
+    node: Node;
+    symbol: Symbol;
+}
+export interface ResolvedTypeReference {
+    type: Type;
+    name: string | null;
+    sourcePath: string | null;
+    symbol: Symbol | null;
+}
+export interface AnalyzedProps {
+    typeName: string;
+    sourcePath: string | null;
+    members: AnalyzedProp[];
+}
+export interface AnalyzedProp {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue?: string;
+    description?: string;
+    inheritedFrom?: string;
+}
+export interface AnalyzedTypeMember {
+    name: string;
+    type: string;
+    required: boolean;
+    description?: string;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalyzedTypeMember[];
+}
+export interface ImportEdge {
+    fromPath: string;
+    toPath: string;
+    sourcePath: string;
+}
+export interface CallEdge {
+    fromSymbol: string;
+    toSymbol: string;
+    callExpression: string;
+    sourcePath: string;
+}
+interface TypeReferenceEdge {
+    fromSymbol: string;
+    toType: string;
+    sourcePath: string;
+}
+export interface ComponentCompositionEdge {
+    fromComponent: string;
+    toComponent: string;
+    jsxElement: string;
+    sourcePath: string;
+}
+interface AnalyzedGraphs {
+    imports: ImportEdge[];
+    calls: CallEdge[];
+    typeReferences: TypeReferenceEdge[];
+    componentComposition: ComponentCompositionEdge[];
+}
+export interface AnalyzedProject {
+    files: AnalyzedFile[];
+    exports: AnalyzedExport[];
+    docBlocks: AnalyzedDocBlock[];
+    tags: AnalyzedTag[];
+    graphs: AnalyzedGraphs;
+}
+export {};

package/dist/analyze/semantic/model.js

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

package/dist/analyze/semantic/paradoxComment.d.ts

@@ -0,0 +1,16 @@
+import type { Node } from 'ts-morph';
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export declare function getParadoxComment(node: Node | undefined): string | null;
+interface ParsedParadoxComment {
+    description: string | null;
+    isConfig: boolean;
+    params: Record<string, string>;
+    returns: string | null;
+}
+/***
+ * Parses a Paradox doc comment into structured metadata.
+ */
+export declare function parseParadoxComment(rawComment: string): ParsedParadoxComment;
+export {};

package/dist/analyze/semantic/paradoxComment.js

@@ -0,0 +1,64 @@
+/***
+ * Reads the nearest Paradox doc comment attached to a declaration.
+ */
+export function getParadoxComment(node) {
+    if (!node)
+        return 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);
+}
+/***
+ * 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 params = {};
+    let returns = null;
+    const description = lines
+        .filter((line) => {
+        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')
+        .trim();
+    return {
+        description: description.length > 0 ? description : null,
+        isConfig,
+        params,
+        returns,
+    };
+}

package/dist/analyze/semantic/tagRegistry.d.ts

@@ -0,0 +1,2 @@
+export type TagRegistry = ReadonlySet<string>;
+export declare const defaultTagRegistry: TagRegistry;

package/dist/analyze/semantic/tagRegistry.js

@@ -0,0 +1 @@
+export const defaultTagRegistry = new Set(['readme', 'config']);

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

@@ -0,0 +1,4 @@
+export declare function toPosixPath(path: string): string;
+export declare function relativeToRoot(root: string, filePath: string): string;
+export declare function isPathInsideRoot(root: string, filePath: string): boolean;
+export declare function isNodeModulePath(filePath: string): boolean;

package/dist/analyze/semantic/utils.js

@@ -0,0 +1,13 @@
+import { normalize, relative } from 'node:path';
+export function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}
+export function relativeToRoot(root, filePath) {
+    return toPosixPath(relative(root, filePath));
+}
+export function isPathInsideRoot(root, filePath) {
+    return normalize(filePath).startsWith(normalize(root));
+}
+export function isNodeModulePath(filePath) {
+    return toPosixPath(filePath).includes('/node_modules/');
+}

package/dist/analyze/types.d.ts

@@ -1,4 +1,9 @@
 import type { Node } from 'ts-morph';
+interface AnalysisExample {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 /***
  * Describes one exported declaration discovered in a package.
  */
@@ -25,11 +30,16 @@ export interface AnalysisMember {
     type: string;
     required: boolean;
     description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalysisMember[];
 }
 export interface AnalysisExport {
     name: string;
     node: Node;
     description: string | null;
+    isReadme: boolean;
+    examples: AnalysisExample[];
     kind: 'function' | 'type' | 'unknown';
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
@@ -44,6 +54,8 @@ export interface AnalysisExport {
 export interface AnalysisComponent {
     name: string;
     description: string | null;
+    isReadme: boolean;
+    examples: AnalysisExample[];
     modulePath: string;
     sourceLocation: AnalysisSourceLocation;
     exportPaths: string[];
@@ -51,6 +63,7 @@ export interface AnalysisComponent {
         name: string;
         type: string;
         required: boolean;
+        defaultValue?: string;
         description: string | null;
     }[];
 }
@@ -58,7 +71,7 @@ export interface AnalysisUsage {
     packageName: string;
     commands: AnalysisUsageCommand[];
 }
-export interface AnalysisUsageCommand {
+interface AnalysisUsageCommand {
     name: string;
     command: string;
 }
@@ -74,6 +87,43 @@ export interface AnalysisModule {
     dependencies: string[];
     exports: string[];
 }
+interface AnalysisTypeMember {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: AnalysisTypeMember[];
+}
+interface ImportEdge {
+    fromPath: string;
+    toPath: string;
+    sourcePath: string;
+}
+interface CallEdge {
+    fromSymbol: string;
+    toSymbol: string;
+    callExpression: string;
+    sourcePath: string;
+}
+interface TypeReferenceEdge {
+    fromSymbol: string;
+    toType: string;
+    sourcePath: string;
+}
+interface ComponentCompositionEdge {
+    fromComponent: string;
+    toComponent: string;
+    jsxElement: string;
+    sourcePath: string;
+}
+interface AnalysisGraphs {
+    imports: ImportEdge[];
+    calls: CallEdge[];
+    typeReferences: TypeReferenceEdge[];
+    componentComposition: ComponentCompositionEdge[];
+}
 /***
  * Complete analysis output used to build the documentation model.
  */
@@ -89,5 +139,9 @@ export interface AnalysisResult {
     usage: AnalysisUsage | null;
     config: {
         exportName: string;
+        isReadme: boolean;
+        members: AnalysisTypeMember[];
     } | null;
+    graphs: AnalysisGraphs;
 }
+export {};

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

@@ -4,9 +4,16 @@
 interface ParsedParadoxComment {
     description: string | null;
     isConfig: boolean;
+    isReadme: boolean;
+    examples: ParsedExample[];
     params: Record<string, string>;
     returns: string | null;
 }
+interface ParsedExample {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
 /***
  * Parses a Paradox doc comment into structured metadata.
  */

package/dist/analyze/utils/parseParadoxComment.js

@@ -2,20 +2,29 @@
  * 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());
+    const lines = normalizeCommentLines(rawComment);
+    const descriptionLines = [];
+    const examples = [];
     let isConfig = false;
+    let isReadme = false;
     const params = {};
     let returns = null;
-    const description = lines
-        .filter((line) => {
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
         const trimmed = line.trimStart();
         if (trimmed.startsWith('@config')) {
             isConfig = true;
-            return false;
+            continue;
+        }
+        if (trimmed.startsWith('@readme')) {
+            isReadme = true;
+            continue;
+        }
+        if (trimmed.startsWith('@example')) {
+            const parsed = parseExample(lines, index);
+            examples.push(parsed.example);
+            index = parsed.nextIndex;
+            continue;
         }
         if (trimmed.startsWith('@param ')) {
             const paramBody = trimmed.slice('@param '.length).trim();
@@ -23,21 +32,59 @@ export function parseParadoxComment(rawComment) {
             if (name) {
                 params[name] = descriptionParts.join(' ').trim();
             }
-            return false;
+            continue;
         }
         if (trimmed.startsWith('@returns') || trimmed.startsWith('@return')) {
             const returnBody = trimmed.replace(/^@returns?/, '').trim();
             returns = returnBody.length > 0 ? returnBody : null;
-            return false;
+            continue;
         }
-        return true;
-    })
-        .join('\n')
-        .trim();
+        descriptionLines.push(line);
+    }
+    const description = descriptionLines.join('\n').trim();
     return {
         description: description.length > 0 ? description : null,
         isConfig,
+        isReadme,
+        examples,
         params,
         returns,
     };
 }
+function parseExample(lines, startIndex) {
+    const header = lines[startIndex]?.trimStart() ?? '';
+    const title = header.slice('@example'.length).trim();
+    let language = null;
+    const codeLines = [];
+    let index = startIndex + 1;
+    while (index < lines.length && (lines[index] ?? '').trim() === '') {
+        index += 1;
+    }
+    const firstCodeLine = lines[index]?.trim() ?? '';
+    if (firstCodeLine.startsWith('```')) {
+        language = firstCodeLine.slice('```'.length).trim() || null;
+        index += 1;
+        while (index < lines.length) {
+            const current = lines[index] ?? '';
+            if (current.trim() === '```')
+                break;
+            codeLines.push(current);
+            index += 1;
+        }
+    }
+    return {
+        example: {
+            title: title.length > 0 ? title : null,
+            language,
+            code: codeLines.join('\n').trimEnd(),
+        },
+        nextIndex: index,
+    };
+}
+function normalizeCommentLines(rawComment) {
+    return rawComment
+        .replace(/^\/\*\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+}

package/dist/config/defineParadoxConfig.d.ts

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

package/dist/config/defineParadoxConfig.js

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

package/dist/config/types.d.ts

@@ -2,6 +2,7 @@
  * Configuration for running Paradox.
  *
  * @config
+ * @readme
  */
 export interface ParadoxConfig {
     mode?: 'safe' | 'write';

package/dist/model/buildModel.d.ts

@@ -1,4 +1,28 @@
 import type { DocumentationModel, ExportKind } from './types.js';
+interface ExampleInput {
+    title: string | null;
+    language: string | null;
+    code: string;
+}
+interface ExportMemberInput {
+    name: string;
+    kind: 'property' | 'method';
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: ExportMemberInput[];
+}
+interface ConfigMemberInput {
+    name: string;
+    type: string;
+    required: boolean;
+    description: string | null;
+    defaultValue?: string;
+    inheritedFrom?: string;
+    children?: ConfigMemberInput[];
+}
 interface BuildModelInput {
     packageName: string;
     packageId: string;
@@ -12,6 +36,8 @@ interface BuildModelInput {
     exports: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         kind: ExportKind;
         modulePath: string;
         sourceLocation: {
@@ -32,17 +58,13 @@ interface BuildModelInput {
             returnType: string | null;
             returnDescription: string | null;
         }[];
-        members: {
-            name: string;
-            kind: 'property' | 'method';
-            type: string;
-            required: boolean;
-            description: string | null;
-        }[];
+        members: ExportMemberInput[];
     }[];
     components: {
         name: string;
         description: string | null;
+        isReadme: boolean;
+        examples: ExampleInput[];
         modulePath: string;
         sourceLocation: {
             filePath: string;
@@ -54,6 +76,7 @@ interface BuildModelInput {
             name: string;
             type: string;
             required: boolean;
+            defaultValue?: string;
             description: string | null;
         }[];
     }[];
@@ -66,6 +89,8 @@ interface BuildModelInput {
     } | null;
     config: {
         exportName: string;
+        isReadme: boolean;
+        members: ConfigMemberInput[];
     } | null;
     entrypoints: string[];
     modules: {
@@ -74,6 +99,30 @@ interface BuildModelInput {
         dependencies: string[];
         exports: string[];
     }[];
+    graphs: {
+        imports: {
+            fromPath: string;
+            toPath: string;
+            sourcePath: string;
+        }[];
+        calls: {
+            fromSymbol: string;
+            toSymbol: string;
+            callExpression: string;
+            sourcePath: string;
+        }[];
+        typeReferences: {
+            fromSymbol: string;
+            toType: string;
+            sourcePath: string;
+        }[];
+        componentComposition: {
+            fromComponent: string;
+            toComponent: string;
+            jsxElement: string;
+            sourcePath: string;
+        }[];
+    };
 }
 /***
  * Converts analysis output into a serializable documentation model.

package/dist/model/buildModel.js

@@ -27,10 +27,12 @@ export function buildModel(analysis) {
         config: analysis.config !== null
             ? {
                 exportName: analysis.config.exportName,
+                isReadme: analysis.config.isReadme,
                 configFile: getDefaultConfigFileName(analysis.packageId),
                 factoryName: findConfigFactoryName(analysis.config.exportName, [
                     ...exportsByName.keys(),
                 ]),
+                members: analysis.config.members,
             }
             : null,
         entrypoints: [...analysis.entrypoints].sort((a, b) => a.localeCompare(b)),
@@ -44,12 +46,20 @@ export function buildModel(analysis) {
             .sort((left, right) => left.path.localeCompare(right.path)),
         exports,
         components: sortByName(analysis.components.map((component) => mapComponent(component, exportsByName.get(component.name)))),
+        graphs: {
+            imports: [...analysis.graphs.imports],
+            calls: [...analysis.graphs.calls],
+            typeReferences: [...analysis.graphs.typeReferences],
+            componentComposition: [...analysis.graphs.componentComposition],
+        },
     };
 }
 function mapExport(item, exportNames) {
     return {
         name: item.name,
         description: item.description,
+        isReadme: item.isReadme,
+        examples: item.examples.map((example) => ({ ...example })),
         kind: item.kind,
         modulePath: item.modulePath,
         sourceLocation: {
@@ -78,6 +88,9 @@ function mapExport(item, exportNames) {
             type: member.type,
             required: member.required,
             description: member.description,
+            defaultValue: member.defaultValue,
+            inheritedFrom: member.inheritedFrom,
+            children: member.children,
         }))),
     };
 }
@@ -85,6 +98,8 @@ function mapComponent(component, exportModel) {
     return {
         name: component.name,
         description: component.description,
+        isReadme: component.isReadme,
+        examples: component.examples.map((example) => ({ ...example })),
         modulePath: component.modulePath,
         sourceLocation: {
             filePath: component.sourceLocation.filePath,
@@ -96,6 +111,7 @@ function mapComponent(component, exportModel) {
             name: prop.name,
             type: prop.type,
             required: prop.required,
+            defaultValue: prop.defaultValue,
             description: prop.description,
         }))),
     };