@fuzdev/fuz_ui 0.194.0 → 0.195.0

package/src/lib/library_analysis.ts

@@ -1,168 +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 '@fuzdev/fuz_ui/library_analysis.js';
- * import {ts_create_program} from '@fuzdev/fuz_ui/ts_helpers.js';
- * import {module_create_source_options} from '@fuzdev/fuz_ui/module_helpers.js';
- * import {AnalysisContext} from '@fuzdev/fuz_ui/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 type {Logger} from '@fuzdev/fuz_util/log.js';
-import type {DeclarationJson} from '@fuzdev/fuz_util/source_json.js';
-
-import {ts_analyze_module} from './ts_helpers.js';
-import {svelte_analyze_module} from './svelte_helpers.js';
-import {
-	type SourceFileInfo,
-	type ModuleSourceOptions,
-	module_extract_path,
-} from './module_helpers.js';
-import type {AnalysisContext} from './analysis_context.js';
-
-/**
- * Result of analyzing a single declaration.
- * Used by both TypeScript and Svelte analyzers for uniform handling.
- */
-export interface DeclarationAnalysis {
-	/** The analyzed declaration metadata. */
-	declaration: DeclarationJson;
-	/** Whether the declaration is marked `@nodocs` (should be excluded from documentation). */
-	nodocs: boolean;
-}
-
-/**
- * Information about a same-name re-export.
- * Used for post-processing to build `also_exported_from` arrays.
- */
-export interface ReExportInfo {
-	/** Name of the re-exported declaration. */
-	name: string;
-	/** Module path (relative to src/lib) where the declaration is originally declared. */
-	original_module: string;
-}
-
-/**
- * Result of analyzing a module (TypeScript or Svelte).
- * Both analyzers return this same structure for uniform handling.
- */
-export interface ModuleAnalysis {
-	/** Module path relative to source root. */
-	path: string;
-	/** Module-level documentation comment. */
-	module_comment?: string;
-	/** All declarations with nodocs flags - consumer filters based on policy. */
-	declarations: Array<DeclarationAnalysis>;
-	/** Dependencies (other source modules this module imports). Empty if none. */
-	dependencies: Array<string>;
-	/** Dependents (other source modules that import this module). Empty if none. */
-	dependents: Array<string>;
-	/** Star exports (`export * from './module'`). Empty for Svelte components. */
-	star_exports: Array<string>;
-	/** Re-exports discovered during analysis. Empty for Svelte components. */
-	re_exports: Array<ReExportInfo>;
-}
-
-/**
- * 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: SourceFileInfo,
-	program: ts.Program,
-	options: ModuleSourceOptions,
-	ctx: AnalysisContext,
-	log?: Logger,
-): ModuleAnalysis | undefined => {
-	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/src/lib/library_generate.ts

@@ -1,215 +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, ModuleJson} 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 {ts_create_program} from './ts_helpers.js';
-import {type SourceFileInfo, type ModuleSourceOptions} from './module_helpers.js';
-import {library_analyze_module} from './library_analysis.js';
-import {
-	library_sort_modules,
-	library_find_duplicates,
-	library_merge_re_exports,
-	type CollectedReExport,
-	type DuplicateInfo,
-} from './library_pipeline.js';
-import {library_generate_output} from './library_output.js';
-import {AnalysisContext, format_diagnostic} from './analysis_context.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 const library_throw_on_duplicates: OnDuplicatesCallback = (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.',
-	);
-};
-
-/** 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 const library_generate = (input: LibraryGenerateInput): LibraryGenerateResult => {
-	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: Array<ModuleJson> = [];
-
-	// Build source_json with array-based modules
-	// Phase 1: Analyze all modules and collect re-exports
-	const source_json: SourceJson = {
-		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: Array<CollectedReExport> = [];
-
-	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: ModuleJson = {
-			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: Array<unknown>) => 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/src/lib/library_pipeline.ts

@@ -1,221 +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,
-	module_is_source,
-	module_validate_source_options,
-	module_get_source_root,
-} 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 const library_find_duplicates = (
-	source_json: SourceJson,
-): Map<string, Array<DuplicateInfo>> => {
-	const all_occurrences: Map<string, Array<DuplicateInfo>> = 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: Map<string, Array<DuplicateInfo>> = 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: Array<ModuleJson>): Array<ModuleJson> => {
-	return modules.slice().sort((a, b) => a.path.localeCompare(b.path));
-};
-
-/**
- * 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 const library_merge_re_exports = (
-	source_json: SourceJson,
-	collected_re_exports: Array<CollectedReExport>,
-): void => {
-	// 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: Map<string, Map<string, Array<string>>> = 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: Iterable<SourceFileInfo>,
-	options: ModuleSourceOptions,
-	log?: Logger,
-): Array<SourceFileInfo> => {
-	// 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: Array<SourceFileInfo> = [];
-	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;
-};