@fuzdev/fuz_gitops 0.57.0

package/src/lib/graph_validation.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared dependency graph validation logic used across multiple workflows.
+ *
+ * Consolidates graph building, cycle detection, and publishing order computation
+ * that was duplicated in three places: `multi_repo_publisher.ts`, `publishing_plan.ts`,
+ * and `gitops_analyze.task.ts`.
+ *
+ * Options pattern supports different behaviors: analyze can tolerate cycles for
+ * reporting, while publish must throw on production cycles.
+ *
+ * See also: `dependency_graph.ts` for core graph data structure and algorithms.
+ */
+
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import {TaskError} from '@ryanatkn/gro';
+import {styleText as st} from 'node:util';
+
+import {DependencyGraph, DependencyGraphBuilder} from './dependency_graph.js';
+import type {LocalRepo} from './local_repo.js';
+
+export interface GraphValidationResult {
+	graph: DependencyGraph;
+	publishing_order: Array<string>;
+	production_cycles: Array<Array<string>>;
+	dev_cycles: Array<Array<string>>;
+	sort_error?: string; // Error message if topological sort failed
+}
+
+/**
+ * Shared utility for building dependency graph, detecting cycles, and computing publishing order.
+ * This centralizes logic that was duplicated across multi_repo_publisher, publishing_plan, and gitops_analyze.
+ *
+ * @param options.throw_on_prod_cycles whether to throw an error if production cycles are detected (default: true)
+ * @param options.log_cycles whether to log cycle information (default: true)
+ * @param options.log_order whether to log publishing order (default: true)
+ * @returns graph validation result with graph, publishing order, and detected cycles
+ * @throws {TaskError} if production cycles detected and throw_on_prod_cycles is true
+ */
+export const validate_dependency_graph = (
+	repos: Array<LocalRepo>,
+	options: {
+		log?: Logger;
+		throw_on_prod_cycles?: boolean;
+		log_cycles?: boolean;
+		log_order?: boolean;
+	} = {},
+): GraphValidationResult => {
+	const {log, throw_on_prod_cycles = true, log_cycles = true, log_order = true} = options;
+
+	// Build dependency graph
+	log?.info('📊 Analyzing dependencies...');
+	const builder = new DependencyGraphBuilder();
+	const graph = builder.build_from_repos(repos);
+
+	// Check for cycles
+	const {production_cycles, dev_cycles} = graph.detect_cycles_by_type();
+
+	// Log production cycles
+	if (production_cycles.length > 0 && log_cycles) {
+		log?.error(st('red', '❌ Production/peer dependency cycles detected:'));
+		for (const cycle of production_cycles) {
+			log?.error(`  ${cycle.join(' → ')}`);
+		}
+
+		if (throw_on_prod_cycles) {
+			throw new TaskError(
+				`Cannot publish with production/peer dependency cycles. ` +
+					`These must be resolved before publishing.`,
+			);
+		}
+	}
+
+	// Log dev cycles (informational, not an error)
+	if (dev_cycles.length > 0 && log_cycles) {
+		log?.info(st('dim', 'ℹ️  Dev dependency cycles detected (this is normal):'));
+		for (const cycle of dev_cycles) {
+			log?.info(st('dim', `  ${cycle.join(' → ')}`));
+		}
+	}
+
+	// Compute publishing order
+	let publishing_order: Array<string>;
+	let sort_error: string | undefined;
+	try {
+		publishing_order = graph.topological_sort(true); // exclude dev deps to break cycles
+		if (log_order && publishing_order.length > 0) {
+			log?.info(`  Publishing order: ${publishing_order.join(' → ')}`);
+		}
+	} catch (error) {
+		// Capture the sort error message for callers to report
+		sort_error = 'Failed to compute publishing order: ' + error;
+
+		// If topological sort fails (due to cycles), return empty array
+		// Only throw if production cycles exist AND throw_on_prod_cycles is true
+		if (production_cycles.length > 0 && throw_on_prod_cycles) {
+			throw new TaskError(sort_error);
+		}
+		// Otherwise, return empty publishing order (let caller handle it)
+		publishing_order = [];
+	}
+
+	return {
+		graph,
+		publishing_order,
+		production_cycles,
+		dev_cycles,
+		sort_error,
+	};
+};

package/src/lib/local_repo.ts

