@fuzdev/fuz_gitops 0.78.1 → 0.79.0

package/src/lib/gitops_validate.task.ts

@@ -2,13 +2,11 @@ import type { Task } from '@fuzdev/gro';
 import { z } from 'zod';
 import { styleText as st } from 'node:util';
 
-import { get_gitops_ready } from './gitops_task_helpers.ts';
-import { analyze_repos, type DependencyAnalysis } from './graph_validation.ts';
-import {
-	generate_publishing_plan,
-	log_publishing_plan,
-	type PublishingPlan
-} from './publishing_plan.ts';
+import { get_gitops_ready, log_readiness_block } from './gitops_task_helpers.ts';
+import { analyze_repos } from './graph_validation.ts';
+import type { DependencyAnalysis } from './dependency_graph.ts';
+import { generate_publishing_plan, type PublishingPlan } from './publishing_plan.ts';
+import { log_publishing_plan } from './publishing_plan_logging.ts';
 import { execute_publishing_plan, type PublishingOptions } from './multi_repo_publisher.ts';
 import { log_dependency_analysis } from './log_helpers.ts';
 import { GITOPS_CONFIG_PATH_DEFAULT } from './gitops_constants.ts';
@@ -20,18 +18,14 @@ export const Args = z.strictObject({
 		.string()
 		.meta({ description: 'path to the gitops config file, absolute or relative to the cwd' })
 		.default(GITOPS_CONFIG_PATH_DEFAULT),
-	dir: z
+	registry: z
 		.string()
-		.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'
+				'path to the repos.toml registry, when `repos` would not find it walking up from the cwd'
 		})
-		.default(false)
+		.optional(),
+	verbose: z.boolean().meta({ description: 'show additional details' }).default(false)
 });
 export type Args = z.infer<typeof Args>;
 
@@ -41,7 +35,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, sync } = args;
+		const { config, registry, verbose } = args;
 
 		log.info(st('cyan', 'Running Gitops Validation Suite'));
 		log.info(st('dim', 'This runs all read-only commands and checks for consistency.'));
@@ -59,10 +53,11 @@ export const task: Task<Args> = {
 
 		const start_time = Date.now();
 
-		// Load repos once (shared by all commands); read the working tree as-is unless `--sync`
+		// Load repos once (shared by all commands), as they sit, and say which aren't at rest
 		log.info(st('dim', 'Loading repositories...'));
-		const { local_repos } = await get_gitops_ready({ config, dir, download: false, sync, log });
+		const { local_repos } = await get_gitops_ready({ config, registry, log });
 		log.info(st('dim', `   Found ${local_repos.length} local repos`));
+		log_readiness_block(local_repos, log);
 
 		// 1. Run gitops_analyze
 		log.info(st('yellow', 'Running gitops_analyze...'));
@@ -203,21 +198,16 @@ export const task: Task<Args> = {
 			log.error(st('red', `  ✗ gitops_publish (dry run) failed: ${error}`));
 		}
 
-		// 4. Reconcile each repo's declared `ci` against actual workflow files on disk.
+		// 4. Reconcile each repo's registry-declared `ci` against actual workflow files on disk.
 		log.info(st('yellow', 'Running ci_reconcile...'));
 		const ci_start = Date.now();
 		try {
 			const ci_drift = reconcile_ci(
 				local_repos.map((r) => ({
-					repo_url: r.repo_config.repo_url,
-					ci: r.repo_config.ci,
+					repo_url: r.entry.url,
+					ci: r.entry.ci,
 					has_workflows: repo_has_workflows(r.repo_dir),
-					// TODO: `local_repos` only ever holds checked-out repos — a missing repo
-					// throws in `local_repos_ensure` before we reach here — so `checkable` is
-					// always `true` today. The gate exists for a future caller that loads a
-					// partial set; until then the skip path is inert and untested.
-					checkable: true,
-					archived: r.repo_config.archived
+					archived: r.entry.archived
 				}))
 			);
 			const ci_duration = Date.now() - ci_start;

package/src/lib/graph_validation.ts

@@ -1,23 +1,17 @@
 /**
- * Shared dependency graph validation logic used across multiple workflows.
+ * Dependency graph validation shared by the publishing plan and the analysis tasks.
  *
- * 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`.
+ * Builds the graph, detects cycles by type, and computes the publishing order,
+ * reporting cycles and sort failures in the result rather than throwing, so
+ * each caller decides how to surface them: the plan turns them into errors,
+ * `gitops_analyze` and `gitops_validate` format them.
  *
- * 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.
+ * See also: `dependency_graph.ts` for the core graph data structure and algorithms.
  *
  * @module
  */
 
-import type { Logger } from '@fuzdev/fuz_util/log.ts';
-import { TaskError } from '@fuzdev/gro';
-import { styleText as st } from 'node:util';
-
-import { DependencyGraph, DependencyGraphBuilder } from './dependency_graph.ts';
+import { DependencyGraph, type DependencyAnalysis } from './dependency_graph.ts';
 import { repo_is_npm, type LocalRepo } from './local_repo.ts';
 
 export interface GraphValidationResult {
@@ -25,79 +19,29 @@ export interface GraphValidationResult {
 	publishing_order: Array<string>;
 	production_cycles: Array<Array<string>>;
 	dev_cycles: Array<Array<string>>;
-	sort_error?: string; // Error message if topological sort failed
+	/** Why the topological sort failed, when it did; `publishing_order` is then empty. */
+	sort_error?: string;
 }
 
 /**
- * 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`.
+ * Builds the dependency graph, detects cycles, and computes the publishing order
+ * (prod/peer dependencies only, so dev cycles don't block it).
  *
- * @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
+ * Never throws on cycles: a production/peer cycle leaves `publishing_order` empty
+ * and sets `sort_error`, and the caller reports it.
+ *
+ * @returns the graph, publishing order, and detected cycles
  */
-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
+export const validate_dependency_graph = (repos: Array<LocalRepo>): GraphValidationResult => {
+	const graph = new DependencyGraph(repos);
 	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 = [];
 	}
 
@@ -110,9 +54,6 @@ export const validate_dependency_graph = (
 	};
 };
 
-/** Cycles, wildcard deps, and missing peers produced by `DependencyGraphBuilder.analyze`. */
-export type DependencyAnalysis = ReturnType<DependencyGraphBuilder['analyze']>;
-
 export interface RepoAnalysis {
 	graph: DependencyGraph;
 	analysis: DependencyAnalysis;
@@ -123,16 +64,14 @@ export interface RepoAnalysis {
 /**
  * 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.
+ * `gitops_validate`, which format the result themselves.
  */
 export const analyze_repos = (repos: Array<LocalRepo>): RepoAnalysis => {
-	// Only npm packages form the dependency graph; non-npm repos (e.g. cargo) are excluded.
-	const { graph, publishing_order: order } = validate_dependency_graph(repos.filter(repo_is_npm), {
-		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 };
+	// only npm packages form the dependency graph; non-npm repos (e.g. cargo) are excluded
+	const { graph, publishing_order } = validate_dependency_graph(repos.filter(repo_is_npm));
+	return {
+		graph,
+		analysis: graph.analyze(),
+		publishing_order: publishing_order.length > 0 ? publishing_order : null
+	};
 };