@fuzdev/fuz_ui 0.169.0

package/src/lib/library_gen_helpers.ts

@@ -0,0 +1,262 @@
+/**
+ * Build-time helpers for library metadata generation.
+ *
+ * These functions handle Gro-specific concerns like file collection and dependency
+ * graph extraction. Core analysis logic has been extracted to reusable helpers:
+ *
+ * - `ts_helpers.ts` - `ts_analyze_module_exports`
+ * - `svelte_helpers.ts` - `svelte_analyze_file`
+ * - `module_helpers.ts` - path utilities and source detection
+ *
+ * Design philosophy: Fail fast with clear errors rather than silently producing invalid
+ * metadata. All validation errors halt the build immediately with actionable messages.
+ *
+ * @see library_gen.ts for the main generation task
+ * @see @fuzdev/fuz_util/source_json.js for type definitions
+ * @see ts_helpers.ts for reusable TypeScript analysis
+ * @see svelte_helpers.ts for reusable Svelte component analysis
+ */
+
+import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import type {ModuleJson, SourceJson} from '@fuzdev/fuz_util/source_json.js';
+import {library_json_parse, type LibraryJson} from '@fuzdev/fuz_util/library_json.js';
+import type {Disknode} from '@ryanatkn/gro/disknode.js';
+import type ts from 'typescript';
+import type {PathId} from '@fuzdev/fuz_util/path.js';
+
+import {ts_analyze_module_exports, type ReExportInfo} from './ts_helpers.js';
+import {svelte_analyze_file} from './svelte_helpers.js';
+import {
+	module_extract_path,
+	module_is_typescript,
+	module_is_svelte,
+	module_matches_source,
+} from './module_helpers.js';
+
+/**
+ * Result of analyzing a TypeScript file.
+ * Includes both the module metadata and re-export information for post-processing.
+ */
+export interface TsFileAnalysis {
+	/** Module metadata for inclusion in source_json. */
+	module: ModuleJson;
+	/** Re-exports from this module for building also_exported_from. */
+	re_exports: Array<ReExportInfo>;
+}
+
+/**
+ * Validates that no declaration names are duplicated across modules.
+ * The flat namespace is intentional - duplicates should fail fast.
+ *
+ * @throws Error if duplicate declaration names are found
+ */
+export const library_gen_validate_no_duplicates = (source_json: SourceJson, log: Logger): void => {
+	const declaration_locations: Map<string, Array<{module: string; kind: string}>> = new Map();
+
+	// Collect all declaration names and their locations
+	for (const mod of source_json.modules ?? []) {
+		for (const declaration of mod.declarations ?? []) {
+			const name = declaration.name;
+			if (!declaration_locations.has(name)) {
+				declaration_locations.set(name, []);
+			}
+			declaration_locations.get(name)!.push({
+				module: mod.path,
+				kind: declaration.kind,
+			});
+		}
+	}
+
+	// Check for duplicates
+	const duplicates: Array<{name: string; locations: Array<{module: string; kind: string}>}> = [];
+	for (const [name, locations] of declaration_locations.entries()) {
+		if (locations.length > 1) {
+			duplicates.push({name, locations});
+		}
+	}
+
+	if (duplicates.length > 0) {
+		log.error('Duplicate declaration names detected in flat namespace:');
+		for (const {name, locations} of duplicates) {
+			log.error(`  "${name}" found in:`);
+			for (const {module, kind} of locations) {
+				log.error(`    - ${module} (${kind})`);
+			}
+		}
+		throw new Error(
+			`Found ${duplicates.length} duplicate declaration name${duplicates.length === 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.',
+		);
+	}
+};
+
+/**
+ * Sort modules alphabetically by path for deterministic output and cleaner diffs.
+ */
+export const library_gen_sort_modules = (modules: Array<ModuleJson>): Array<ModuleJson> => {
+	return modules.slice().sort((a, b) => a.path.localeCompare(b.path));
+};
+
+/**
+ * Generate the library.ts file content with library_json export.
+ * Parses at generation time so runtime only needs the pre-computed result.
+ */
+export const library_gen_generate_ts = (
+	package_json: PackageJson,
+	source_json: SourceJson,
+): string => {
+	const is_this_belt = package_json.name === '@fuzdev/fuz_util';
+	const banner = `// generated by library.gen.ts !! do not edit directly or risk lost data`;
+
+	// Parse at generation time, not runtime
+	const library_json: LibraryJson = library_json_parse(package_json, source_json);
+
+	return `${banner}
+
+import type {LibraryJson} from '${is_this_belt ? './library_json.js' : '@fuzdev/fuz_util/library_json.js'}';
+
+export const library_json: LibraryJson = ${stringify(library_json)};
+
+${banner}
+`;
+};
+
+const stringify = (v: unknown): string => JSON.stringify(v, null, '\t');
+
+/**
+ * Collect and filter source files from filer.
+ *
+ * Returns disknodes for TypeScript/JS files and Svelte components from src/lib, excluding test files.
+ * Returns an empty array with a warning if no source files are found.
+ */
+export const library_gen_collect_source_files = (
+	files: Map<PathId, Disknode>,
+	log: Logger,
+): Array<Disknode> => {
+	log.info(`filer has ${files.size} files total`);
+
+	const source_disknodes: Array<Disknode> = [];
+	for (const [id, disknode] of files.entries()) {
+		if (module_matches_source(id)) {
+			// Include TypeScript/JS files and Svelte components
+			if (module_is_typescript(id) || module_is_svelte(id)) {
+				source_disknodes.push(disknode);
+			}
+		}
+	}
+
+	log.info(`found ${source_disknodes.length} source files to analyze`);
+
+	if (source_disknodes.length === 0) {
+		log.warn('No source files found in src/lib - generating empty library metadata');
+		return [];
+	}
+
+	// Sort for deterministic output (stable alphabetical module ordering)
+	source_disknodes.sort((a, b) => a.id.localeCompare(b.id));
+
+	return source_disknodes;
+};
+
+/**
+ * Analyze a Svelte component file and extract metadata.
+ *
+ * Uses `svelte_analyze_file` for core analysis, then adds
+ * Gro-specific dependency information from the disknode.
+ */
+export const library_gen_analyze_svelte_file = (
+	disknode: Disknode,
+	module_path: string,
+	checker: ts.TypeChecker,
+): ModuleJson => {
+	// Use the extracted helper for core analysis
+	const declaration_json = svelte_analyze_file(disknode.id, module_path, checker);
+
+	// Extract dependencies and dependents (Gro-specific)
+	const {dependencies, dependents} = library_gen_extract_dependencies(disknode);
+
+	return {
+		path: module_path,
+		declarations: [declaration_json],
+		dependencies: dependencies.length > 0 ? dependencies : undefined,
+		dependents: dependents.length > 0 ? dependents : undefined,
+	};
+};
+
+/**
+ * Analyze a TypeScript file and extract all declarations.
+ *
+ * Uses `ts_analyze_module_exports` for core analysis, then adds
+ * Gro-specific dependency information from the disknode.
+ *
+ * Returns both the module metadata and re-export information for post-processing.
+ */
+export const library_gen_analyze_typescript_file = (
+	disknode: Disknode,
+	source_file: ts.SourceFile,
+	module_path: string,
+	checker: ts.TypeChecker,
+): TsFileAnalysis => {
+	// Use the extracted helper for core analysis
+	const {module_comment, declarations, re_exports} = ts_analyze_module_exports(
+		source_file,
+		checker,
+	);
+
+	const mod: ModuleJson = {
+		path: module_path,
+		declarations,
+	};
+
+	if (module_comment) {
+		mod.module_comment = module_comment;
+	}
+
+	// Extract dependencies and dependents (Gro-specific)
+	const {dependencies, dependents} = library_gen_extract_dependencies(disknode);
+	if (dependencies.length > 0) {
+		mod.dependencies = dependencies;
+	}
+	if (dependents.length > 0) {
+		mod.dependents = dependents;
+	}
+
+	return {module: mod, re_exports};
+};
+
+/**
+ * Extract dependencies and dependents for a module from the filer's dependency graph.
+ *
+ * Filters to only include source modules from src/lib (excludes external packages, node_modules, tests).
+ * Returns sorted arrays of module paths (relative to src/lib) for deterministic output.
+ */
+export const library_gen_extract_dependencies = (
+	disknode: Disknode,
+): {dependencies: Array<string>; dependents: Array<string>} => {
+	const dependencies: Array<string> = [];
+	const dependents: Array<string> = [];
+
+	// Extract dependencies (files this module imports)
+	for (const dep_id of disknode.dependencies.keys()) {
+		if (module_matches_source(dep_id)) {
+			dependencies.push(module_extract_path(dep_id));
+		}
+	}
+
+	// Extract dependents (files that import this module)
+	for (const dependent_id of disknode.dependents.keys()) {
+		if (module_matches_source(dependent_id)) {
+			dependents.push(module_extract_path(dependent_id));
+		}
+	}
+
+	// Sort for deterministic output
+	dependencies.sort();
+	dependents.sort();
+
+	return {dependencies, dependents};
+};

package/src/lib/library_helpers.ts

@@ -0,0 +1,123 @@
+import {ensure_end, strip_end, strip_start} from '@fuzdev/fuz_util/string.js';
+import type {PackageJson} from '@fuzdev/fuz_util/package_json.js';
+import {page} from '$app/state';
+
+import {DOCS_API_PATH, DOCS_PATH_DEFAULT} from './docs_helpers.svelte.js';
+
+/**
+ * Build project-relative API documentation URL with hash anchor.
+ */
+export const url_api_declaration = (declaration_name: string): string =>
+	`${DOCS_API_PATH}#${encodeURIComponent(declaration_name)}`;
+
+/**
+ * Build full API documentation URL with domain and hash anchor.
+ */
+export const url_api_declaration_full = (homepage: string, declaration_name: string): string =>
+	`${homepage}${DOCS_PATH_DEFAULT}/api#${encodeURIComponent(declaration_name)}`;
+
+/**
+ * Build project-relative module documentation URL.
+ */
+export const url_api_module = (module_path: string): string => `${DOCS_API_PATH}/${module_path}`;
+
+/**
+ * Build GitHub file URL for a repository.
+ */
+export const url_github_file = (repo_url: string, file_path: string, line?: number): string => {
+	const clean_path = file_path.replace(/^\.\//, '');
+	const base = `${repo_url}/blob/main/${clean_path}`;
+	return line ? `${base}#L${line}` : base;
+};
+
+/**
+ * Build GitHub organization URL from repo URL and repo name.
+ */
+export const url_github_org = (repo_url: string, repo_name: string): string | null => {
+	return repo_url.endsWith('/' + repo_name) ? strip_end(repo_url, '/' + repo_name) : null;
+};
+
+/**
+ * Parse GitHub owner/org name from repository URL.
+ */
+export const github_owner_parse = (repo_url: string): string | null => {
+	const stripped = strip_start(repo_url, 'https://github.com/');
+	if (stripped === repo_url) return null;
+	const parts = stripped.split('/');
+	return parts[0] || null;
+};
+
+/**
+ * Build npm package URL.
+ */
+export const url_npm_package = (package_name: string): string =>
+	'https://www.npmjs.com/package/' + package_name;
+
+/**
+ * Check if a package is published to npm.
+ */
+export const package_is_published = (package_json: PackageJson): boolean => {
+	return !package_json.private && !!package_json.exports && package_json.version !== '0.0.1';
+};
+
+/**
+ * Build package logo URL with favicon.png fallback.
+ */
+export const url_package_logo = (
+	homepage_url: string | null,
+	logo_path?: string,
+): string | null => {
+	if (!homepage_url) return null;
+	const path = logo_path ? strip_start(logo_path, '/') : 'favicon.png';
+	return ensure_end(homepage_url, '/') + path;
+};
+
+/**
+ * Extract repository name without scope from package name.
+ */
+export const repo_name_parse = (name: string): string => {
+	if (name[0] === '@') {
+		const parts = name.split('/');
+		if (parts.length < 2) {
+			throw new Error(`invalid scoped package name: "${name}" (expected format: @org/package)`);
+		}
+		return parts[1]!;
+	}
+	return name;
+};
+
+/**
+ * Parse repository URL from package.json format.
+ */
+export const repo_url_parse = (repository: PackageJson['repository']): string | null => {
+	if (!repository) return null;
+	const url = typeof repository === 'string' ? repository : repository.url;
+	if (!url) return null;
+	return strip_end(strip_start(strip_end(url, '.git'), 'git+'), '/');
+};
+
+/**
+ * Build .well-known URL for package metadata files.
+ */
+export const url_well_known = (homepage_url: string, filename: string): string => {
+	return `${ensure_end(homepage_url, '/')}.well-known/${filename}`;
+};
+
+/**
+ * Convert a full URL to root-relative format by removing the origin.
+ */
+export const url_to_root_relative = (url: string, origin: string = page.url.origin): string => {
+	const origin_with_slash = ensure_end(origin, '/');
+
+	if (url === origin || url === origin_with_slash) {
+		return '/';
+	}
+
+	const stripped = strip_start(url, origin_with_slash);
+
+	if (stripped === url) {
+		return url;
+	}
+
+	return '/' + stripped;
+};