@fuzdev/fuz_ui 0.174.0 → 0.176.0

package/dist/library_analysis.js

@@ -0,0 +1,106 @@
+/**
+ * Library source analysis - unified entry point and shared types.
+ *
+ * Provides a single function for analyzing TypeScript and Svelte source files,
+ * dispatching to the appropriate domain-specific analyzer.
+ *
+ * This module also exports shared types used by both analyzers:
+ * - `DeclarationAnalysis` - A declaration with its nodocs flag
+ * - `ReExportInfo` - Information about a same-name re-export
+ * - `ModuleAnalysis` - Result of analyzing a module (unified structure)
+ *
+ * @example
+ * ```ts
+ * import {library_analyze_module} from './library_analysis.js';
+ * import {ts_create_program} from './ts_helpers.js';
+ * import {module_create_source_options} from './module_helpers.js';
+ * import {AnalysisContext} from './analysis_context.js';
+ *
+ * const {program} = ts_create_program({root: './my-project'});
+ * const ctx = new AnalysisContext();
+ * const options = module_create_source_options('/my-project');
+ *
+ * const result = library_analyze_module(
+ *   {id: '/my-project/src/lib/file.ts', content: '...'},
+ *   program,
+ *   options,
+ *   ctx,
+ * );
+ *
+ * if (result) {
+ *   // Filter out @nodocs declarations
+ *   const declarations = result.declarations
+ *     .filter(d => !d.nodocs)
+ *     .map(d => d.declaration);
+ *   console.log('Declarations:', declarations);
+ * }
+ * ```
+ *
+ * @see ts_helpers.ts for TypeScript-specific analysis
+ * @see svelte_helpers.ts for Svelte component analysis
+ * @see module_helpers.ts for path utilities and SourceFileInfo
+ *
+ * @module
+ */
+import ts from 'typescript';
+import { ts_analyze_module } from './ts_helpers.js';
+import { svelte_analyze_module } from './svelte_helpers.js';
+import { module_extract_path, } from './module_helpers.js';
+/**
+ * Analyze a source file and extract module metadata.
+ *
+ * Unified entry point that dispatches to the appropriate analyzer based on file type:
+ * - TypeScript/JavaScript files → `ts_analyze_module`
+ * - Svelte components → `svelte_analyze_module`
+ *
+ * Returns raw analysis data including `nodocs` flags on declarations.
+ * Consumer is responsible for filtering based on their policy.
+ *
+ * This function can be called incrementally - consumers may cache results and
+ * only re-analyze changed files. The TypeScript program should include all files
+ * for accurate type resolution, but only changed files need re-analysis.
+ *
+ * @param source_file The source file info with content and optional dependency data
+ * @param program TypeScript program (used for type checking and source file lookup)
+ * @param options Module source options for path extraction
+ * @param ctx Analysis context for collecting diagnostics
+ * @param log Optional logger for warnings
+ * @returns Module metadata and re-exports, or undefined if source file not found in program
+ */
+export const library_analyze_module = (source_file, program, options, ctx, log) => {
+    const checker = program.getTypeChecker();
+    const module_path = module_extract_path(source_file.id, options);
+    const analyzer_type = options.get_analyzer(source_file.id);
+    if (analyzer_type === 'svelte') {
+        return svelte_analyze_module(source_file, module_path, checker, options, ctx);
+    }
+    if (analyzer_type === 'typescript') {
+        const ts_source_file = program.getSourceFile(source_file.id);
+        if (!ts_source_file) {
+            ctx.add({
+                kind: 'module_skipped',
+                file: module_path,
+                line: null,
+                column: null,
+                message: `Could not get source file from program: ${source_file.id}`,
+                severity: 'warning',
+                reason: 'not_in_program',
+            });
+            log?.warn(`Could not get source file from program: ${source_file.id}`);
+            return undefined;
+        }
+        return ts_analyze_module(source_file, ts_source_file, module_path, checker, options, ctx);
+    }
+    // analyzer_type is null - skip this file
+    ctx.add({
+        kind: 'module_skipped',
+        file: module_path,
+        line: null,
+        column: null,
+        message: `No analyzer for file type: ${source_file.id}`,
+        severity: 'warning',
+        reason: 'no_analyzer',
+    });
+    log?.warn(`No analyzer for file: ${source_file.id}`);
+    return undefined;
+};

