@fuzdev/fuz_ui 0.194.0 → 0.195.1

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;
-};