@@ -0,0 +1,359 @@
+import {strip_end} from '@fuzdev/fuz_util/string.js';
+import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
+import {Library} from '@fuzdev/fuz_ui/library.svelte.js';
+import {existsSync} from 'node:fs';
+import {join} from 'node:path';
+import {TaskError} from '@ryanatkn/gro';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import {spawn} from '@fuzdev/fuz_util/process.js';
+import type {GitOperations, NpmOperations} from './operations.js';
+import {default_git_operations, default_npm_operations} from './operations_defaults.js';
+
+import type {GitopsConfig, GitopsRepoConfig} from './gitops_config.js';
+import type {ResolvedGitopsConfig} from './resolved_gitops_config.js';
+
+/**
+ * Fully loaded local repo with Library and extracted dependency data.
+ * Does not extend LocalRepoPath - Library is source of truth for name/repo_url/etc.
+ */
+export interface LocalRepo {
+	library: Library;
+	library_json: LibraryJson;
+	repo_dir: string;
+	repo_git_ssh_url: string;
+	repo_config: GitopsRepoConfig;
+	dependencies?: Map<string, string>;
+	dev_dependencies?: Map<string, string>;
+	peer_dependencies?: Map<string, string>;
+}
+
+/**
+ * A repo that has been located on the filesystem (path exists).
+ * Used before loading - just filesystem/git concerns.
+ */
+export interface LocalRepoPath {
+	type: 'local_repo_path';
+	repo_name: string; // from URL parsing (for display/logging before Library loaded)
+	repo_dir: string;
+	repo_url: string;
+	repo_git_ssh_url: string;
+	repo_config: GitopsRepoConfig;
+}
+
+/**
+ * A repo that is missing from the filesystem (needs cloning).
+ */
+export interface LocalRepoMissing {
+	type: 'local_repo_missing';
+	repo_name: string;
+	repo_url: string;
+	repo_git_ssh_url: string;
+	repo_config: GitopsRepoConfig;
+}
+
+/**
+ * Loads repo data with automatic syncing and dependency management.
+ *
+ * Workflow:
+ * 1. Records current commit hash (for detecting changes)
+ * 2. Switches to target branch if needed (requires clean workspace)
+ * 3. Pulls latest changes from remote (skipped for local-only repos)
+ * 4. Validates workspace is clean after pull
+ * 5. Auto-installs dependencies if package.json changed
+ * 6. Imports library_json from src/routes/library.ts
+ * 7. Creates Library and extracts dependency maps
+ *
+ * This ensures repos are always in sync with their configured branch
+ * before being used by gitops commands.
+ *
+ * @throws {TaskError} if workspace dirty, branch switch fails, install fails, or library.ts missing
+ */
+export const local_repo_load = async ({
+	local_repo_path,
+	log: _log,
+	git_ops = default_git_operations,
+	npm_ops = default_npm_operations,
+}: {
+	local_repo_path: LocalRepoPath;
+	log?: Logger;
+	git_ops?: GitOperations;
+	npm_ops?: NpmOperations;
+}): Promise<LocalRepo> => {
+	const {repo_config, repo_dir, repo_name, repo_git_ssh_url} = local_repo_path;
+
+	// Record commit hash before any changes
+	const commit_before_result = await git_ops.current_commit_hash({cwd: repo_dir});
+	if (!commit_before_result.ok) {
+		throw new TaskError(
+			`Failed to get commit hash in ${repo_dir}: ${commit_before_result.message}`,
+		);
+	}
+	const commit_before = commit_before_result.value;
+
+	// Switch to target branch if needed
+	const branch_result = await git_ops.current_branch_name({cwd: repo_dir});
+	if (!branch_result.ok) {
+		throw new TaskError(`Failed to get current branch in ${repo_dir}: ${branch_result.message}`);
+	}
+
+	const switched_branches = branch_result.value !== repo_config.branch;
+	if (switched_branches) {
+		const clean_result = await git_ops.check_clean_workspace({cwd: repo_dir});
+		if (!clean_result.ok) {
+			throw new TaskError(`Failed to check workspace in ${repo_dir}: ${clean_result.message}`);
+		}
+
+		if (!clean_result.value) {
+			throw new TaskError(
+				`Repo ${repo_dir} is not on branch "${repo_config.branch}" and the workspace is unclean, blocking switch`,
+			);
+		}
+
+		const checkout_result = await git_ops.checkout({branch: repo_config.branch, cwd: repo_dir});
+		if (!checkout_result.ok) {
+			throw new TaskError(
+				`Failed to checkout branch "${repo_config.branch}" in ${repo_dir}: ${checkout_result.message}`,
+			);
+		}
+	}
+
+	// Only pull if remote exists (skip for local-only repos, test fixtures)
+	const origin_result = await git_ops.has_remote({remote: 'origin', cwd: repo_dir});
+	if (!origin_result.ok) {
+		throw new TaskError(`Failed to check for remote in ${repo_dir}: ${origin_result.message}`);
+	}
+
+	if (origin_result.value) {
+		const pull_result = await git_ops.pull({cwd: repo_dir});
+		if (!pull_result.ok) {
+			throw new TaskError(`Failed to pull in ${repo_dir}: ${pull_result.message}`);
+		}
+	}
+
+	// Check clean workspace after pull to ensure we're in a good state
+	const clean_after_result = await git_ops.check_clean_workspace({cwd: repo_dir});
+	if (!clean_after_result.ok) {
+		throw new TaskError(`Failed to check workspace in ${repo_dir}: ${clean_after_result.message}`);
+	}
+
+	if (!clean_after_result.value) {
+		throw new TaskError(
+			`Workspace ${repo_dir} is unclean after pulling branch "${repo_config.branch}"`,
+		);
+	}
+
+	// Record commit hash after pull
+	const commit_after_result = await git_ops.current_commit_hash({cwd: repo_dir});
+	if (!commit_after_result.ok) {
+		throw new TaskError(`Failed to get commit hash in ${repo_dir}: ${commit_after_result.message}`);
+	}
+	const commit_after = commit_after_result.value;
+
+	// Track if we got new commits
+	const got_new_commits = commit_before !== commit_after;
+
+	// Only install if package.json changed
+	if (got_new_commits) {
+		const changed_result = await git_ops.has_file_changed({
+			from_commit: commit_before,
+			to_commit: commit_after,
+			file_path: 'package.json',
+			cwd: repo_dir,
+		});
+
+		if (!changed_result.ok) {
+			throw new TaskError(
+				`Failed to check if package.json changed in ${repo_dir}: ${changed_result.message}`,
+			);
+		}
+
+		if (changed_result.value) {
+			const install_result = await npm_ops.install({cwd: repo_dir});
+			if (!install_result.ok) {
+				throw new TaskError(
+					`Failed to install dependencies in ${repo_dir}: ${install_result.message}${install_result.stderr ? `\n${install_result.stderr}` : ''}`,
+				);
+			}
+		}
+	}
+
+	// Validate and load library.ts
+	const library_path = join(repo_dir, 'src/routes/library.ts');
+	if (!existsSync(library_path)) {
+		throw new TaskError(
+			`Repo "${repo_name}" is missing src/routes/library.ts\n` +
+				`This file is required for fuz_gitops. To fix:\n` +
+				`  1. Create src/routes/library.gen.ts with:\n` +
+				`     import {library_gen} from '@fuzdev/fuz_ui/library_gen.js';\n` +
+				`     export const gen = library_gen();\n` +
+				`  2. Run: cd ${repo_dir} && gro gen`,
+		);
+	}
+
+	const library_module = await import(library_path);
+	const {library_json} = library_module as {library_json: LibraryJson | undefined};
+	if (!library_json) {
+		throw new TaskError(
+			`Repo "${repo_name}" has invalid src/routes/library.ts - missing library_json export\n` +
+				`The file must export a library_json object. To fix:\n` +
+				`  1. Ensure src/routes/library.gen.ts uses library_gen from @fuzdev/fuz_ui\n` +
+				`  2. Run: cd ${repo_dir} && gro gen`,
+		);
+	}
+	const library = new Library(library_json);
+
+	const local_repo: LocalRepo = {
+		library,
+		library_json,
+		repo_dir,
+		repo_git_ssh_url,
+		repo_config,
+	};
+
+	// Extract dependencies from package_json
+	const {package_json} = library;
+	if (package_json.dependencies) {
+		local_repo.dependencies = new Map(Object.entries(package_json.dependencies));
+	}
+	if (package_json.devDependencies) {
+		local_repo.dev_dependencies = new Map(Object.entries(package_json.devDependencies));
+	}
+	if (package_json.peerDependencies) {
+		local_repo.peer_dependencies = new Map(Object.entries(package_json.peerDependencies));
+	}
+
+	return local_repo;
+};
+
+export const local_repos_ensure = async ({
+	resolved_config,
+	repos_dir,
+	gitops_config,
+	download,
+	log,
+	npm_ops = default_npm_operations,
+}: {
+	resolved_config: ResolvedGitopsConfig;
+	repos_dir: string;
+	gitops_config: GitopsConfig;
+	download: boolean;
+	log?: Logger;
+	npm_ops?: NpmOperations;
+}): Promise<Array<LocalRepoPath>> => {
+	let local_repo_paths: Array<LocalRepoPath> | null = null;
+
+	if (!resolved_config.local_repos_missing) {
+		local_repo_paths = resolved_config.local_repo_paths;
+	} else {
+		if (download) {
+			const downloaded = await download_repos({
+				repos_dir,
+				local_repos_missing: resolved_config.local_repos_missing,
+				log,
+				npm_ops,
+			});
+			local_repo_paths = (resolved_config.local_repo_paths ?? [])
+				.concat(downloaded)
+				.sort(
+					(a, b) =>
+						gitops_config.repos.findIndex((r) => r.repo_url === a.repo_url) -
+						gitops_config.repos.findIndex((r) => r.repo_url === b.repo_url),
+				);
+		} else {
+			log?.error(
+				`Failed to resolve local repos in ${repos_dir} - do you need to pass \`--download\` or configure the directory?`, // TODO leaking task impl details
+				resolved_config.local_repos_missing.map((r) => r.repo_url),
+			);
+			throw new TaskError('Failed to resolve local configs');
+		}
+	}
+
+	if (!local_repo_paths) {
+		throw new TaskError('No repos are configured in `gitops_config.ts`');
+	}
+
+	return local_repo_paths;
+};
+
+export const local_repos_load = async ({
+	local_repo_paths,
+	log,
+	git_ops = default_git_operations,
+	npm_ops = default_npm_operations,
+}: {
+	local_repo_paths: Array<LocalRepoPath>;
+	log?: Logger;
+	git_ops?: GitOperations;
+	npm_ops?: NpmOperations;
+}): Promise<Array<LocalRepo>> => {
+	const loaded: Array<LocalRepo> = [];
+	for (const local_repo_path of local_repo_paths) {
+		loaded.push(await local_repo_load({local_repo_path, log, git_ops, npm_ops})); // eslint-disable-line no-await-in-loop
+	}
+	return loaded;
+};
+
+export const local_repo_locate = ({
+	repo_config,
+	repos_dir,
+}: {
+	repo_config: GitopsRepoConfig;
+	repos_dir: string;
+}): LocalRepoPath | LocalRepoMissing => {
+	const {repo_url} = repo_config;
+	const repo_name = strip_end(repo_url, '/').split('/').at(-1);
+	if (!repo_name) throw Error('Invalid `repo_config.repo_url` ' + repo_url);
+
+	const repo_git_ssh_url = to_repo_git_ssh_url(repo_url);
+
+	const repo_dir = repo_config.repo_dir ?? join(repos_dir, repo_name);
+	if (!existsSync(repo_dir)) {
+		return {type: 'local_repo_missing', repo_name, repo_url, repo_git_ssh_url, repo_config};
+	}
+
+	return {
+		type: 'local_repo_path',
+		repo_name,
+		repo_dir,
+		repo_url,
+		repo_git_ssh_url,
+		repo_config,
+	};
+};
+
+const to_repo_git_ssh_url = (repo_url: string): string => {
+	const url = new URL(repo_url);
+	return `git@${url.hostname}:${url.pathname.substring(1)}`;
+};
+
+const download_repos = async ({
+	repos_dir,
+	local_repos_missing,
+	log,
+	npm_ops = default_npm_operations,
+}: {
+	repos_dir: string;
+	local_repos_missing: Array<LocalRepoMissing>;
+	log?: Logger;
+	npm_ops?: NpmOperations;
+}): Promise<Array<LocalRepoPath>> => {
+	const resolved: Array<LocalRepoPath> = [];
+	for (const {repo_config, repo_git_ssh_url} of local_repos_missing) {
+		log?.info(`cloning repo ${repo_git_ssh_url} to ${repos_dir}`);
+		await spawn('git', ['clone', repo_git_ssh_url], {cwd: repos_dir}); // eslint-disable-line no-await-in-loop
+		const local_repo = local_repo_locate({repo_config, repos_dir});
+		if (local_repo.type === 'local_repo_missing') {
+			throw new TaskError(`Failed to clone repo ${repo_git_ssh_url} to ${repos_dir}`);
+		}
+		// Always install dependencies after cloning
+		log?.info(`installing dependencies for newly cloned repo ${local_repo.repo_dir}`);
+		const install_result = await npm_ops.install({cwd: local_repo.repo_dir}); // eslint-disable-line no-await-in-loop
+		if (!install_result.ok) {
+			throw new TaskError(
+				`Failed to install dependencies in ${local_repo.repo_dir}: ${install_result.message}${install_result.stderr ? `\n${install_result.stderr}` : ''}`,
+			);
+		}
+		resolved.push(local_repo);
+	}
+	return resolved;
+};

