@ankhorage/paradox 0.0.5 → 0.0.7

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.0.7
+
+### Patch Changes
+
+- 5246138: Generate deterministic README quality badges from local repository metadata.
+
+  Paradox now computes README badge metadata from local package, TypeScript, linting, formatting, workflow, test, coverage, and documentation signals, then renders stable local SVG badge assets under `paradox/badges/` and includes them in generated README output without relying on external badge services.
+
+## 0.0.6
+
+### Patch Changes
+
+- 1a836cf: Generate a deterministic static documentation app with computed API metadata and Mermaid diagrams.
+
+  Paradox now emits an offline `paradox/index.html` documentation app, diagram artifacts, richer export metadata, function signature details, parameter and return descriptions, related symbols, and README links to the generated documentation outputs.
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -1,5 +1,7 @@
 # @ankhorage/paradox
 
+![license: MIT](./paradox/badges/license.svg) ![npm: v0.0.6](./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
@@ -20,6 +22,134 @@ export default defineParadoxConfig({
 });
 ```
 
+## Generated documentation
+
+- [Interactive documentation app](./paradox/index.html)
+- [Public API reference](./paradox/exports.md)
+- [Component registry](./paradox/components.md)
+- [Architecture overview](./paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](./paradox/diagrams/module-relationships.mmd)
+- [Export graph](./paradox/diagrams/export-graph.mmd)
+- [Entrypoint sequence](./paradox/diagrams/entrypoint-sequence.mmd)
+
+## Architecture preview
+
+```mermaid
+graph TD
+  package__ankhorage_paradox["@ankhorage/paradox"]
+  entrypoint_src_index_ts["src/index.ts"]
+  package__ankhorage_paradox --> entrypoint_src_index_ts
+  module_src_analyze_analyze_ts["src/analyze/analyze.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_analyze_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_badges_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_components_ts
+  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_types_ts
+  module_src_analyze_analyze_ts --> module_src_analyze_usage_ts
+  module_src_analyze_analyze_ts --> module_src_config_types_ts
+  module_src_analyze_badges_ts["src/analyze/badges.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_badges_ts
+  module_src_analyze_badges_ts --> module_src_analyze_types_ts
+  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_types_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_getComponentPropsType_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_getPropsFromType_ts
+  module_src_analyze_components_ts --> module_src_analyze_utils_isReactComponent_ts
+  module_src_analyze_exports_ts["src/analyze/exports.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_exports_ts
+  module_src_analyze_exports_ts --> module_src_analyze_types_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_getExportMetadata_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_exports_ts --> module_src_analyze_utils_resolveExportSymbol_ts
+  module_src_analyze_modules_ts["src/analyze/modules.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_modules_ts
+  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_types_ts["src/analyze/types.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_types_ts
+  module_src_analyze_usage_ts["src/analyze/usage.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_usage_ts
+  module_src_analyze_usage_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getComponentPropsType_ts["src/analyze/utils/getComponentPropsType.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getComponentPropsType_ts
+  module_src_analyze_utils_getExportMetadata_ts["src/analyze/utils/getExportMetadata.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getExportMetadata_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getExportMetadata_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_getParadoxComment_ts["src/analyze/utils/getParadoxComment.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getPropsFromType_ts["src/analyze/utils/getPropsFromType.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_getPropsFromType_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_types_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_utils_getParadoxComment_ts
+  module_src_analyze_utils_getPropsFromType_ts --> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_isReactComponent_ts["src/analyze/utils/isReactComponent.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_isReactComponent_ts
+  module_src_analyze_utils_parseParadoxComment_ts["src/analyze/utils/parseParadoxComment.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_parseParadoxComment_ts
+  module_src_analyze_utils_resolveExportSymbol_ts["src/analyze/utils/resolveExportSymbol.ts"]
+  package__ankhorage_paradox -.-> module_src_analyze_utils_resolveExportSymbol_ts
+  module_src_cli_ts["src/cli.ts"]
+  package__ankhorage_paradox -.-> module_src_cli_ts
+  module_src_cli_ts --> module_src_analyze_analyze_ts
+  module_src_cli_ts --> module_src_model_buildModel_ts
+  module_src_cli_ts --> module_src_paths_policy_ts
+  module_src_cli_ts --> module_src_render_render_ts
+  module_src_cli_ts --> module_src_write_write_ts
+  module_src_config_defineParadoxConfig_ts["src/config/defineParadoxConfig.ts"]
+  package__ankhorage_paradox -.-> module_src_config_defineParadoxConfig_ts
+  module_src_config_defineParadoxConfig_ts --> module_src_config_types_ts
+  module_src_config_types_ts["src/config/types.ts"]
+  package__ankhorage_paradox -.-> module_src_config_types_ts
+  module_src_index_ts["src/index.ts"]
+  module_src_model_buildModel_ts["src/model/buildModel.ts"]
+  package__ankhorage_paradox -.-> module_src_model_buildModel_ts
+  module_src_model_buildModel_ts --> module_src_model_types_ts
+  module_src_model_types_ts["src/model/types.ts"]
+  package__ankhorage_paradox -.-> module_src_model_types_ts
+  module_src_paths_policy_ts["src/paths/policy.ts"]
+  package__ankhorage_paradox -.-> module_src_paths_policy_ts
+  module_src_paths_policy_ts --> module_src_config_types_ts
+  module_src_render_render_ts["src/render/render.ts"]
+  package__ankhorage_paradox -.-> module_src_render_render_ts
+  module_src_render_render_ts --> module_src_model_types_ts
+  module_src_render_render_ts --> module_src_render_renderers_badges_ts
+  module_src_render_render_ts --> module_src_render_renderers_diagrams_ts
+  module_src_render_render_ts --> module_src_render_renderers_html_ts
+  module_src_render_render_ts --> module_src_render_renderers_markdown_ts
+  module_src_render_render_ts --> module_src_render_types_ts
+  module_src_render_renderers_badges_ts["src/render/renderers/badges.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_badges_ts
+  module_src_render_renderers_badges_ts --> module_src_model_types_ts
+  module_src_render_renderers_badges_ts --> module_src_render_types_ts
+  module_src_render_renderers_diagrams_ts["src/render/renderers/diagrams.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_diagrams_ts
+  module_src_render_renderers_diagrams_ts --> module_src_model_types_ts
+  module_src_render_renderers_diagrams_ts --> module_src_render_types_ts
+  module_src_render_renderers_html_ts["src/render/renderers/html.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_html_ts
+  module_src_render_renderers_html_ts --> module_src_model_types_ts
+  module_src_render_renderers_html_ts --> module_src_render_types_ts
+  module_src_render_renderers_markdown_ts["src/render/renderers/markdown.ts"]
+  package__ankhorage_paradox -.-> module_src_render_renderers_markdown_ts
+  module_src_render_renderers_markdown_ts --> module_src_model_types_ts
+  module_src_render_renderers_markdown_ts --> module_src_render_types_ts
+  module_src_render_types_ts["src/render/types.ts"]
+  package__ankhorage_paradox -.-> module_src_render_types_ts
+  module_src_render_types_ts --> module_src_model_types_ts
+  module_src_write_write_ts["src/write/write.ts"]
+  package__ankhorage_paradox -.-> module_src_write_write_ts
+  module_src_write_write_ts --> module_src_config_types_ts
+  module_src_write_write_ts --> module_src_render_types_ts
+```
+
 ## Path resolution
 
 - Config discovery: searches upward from `process.cwd()` for `paradox.config.ts/js/mjs/cjs` (required; no fallback).
@@ -35,6 +165,17 @@ export default defineParadoxConfig({
 
 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`
+
 ### ParadoxConfig
 
 Configuration for running Paradox.
+
+- Kind: `type`
+- Module: `src/config/types.ts`
+- Source: `src/config/types.ts:6:1`
+- Export paths: `src/index.ts`

package/dist/analyze/analyze.js

@@ -1,7 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { analyzeBadges } from './badges.js';
 import { analyzeComponents } from './components.js';
 import { analyzeExports } from './exports.js';
+import { analyzeModules } from './modules.js';
 import { createProject } from './project.js';
 import { createUsageFromPackageJson } from './usage.js';
 /***
@@ -11,6 +13,7 @@ export async function analyze(config, runtime) {
     const root = runtime.packageRoot;
     const pkg = await readPackageJson(root);
     const usage = createUsageFromPackageJson(pkg);
+    const badges = await analyzeBadges(root, pkg);
     const project = createProject(root);
     const entrypoints = config.package?.entrypoints ?? ['src/index.ts'];
     const { config: configMetadata, exports } = analyzeExports(project, {
@@ -18,12 +21,19 @@ export async function analyze(config, runtime) {
         entrypoints,
     });
     const components = analyzeComponents(exports);
+    const modules = analyzeModules(project, {
+        root,
+        entrypoints,
+    });
     return {
         packageName: config.docs?.title ?? pkg.name,
         packageId: pkg.name,
         description: config.docs?.description ?? pkg.description ?? null,
         exports,
         components,
+        entrypoints: entrypoints.map((entrypoint) => entrypoint.replaceAll('\\', '/')).sort(),
+        modules,
+        badges,
         usage,
         config: configMetadata,
     };

package/dist/analyze/badges.d.ts

@@ -0,0 +1,6 @@
+import type { AnalysisBadge } from './types.js';
+import type { PackageJsonModel } from './usage.js';
+/***
+ * Derives deterministic repository metadata badges from local repository files.
+ */
+export declare function analyzeBadges(root: string, pkg: PackageJsonModel): Promise<AnalysisBadge[]>;

package/dist/analyze/badges.js

@@ -0,0 +1,256 @@
+import { access, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const ESLINT_CONFIG_FILES = [
+    'eslint.config.js',
+    'eslint.config.mjs',
+    'eslint.config.cjs',
+    'eslint.config.ts',
+    '.eslintrc',
+    '.eslintrc.js',
+    '.eslintrc.cjs',
+    '.eslintrc.json',
+    '.eslintrc.yaml',
+    '.eslintrc.yml',
+];
+const PRETTIER_CONFIG_FILES = [
+    '.prettierrc',
+    '.prettierrc.js',
+    '.prettierrc.cjs',
+    '.prettierrc.json',
+    '.prettierrc.yaml',
+    '.prettierrc.yml',
+    'prettier.config.js',
+    'prettier.config.cjs',
+    'prettier.config.mjs',
+    'prettier.config.ts',
+];
+const BADGE_ORDER = [
+    'license',
+    'npm',
+    'runtime',
+    'typescript',
+    'eslint',
+    'prettier',
+    'build',
+    'tests',
+    'coverage',
+    'docs',
+];
+/***
+ * Derives deterministic repository metadata badges from local repository files.
+ */
+export async function analyzeBadges(root, pkg) {
+    const workflowFiles = await readWorkflowFiles(root);
+    const badges = [];
+    if ((await hasAnyFile(root, ESLINT_CONFIG_FILES)) ||
+        pkg.eslintConfig !== undefined ||
+        scriptContains(pkg, 'lint', 'eslint')) {
+        badges.push({
+            id: 'eslint',
+            label: 'eslint',
+            value: workflowRunsScript(workflowFiles, 'lint') ? 'checked' : 'configured',
+            color: workflowRunsScript(workflowFiles, 'lint') ? '0a7f3f' : '2563eb',
+        });
+    }
+    if ((await hasAnyFile(root, PRETTIER_CONFIG_FILES)) ||
+        pkg.prettier !== undefined ||
+        scriptContains(pkg, 'format', 'prettier') ||
+        scriptContains(pkg, 'format:check', 'prettier')) {
+        const prettierChecked = workflowRunsScript(workflowFiles, 'format') ||
+            workflowRunsScript(workflowFiles, 'format:check');
+        badges.push({
+            id: 'prettier',
+            label: 'prettier',
+            value: prettierChecked ? 'checked' : 'configured',
+            color: prettierChecked ? '0a7f3f' : '2563eb',
+        });
+    }
+    if (hasScript(pkg, 'build')) {
+        const buildChecked = workflowRunsScript(workflowFiles, 'build');
+        badges.push({
+            id: 'build',
+            label: 'build',
+            value: buildChecked ? 'checked' : 'configured',
+            color: buildChecked ? '0a7f3f' : '6f42c1',
+        });
+    }
+    if (hasScript(pkg, 'test')) {
+        const testsChecked = workflowRunsScript(workflowFiles, 'test');
+        badges.push({
+            id: 'tests',
+            label: 'tests',
+            value: testsChecked ? 'checked' : 'configured',
+            color: testsChecked ? '0a7f3f' : '6f42c1',
+        });
+    }
+    if (await hasTypeScriptStrictMode(root)) {
+        badges.push({
+            id: 'typescript',
+            label: 'typescript',
+            value: 'strict',
+            color: '2563eb',
+        });
+    }
+    if (supportsBun(pkg, workflowFiles)) {
+        badges.push({
+            id: 'runtime',
+            label: 'runtime',
+            value: 'bun',
+            color: 'f59e0b',
+        });
+    }
+    const coverage = await readCoveragePercent(root);
+    if (coverage !== null) {
+        badges.push({
+            id: 'coverage',
+            label: 'coverage',
+            value: `${formatPercent(coverage)}%`,
+            color: getCoverageColor(coverage),
+        });
+    }
+    if (typeof pkg.license === 'string' && pkg.license.length > 0) {
+        badges.push({
+            id: 'license',
+            label: 'license',
+            value: pkg.license,
+            color: '2563eb',
+        });
+    }
+    if (typeof pkg.version === 'string' && pkg.version.length > 0) {
+        badges.push({
+            id: 'npm',
+            label: 'npm',
+            value: `v${pkg.version}`,
+            color: 'cb3837',
+        });
+    }
+    badges.push({
+        id: 'docs',
+        label: 'docs',
+        value: 'paradox',
+        color: '0f766e',
+    });
+    return sortBadges(badges);
+}
+async function hasAnyFile(root, paths) {
+    for (const relativePath of paths) {
+        if (await fileExists(join(root, relativePath))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function hasTypeScriptStrictMode(root) {
+    const tsconfig = await readJsonFile(join(root, 'tsconfig.json'));
+    return tsconfig?.compilerOptions?.strict === true;
+}
+async function readCoveragePercent(root) {
+    const coverage = await readJsonFile(join(root, 'coverage', 'coverage-summary.json'));
+    const value = coverage?.total?.lines?.pct;
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function formatPercent(value) {
+    return Number.isInteger(value) ? `${value}` : value.toFixed(1);
+}
+function getCoverageColor(value) {
+    if (value >= 90)
+        return '0a7f3f';
+    if (value >= 75)
+        return '65a30d';
+    if (value >= 50)
+        return 'ca8a04';
+    return 'dc2626';
+}
+function hasScript(pkg, name) {
+    return typeof pkg.scripts?.[name] === 'string' && pkg.scripts[name].length > 0;
+}
+function scriptContains(pkg, name, command) {
+    return pkg.scripts?.[name]?.includes(command) ?? false;
+}
+function supportsBun(pkg, workflowFiles) {
+    if (pkg.packageManager?.startsWith('bun@') ?? false) {
+        return true;
+    }
+    if (Object.values(pkg.scripts ?? {}).some((script) => script.includes('bun') || script.includes('bunx'))) {
+        return true;
+    }
+    return workflowFiles.some((workflow) => workflow.includes('oven-sh/setup-bun') ||
+        workflow.includes('bun install') ||
+        /\bbun(?:x)?\b/.test(workflow));
+}
+function workflowRunsScript(workflowFiles, scriptName) {
+    const escaped = escapeRegExp(scriptName);
+    const patterns = [
+        new RegExp(`\\bbun\\s+run\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\bnpm\\s+run\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\bpnpm\\s+${escaped}(?=\\s|$)`, 'i'),
+        new RegExp(`\\byarn\\s+${escaped}(?=\\s|$)`, 'i'),
+    ];
+    return workflowFiles.some((workflow) => patterns.some((pattern) => pattern.test(workflow)));
+}
+function escapeRegExp(value) {
+    return value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+async function readWorkflowFiles(root) {
+    const workflowsPath = join(root, '.github', 'workflows');
+    const entries = await readDirectory(workflowsPath);
+    const contents = await Promise.all(entries
+        .filter((entry) => entry.endsWith('.yml') || entry.endsWith('.yaml'))
+        .sort((a, b) => a.localeCompare(b))
+        .map((entry) => readFile(join(workflowsPath, entry), 'utf-8')));
+    return contents;
+}
+async function readDirectory(path) {
+    try {
+        return await readdir(path);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return [];
+        }
+        throw new Error(`Unable to read workflow directory: ${path}`, { cause: error });
+    }
+}
+function isNotFoundError(error) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}
+async function readJsonFile(path) {
+    let content;
+    try {
+        content = await readFile(path, 'utf-8');
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw new Error(`Unable to read JSON metadata file: ${path}`, { cause: error });
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Unable to parse JSON metadata file: ${path}`, { cause: error });
+    }
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function sortBadges(badges) {
+    return [...badges].sort((left, right) => {
+        const order = getBadgeOrder(left.id) - getBadgeOrder(right.id);
+        return order !== 0 ? order : left.id.localeCompare(right.id);
+    });
+}
+function getBadgeOrder(id) {
+    const index = BADGE_ORDER.indexOf(id);
+    return index === -1 ? BADGE_ORDER.length : index;
+}

package/dist/analyze/components.js

@@ -14,6 +14,9 @@ export function analyzeComponents(exports) {
         components.push({
             name: e.name,
             description: e.description,
+            modulePath: e.modulePath,
+            sourceLocation: e.sourceLocation,
+            exportPaths: e.exportPaths,
             props,
         });
     }

package/dist/analyze/exports.js

@@ -1,4 +1,5 @@
-import { isAbsolute, join, normalize } from 'node:path';
+import { isAbsolute, join, normalize, relative } from 'node:path';
+import { getExportMetadata } from './utils/getExportMetadata.js';
 import { getParadoxComment } from './utils/getParadoxComment.js';
 import { parseParadoxComment } from './utils/parseParadoxComment.js';
 import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
@@ -6,9 +7,10 @@ import { resolveExportSymbol } from './utils/resolveExportSymbol.js';
  * Collects exported declarations from configured package entrypoints.
  */
 export function analyzeExports(project, options) {
-    const exports = [];
+    const exportsByName = new Map();
     let config = null;
     for (const sourceFile of getEntryPointSourceFiles(project, options)) {
+        const entrypointPath = toPosixPath(relative(options.root, sourceFile.getFilePath()));
         const exported = sourceFile.getExportSymbols();
         for (const symbol of exported) {
             const resolved = resolveExportSymbol(symbol);
@@ -16,22 +18,44 @@ export function analyzeExports(project, options) {
             const rawComment = getParadoxComment(decl);
             const parsed = rawComment
                 ? parseParadoxComment(rawComment)
-                : { description: null, isConfig: false };
+                : { description: null, isConfig: false, params: {}, returns: null };
+            const name = resolved.getName();
             if (parsed.isConfig) {
                 config = {
-                    exportName: resolved.getName(),
+                    exportName: name,
                 };
             }
-            exports.push({
-                name: resolved.getName(),
+            const metadata = getExportMetadata({
+                name,
                 node: decl,
-                description: parsed.description,
-                kind: inferKind(decl),
+                root: options.root,
+                entrypointPath,
+                symbol: resolved,
             });
+            const existing = exportsByName.get(name);
+            exportsByName.set(name, existing
+                ? {
+                    ...existing,
+                    description: existing.description ?? parsed.description,
+                    exportPaths: uniqueSorted([...existing.exportPaths, ...metadata.exportPaths]),
+                    relatedSymbols: uniqueSorted([
+                        ...existing.relatedSymbols,
+                        ...metadata.relatedSymbols,
+                    ]),
+                    signatures: existing.signatures.length > 0 ? existing.signatures : metadata.signatures,
+                    members: existing.members.length > 0 ? existing.members : metadata.members,
+                }
+                : {
+                    name,
+                    node: decl,
+                    description: parsed.description,
+                    kind: inferKind(decl),
+                    ...metadata,
+                });
         }
     }
     return {
-        exports,
+        exports: [...exportsByName.values()],
         config,
     };
 }
@@ -50,3 +74,9 @@ function inferKind(node) {
         return 'type';
     return 'unknown';
 }
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}

package/dist/analyze/modules.d.ts

@@ -0,0 +1,9 @@
+import type { Project } from 'ts-morph';
+import type { AnalysisModule } from './types.js';
+/***
+ * Builds a deterministic module relationship graph for documentation renderers.
+ */
+export declare function analyzeModules(project: Project, options: {
+    root: string;
+    entrypoints: readonly string[];
+}): AnalysisModule[];

package/dist/analyze/modules.js

@@ -0,0 +1,44 @@
+import { isAbsolute, join, normalize, relative } from 'node:path';
+/***
+ * Builds a deterministic module relationship graph for documentation renderers.
+ */
+export function analyzeModules(project, options) {
+    const rootPath = normalize(options.root);
+    const entrypointPaths = new Set(options.entrypoints.map((entrypoint) => normalize(isAbsolute(entrypoint) ? entrypoint : join(options.root, entrypoint))));
+    return project
+        .getSourceFiles()
+        .filter((sourceFile) => {
+        const filePath = normalize(sourceFile.getFilePath());
+        const normalizedPath = toPosixPath(filePath);
+        return (!sourceFile.isDeclarationFile() &&
+            filePath.startsWith(rootPath) &&
+            !normalizedPath.includes('/node_modules/'));
+    })
+        .map((sourceFile) => {
+        const path = toPosixPath(relative(options.root, sourceFile.getFilePath()));
+        const dependencies = sourceFile
+            .getImportDeclarations()
+            .map((declaration) => declaration.getModuleSpecifierSourceFile())
+            .filter((dependency) => dependency != null)
+            .map((dependency) => normalize(dependency.getFilePath()))
+            .filter((dependency) => dependency.startsWith(rootPath) && !toPosixPath(dependency).includes('/node_modules/'))
+            .map((dependency) => toPosixPath(relative(options.root, dependency)));
+        const exports = sourceFile
+            .getExportSymbols()
+            .map((symbol) => symbol.getName())
+            .sort((left, right) => left.localeCompare(right));
+        return {
+            path,
+            isEntrypoint: entrypointPaths.has(normalize(sourceFile.getFilePath())),
+            dependencies: uniqueSorted(dependencies),
+            exports: uniqueSorted(exports),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function toPosixPath(path) {
+    return path.replaceAll('\\', '/');
+}