@ankhorage/paradox 0.0.9 → 0.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.0
+
+### Minor Changes
+
+- dd41897: Generate compact README docs from `@readme` symbols.
+
+## 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

package/README.md

@@ -1,15 +1,41 @@
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
 # @ankhorage/paradox
 
-![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.8](./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.10](./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.
 
-## Usage
+## Installation
 
 ```bash
 bunx @ankhorage/paradox
 ```
 
+## Documentation Tags
+
+<details>
+<summary>@readme</summary>
+
+Includes a documentation block or exported symbol in README output.
+
+</details>
+
+<details>
+<summary>@config</summary>
+
+Marks a type or interface as part of the Paradox configuration model. `@config` alone does not imply README inclusion; use `@config` plus `@readme` for README output.
+
+</details>
+
+<details>
+<summary>@example</summary>
+
+Adds a titled fenced code example to the generated documentation for a symbol.
+
+</details>
+
 ## Configuration
 
 Create a `paradox.config.ts` file:
@@ -22,6 +48,18 @@ export default defineParadoxConfig({
 });
 ```
 
+<details>
+<summary>Configuration options</summary>
+
+| 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       | —       |             |
+
+</details>
+
 ## Generated documentation
 
 - [Interactive documentation app](./paradox/index.html)
@@ -34,6 +72,9 @@ export default defineParadoxConfig({
 
 ## Architecture preview
 
+<details>
+<summary>Architecture overview</summary>
+
 ```mermaid
 graph TD
   package__ankhorage_paradox["@ankhorage/paradox"]
@@ -46,6 +87,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 +99,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 +117,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"]
@@ -150,6 +244,8 @@ graph TD
   module_src_write_write_ts --> module_src_render_types_ts
 ```
 
+</details>
+
 ## Path resolution
 
 - Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
@@ -161,21 +257,29 @@ graph TD
 
 ## Public API
 
-### defineParadoxConfig
+### Configuration
+
+<details>
+<summary>defineParadoxConfig</summary>
+
+```ts
+defineParadoxConfig(config: ParadoxConfig) => ParadoxConfig
+```
 
 Defines a Paradox configuration object without changing its shape.
 
-- Kind: `function`
-- Module: `src/config/defineParadoxConfig.ts`
-- Source: `src/config/defineParadoxConfig.ts:6:1`
-- Export paths: `src/index.ts`
-- Related symbols: `ParadoxConfig`
+Module: `src/config/defineParadoxConfig.ts`
+Source: `src/config/defineParadoxConfig.ts:8:1`
+Related symbols: `ParadoxConfig`
 
-### ParadoxConfig
+</details>
+
+<details>
+<summary>ParadoxConfig</summary>
 
 Configuration for running Paradox.
 
-- Kind: `type`
-- Module: `src/config/types.ts`
-- Source: `src/config/types.ts:6:1`
-- Export paths: `src/index.ts`
+Module: `src/config/types.ts`
+Source: `src/config/types.ts:7:1`
+
+</details>

package/dist/analyze/analyze.d.ts

@@ -1,8 +1,5 @@
 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

@@ -5,10 +5,10 @@ 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.
- */
 export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
@@ -16,15 +16,31 @@ 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 { config: configMetadata, exports } = analyzeExports(project, {
-        root,
-        entrypoints,
-    });
-    const components = analyzeComponents(exports);
-    const modules = analyzeModules(project, {
-        root,
-        entrypoints,
-    });
+    const program = createTypeScriptProgram({ root, entrypoints, project });
+    const { config: configMetadata, exports } = analyzeExports(project, { root, entrypoints });
+    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 +51,27 @@ export async function analyze(config, runtime) {
         modules,
         badges,
         usage,
-        config: configMetadata,
+        config: configMetadata
+            ? {
+                exportName: configMetadata.exportName,
+                isReadme: configMetadata.isReadme,
+                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,19 +1,33 @@
+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,
+            ...(member.defaultValue !== undefined ? { defaultValue: member.defaultValue } : {}),
+            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,
+            isReadme: e.isReadme,
+            examples: e.examples,
             modulePath: e.modulePath,
             sourceLocation: e.sourceLocation,
             exportPaths: e.exportPaths,

package/dist/analyze/exports.d.ts

@@ -4,6 +4,7 @@ interface AnalyzeExportsResult {
     exports: AnalysisExport[];
     config: {
         exportName: string;
+        isReadme: boolean;
     } | null;
 }
 /***

package/dist/analyze/exports.js

@@ -19,13 +19,12 @@ export function analyzeExports(project, options) {
                 continue;
             }
             const rawComment = getParadoxComment(decl);
-            const parsed = rawComment
-                ? parseParadoxComment(rawComment)
-                : { description: null, isConfig: false, params: {}, returns: null };
+            const parsed = rawComment ? parseParadoxComment(rawComment) : createEmptyMetadata();
             const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
                     exportName: name,
+                    isReadme: parsed.isReadme,
                 };
             }
             const metadata = getExportMetadata({
@@ -40,6 +39,8 @@ export function analyzeExports(project, options) {
                 ? {
                     ...existing,
                     description: existing.description ?? parsed.description,
+                    isReadme: existing.isReadme || parsed.isReadme,
+                    examples: existing.examples.length > 0 ? existing.examples : parsed.examples,
                     exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
                     relatedSymbols: uniqueSorted([
                         ...existing.relatedSymbols,
@@ -52,6 +53,8 @@ export function analyzeExports(project, options) {
                     name,
                     node: decl,
                     description: parsed.description,
+                    isReadme: parsed.isReadme,
+                    examples: parsed.examples,
                     kind: inferKind(decl),
                     ...metadata,
                 });
@@ -87,3 +90,13 @@ function uniqueSorted(values) {
 function toPosixPath(path) {
     return path.replaceAll('\\', '/');
 }
+function createEmptyMetadata() {
+    return {
+        description: null,
+        isConfig: false,
+        isReadme: false,
+        examples: [],
+        params: {},
+        returns: null,
+    };
+}

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[];