@fuzdev/fuz_gitops 0.71.0 → 0.73.0

package/src/lib/gitops_validate.task.ts

@@ -3,10 +3,13 @@ import {z} from 'zod';
 import {styleText as st} from 'node:util';
 
 import {get_gitops_ready} from './gitops_task_helpers.js';
-import {validate_dependency_graph} from './graph_validation.js';
-import {DependencyGraphBuilder} from './dependency_graph.js';
-import {generate_publishing_plan, log_publishing_plan} from './publishing_plan.js';
-import {publish_repos, type PublishingOptions} from './multi_repo_publisher.js';
+import {analyze_repos, type DependencyAnalysis} from './graph_validation.js';
+import {
+	generate_publishing_plan,
+	log_publishing_plan,
+	type PublishingPlan,
+} from './publishing_plan.js';
+import {execute_publishing_plan, type PublishingOptions} from './multi_repo_publisher.js';
 import {log_dependency_analysis} from './log_helpers.js';
 import {GITOPS_CONFIG_PATH_DEFAULT} from './gitops_constants.js';
 
@@ -21,6 +24,13 @@ export const Args = z.strictObject({
 		.meta({description: 'path containing the repos, defaults to the parent of the config dir'})
 		.optional(),
 	verbose: z.boolean().meta({description: 'show additional details'}).default(false),
+	sync: z
+		.boolean()
+		.meta({
+			description:
+				'sync repos (switch branch, pull, install) before validating instead of reading the working tree as-is',
+		})
+		.default(false),
 });
 export type Args = z.infer<typeof Args>;
 
