@ankhorage/paradox 0.0.8 → 0.0.10

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.0.10
+
+### Patch Changes
+
+- 46bc15e: Add a reusable semantic TypeScript analysis foundation for exports, props, type members, and graph metadata.
+
+## 0.0.9
+
+### Patch Changes
+
+- 8904673: Handle exports and type members without declaration nodes defensively during analysis.
+
 ## 0.0.8
 
 ### Patch Changes

package/README.md

@@ -1,6 +1,6 @@
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.7](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.9](./paradox/badges/npm.svg) ![runtime: bun](./paradox/badges/runtime.svg) ![typescript: strict](./paradox/badges/typescript.svg) ![eslint: checked](./paradox/badges/eslint.svg) ![prettier: checked](./paradox/badges/prettier.svg) ![build: checked](./paradox/badges/build.svg) ![tests: checked](./paradox/badges/tests.svg) ![docs: paradox](./paradox/badges/docs.svg)
 
 Deterministic documentation generator for TypeScript packages.
 
@@ -22,6 +22,15 @@ export default defineParadoxConfig({
 });
 ```
 
+### Configuration options
+
+| Field   | Type                                                      | Required | Default | Description |
+| ------- | --------------------------------------------------------- | -------- | ------- | ----------- |
+| mode    | `'safe' \| 'write' \| undefined`                          | no       |         |             |
+| docs    | `{ title?: string; description?: string; } \| undefined`  | no       |         |             |
+| package | `{ root?: string; entrypoints?: string[]; } \| undefined` | no       |         |             |
+| output  | `{ dir?: string; } \| undefined`                          | no       |         |             |
+
 ## Generated documentation
 
 - [Interactive documentation app](./paradox/index.html)
@@ -46,6 +55,9 @@ graph TD
   module_src_analyze_analyze_ts --> module_src_analyze_exports_ts
   module_src_analyze_analyze_ts --> module_src_analyze_modules_ts
   module_src_analyze_analyze_ts --> module_src_analyze_project_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_semantic_createTypeScriptProgram_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_semantic_exports_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_semantic_graphs_ts
   module_src_analyze_analyze_ts --> module_src_analyze_types_ts
   module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
   module_src_analyze_analyze_ts --> module_src_config_types_ts
@@ -55,6 +67,8 @@ graph TD
   module_src_analyze_badges_ts --> module_src_analyze_usage_ts
   module_src_analyze_components_ts["src/analyze/components.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_components_ts
+  module_src_analyze_components_ts --> module_src_analyze_semantic_exports_ts
+  module_src_analyze_components_ts --> module_src_analyze_semantic_model_ts
   module_src_analyze_components_ts --> module_src_analyze_types_ts
   module_src_analyze_components_ts --> module_src_analyze_utils_getComponentPropsType_ts
   module_src_analyze_components_ts --> module_src_analyze_utils_getPropsFromType_ts
@@ -71,6 +85,54 @@ graph TD
   module_src_analyze_modules_ts --> module_src_analyze_types_ts
   module_src_analyze_project_ts["src/analyze/project.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_project_ts
+  module_src_analyze_semantic_analyzeProject_ts["src/analyze/semantic/analyzeProject.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_analyzeProject_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_associateDocBlocksWithSymbols_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_collectSourceFiles_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_createTypeScriptProgram_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_docBlocks_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_exports_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_graphs_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_analyzeProject_ts --> module_src_analyze_semantic_tagRegistry_ts
+  module_src_analyze_semantic_associateDocBlocksWithSymbols_ts["src/analyze/semantic/associateDocBlocksWithSymbols.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_associateDocBlocksWithSymbols_ts
+  module_src_analyze_semantic_associateDocBlocksWithSymbols_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_associateDocBlocksWithSymbols_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_collectSourceFiles_ts["src/analyze/semantic/collectSourceFiles.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_collectSourceFiles_ts
+  module_src_analyze_semantic_collectSourceFiles_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_collectSourceFiles_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_createTypeScriptProgram_ts["src/analyze/semantic/createTypeScriptProgram.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_createTypeScriptProgram_ts
+  module_src_analyze_semantic_createTypeScriptProgram_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_createTypeScriptProgram_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_docBlocks_ts["src/analyze/semantic/docBlocks.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_docBlocks_ts
+  module_src_analyze_semantic_docBlocks_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_docBlocks_ts --> module_src_analyze_semantic_tagRegistry_ts
+  module_src_analyze_semantic_docBlocks_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_exports_ts["src/analyze/semantic/exports.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_exports_ts
+  module_src_analyze_semantic_exports_ts --> module_src_analyze_semantic_isReactComponent_ts
+  module_src_analyze_semantic_exports_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_exports_ts --> module_src_analyze_semantic_paradoxComment_ts
+  module_src_analyze_semantic_exports_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_graphs_ts["src/analyze/semantic/graphs.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_graphs_ts
+  module_src_analyze_semantic_graphs_ts --> module_src_analyze_semantic_exports_ts
+  module_src_analyze_semantic_graphs_ts --> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_graphs_ts --> module_src_analyze_semantic_utils_ts
+  module_src_analyze_semantic_isReactComponent_ts["src/analyze/semantic/isReactComponent.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_isReactComponent_ts
+  module_src_analyze_semantic_model_ts["src/analyze/semantic/model.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_model_ts
+  module_src_analyze_semantic_paradoxComment_ts["src/analyze/semantic/paradoxComment.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_paradoxComment_ts
+  module_src_analyze_semantic_tagRegistry_ts["src/analyze/semantic/tagRegistry.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_tagRegistry_ts
+  module_src_analyze_semantic_utils_ts["src/analyze/semantic/utils.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_semantic_utils_ts
   module_src_analyze_types_ts["src/analyze/types.ts"]
   package__ankhorage_paradox -.-> module_src_analyze_types_ts
   module_src_analyze_usage_ts["src/analyze/usage.ts"]

package/dist/analyze/analyze.js

@@ -5,6 +5,9 @@ import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
 import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
+import { createTypeScriptProgram } from './semantic/createTypeScriptProgram.js';
+import { collectTypeMembers, resolveTypeReference } from './semantic/exports.js';
+import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './semantic/graphs.js';
 import { createUsageFromPackageJson } from './usage.js';
 /***
  * Runs the source analysis pipeline for a configured package.
@@ -16,15 +19,37 @@ export async function analyze(config, runtime) {
     const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
+    const program = createTypeScriptProgram({ root, entrypoints, project });
     const { config: configMetadata, exports } = analyzeExports(project, {
         root,
         entrypoints,
     });
-    const components = analyzeComponents(exports);
+    const components = analyzeComponents(exports, { program });
     const modules = analyzeModules(project, {
         root,
         entrypoints,
     });
+    const configExport = configMetadata
+        ? (exports.find((entry) => entry.name === configMetadata.exportName) ?? null)
+        : null;
+    const configMembers = configExport && (configExport.kind === 'type' || configExport.kind === 'unknown')
+        ? collectTypeMembers(program, resolveTypeReference(program, configExport.node) ?? {
+            type: configExport.node.getType(),
+            name: configExport.name,
+            sourcePath: configExport.modulePath,
+            symbol: configExport.node.getSymbol() ?? null,
+        })
+        : [];
+    const graphs = {
+        imports: collectImportGraph(program),
+        calls: collectCallGraph(program),
+        typeReferences: exports.flatMap((entry) => entry.relatedSymbols.map((symbol) => ({
+            fromSymbol: entry.name,
+            toType: symbol,
+            sourcePath: entry.modulePath,
+        }))),
+        componentComposition: collectComponentCompositionGraph(program),
+    };
     return {
         packageName: config.docs?.title ?? pkg.name,
         packageId: pkg.name,
@@ -35,9 +60,26 @@ export async function analyze(config, runtime) {
         modules,
         badges,
         usage,
-        config: configMetadata,
+        config: configMetadata
+            ? {
+                exportName: configMetadata.exportName,
+                members: mapTypeMembers(configMembers),
+            }
+            : null,
+        graphs,
     };
 }
+function mapTypeMembers(members) {
+    return members.map((member) => ({
+        name: member.name,
+        type: member.type,
+        required: member.required,
+        description: member.description ?? null,
+        ...(member.defaultValue !== undefined ? { defaultValue: member.defaultValue } : {}),
+        ...(member.inheritedFrom !== undefined ? { inheritedFrom: member.inheritedFrom } : {}),
+        ...(member.children ? { children: mapTypeMembers(member.children) } : {}),
+    }));
+}
 async function readPackageJson(root) {
     const raw = await readFile(join(root, 'package.json'), 'utf-8');
     return JSON.parse(raw);

package/dist/analyze/components.d.ts

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

package/dist/analyze/components.js

@@ -1,16 +1,27 @@
+import { collectPropsForExport } from './semantic/exports.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) {
+export function analyzeComponents(exports, options = {}) {
     const components = [];
     for (const e of exports) {
         if (!isReactComponent(e.node))
             continue;
+        const propsFromAnalyzer = options.program
+            ? collectPropsForExport(options.program, { name: e.name, node: e.node })
+            : undefined;
+        const analyzerProps = propsFromAnalyzer?.members.map((member) => ({
+            name: member.name,
+            type: member.type,
+            required: member.required,
+            description: member.description ?? null,
+        })) ?? [];
         const propsType = getComponentPropsType(e.node);
-        const props = propsType != null ? getPropsFromType(propsType) : [];
+        const legacyProps = propsType != null ? getPropsFromType(propsType) : [];
+        const props = analyzerProps.length > 0 ? analyzerProps : legacyProps;
         components.push({
             name: e.name,
             description: e.description,

package/dist/analyze/exports.js

@@ -14,7 +14,10 @@ export function analyzeExports(project, options) {
         const exported = sourceFile.getExportSymbols();
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
-            const [decl] = resolved.getDeclarations();
+            const decl = getFirstDeclaration(resolved.getDeclarations());
+            if (decl === null) {
+                continue;
+            }
             const rawComment = getParadoxComment(decl);
             const parsed = rawComment
                 ? parseParadoxComment(rawComment)
@@ -67,6 +70,10 @@ function getEntryPointSourceFiles(project, options) {
     })
         .filter((sourceFile) => sourceFile != null);
 }
+function getFirstDeclaration(declarations) {
+    const [declaration = null] = declarations;
+    return declaration;
+}
 function inferKind(node) {
     if ('getParameters' in node)
         return 'function';

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

@@ -0,0 +1,10 @@
+import type { AnalyzedProject } from './model.js';
+interface AnalyzeProjectConfig {
+    root: string;
+    entrypoints?: string[];
+}
+/***
+ * Runs the semantic analyzer pipeline for a project.
+ */
+export declare function analyzeProject(config: AnalyzeProjectConfig): AnalyzedProject;
+export {};

package/dist/analyze/semantic/analyzeProject.js

@@ -0,0 +1,62 @@
+import { associateDocBlocksWithSymbols } from './associateDocBlocksWithSymbols.js';
+import { collectSourceFiles } from './collectSourceFiles.js';
+import { createTypeScriptProgram } from './createTypeScriptProgram.js';
+import { collectDocBlocks } from './docBlocks.js';
+import { collectExports, collectPropsForExport, collectRelatedTypes, collectTypeMembers, getExportSignature, resolveTypeReference, } from './exports.js';
+import { collectCallGraph, collectComponentCompositionGraph, collectImportGraph, } from './graphs.js';
+import { defaultTagRegistry } from './tagRegistry.js';
+/***
+ * Runs the semantic analyzer pipeline for a project.
+ */
+export function analyzeProject(config) {
+    const program = createTypeScriptProgram({
+        root: config.root,
+        entrypoints: config.entrypoints,
+    });
+    const files = collectSourceFiles(program);
+    const docBlocks = files.flatMap((file) => collectDocBlocks(file.sourceFile, { program, tagRegistry: defaultTagRegistry }));
+    const exports = associateDocBlocksWithSymbols(program, docBlocks, collectExports(program)).map((entry) => {
+        const signature = getExportSignature(program, entry);
+        const props = collectPropsForExport(program, entry);
+        const typeReference = resolveTypeReference(program, entry.node);
+        const typeMembers = typeReference && (entry.kind === 'interface' || entry.kind === 'type')
+            ? collectTypeMembers(program, typeReference)
+            : undefined;
+        const relatedTypes = collectRelatedTypes({
+            name: entry.name,
+            signature,
+            props,
+            typeMembers,
+        });
+        return {
+            ...entry,
+            signature,
+            props,
+            typeMembers,
+            relatedTypes,
+        };
+    });
+    const tags = new Map();
+    for (const docBlock of docBlocks) {
+        for (const tag of docBlock.tags) {
+            tags.set(tag.name, tag.value ?? null);
+        }
+    }
+    const graphs = {
+        imports: collectImportGraph(program),
+        calls: collectCallGraph(program),
+        typeReferences: exports.flatMap((entry) => entry.relatedTypes.map((typeName) => ({
+            fromSymbol: entry.name,
+            toType: typeName,
+            sourcePath: entry.sourcePath,
+        }))),
+        componentComposition: collectComponentCompositionGraph(program, exports),
+    };
+    return {
+        files,
+        exports,
+        docBlocks,
+        tags: [...tags.entries()].map(([name, value]) => ({ name, value })),
+        graphs,
+    };
+}

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

@@ -0,0 +1,5 @@
+import type { AnalyzedDocBlock, AnalyzedExport, AnalyzedProgram } from './model.js';
+/***
+ * Attaches doc blocks and tags to their nearest symbol declarations.
+ */
+export declare function associateDocBlocksWithSymbols(program: AnalyzedProgram, docBlocks: readonly AnalyzedDocBlock[], exports: readonly AnalyzedExport[]): AnalyzedExport[];

package/dist/analyze/semantic/associateDocBlocksWithSymbols.js

@@ -0,0 +1,51 @@
+import { relativeToRoot } from './utils.js';
+/***
+ * Attaches doc blocks and tags to their nearest symbol declarations.
+ */
+export function associateDocBlocksWithSymbols(program, docBlocks, exports) {
+    const docBlocksByFile = new Map();
+    for (const docBlock of docBlocks) {
+        const entries = docBlocksByFile.get(docBlock.sourcePath);
+        if (entries) {
+            entries.push(docBlock);
+        }
+        else {
+            docBlocksByFile.set(docBlock.sourcePath, [docBlock]);
+        }
+    }
+    for (const [, entries] of docBlocksByFile) {
+        entries.sort((left, right) => left.start - right.start);
+    }
+    return exports.map((entry) => {
+        const sourceFile = entry.node.getSourceFile();
+        const sourcePath = relativeToRoot(program.root, sourceFile.getFilePath());
+        const docBlocksForFile = docBlocksByFile.get(sourcePath) ?? [];
+        const nodeStart = entry.node.getStart(false);
+        let match = undefined;
+        for (const block of docBlocksForFile) {
+            if (block.end > nodeStart)
+                break;
+            if (block.end > 0) {
+                match = block;
+            }
+        }
+        if (match) {
+            const text = sourceFile.getFullText();
+            const between = text.slice(match.end, nodeStart);
+            if (!/^[\s;]*(export\s+)?(default\s+)?$/.test(between)) {
+                match = undefined;
+            }
+        }
+        if (!match) {
+            return {
+                ...entry,
+                tags: entry.tags,
+            };
+        }
+        return {
+            ...entry,
+            docBlock: match,
+            tags: match.tags,
+        };
+    });
+}

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

@@ -0,0 +1,5 @@
+import type { AnalyzedFile, AnalyzedProgram } from './model.js';
+/***
+ * Collects stable source file metadata for the analyzer.
+ */
+export declare function collectSourceFiles(program: AnalyzedProgram): AnalyzedFile[];

package/dist/analyze/semantic/collectSourceFiles.js

@@ -0,0 +1,22 @@
+import { normalize } from 'node:path';
+import { isNodeModulePath, isPathInsideRoot, relativeToRoot } from './utils.js';
+/***
+ * Collects stable source file metadata for the analyzer.
+ */
+export function collectSourceFiles(program) {
+    const entrypoints = new Set(program.entrypointFilePaths.map((entrypoint) => normalize(entrypoint)));
+    return program.project
+        .getSourceFiles()
+        .filter((sourceFile) => {
+        const filePath = sourceFile.getFilePath();
+        return (!sourceFile.isDeclarationFile() &&
+            isPathInsideRoot(program.root, filePath) &&
+            !isNodeModulePath(filePath));
+    })
+        .map((sourceFile) => ({
+        path: relativeToRoot(program.root, sourceFile.getFilePath()),
+        sourceFile,
+        isEntrypoint: entrypoints.has(normalize(sourceFile.getFilePath())),
+    }))
+        .sort((left, right) => left.path.localeCompare(right.path));
+}

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

@@ -0,0 +1,13 @@
+import { Project } from 'ts-morph';
+import type { AnalyzedProgram } from './model.js';
+interface CreateProgramOptions {
+    root: string;
+    entrypoints?: string[];
+    project?: Project;
+    tsconfigPath?: string;
+}
+/***
+ * Creates or reuses a ts-morph project for analysis.
+ */
+export declare function createTypeScriptProgram(options: CreateProgramOptions): AnalyzedProgram;
+export {};

package/dist/analyze/semantic/createTypeScriptProgram.js

@@ -0,0 +1,23 @@
+import { isAbsolute, join, normalize } from 'node:path';
+import { Project } from 'ts-morph';
+import { toPosixPath } from './utils.js';
+/***
+ * Creates or reuses a ts-morph project for analysis.
+ */
+export function createTypeScriptProgram(options) {
+    const root = normalize(options.root);
+    const entrypoints = options.entrypoints ?? ['src/index.ts'];
+    const entrypointFilePaths = entrypoints.map((entrypoint) => normalize(isAbsolute(entrypoint) ? entrypoint : join(root, entrypoint)));
+    const project = options.project ??
+        new Project({
+            tsConfigFilePath: options.tsconfigPath ?? join(root, 'tsconfig.json'),
+            skipAddingFilesFromTsConfig: false,
+        });
+    return {
+        project,
+        typeChecker: project.getTypeChecker(),
+        root,
+        entrypoints: entrypoints.map((entrypoint) => toPosixPath(entrypoint)),
+        entrypointFilePaths,
+    };
+}

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

@@ -0,0 +1,10 @@
+import type { SourceFile } from 'ts-morph';
+import type { AnalyzedDocBlock, AnalyzedProgram } from './model.js';
+import type { TagRegistry } from './tagRegistry.js';
+/***
+ * Collects all Paradox doc blocks from a source file.
+ */
+export declare function collectDocBlocks(sourceFile: SourceFile, options: {
+    program: AnalyzedProgram;
+    tagRegistry?: TagRegistry;
+}): AnalyzedDocBlock[];

package/dist/analyze/semantic/docBlocks.js

@@ -0,0 +1,102 @@
+import { defaultTagRegistry } from './tagRegistry.js';
+import { relativeToRoot } from './utils.js';
+const DOC_BLOCK_REGEX = /\/\*\*\*[\s\S]*?\*\//g;
+/***
+ * Collects all Paradox doc blocks from a source file.
+ */
+export function collectDocBlocks(sourceFile, options) {
+    const { program } = options;
+    const tagRegistry = options.tagRegistry ?? defaultTagRegistry;
+    const text = sourceFile.getFullText();
+    const sourcePath = relativeToRoot(program.root, sourceFile.getFilePath());
+    const blocks = [];
+    for (const match of text.matchAll(DOC_BLOCK_REGEX)) {
+        const [raw = ''] = match;
+        const start = match.index;
+        const end = start + raw.length;
+        const { line, column } = sourceFile.getLineAndColumnAtPos(start);
+        const parsed = parseDocBlock(raw, tagRegistry);
+        const id = `${sourcePath}:${line}:${column}`;
+        blocks.push({
+            id,
+            sourcePath,
+            start,
+            end,
+            line,
+            column,
+            raw,
+            description: parsed.description,
+            params: parsed.params,
+            returns: parsed.returns,
+            tags: parsed.tags,
+        });
+    }
+    return blocks;
+}
+/***
+ * Extracts registered tags from a doc block.
+ */
+function collectTags(raw, tagRegistry = defaultTagRegistry) {
+    const tags = [];
+    const lines = normalizeDocBlock(raw);
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('@'))
+            continue;
+        const [tagName, ...rest] = trimmed.slice(1).split(/\s+/);
+        if (!tagName || !tagRegistry.has(tagName))
+            continue;
+        const value = rest.join(' ').trim();
+        tags.push({
+            name: tagName,
+            value: value.length > 0 ? value : null,
+        });
+    }
+    return tags;
+}
+function parseDocBlock(raw, tagRegistry) {
+    const lines = normalizeDocBlock(raw);
+    const tags = collectTags(raw, tagRegistry);
+    const params = {};
+    let returns = null;
+    const description = lines
+        .filter((line) => {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('@'))
+            return true;
+        const [tagName, ...rest] = trimmed.slice(1).split(/\s+/);
+        if (!tagName)
+            return false;
+        if (tagName === 'param') {
+            const [name, ...descParts] = rest;
+            if (name) {
+                params[name] = descParts.join(' ').trim();
+            }
+            return false;
+        }
+        if (tagName === 'returns' || tagName === 'return') {
+            const returnBody = rest.join(' ').trim();
+            returns = returnBody.length > 0 ? returnBody : null;
+            return false;
+        }
+        if (tagRegistry.has(tagName)) {
+            return false;
+        }
+        return true;
+    })
+        .join('\n')
+        .trim();
+    return {
+        description: description.length > 0 ? description : null,
+        tags,
+        params,
+        returns,
+    };
+}
+function normalizeDocBlock(raw) {
+    return raw
+        .replace(/^\/\*\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map((line) => line.replace(/^\s*\*\s?/, '').trimEnd());
+}

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

@@ -0,0 +1,29 @@
+import type { Node, Symbol as MorphSymbol, Type } from 'ts-morph';
+import type { AnalyzedExport, AnalyzedProgram, AnalyzedProps, AnalyzedTypeMember, ResolvedTypeReference } from './model.js';
+/***
+ * Collects exported declarations from configured entrypoints.
+ */
+export declare function collectExports(program: AnalyzedProgram): AnalyzedExport[];
+/***
+ * Returns a human-readable signature for callable exports.
+ */
+export declare function getExportSignature(_program: AnalyzedProgram, analyzedExport: Pick<AnalyzedExport, 'node'>): string | undefined;
+/***
+ * Resolves a named type reference from a node or symbol.
+ */
+export declare function resolveTypeReference(program: AnalyzedProgram, typeNodeOrSymbol: Node | Type | MorphSymbol): ResolvedTypeReference | null;
+/***
+ * Collects nested type members for interfaces and type literals.
+ */
+export declare function collectTypeMembers(program: AnalyzedProgram, reference: ResolvedTypeReference, options?: {
+    inheritedFrom?: string;
+    depth?: number;
+}): AnalyzedTypeMember[];
+/***
+ * Extracts props metadata for a callable export.
+ */
+export declare function collectPropsForExport(program: AnalyzedProgram, analyzedExport: Pick<AnalyzedExport, 'name' | 'node'>): AnalyzedProps | undefined;
+/***
+ * Collects related types referenced by an export.
+ */
+export declare function collectRelatedTypes(analyzedExport: Pick<AnalyzedExport, 'name' | 'signature' | 'props' | 'typeMembers'>): string[];