@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/src/lib/graph_validation.ts

@@ -1,103 +1,47 @@
 /**
- * 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 {repo_is_npm, type LocalRepo} from './local_repo.ts';
+import { DependencyGraph, type DependencyAnalysis } from './dependency_graph.ts';
+import { repo_is_npm, type LocalRepo } from './local_repo.ts';
 
 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
+	/** 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
-	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.`,
-			);
-		}
-	}
+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 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 = [];
 	}
 
@@ -106,13 +50,10 @@ export const validate_dependency_graph = (
 		publishing_order,
 		production_cycles,
 		dev_cycles,
-		sort_error,
+		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;
@@ -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
+	};
 };