@@ -30,7 +40,7 @@ export const task: Task<Args> = {
 	summary:
 		'validate gitops configuration by running all read-only commands and checking for issues',
 	run: async ({args, log}) => {
-		const {config, dir, verbose} = args;
+		const {config, dir, verbose, sync} = args;
 
 		log.info(st('cyan', 'Running Gitops Validation Suite'));
 		log.info(st('dim', 'This runs all read-only commands and checks for consistency.'));
@@ -43,30 +53,22 @@ export const task: Task<Args> = {
 			duration: number;
 			warning_details?: Array<string>;
 			info_details?: Array<string>;
-			analysis?: ReturnType<DependencyGraphBuilder['analyze']>;
+			analysis?: DependencyAnalysis;
 		}> = [];
 
 		const start_time = Date.now();
 
-		// Load repos once (shared by all commands)
+		// Load repos once (shared by all commands); read the working tree as-is unless `--sync`
 		log.info(st('dim', 'Loading repositories...'));
-		const {local_repos} = await get_gitops_ready({config, dir, download: false, log});
+		const {local_repos} = await get_gitops_ready({config, dir, download: false, sync, log});
 		log.info(st('dim', `   Found ${local_repos.length} local repos`));
 
 		// 1. Run gitops_analyze
 		log.info(st('yellow', 'Running gitops_analyze...'));
 		const analyze_start = Date.now();
 		try {
-			// Build dependency graph and validate (but don't throw on cycles for analyze)
-			const {graph} = validate_dependency_graph(local_repos, {
-				throw_on_prod_cycles: false, // Analyze should report, not throw
-				log_cycles: false, // We'll collect our own statistics
-				log_order: false,
-			});
-
-			// Perform additional analysis
-			const builder = new DependencyGraphBuilder();
-			const analysis = builder.analyze(graph);
+			// Build dependency graph and analyze cycles/wildcards (tolerating cycles)
+			const {analysis} = analyze_repos(local_repos);
 
 			const analyze_duration = Date.now() - analyze_start;
 
@@ -113,11 +115,13 @@ export const task: Task<Args> = {
 			log.error(st('red', `  ✗ gitops_analyze failed: ${error}`));
 		}
 
-		// 2. Run gitops_plan
+		// 2. Run gitops_plan (generated once here and reused by the dry run below)
+		let publishing_plan: PublishingPlan | undefined;
 		log.info(st('yellow', 'Running gitops_plan...'));
 		const plan_start = Date.now();
 		try {
-			const plan = await generate_publishing_plan(local_repos, {log: undefined, verbose});
+			const plan = await generate_publishing_plan(local_repos, {verbose});
+			publishing_plan = plan;
 			const plan_duration = Date.now() - plan_start;
 
 			const warnings = plan.warnings.length;
@@ -159,11 +163,15 @@ export const task: Task<Args> = {
 		try {
 			const options: PublishingOptions = {
 				wetrun: false,
-				update_deps: true,
 				log: undefined, // Silent for validation
 			};
 
-			const result = await publish_repos(local_repos, options);
+			// Reuse the plan from step 2 (regenerate only if that step failed to produce one).
+			const result = await execute_publishing_plan(
+				local_repos,
+				publishing_plan ?? (await generate_publishing_plan(local_repos, {verbose})),
+				options,
+			);
 			const dry_duration = Date.now() - dry_start;
 
 			// Dry run doesn't have warnings/errors in the same format

package/src/lib/graph_validation.ts

@@ -109,3 +109,29 @@ export const validate_dependency_graph = (
 		sort_error,
 	};
 };
+
+/** Cycles, wildcard deps, and missing peers produced by `DependencyGraphBuilder.analyze`. */
+export type DependencyAnalysis = ReturnType<DependencyGraphBuilder['analyze']>;
+
+export interface RepoAnalysis {
+	graph: DependencyGraph;
+	analysis: DependencyAnalysis;
+	/** Topological publishing order, or `null` when prod/peer cycles prevent ordering. */
+	publishing_order: Array<string> | null;
+}
+
+/**
+ * Builds the dependency graph and runs cycle/wildcard analysis, tolerating cycles
+ * (reports rather than throws). The shared core of `gitops_analyze` and
+ * `gitops_validate`, which format the result themselves — so this stays silent
+ * (no `log`) to avoid emitting a redundant "Analyzing dependencies" line.
+ */
+export const analyze_repos = (repos: Array<LocalRepo>): RepoAnalysis => {
+	const {graph, publishing_order: order} = validate_dependency_graph(repos, {
+		throw_on_prod_cycles: false, // report, don't throw
+		log_cycles: false, // callers format their own cycle output
+		log_order: false,
+	});
+	const analysis = new DependencyGraphBuilder().analyze(graph);
+	return {graph, analysis, publishing_order: order.length > 0 ? order : null};
+};

package/src/lib/local_repo.ts

@@ -55,128 +55,153 @@ export interface LocalRepoMissing {
 }
 
 /**
- * Loads repo data with automatic syncing and dependency management.
+ * Loads repo data, optionally syncing the working tree first.
  *
- * Workflow:
+ * When `sync` is `false` (the default for read-only diagnostics like
+ * `gitops_analyze`/`gitops_plan`), the repo is loaded exactly as it sits on
+ * disk — no branch switch, pull, install, or clean-workspace check. This makes
+ * those commands safe to run on an active workspace with uncommitted changes or
+ * feature branches checked out.
+ *
+ * When `sync` is `true` (used by `gitops_sync`), the working tree is brought in
+ * line with the configured branch first:
  * 1. Records current commit hash (for detecting changes)
- * 2. Switches to target branch if needed (requires clean workspace)
+ * 2. Switches to target branch if needed (requires clean workspace unless `allow_dirty`)
  * 3. Pulls latest changes from remote (skipped for local-only repos)
- * 4. Validates workspace is clean after pull
+ * 4. Validates workspace is clean after pull (skipped if `allow_dirty`)
  * 5. Auto-installs dependencies if `package.json` changed
+ *
+ * Either way it then:
  * 6. Loads `library_json` via `library_load_from_repo` (svelte-docinfo analysis)
  * 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 analysis fails
+ * @param sync - sync the working tree to the configured branch before loading (default `true`)
+ * @param allow_dirty - when syncing, tolerate uncommitted changes instead of throwing (default `false`)
+ * @throws {TaskError} if syncing fails (dirty workspace, branch switch, install) or analysis fails
  */
 export const local_repo_load = async ({
 	local_repo_path,
 	log: _log,
 	git_ops = default_git_operations,
 	npm_ops = default_npm_operations,
+	sync = true,
+	allow_dirty = false,
 }: {
 	local_repo_path: LocalRepoPath;
 	log?: Logger;
 	git_ops?: GitOperations;
 	npm_ops?: NpmOperations;
+	sync?: boolean;
+	allow_dirty?: boolean;
 }): 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) {
+	if (sync) {
+		// 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(
-				`Repo ${repo_dir} is not on branch "${repo_config.branch}" and the workspace is unclean, blocking switch`,
+				`Failed to get commit hash in ${repo_dir}: ${commit_before_result.message}`,
 			);
 		}
+		const commit_before = commit_before_result.value;
 
-		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}`,
-			);
+		// 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}`);
 		}
-	}
 
-	// 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}`);
-	}
+		const switched_branches = branch_result.value !== repo_config.branch;
+		if (switched_branches) {
+			// Guard the switch on a clean workspace unless the caller opts into `allow_dirty`,
+			// in which case we let `git checkout` itself fail loudly if it can't proceed.
+			if (!allow_dirty) {
+				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`,
+					);
+				}
+			}
 
-	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}`);
+			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}`,
+				);
+			}
 		}
-	}
 
-	// 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}"`,
-		);
-	}
+		// 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}`);
+		}
 