package/dist/library_gen.d.ts

@@ -11,13 +11,79 @@
  * - Dependency graphs
  * - Svelte component props
  *
+ * This file contains Gro-specific integration. The actual analysis logic is in
+ * build-tool agnostic helpers that work with `SourceFileInfo`.
+ *
  * @see @fuzdev/fuz_util/source_json.js for type definitions
- * @see src/lib/library_gen_helpers.ts for buildtime-only helpers
- * @see src/lib/tsdoc_helpers.ts for JSDoc/TSDoc parsing
- * @see src/lib/ts_helpers.ts for TypeScript analysis
- * @see src/lib/svelte_helpers.ts for Svelte component analysis
+ * @see `library_analysis.ts` for the unified analysis entry point
+ * @see `library_gen_helpers.ts` for pipeline orchestration helpers
+ * @see `tsdoc_helpers.ts` for JSDoc/TSDoc parsing
+ * @see `ts_helpers.ts` for TypeScript analysis
+ * @see `svelte_helpers.ts` for Svelte component analysis
+ *
+ * @module
  */
 import type { Gen } from '@ryanatkn/gro';
+import type { Disknode } from '@ryanatkn/gro/disknode.js';
+import { type SourceFileInfo, type ModuleSourceOptions, type ModuleSourcePartial } from './module_helpers.js';
+import { type DuplicateInfo } from './library_gen_helpers.js';
+/** Options for library generation. */
+export interface LibraryGenOptions {
+    /**
+     * Module source options for filtering and path extraction.
+     *
+     * Can provide full `ModuleSourceOptions` or partial options that will be
+     * merged with defaults. The `project_root` is automatically set to
+     * `process.cwd()` if not provided.
+     */
+    source?: ModuleSourceOptions | Partial<ModuleSourcePartial>;
+    /**
+     * Callback invoked when duplicate declaration names are found.
+     *
+     * Consumers decide how to handle duplicates: throw, warn, or ignore.
+     * Use `library_gen_throw_on_duplicates` for strict flat namespace enforcement.
+     *
+     * @example
+     * // Throw on duplicates (strict flat namespace)
+     * library_gen({ on_duplicates: library_gen_throw_on_duplicates });
+     *
+     * // Warn but continue
+     * library_gen({
+     *   on_duplicates: (dupes, log) => {
+     *     for (const [name, locs] of dupes) {
+     *       log.warn(`Duplicate: ${name} in ${locs.map(l => l.module).join(', ')}`);
+     *     }
+     *   }
+     * });
+     */
+    on_duplicates?: OnDuplicatesCallback;
+}
+/**
+ * Callback for handling duplicate declaration names.
+ *
+ * @param duplicates Map of declaration names to their occurrences across modules
+ * @param log Logger for reporting
+ */
+export type OnDuplicatesCallback = (duplicates: Map<string, Array<DuplicateInfo>>, log: {
+    error: (...args: Array<unknown>) => void;
+}) => void;
+/**
+ * Strict duplicate handler that throws on any duplicate declaration names.
+ *
+ * Use this callback with `library_gen({ on_duplicates: library_gen_throw_on_duplicates })`
+ * to enforce a flat namespace where all declaration names must be unique.
+ *
+ * @throws Error if any duplicate declaration names are found
+ */
+export declare const library_gen_throw_on_duplicates: OnDuplicatesCallback;
+/**
+ * Convert Gro's Disknode to the build-tool agnostic SourceFileInfo interface.
+ *
+ * Use this when you want to analyze files using Gro's filer directly.
+ *
+ * @throws Error if disknode has no content (should be loaded by Gro filer)
+ */
+export declare const source_file_from_disknode: (disknode: Disknode) => SourceFileInfo;
 /**
  * Creates a Gen object for generating library metadata with full TypeScript analysis.
  *
@@ -28,6 +94,8 @@ import type { Gen } from '@ryanatkn/gro';
  *
  * export const gen = library_gen();
  * ```
+ *
+ * @param options Optional generation options
  */