package/src/lib/log_helpers.ts

@@ -0,0 +1,147 @@
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import {styleText as st} from 'node:util';
+
+import type {DependencyGraphBuilder} from './dependency_graph.js';
+
+/**
+ * Formats wildcard dependencies as styled strings.
+ * Returns array of lines for inclusion in output.
+ */
+export const format_wildcard_dependencies = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+): Array<string> => {
+	if (analysis.wildcard_deps.length === 0) return [];
+
+	const lines: Array<string> = [];
+	lines.push(st('yellow', `\n⚠️  Found ${analysis.wildcard_deps.length} wildcard dependencies:`));
+	for (const {pkg, dep, version} of analysis.wildcard_deps) {
+		lines.push(`  ${pkg} → ${dep} ${st('red', version)}`);
+	}
+	return lines;
+};
+
+/**
+ * Formats dev circular dependencies as styled strings.
+ * Returns array of lines for inclusion in output.
+ */
+export const format_dev_cycles = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+): Array<string> => {
+	if (analysis.dev_cycles.length === 0) return [];
+
+	const lines: Array<string> = [];
+	lines.push(
+		st(
+			'dim',
+			`\nℹ️  Found ${analysis.dev_cycles.length} dev circular dependencies (normal, non-blocking):`,
+		),
+	);
+	for (const cycle of analysis.dev_cycles) {
+		lines.push(st('dim', `  ${cycle.join(' → ')}`));
+	}
+	return lines;
+};
+
+/**
+ * Formats production/peer circular dependencies as styled strings.
+ * Returns array of lines for inclusion in output.
+ */
+export const format_production_cycles = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+): Array<string> => {
+	if (analysis.production_cycles.length === 0) return [];
+
+	const lines: Array<string> = [];
+	lines.push(
+		st(
+			'red',
+			`\n❌ Found ${analysis.production_cycles.length} production/peer circular dependencies (blocks publishing):`,
+		),
+	);
+	for (const cycle of analysis.production_cycles) {
+		lines.push(`  ${st('red', cycle.join(' → '))}`);
+	}
+	return lines;
+};
+
+/**
+ * Logs wildcard dependencies as warnings.
+ * Wildcard dependencies require attention and should be reviewed.
+ */
+export const log_wildcard_dependencies = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	log: Logger,
+	indent = '',
+): void => {
+	const lines = format_wildcard_dependencies(analysis);
+	for (const line of lines) {
+		log.warn(indent + line);
+	}
+};
+
+/**
+ * Logs dev circular dependencies as info.
+ * Dev cycles are normal and non-blocking, so they're informational, not warnings.
+ */
+export const log_dev_cycles = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	log: Logger,
+	indent = '',
+): void => {
+	const lines = format_dev_cycles(analysis);
+	for (const line of lines) {
+		log.info(indent + line);
+	}
+};
+
+/**
+ * Logs production/peer circular dependencies as errors.
+ * Production cycles block publishing and must be resolved.
+ */
+export const log_production_cycles = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	log: Logger,
+	indent = '',
+): void => {
+	const lines = format_production_cycles(analysis);
+	for (const line of lines) {
+		log.error(indent + line);
+	}
+};
+
+/**
+ * Logs all dependency analysis results (wildcards, production cycles, dev cycles).
+ * Convenience function that calls all three logging functions in order.
+ */
+export const log_dependency_analysis = (
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	log: Logger,
+	indent = '',
+): void => {
+	log_wildcard_dependencies(analysis, log, indent);
+	log_production_cycles(analysis, log, indent);
+	log_dev_cycles(analysis, log, indent);
+};
+
+/**
+ * Logs a simple bulleted list with a header.
+ * Common pattern for warnings, info messages, and other lists.
+ */
+export const log_list = (
+	items: Array<string>,
+	header: string,
+	color: 'cyan' | 'yellow' | 'red' | 'dim',
+	log: Logger,
+	log_method: 'info' | 'warn' | 'error' = 'info',
+): void => {
+	if (items.length === 0) return;
+
+	// Only add newline prefix if header is non-empty
+	const formatted_header = header ? `\n${header}` : '';
+	if (formatted_header) {
+		log[log_method](st(color, formatted_header));
+	}
+	for (const item of items) {
+		log[log_method](st(color, `  • ${item}`));
+	}
+};