-	// 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;
+		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}`);
+			}
+		}
 
-	// Track if we got new commits
-	const got_new_commits = commit_before !== commit_after;
+		// Check clean workspace after pull to ensure we're in a good state
+		// (skipped when `allow_dirty`, since uncommitted changes are expected then)
+		if (!allow_dirty) {
+			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}`,
+				);
+			}
 
-	// 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 (!clean_after_result.value) {
+				throw new TaskError(
+					`Workspace ${repo_dir} is unclean after pulling branch "${repo_config.branch}"`,
+				);
+			}
+		}
 
-		if (!changed_result.ok) {
+		// 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 check if package.json changed in ${repo_dir}: ${changed_result.message}`,
+				`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.value) {
-			const install_result = await npm_ops.install({cwd: repo_dir});
-			if (!install_result.ok) {
+			if (!changed_result.ok) {
 				throw new TaskError(
-					`Failed to install dependencies in ${repo_dir}: ${install_result.message}${install_result.stderr ? `\n${install_result.stderr}` : ''}`,
+					`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}` : ''}`,
+					);
+				}
+			}
 		}
 	}
 
@@ -275,6 +300,8 @@ export const local_repos_load = async ({
 	npm_ops = default_npm_operations,
 	parallel = true,
 	concurrency = GITOPS_CONCURRENCY_DEFAULT,
+	sync = true,
+	allow_dirty = false,
 }: {
 	local_repo_paths: Array<LocalRepoPath>;
 	log?: Logger;
@@ -282,12 +309,16 @@ export const local_repos_load = async ({
 	npm_ops?: NpmOperations;
 	parallel?: boolean;
 	concurrency?: number;
+	sync?: boolean;
+	allow_dirty?: boolean;
 }): Promise<Array<LocalRepo>> => {
 	if (!parallel) {
 		// Sequential loading (original behavior)
 		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}));
+			loaded.push(
+				await local_repo_load({local_repo_path, log, git_ops, npm_ops, sync, allow_dirty}),
+			);
 		}
 		return loaded;
 	}
@@ -297,7 +328,7 @@ export const local_repos_load = async ({
 		local_repo_paths,
 		concurrency,
 		async (local_repo_path) => {
-			return local_repo_load({local_repo_path, log, git_ops, npm_ops});
+			return local_repo_load({local_repo_path, log, git_ops, npm_ops, sync, allow_dirty});
 		},
 	);
 

package/src/lib/log_helpers.ts

@@ -13,7 +13,10 @@ export const format_wildcard_dependencies = (
 	if (analysis.wildcard_deps.length === 0) return [];
 
 	const lines: Array<string> = [];
-	lines.push(st('yellow', `\n⚠️  Found ${analysis.wildcard_deps.length} wildcard dependencies:`));
+	// Blank separator as its own line so the logger prefixes it correctly; embedding
+	// a leading `\n` in the header would leave the header line unprefixed.
+	lines.push('');
+	lines.push(st('yellow', `⚠️  Found ${analysis.wildcard_deps.length} wildcard dependencies:`));
 	for (const {pkg, dep, version} of analysis.wildcard_deps) {
 		lines.push(`  ${pkg} → ${dep} ${st('red', version)}`);
 	}
@@ -30,10 +33,11 @@ export const format_dev_cycles = (
 	if (analysis.dev_cycles.length === 0) return [];
 
 	const lines: Array<string> = [];
+	lines.push('');
 	lines.push(
 		st(
 			'dim',
-			`\nℹ️  Found ${analysis.dev_cycles.length} dev circular dependencies (normal, non-blocking):`,
+			`ℹ️  Found ${analysis.dev_cycles.length} dev circular dependencies (normal, non-blocking):`,
 		),
 	);
 	for (const cycle of analysis.dev_cycles) {
@@ -52,10 +56,11 @@ export const format_production_cycles = (
 	if (analysis.production_cycles.length === 0) return [];
 
 	const lines: Array<string> = [];
+	lines.push('');
 	lines.push(
 		st(
 			'red',
-			`\n❌ Found ${analysis.production_cycles.length} production/peer circular dependencies (blocks publishing):`,
+			`❌ Found ${analysis.production_cycles.length} production/peer circular dependencies (blocks publishing):`,
 		),
 	);
 	for (const cycle of analysis.production_cycles) {
@@ -122,26 +127,3 @@ export const log_dependency_analysis = (
 	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}`));
-	}
-};