-export declare const library_gen: () => Gen;
+export declare const library_gen: (options?: LibraryGenOptions) => Gen;
 //# sourceMappingURL=library_gen.d.ts.map

package/dist/library_gen.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library_gen.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,eAAe,CAAC;AAevC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,QAAO,GAiH9B,CAAC"}
+{"version":3,"file":"library_gen.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,eAAe,CAAC;AAEvC,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAIxD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAGxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAMN,KAAK,aAAa,EAClB,MAAM,0BAA0B,CAAC;AAIlC,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IACjC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5D;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAClC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC,EAC7C,GAAG,EAAE;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CAAC,KAC3C,IAAI,CAAC;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,EAAE,oBAkB7C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,UAAU,QAAQ,KAAG,cAY9D,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,iBAAiB,KAAG,GAuHzD,CAAC"}

package/dist/library_gen.js

@@ -11,16 +11,68 @@
  * - Dependency graphs
  * - Svelte component props
  *
+ * This file contains Gro-specific integration. The actual analysis logic is in
+ * build-tool agnostic helpers that work with `SourceFileInfo`.
+ *
  * @see @fuzdev/fuz_util/source_json.js for type definitions
- * @see src/lib/library_gen_helpers.ts for buildtime-only helpers
- * @see src/lib/tsdoc_helpers.ts for JSDoc/TSDoc parsing
- * @see src/lib/ts_helpers.ts for TypeScript analysis
- * @see src/lib/svelte_helpers.ts for Svelte component analysis
+ * @see `library_analysis.ts` for the unified analysis entry point
+ * @see `library_gen_helpers.ts` for pipeline orchestration helpers
+ * @see `tsdoc_helpers.ts` for JSDoc/TSDoc parsing
+ * @see `ts_helpers.ts` for TypeScript analysis
+ * @see `svelte_helpers.ts` for Svelte component analysis
+ *
+ * @module
  */
 import { package_json_load } from '@ryanatkn/gro/package_json.js';
-import { ts_create_program } from "./ts_helpers.js";
-import { module_extract_path, module_is_svelte } from "./module_helpers.js";
-import { library_gen_collect_source_files, library_gen_sort_modules, library_gen_validate_no_duplicates, library_gen_generate_json, library_gen_analyze_svelte_file, library_gen_analyze_typescript_file, } from "./library_gen_helpers.js";
+import { ts_create_program } from './ts_helpers.js';
+import { module_create_source_options, module_validate_source_options, } from './module_helpers.js';
+import { library_analyze_module } from './library_analysis.js';
+import { library_collect_source_files, library_sort_modules, library_find_duplicates, library_merge_re_exports, } from './library_gen_helpers.js';
+import { library_generate_json } from './library_gen_output.js';
+import { AnalysisContext, format_diagnostic } from './analysis_context.js';
+/**
+ * Strict duplicate handler that throws on any duplicate declaration names.
+ *
+ * Use this callback with `library_gen({ on_duplicates: library_gen_throw_on_duplicates })`
+ * to enforce a flat namespace where all declaration names must be unique.
+ *
+ * @throws Error if any duplicate declaration names are found
+ */
+export const library_gen_throw_on_duplicates = (duplicates, log) => {
+    if (duplicates.size === 0)
+        return;
+    log.error('Duplicate declaration names detected in flat namespace:');
+    for (const [name, occurrences] of duplicates) {
+        log.error(`  "${name}" found in:`);
+        for (const { declaration, module } of occurrences) {
+            const line_info = declaration.source_line !== undefined ? `:${declaration.source_line}` : '';
+            log.error(`    - ${module}${line_info} (${declaration.kind})`);
+        }
+    }
+    throw new Error(`Found ${duplicates.size} duplicate declaration name${duplicates.size === 1 ? '' : 's'} across modules. ` +
+        'The flat namespace requires unique names. To resolve: ' +
+        '(1) rename one of the conflicting declarations, or ' +
+        '(2) add /** @nodocs */ to exclude from documentation. ' +
+        'See CLAUDE.md "Declaration namespacing" section for details.');
+};
+/**
+ * Convert Gro's Disknode to the build-tool agnostic SourceFileInfo interface.
+ *
+ * Use this when you want to analyze files using Gro's filer directly.
+ *
+ * @throws Error if disknode has no content (should be loaded by Gro filer)
+ */
+export const source_file_from_disknode = (disknode) => {
+    if (disknode.contents == null) {
+        throw new Error(`Source file has no content: ${disknode.id} (ensure Gro filer loads file contents)`);
+    }
+    return {
+        id: disknode.id,
+        content: disknode.contents,
+        dependencies: [...disknode.dependencies.keys()],
+        dependents: [...disknode.dependents.keys()],
+    };
+};
 /**
  * Creates a Gen object for generating library metadata with full TypeScript analysis.
  *
@@ -31,92 +83,102 @@ import { library_gen_collect_source_files, library_gen_sort_modules, library_gen
  *
  * export const gen = library_gen();
  * ```
+ *
+ * @param options Optional generation options
  */
