@fuzdev/fuz_ui 0.193.1 → 0.195.0

package/dist/library_analysis.js

@@ -1,106 +0,0 @@
-/**
- * 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/JS 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_generate.d.ts

@@ -1,94 +0,0 @@
-/**
- * Generic library metadata generation.
- *
- * This module provides build-tool agnostic library generation. It takes source files
- * and package metadata, analyzes them, and produces structured metadata with:
- * - JSDoc/TSDoc comments with full tag support
- * - Full type signatures
- * - Source code locations
- * - Parameter information with descriptions and defaults
- * - Return value documentation
- * - Usage examples
- * - Dependency graphs
- * - Svelte component props
- *
- * For Gro integration, see `library_gen.ts` which wraps this with Gro's `Gen` interface.
- *
- * @see `@fuzdev/fuz_util/source_json.js` for type definitions
- * @see `library_analysis.ts` for the unified analysis entry point
- * @see `library_pipeline.ts` for pipeline helpers
- * @see `library_output.ts` for JSON/TS file generation
- *
- * @module
- */
-import type ts from 'typescript';
-import type { SourceJson } from '@fuzdev/fuz_util/source_json.js';
-import type { PackageJson } from '@fuzdev/fuz_util/package_json.js';
-import type { Logger } from '@fuzdev/fuz_util/log.js';
-import { type SourceFileInfo, type ModuleSourceOptions } from './module_helpers.js';
-import { type DuplicateInfo } from './library_pipeline.js';
-/**
- * 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_generate({ on_duplicates: library_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_throw_on_duplicates: OnDuplicatesCallback;
-/** Input for library metadata generation. */
-export interface LibraryGenerateInput {
-    /** Source files to analyze (must have content loaded). */
-    source_files: Array<SourceFileInfo>;
-    /** Package metadata (name, version). */
-    package_json: PackageJson;
-    /** Module source options for path extraction. */
-    source_options: ModuleSourceOptions;
-    /**
-     * Optional TypeScript program. If not provided, one will be created.
-     * Pass an existing program to reuse across multiple calls.
-     */
-    program?: ts.Program;
-    /** Optional callback for handling duplicate declaration names. */
-    on_duplicates?: OnDuplicatesCallback;
-    /** Optional logger for status and diagnostic messages. */
-    log?: Logger;
-}
-/** Result of library metadata generation. */
-export interface LibraryGenerateResult {
-    /** The generated source metadata. */
-    source_json: SourceJson;
-    /** JSON file content string. */
-    json_content: string;
-    /** TypeScript wrapper file content string. */
-    ts_content: string;
-}
-/**
- * Generate library metadata from source files.
- *
- * This is the main entry point for library generation. It analyzes source files,
- * extracts metadata, and produces both structured data and file contents.
- *
- * @example
- * ```ts
- * const result = library_generate({
- *   source_files,
- *   package_json: {name: '@my/lib', version: '1.0.0'},
- *   source_options: module_create_source_options(process.cwd()),
- * });
- *
- * await writeFile('library.json', result.json_content);
- * await writeFile('library.ts', result.ts_content);
- * ```
- */
-export declare const library_generate: (input: LibraryGenerateInput) => LibraryGenerateResult;
-//# sourceMappingURL=library_generate.d.ts.map

package/dist/library_generate.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"library_generate.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,KAAK,EAAC,UAAU,EAAa,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,EAAC,KAAK,cAAc,EAAE,KAAK,mBAAmB,EAAC,MAAM,qBAAqB,CAAC;AAElF,OAAO,EAKN,KAAK,aAAa,EAClB,MAAM,uBAAuB,CAAC;AAI/B;;;;;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,2BAA2B,EAAE,oBAiBzC,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,oBAAoB;IACpC,0DAA0D;IAC1D,YAAY,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IACpC,wCAAwC;IACxC,YAAY,EAAE,WAAW,CAAC;IAC1B,iDAAiD;IACjD,cAAc,EAAE,mBAAmB,CAAC;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC;IACrB,kEAAkE;IAClE,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACrC,qCAAqC;IACrC,WAAW,EAAE,UAAU,CAAC;IACxB,gCAAgC;IAChC,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,oBAAoB,KAAG,qBAuF9D,CAAC"}

package/dist/library_generate.js

