@fuzdev/fuz_ui 0.176.1 → 0.177.0

package/dist/LibraryDetail.svelte

@@ -7,7 +7,7 @@
 	import ImgOrSvg from './ImgOrSvg.svelte';
 	import DeclarationLink from './DeclarationLink.svelte';
 	import ModuleLink from './ModuleLink.svelte';
-	import {url_github_file, repo_url_parse, url_well_known} from './library_helpers.js';
+	import {url_github_file, repo_url_parse, url_well_known} from './package_helpers.js';
 	import {
 		module_is_typescript,
 		module_is_svelte,

package/dist/declaration.svelte.js

@@ -1,5 +1,5 @@
 import { declaration_generate_import, declaration_get_display_name, } from '@fuzdev/fuz_util/source_json.js';
-import { url_github_file } from './library_helpers.js';
+import { url_github_file } from './package_helpers.js';
 /**
  * Rich runtime representation of an exported declaration.
  */

package/dist/library_gen.d.ts

@@ -1,33 +1,23 @@
 /**
- * Library metadata generator helper.
+ * Gro-specific library metadata generation.
  *
- * Generates package_json and source_json with rich metadata:
- * - 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
+ * This module provides Gro integration for library generation. It wraps the generic
+ * `library_generate` function with Gro's `Gen` interface and provides adapters for
+ * converting Gro's `Disknode` to the build-tool agnostic `SourceFileInfo`.
  *
- * This file contains Gro-specific integration. The actual analysis logic is in
- * build-tool agnostic helpers that work with `SourceFileInfo`.
+ * For build-tool agnostic usage, see `library_generate.ts`.
  *
- * @see @fuzdev/fuz_util/source_json.js for type definitions
- * @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
+ * @see library_generate.ts for the generic generation entry point
+ * @see library_pipeline.ts for pipeline helpers
+ * @see library_output.ts for output file generation
  *
  * @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. */
+import { type OnDuplicatesCallback } from './library_generate.js';
+/** Options for Gro library generation. */
 export interface LibraryGenOptions {
     /**
      * Module source options for filtering and path extraction.
@@ -41,11 +31,11 @@ export interface LibraryGenOptions {
      * 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.
+     * Use `library_throw_on_duplicates` for strict flat namespace enforcement.
      *
      * @example
      * // Throw on duplicates (strict flat namespace)
-     * library_gen({ on_duplicates: library_gen_throw_on_duplicates });
+     * library_gen({ on_duplicates: library_throw_on_duplicates });
      *
      * // Warn but continue
      * library_gen({
@@ -58,24 +48,6 @@ export interface LibraryGenOptions {
      */
     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.
  *
@@ -102,6 +74,13 @@ export declare const library_collect_source_files_from_disknodes: (disknodes: It
 /**
  * Creates a Gen object for generating library metadata with full TypeScript analysis.
  *
+ * This is the Gro-specific entry point. It handles:
+ * - Reading files from Gro's filer
+ * - Loading package.json via Gro utilities
+ * - Returning output in Gro's Gen format
+ *
+ * For build-tool agnostic usage, use `library_generate` directly.
+ *
  * Usage in a `.gen.ts` file:
  *
  * ```ts

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;;;;;;;;;;;;;;;;;;;;;;;;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,EAKxB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAKN,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;AAGF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2CAA2C,GACvD,WAAW,QAAQ,CAAC,QAAQ,CAAC,EAC7B,SAAS,mBAAmB,EAC5B,MAAM;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CAAC,KACtF,KAAK,CAAC,cAAc,CA6BtB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,iBAAiB,KAAG,GAsHzD,CAAC"}
+{"version":3,"file":"library_gen.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_gen.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,eAAe,CAAC;AAEvC,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,2BAA2B,CAAC;AAExD,OAAO,EACN,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EAKxB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAmB,KAAK,oBAAoB,EAAC,MAAM,uBAAuB,CAAC;AAElF,0CAA0C;AAC1C,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;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,UAAU,QAAQ,KAAG,cAY9D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,2CAA2C,GACvD,WAAW,QAAQ,CAAC,QAAQ,CAAC,EAC7B,SAAS,mBAAmB,EAC5B,MAAM;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,IAAI,CAAA;CAAC,KACtF,KAAK,CAAC,cAAc,CA6BtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,WAAW,GAAI,UAAU,iBAAiB,KAAG,GA0CzD,CAAC"}

package/dist/library_gen.js

@@ -1,60 +1,21 @@
 /**
- * Library metadata generator helper.
+ * Gro-specific library metadata generation.
  *
- * Generates package_json and source_json with rich metadata:
- * - 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
+ * This module provides Gro integration for library generation. It wraps the generic
+ * `library_generate` function with Gro's `Gen` interface and provides adapters for
+ * converting Gro's `Disknode` to the build-tool agnostic `SourceFileInfo`.
  *
- * This file contains Gro-specific integration. The actual analysis logic is in
- * build-tool agnostic helpers that work with `SourceFileInfo`.
+ * For build-tool agnostic usage, see `library_generate.ts`.
  *
- * @see @fuzdev/fuz_util/source_json.js for type definitions
- * @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
+ * @see library_generate.ts for the generic generation entry point
+ * @see library_pipeline.ts for pipeline helpers
+ * @see library_output.ts for output file generation
  *
  * @module
  */
 import { package_json_load } from '@ryanatkn/gro/package_json.js';
-import { ts_create_program } from './ts_helpers.js';
 import { module_create_source_options, module_validate_source_options, module_is_source, module_get_source_root, } 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_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.');
-};
+import { library_generate } from './library_generate.js';
 /**
  * Convert Gro's Disknode to the build-tool agnostic SourceFileInfo interface.
  *
@@ -73,7 +34,6 @@ export const source_file_from_disknode = (disknode) => {
         dependents: [...disknode.dependents.keys()],
     };
 };
-// TODO more generic helpers
 /**
  * Collect source files from Gro disknodes, filtering BEFORE conversion to SourceFileInfo.
  *
@@ -112,6 +72,13 @@ export const library_collect_source_files_from_disknodes = (disknodes, options,
 /**
  * Creates a Gen object for generating library metadata with full TypeScript analysis.
  *
+ * This is the Gro-specific entry point. It handles:
+ * - Reading files from Gro's filer
+ * - Loading package.json via Gro utilities
+ * - Returning output in Gro's Gen format
+ *
+ * For build-tool agnostic usage, use `library_generate` directly.
+ *
  * Usage in a `.gen.ts` file:
  *
  * ```ts
@@ -130,91 +97,26 @@ export const library_gen = (options) => {
             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(undefined, log);
-            // Create analysis context for collecting diagnostics
-            const ctx = new AnalysisContext();
-            // Collect source files, filtering by source_options BEFORE converting to SourceFileInfo
-            // This avoids errors from files outside source directories (like test fixtures)
+            // Collect source files from Gro filer
             const source_files = library_collect_source_files_from_disknodes(filer.files.values(), 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,
-            };
-            // 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 (options?.on_duplicates) {
-                const duplicates = library_find_duplicates(source_json);
-                if (duplicates.size > 0) {
-                    options.on_duplicates(duplicates, log);
-                }
-            }
-            // 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)}`);
-                    }
-                }
-            }
+            // Use generic library_generate for the actual work
+            const result = library_generate({
+                source_files,
+                package_json,
+                source_options,
+                on_duplicates: options?.on_duplicates,
+                log,
+            });
             log.info('library metadata generation complete');
-            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)
-            return [{ content: ts_content }, { content: json_content, filename: 'library.json' }];
+            // Return array of files in Gro's expected format
+            return [
+                { content: result.ts_content },
+                { content: result.json_content, filename: 'library.json' },
+            ];
         },
     };
 };

package/dist/library_generate.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,147 @@
+/**
+ * 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_helpers.d.ts

@@ -1,54 +1,56 @@
-import type { PackageJson } from '@fuzdev/fuz_util/package_json.js';
+/**
+ * Library documentation URL helpers.
+ *
+ * Runtime UI helpers for building URLs in the library documentation system.
+ * These depend on fuz_ui's documentation paths and SvelteKit's runtime state.
+ *
+ * For generic package/repository URL helpers, see `package_helpers.ts`.
+ *
+ * @module
+ */
 /**
  * Build project-relative API documentation URL with hash anchor.
+ *
+ * @param declaration_name Name of the declaration to link to
+ * @returns URL path like '/docs/api#declaration_name'
  */
 export declare const url_api_declaration: (declaration_name: string) => string;
 /**
  * Build full API documentation URL with domain and hash anchor.
+ *
+ * @param homepage Package homepage URL
+ * @param declaration_name Name of the declaration to link to
+ * @returns Full URL like 'https://example.com/docs/api#declaration_name'
  */
 export declare const url_api_declaration_full: (homepage: string, declaration_name: string) => string;
 /**
  * Build project-relative module documentation URL.
+ *
+ * @param module_path Module path (e.g., 'helpers.ts')
+ * @returns URL path like '/docs/api/helpers.ts'
  */
 export declare const url_api_module: (module_path: string) => string;
-/**
- * Build GitHub file URL for a repository.
- */
-export declare const url_github_file: (repo_url: string, file_path: string, line?: number) => string;
-/**
- * Build GitHub organization URL from repo URL and repo name.
- */
-export declare const url_github_org: (repo_url: string, repo_name: string) => string | null;
-/**
- * Parse GitHub owner/org name from repository URL.
- */
-export declare const github_owner_parse: (repo_url: string) => string | null;
-/**
- * Build npm package URL.
- */
-export declare const url_npm_package: (package_name: string) => string;
-/**
- * Check if a package is published to npm.
- */
-export declare const package_is_published: (package_json: PackageJson) => boolean;
 /**
  * Build package logo URL with favicon.png fallback.
+ *
+ * @param homepage_url Package homepage URL, or null
+ * @param logo_path Optional custom logo path (defaults to 'favicon.png')
+ * @returns Full URL to the logo, or null if no homepage
  */
 export declare const url_package_logo: (homepage_url: string | null, logo_path?: string) => string | null;
-/**
- * Extract repository name without scope from package name.
- */
-export declare const repo_name_parse: (name: string) => string;
-/**
- * Parse repository URL from package.json format.
- */
-export declare const repo_url_parse: (repository: PackageJson["repository"]) => string | null;
-/**
- * Build .well-known URL for package metadata files.
- */
-export declare const url_well_known: (homepage_url: string, filename: string) => string;
 /**
  * Convert a full URL to root-relative format by removing the origin.
+ *
+ * Uses SvelteKit's page state for the current origin by default.
+ *
+ * @param url Full URL to convert
+ * @param origin Origin to strip (defaults to current page origin)
+ * @returns Root-relative URL starting with '/'
+ *
+ * @example
+ * // Assuming page.url.origin is 'https://example.com'
+ * url_to_root_relative('https://example.com/docs/api')
+ * // => '/docs/api'
  */
 export declare const url_to_root_relative: (url: string, origin?: string) => string;
 //# sourceMappingURL=library_helpers.d.ts.map

package/dist/library_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAKlE;;GAEG;AACH,eAAO,MAAM,mBAAmB,GAAI,kBAAkB,MAAM,KAAG,MACJ,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,MAAM,EAAE,kBAAkB,MAAM,KAAG,MACR,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAA2C,CAAC;AAEjG;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,UAAU,MAAM,EAAE,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,MAIpF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,UAAU,MAAM,EAAE,WAAW,MAAM,KAAG,MAAM,GAAG,IAE7E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAAM,GAAG,IAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,cAAc,MAAM,KAAG,MACP,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,cAAc,WAAW,KAAG,OAEhE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,cAAc,MAAM,GAAG,IAAI,EAC3B,YAAY,MAAM,KAChB,MAAM,GAAG,IAIX,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,MAS9C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,YAAY,WAAW,CAAC,YAAY,CAAC,KAAG,MAAM,GAAG,IAK/E,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,cAAc,MAAM,EAAE,UAAU,MAAM,KAAG,MAEvE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,EAAE,SAAQ,MAAwB,KAAG,MAcpF,CAAC"}
+{"version":3,"file":"library_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAOH;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,kBAAkB,MAAM,KAAG,MACJ,CAAC;AAE5D;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GAAI,UAAU,MAAM,EAAE,kBAAkB,MAAM,KAAG,MACR,CAAC;AAE/E;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,aAAa,MAAM,KAAG,MAA2C,CAAC;AAEjG;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC5B,cAAc,MAAM,GAAG,IAAI,EAC3B,YAAY,MAAM,KAChB,MAAM,GAAG,IAIX,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,EAAE,SAAQ,MAAwB,KAAG,MAcpF,CAAC"}