-export const library_gen = () => {
+export const library_gen = (options) => {
     return {
         generate: async ({ log, filer }) => {
             log.info('generating library metadata with full TypeScript analysis...');
+            // Build source options with project_root from cwd
+            const source_options = options?.source && 'project_root' in options.source
+                ? options.source
+                : module_create_source_options(process.cwd(), options?.source);
+            // Validate options early to fail fast on misconfiguration
+            // (before expensive operations like program creation)
+            module_validate_source_options(source_options);
             // Ensure filer is initialized
             await filer.init();
             // Read package.json
             const package_json = await package_json_load();
             // Create TypeScript program
-            const program = ts_create_program(log);
-            if (!program) {
-                throw new Error('Failed to create TypeScript program - cannot generate library metadata');
+            const { program } = ts_create_program(undefined, log);
+            // Create analysis context for collecting diagnostics
+            const ctx = new AnalysisContext();
+            // Convert Gro's filer files to build-tool agnostic SourceFileInfo
+            const all_source_files = [];
+            for (const disknode of filer.files.values()) {
+                all_source_files.push(source_file_from_disknode(disknode));
             }
-            const checker = program.getTypeChecker();
-            // Collect source files from filer
-            const source_disknodes = library_gen_collect_source_files(filer.files, log);
+            // Collect and filter source files
+            const source_files = library_collect_source_files(all_source_files, source_options, log);
+            // Collect modules (declared before source_json to include directly)
+            const modules = [];
             // Build source_json with array-based modules
             // Phase 1: Analyze all modules and collect re-exports
             const source_json = {
                 name: package_json.name,
                 version: package_json.version,
-                modules: [],
+                modules,
             };
-            // Collect all re-exports: Map<declaration_name, Set<re_exporting_module_path>>
-            // The Set tracks which modules re-export each declaration
-            const all_re_exports = [];
-            for (const disknode of source_disknodes) {
-                const source_id = disknode.id;
-                const module_path = module_extract_path(source_id);
-                const is_svelte = module_is_svelte(module_path);
-                // Handle Svelte files separately (before trying to get TypeScript source file)
-                if (is_svelte) {
-                    const mod = library_gen_analyze_svelte_file(disknode, module_path, checker);
-                    source_json.modules.push(mod);
-                }
-                else {
-                    // For TypeScript/JS files, get the source file from the program
-                    const source_file = program.getSourceFile(source_id);
-                    if (!source_file) {
-                        log.warn(`Could not get source file: ${source_id}`);
-                        continue;
-                    }
-                    // May throw, which we want to see
-                    const { module: mod, re_exports } = library_gen_analyze_typescript_file(disknode, source_file, module_path, checker);
-                    source_json.modules.push(mod);
-                    // Collect re-exports for post-processing
-                    for (const re_export of re_exports) {
-                        all_re_exports.push({ re_exporting_module: module_path, re_export });
-                    }
+            // Collect re-exports for phase 2 merging
+            // See library_merge_re_exports for the two-phase resolution strategy
+            const collected_re_exports = [];
+            for (const source_file of source_files) {
+                // Use unified analyzer that dispatches based on file type
+                const result = library_analyze_module(source_file, program, source_options, ctx, log);
+                if (!result)
+                    continue;
+                // Build ModuleJson, filtering out @nodocs declarations
+                const module = {
+                    path: result.path,
+                    declarations: result.declarations.filter((d) => !d.nodocs).map((d) => d.declaration),
+                };
+                if (result.module_comment)
+                    module.module_comment = result.module_comment;
+                if (result.dependencies.length > 0)
+                    module.dependencies = result.dependencies;
+                if (result.dependents.length > 0)
+                    module.dependents = result.dependents;
+                if (result.star_exports.length > 0)
+                    module.star_exports = result.star_exports;
+                modules.push(module);
+                // Collect re-exports for phase 2 merging
+                for (const re_export of result.re_exports) {
+                    collected_re_exports.push({ re_exporting_module: result.path, re_export });
                 }
             }
             // Phase 2: Build also_exported_from arrays from re-export data
-            // Group re-exports by original module and declaration name
-            const re_export_map = new Map();
-            for (const { re_exporting_module, re_export } of all_re_exports) {
-                const { name, original_module } = re_export;
-                if (!re_export_map.has(original_module)) {
-                    re_export_map.set(original_module, new Map());
-                }
-                const module_map = re_export_map.get(original_module);
-                if (!module_map.has(name)) {
-                    module_map.set(name, []);
+            library_merge_re_exports(source_json, collected_re_exports);
+            // Sort modules alphabetically for deterministic output and cleaner diffs
+            source_json.modules = library_sort_modules(modules);
+            // Check for duplicate declaration names and invoke callback if provided
+            if (options?.on_duplicates) {
+                const duplicates = library_find_duplicates(source_json);
+                if (duplicates.size > 0) {
+                    options.on_duplicates(duplicates, log);
                 }
-                module_map.get(name).push(re_exporting_module);
             }
-            // Merge into original declarations
-            for (const mod of source_json.modules ?? []) {
-                const module_re_exports = re_export_map.get(mod.path);
-                if (!module_re_exports)
-                    continue;
-                for (const declaration of mod.declarations ?? []) {
-                    const re_exporters = module_re_exports.get(declaration.name);
-                    if (re_exporters?.length) {
-                        declaration.also_exported_from = re_exporters.sort();
+            // Report any analysis diagnostics
+            if (ctx.diagnostics.length > 0) {
+                const errors = ctx.errors();
+                const warnings = ctx.warnings();
+                const format_options = { strip_base: process.cwd() };
+                if (errors.length > 0) {
+                    log.error(`Analysis completed with ${errors.length} error(s):`);
+                    for (const diagnostic of errors) {
+                        log.error(`  ${format_diagnostic(diagnostic, format_options)}`);
+                    }
+                }
+                if (warnings.length > 0) {
+                    log.warn(`Analysis completed with ${warnings.length} warning(s):`);
+                    for (const diagnostic of warnings) {
+                        log.warn(`  ${format_diagnostic(diagnostic, format_options)}`);
                     }
                 }
             }
-            // Sort modules alphabetically for deterministic output and cleaner diffs
-            source_json.modules = source_json.modules
-                ? library_gen_sort_modules(source_json.modules)
-                : undefined;
-            // Validate no duplicate declaration names across modules
-            library_gen_validate_no_duplicates(source_json, log);
             log.info('library metadata generation complete');
-            const { json_content, ts_content } = library_gen_generate_json(package_json, source_json);
+            const { json_content, ts_content } = library_generate_json(package_json, source_json);
             // Return array of files:
             // - library.json (default from .gen.json.ts naming)
             // - library.ts (typed wrapper that validates with zod)

package/dist/library_gen_helpers.d.ts

@@ -1,101 +1,110 @@
 /**
- * Build-time helpers for library metadata generation.
+ * Library metadata generation helpers - pipeline orchestration.
  *
- * These functions handle Gro-specific concerns like file collection and dependency
- * graph extraction. Core analysis logic has been extracted to reusable helpers:
+ * These functions handle collection, validation, and transformation of library metadata
+ * during the generation pipeline. They are internal to the generation process.
  *
- * - `ts_helpers.ts` - `ts_analyze_module_exports`
- * - `svelte_helpers.ts` - `svelte_analyze_file`
- * - `module_helpers.ts` - path utilities and source detection
+ * For source analysis (the consumer-facing API), see `library_analysis.ts`.
  *
- * Design philosophy: Fail fast with clear errors rather than silently producing invalid
- * metadata. All validation errors halt the build immediately with actionable messages.
+ * Pipeline stages:
+ * 1. **Collection** - `library_collect_source_files` gathers and filters source files
+ * 2. **Analysis** - `library_analyze_module` (in library_analysis.ts) extracts metadata
+ * 3. **Validation** - `library_find_duplicates` checks flat namespace constraints
+ * 4. **Transformation** - `library_merge_re_exports` resolves re-export relationships
+ * 5. **Output** - `library_sort_modules` prepares deterministic output
  *
- * @see library_gen.ts for the main generation task
- * @see @fuzdev/fuz_util/source_json.js for type definitions
- * @see ts_helpers.ts for reusable TypeScript analysis
- * @see svelte_helpers.ts for reusable Svelte component analysis
+ * @see library_analysis.ts for the analysis entry point
+ * @see library_gen_output.ts for output file generation (JSON/TS wrapper)
+ * @see library_gen.ts for the main generation task (Gro-specific)
+ *
+ * @module
  */
-import type { PackageJson } from '@fuzdev/fuz_util/package_json.js';
 import type { Logger } from '@fuzdev/fuz_util/log.js';
-import type { ModuleJson, SourceJson } from '@fuzdev/fuz_util/source_json.js';
-import type { Disknode } from '@ryanatkn/gro/disknode.js';
-import type ts from 'typescript';
-import type { PathId } from '@fuzdev/fuz_util/path.js';
-import { type ReExportInfo } from './ts_helpers.js';
+import type { DeclarationJson, ModuleJson, SourceJson } from '@fuzdev/fuz_util/source_json.js';
+import type { ReExportInfo } from './library_analysis.js';
+import { type SourceFileInfo, type ModuleSourceOptions } from './module_helpers.js';
 /**
- * Result of analyzing a TypeScript file.
- * Includes both the module metadata and re-export information for post-processing.
+ * A duplicate declaration with its full metadata and module path.
  */
-export interface TsFileAnalysis {
-    /** Module metadata for inclusion in source_json. */
-    module: ModuleJson;
-    /** Re-exports from this module for building also_exported_from. */
-    re_exports: Array<ReExportInfo>;
+export interface DuplicateInfo {
+    /** The full declaration metadata. */
+    declaration: DeclarationJson;
+    /** Module path where this declaration is defined. */
+    module: string;
 }
 /**
- * Validates that no declaration names are duplicated across modules.
- * The flat namespace is intentional - duplicates should fail fast.
+ * Find duplicate declaration names across modules.
+ *
+ * Returns a Map of declaration names to their full metadata (only includes duplicates).
+ * Callers can decide how to handle duplicates (throw, warn, ignore).
  *
- * @throws Error if duplicate declaration names are found
+ * @example
+ * const duplicates = library_find_duplicates(source_json);
+ * if (duplicates.size > 0) {
+ *   for (const [name, occurrences] of duplicates) {
+ *     console.error(`"${name}" found in:`);
+ *     for (const {declaration, module} of occurrences) {
+ *       console.error(`  - ${module}:${declaration.source_line} (${declaration.kind})`);
+ *     }
+ *   }
+ *   throw new Error(`Found ${duplicates.size} duplicate declaration names`);
+ * }
  */
-export declare const library_gen_validate_no_duplicates: (source_json: SourceJson, log: Logger) => void;
+export declare const library_find_duplicates: (source_json: SourceJson) => Map<string, Array<DuplicateInfo>>;
 /**
  * Sort modules alphabetically by path for deterministic output and cleaner diffs.
  */
-export declare const library_gen_sort_modules: (modules: Array<ModuleJson>) => Array<ModuleJson>;
+export declare const library_sort_modules: (modules: Array<ModuleJson>) => Array<ModuleJson>;
 /**
- * Result of generating library files.
- * Contains both the JSON data and the TypeScript wrapper file.
+ * A collected re-export with its source module context.
+ *
+ * Used during the two-phase re-export resolution:
+ * 1. Phase 1: Collect re-exports from each module during analysis
+ * 2. Phase 2: Group by original module and merge into `also_exported_from`
  */
-export interface LibraryGenOutput {
-    /** JSON content for library.json */
-    json_content: string;
-    /** TypeScript wrapper content for library.ts */
-    ts_content: string;
+export interface CollectedReExport {
+    /** The module that re-exports the declaration. */
+    re_exporting_module: string;
+    /** The re-export info (name and original module). */
+    re_export: ReExportInfo;
 }
 /**
- * Generate the library.json and library.ts file contents.
- * Parses at generation time so runtime only needs the pre-computed result.
- *
- * Returns JSON + .ts wrapper because:
- * - JSON is natively importable by Node.js and Vite without TypeScript loaders
- * - Works in CI environments that don't have TS compilation
- * - The .ts wrapper validates with zod and exports with proper types
- *   (JSON imports get widened types like `string` instead of literal unions)
- */
-export declare const library_gen_generate_json: (package_json: PackageJson, source_json: SourceJson) => LibraryGenOutput;
-/**
- * Collect and filter source files from filer.
+ * Build `also_exported_from` arrays from collected re-export data.
  *
- * Returns disknodes for TypeScript/JS files and Svelte components from src/lib, excluding test files.
- * Returns an empty array with a warning if no source files are found.
- */
-export declare const library_gen_collect_source_files: (files: Map<PathId, Disknode>, log: Logger) => Array<Disknode>;
-/**
- * Analyze a Svelte component file and extract metadata.
+ * This function resolves the two-phase re-export problem:
  *
- * Uses `svelte_analyze_file` for core analysis, then adds
- * Gro-specific dependency information from the disknode.
- */
-export declare const library_gen_analyze_svelte_file: (disknode: Disknode, module_path: string, checker: ts.TypeChecker) => ModuleJson;
-/**
- * Analyze a TypeScript file and extract all declarations.
+ * **Problem**: When module A re-exports from module B, we discover this while
+ * analyzing A, but need to update B's declarations. However, B may already be
+ * processed or may be processed later.
+ *
+ * **Solution**: Collect all re-exports in phase 1, then merge them in phase 2
+ * after all modules are analyzed.
  *
- * Uses `ts_analyze_module_exports` for core analysis, then adds
- * Gro-specific dependency information from the disknode.
+ * @example
+ * // helpers.ts exports: foo, bar
+ * // index.ts does: export {foo, bar} from './helpers.js'
+ * //
+ * // After processing:
+ * // - helpers.ts foo declaration gets: also_exported_from: ['index.ts']
+ * // - helpers.ts bar declaration gets: also_exported_from: ['index.ts']
  *
- * Returns both the module metadata and re-export information for post-processing.
+ * @param source_json The source JSON with all modules (will be mutated)
+ * @param collected_re_exports Array of re-exports collected during phase 1
+ * @mutates source_json - adds `also_exported_from` to declarations
  */
-export declare const library_gen_analyze_typescript_file: (disknode: Disknode, source_file: ts.SourceFile, module_path: string, checker: ts.TypeChecker) => TsFileAnalysis;
+export declare const library_merge_re_exports: (source_json: SourceJson, collected_re_exports: Array<CollectedReExport>) => void;
 /**
- * Extract dependencies and dependents for a module from the filer's dependency graph.
+ * Collect and filter source files.
+ *
+ * Returns source files for TypeScript/JS files and Svelte components, excluding test files.
+ * Returns an empty array with a warning if no source files are found.
+ *
+ * File types are determined by `options.get_analyzer`. By default, `.ts`, `.js`, and `.svelte`
+ * files are supported. Customize `get_analyzer` to support additional file types like `.svx`.
  *
- * Filters to only include source modules from src/lib (excludes external packages, node_modules, tests).
- * Returns sorted arrays of module paths (relative to src/lib) for deterministic output.
+ * @param files Iterable of source file info (from Gro filer, file system, or other source)
+ * @param options Module source options for filtering
+ * @param log Optional logger for status messages
  */
-export declare const library_gen_extract_dependencies: (disknode: Disknode) => {
-    dependencies: Array<string>;
-    dependents: Array<string>;
-};
+export declare const library_collect_source_files: (files: Iterable<SourceFileInfo>, options: ModuleSourceOptions, log?: Logger) => Array<SourceFileInfo>;
 //# sourceMappingURL=library_gen_helpers.d.ts.map