@@ -1,147 +0,0 @@
-/**
- * Generic library metadata generation.
- *
- * This module provides build-tool agnostic library generation. It takes source files
- * and package metadata, analyzes them, and produces structured metadata with:
- * - JSDoc/TSDoc comments with full tag support
- * - Full type signatures
- * - Source code locations
- * - Parameter information with descriptions and defaults
- * - Return value documentation
- * - Usage examples
- * - Dependency graphs
- * - Svelte component props
- *
- * For Gro integration, see `library_gen.ts` which wraps this with Gro's `Gen` interface.
- *
- * @see `@fuzdev/fuz_util/source_json.js` for type definitions
- * @see `library_analysis.ts` for the unified analysis entry point
- * @see `library_pipeline.ts` for pipeline helpers
- * @see `library_output.ts` for JSON/TS file generation
- *
- * @module
- */
-import { ts_create_program } from './ts_helpers.js';
-import {} from './module_helpers.js';
-import { library_analyze_module } from './library_analysis.js';
-import { library_sort_modules, library_find_duplicates, library_merge_re_exports, } from './library_pipeline.js';
-import { library_generate_output } from './library_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_generate({ on_duplicates: library_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_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.');
-};
-/**
- * Generate library metadata from source files.
- *
- * This is the main entry point for library generation. It analyzes source files,
- * extracts metadata, and produces both structured data and file contents.
- *
- * @example
- * ```ts
- * const result = library_generate({
- *   source_files,
- *   package_json: {name: '@my/lib', version: '1.0.0'},
- *   source_options: module_create_source_options(process.cwd()),
- * });
- *
- * await writeFile('library.json', result.json_content);
- * await writeFile('library.ts', result.ts_content);
- * ```
- */
-export const library_generate = (input) => {
-    const { source_files, package_json, source_options, on_duplicates, log } = input;
-    // Create or use provided TypeScript program
-    const program = input.program ?? ts_create_program(undefined, log).program;
-    // Create analysis context for collecting diagnostics
-    const ctx = new AnalysisContext();
-    // Collect modules
-    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,
-    };
-    // 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
-    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 (on_duplicates) {
-        const duplicates = library_find_duplicates(source_json);
-        if (duplicates.size > 0) {
-            // Use provided logger or a minimal fallback
-            const error_log = log ?? { error: (...args) => console.error(...args) }; // eslint-disable-line no-console
-            on_duplicates(duplicates, error_log);
-        }
-    }
-    // Report any analysis diagnostics
-    if (ctx.diagnostics.length > 0 && log) {
-        const errors = ctx.errors();
-        const warnings = ctx.warnings();
-        const format_options = { strip_base: source_options.project_root };
-        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)}`);
-            }
-        }
-    }
-    const { json_content, ts_content } = library_generate_output(package_json, source_json);
-    return { source_json, json_content, ts_content };
-};

package/dist/library_pipeline.d.ts

@@ -1,113 +0,0 @@
-/**
- * Library metadata generation pipeline.
- *
- * These functions handle collection, validation, and transformation of library metadata
- * during the generation pipeline.
- *
- * 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_generate.ts` for the main generation entry point
- * @see `library_analysis.ts` for module-level analysis
- * @see `library_output.ts` for output file generation (JSON/TS wrapper)
- * @see `library_gen.ts` for Gro-specific integration
- *
- * @module
- */
-import type { Logger } from '@fuzdev/fuz_util/log.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';
-/**
- * A duplicate declaration with its full metadata and module path.
- */
-export interface DuplicateInfo {
-    /** The full declaration metadata. */
-    declaration: DeclarationJson;
-    /** Module path where this declaration is defined. */
-    module: string;
-}
-/**
- * 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).
- *
- * @example
- * ```ts
- * 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_find_duplicates: (source_json: SourceJson) => Map<string, Array<DuplicateInfo>>;
-/**
- * Sort modules alphabetically by path for deterministic output and cleaner diffs.
- */
-export declare const library_sort_modules: (modules: Array<ModuleJson>) => Array<ModuleJson>;
-/**
- * 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 CollectedReExport {
-    /** The module that re-exports the declaration. */
-    re_exporting_module: string;
-    /** The re-export info (name and original module). */
-    re_export: ReExportInfo;
-}
-/**
- * Build `also_exported_from` arrays from collected re-export data.
- *
- * This function resolves the two-phase re-export problem:
- *
- * **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.
- *
- * @example
- * ```ts
- * // 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']
- * ```
- *
- * @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_merge_re_exports: (source_json: SourceJson, collected_re_exports: Array<CollectedReExport>) => void;
-/**
- * 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`.
- *
- * @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_collect_source_files: (files: Iterable<SourceFileInfo>, options: ModuleSourceOptions, log?: Logger) => Array<SourceFileInfo>;
-//# sourceMappingURL=library_pipeline.d.ts.map

package/dist/library_pipeline.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"library_pipeline.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,eAAe,EAAE,UAAU,EAAE,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAE7F,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,uBAAuB,CAAC;AACxD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,mBAAmB,EAIxB,MAAM,qBAAqB,CAAC;AAE7B;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,qCAAqC;IACrC,WAAW,EAAE,eAAe,CAAC;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,uBAAuB,GACnC,aAAa,UAAU,KACrB,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CA0BlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,KAAK,CAAC,UAAU,CAAC,KAAG,KAAK,CAAC,UAAU,CAEjF,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IACjC,kDAAkD;IAClD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,SAAS,EAAE,YAAY,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,wBAAwB,GACpC,aAAa,UAAU,EACvB,sBAAsB,KAAK,CAAC,iBAAiB,CAAC,KAC5C,IAgCF,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B,GACxC,OAAO,QAAQ,CAAC,cAAc,CAAC,EAC/B,SAAS,mBAAmB,EAC5B,MAAM,MAAM,KACV,KAAK,CAAC,cAAc,CA0BtB,CAAC"}

package/dist/library_pipeline.js

@@ -1,160 +0,0 @@
-/**
- * Library metadata generation pipeline.
- *
- * These functions handle collection, validation, and transformation of library metadata
- * during the generation pipeline.
- *
- * 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_generate.ts` for the main generation entry point
- * @see `library_analysis.ts` for module-level analysis
- * @see `library_output.ts` for output file generation (JSON/TS wrapper)
- * @see `library_gen.ts` for Gro-specific integration
- *
- * @module
- */
-import { module_is_source, module_validate_source_options, module_get_source_root, } from './module_helpers.js';
-/**
- * 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).
- *
- * @example
- * ```ts
- * 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 const library_find_duplicates = (source_json) => {
-    const all_occurrences = new Map();
-    // Collect all declaration names and their full metadata
-    for (const mod of source_json.modules ?? []) {
-        for (const declaration of mod.declarations ?? []) {
-            const name = declaration.name;
-            if (!all_occurrences.has(name)) {
-                all_occurrences.set(name, []);
-            }
-            all_occurrences.get(name).push({
-                declaration,
-                module: mod.path,
-            });
-        }
-    }
-    // Filter to only duplicates
-    const duplicates = new Map();
-    for (const [name, occurrences] of all_occurrences) {
-        if (occurrences.length > 1) {
-            duplicates.set(name, occurrences);
-        }
-    }
-    return duplicates;
-};
-/**
- * Sort modules alphabetically by path for deterministic output and cleaner diffs.
- */
-export const library_sort_modules = (modules) => {
-    return modules.slice().sort((a, b) => a.path.localeCompare(b.path));
-};
-/**
- * Build `also_exported_from` arrays from collected re-export data.
- *
- * This function resolves the two-phase re-export problem:
- *
- * **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.
- *
- * @example
- * ```ts
- * // 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']
- * ```
- *
- * @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 const library_merge_re_exports = (source_json, collected_re_exports) => {
-    // Group re-exports by original module and declaration name
-    // Structure: Map<original_module_path, Map<declaration_name, Array<re_exporting_module_path>>>
-    const re_export_map = new Map();
-    for (const { re_exporting_module, re_export } of collected_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, []);
-        }
-        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) {
-                // Sort for deterministic output
-                declaration.also_exported_from = re_exporters.sort();
-            }
-        }
-    }
-};
-/**
- * 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`.
- *
- * @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 const library_collect_source_files = (files, options, log) => {
-    // Validate options early to fail fast on misconfiguration
-    module_validate_source_options(options);
-    const all_files = Array.from(files);
-    log?.info(`received ${all_files.length} files total`);
-    const source_files = [];
-    for (const file of all_files) {
-        if (module_is_source(file.id, options)) {
-            source_files.push(file);
-        }
-    }
-    log?.info(`found ${source_files.length} source files to analyze`);
-    if (source_files.length === 0) {
-        const effective_root = module_get_source_root(options);
-        log?.warn(`No source files found in ${effective_root} - generating empty library metadata`);
-        return [];
-    }
-    // Sort for deterministic output (stable alphabetical module ordering)
-    source_files.sort((a, b) => a.id.localeCompare(b.id));
-    return source_files;
-};