@fuzdev/fuz_gitops 0.57.0

package/src/lib/gitops_analyze.task.ts

@@ -0,0 +1,261 @@
+import type {Task} from '@ryanatkn/gro';
+import {z} from 'zod';
+import {styleText as st} from 'node:util';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+
+import {get_gitops_ready} from './gitops_task_helpers.js';
+import {type DependencyGraph, DependencyGraphBuilder} from './dependency_graph.js';
+import type {LocalRepo} from './local_repo.js';
+import {validate_dependency_graph} from './graph_validation.js';
+import {
+	format_wildcard_dependencies,
+	format_dev_cycles,
+	format_production_cycles,
+} from './log_helpers.js';
+import {format_and_output, type OutputFormatters} from './output_helpers.js';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	path: z
+		.string()
+		.meta({description: 'path to the gitops config file, absolute or relative to the cwd'})
+		.default('gitops.config.ts'),
+	dir: z
+		.string()
+		.meta({description: 'path containing the repos, defaults to the parent of the `path` dir'})
+		.optional(),
+	format: z
+		.enum(['stdout', 'json', 'markdown'])
+		.meta({description: 'output format'})
+		.default('stdout'),
+	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
+});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	Args,
+	summary: 'analyze dependency structure and relationships across repos',
+	run: async ({args, log}) => {
+		const {path, dir, format, outfile} = args;
+
+		// Get repos ready (without downloading)
+		const {local_repos} = await get_gitops_ready({path, dir, download: false, log});
+
+		// Build dependency graph and validate (but don't throw on cycles for analyze)
+		const {graph, publishing_order: order} = validate_dependency_graph(local_repos, {
+			log,
+			throw_on_prod_cycles: false, // Analyze should report, not throw
+			log_cycles: false, // We'll show cycles in our formatted output
+			log_order: false, // We'll show order in our formatted output
+		});
+
+		// Perform additional analysis
+		const builder = new DependencyGraphBuilder();
+		const analysis = builder.analyze(graph);
+
+		// Publishing order (may be null if prod cycles exist)
+		const publishing_order = order.length > 0 ? order : null;
+
+		// Format and output using output_helpers
+		const data = {
+			repos: local_repos,
+			graph,
+			analysis,
+			publishing_order,
+		};
+
+		await format_and_output(data, create_formatters(), {format, outfile, log});
+	},
+};
+
+// Data type for analysis output
+interface AnalysisData {
+	repos: Array<LocalRepo>;
+	graph: DependencyGraph;
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>;
+	publishing_order: Array<string> | null;
+}
+
+// Create formatters for output_helpers
+const create_formatters = (): OutputFormatters<AnalysisData> => ({
+	json: (data) => format_json(data.graph, data.analysis, data.publishing_order),
+	markdown: (data) => format_markdown(data.repos, data.graph, data.analysis, data.publishing_order),
+	stdout: (data, log) =>
+		format_stdout(data.repos, data.graph, data.analysis, data.publishing_order, log),
+});
+
+// Helper to calculate common statistics
+const calculate_stats = (graph: DependencyGraph) => {
+	const total_deps = Array.from(graph.nodes.values()).reduce(
+		(sum, node) => sum + node.dependencies.size,
+		0,
+	);
+	const internal_deps = Array.from(graph.nodes.values()).reduce(
+		(sum, node) =>
+			sum + Array.from(node.dependencies.keys()).filter((name) => graph.nodes.has(name)).length,
+		0,
+	);
+	return {total_deps, internal_deps};
+};
+
+const format_json = (
+	graph: DependencyGraph,
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	publishing_order: Array<string> | null,
+): string => {
+	const output = {
+		graph: graph.toJSON(),
+		analysis,
+		publishing_order,
+	};
+	return JSON.stringify(output, null, 2);
+};
+
+const format_markdown = (
+	repos: Array<LocalRepo>,
+	graph: DependencyGraph,
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	publishing_order: Array<string> | null,
+): Array<string> => {
+	const lines: Array<string> = ['# Dependency Analysis'];
+
+	// Summary stats
+	const {total_deps, internal_deps} = calculate_stats(graph);
+
+	lines.push('', '## Summary', '');
+	lines.push(`- **Total packages**: ${repos.length}`);
+	lines.push(`- **Total dependencies**: ${total_deps}`);
+	lines.push(`- **Internal dependencies**: ${internal_deps}`);
+	lines.push(`- **Wildcard dependencies**: ${analysis.wildcard_deps.length}`);
+	lines.push(`- **Production/peer cycles**: ${analysis.production_cycles.length}`);
+	lines.push(`- **Dev cycles**: ${analysis.dev_cycles.length}`);
+
+	// Publishing order
+	if (publishing_order) {
+		lines.push('', '## Publishing Order', '');
+		publishing_order.forEach((name, i) => {
+			const node = graph.get_node(name);
+			const version = node ? `v${node.version}` : '';
+			lines.push(`${i + 1}. \`${name}\` ${version}`);
+		});
+	}
+
+	// Cycles (show problems first)
+	if (analysis.production_cycles.length > 0) {
+		lines.push('', '## ❌ Production/Peer Circular Dependencies', '');
+		lines.push('> **These block publishing and must be resolved!**');
+		lines.push('');
+		for (const cycle of analysis.production_cycles) {
+			lines.push(`- ${cycle.map((n) => `\`${n}\``).join(' → ')}`);
+		}
+	}
+
+	if (analysis.dev_cycles.length > 0) {
+		lines.push('', '## ⚠️ Dev Circular Dependencies', '');
+		lines.push('> These are normal and do not block publishing.');
+		lines.push('');
+		for (const cycle of analysis.dev_cycles) {
+			lines.push(`- ${cycle.map((n) => `\`${n}\``).join(' → ')}`);
+		}
+	}
+
+	// Wildcard dependencies
+	if (analysis.wildcard_deps.length > 0) {
+		lines.push('', '## ⚠️ Wildcard Dependencies', '');
+		lines.push('| Package | Dependency | Version |');
+		lines.push('|---------|------------|---------|');
+		for (const {pkg, dep, version} of analysis.wildcard_deps) {
+			lines.push(`| \`${pkg}\` | \`${dep}\` | \`${version}\` |`);
+		}
+	}
+
+	// Dependency graph (simplified)
+	lines.push('', '## Internal Dependencies', '');
+	for (const node of graph.nodes.values()) {
+		const internal_deps = Array.from(node.dependencies.entries()).filter(([name]) =>
+			graph.nodes.has(name),
+		);
+		if (internal_deps.length > 0) {
+			lines.push(`- **${node.name}**`);
+			for (const [dep_name, spec] of internal_deps) {
+				const badge = spec.type === 'peer' ? '(peer)' : spec.type === 'dev' ? '(dev)' : '';
+				lines.push(`  - ${dep_name} ${badge}`);
+			}
+		}
+	}
+
+	return lines;
+};
+
+const format_stdout = (
+	repos: Array<LocalRepo>,
+	graph: DependencyGraph,
+	analysis: ReturnType<DependencyGraphBuilder['analyze']>,
+	publishing_order: Array<string> | null,
+	log: Logger,
+): void => {
+	log.info(st('cyan', `📊 Analyzing ${repos.length} repositories...`));
+
+	// Publishing order
+	if (publishing_order) {
+		log.info(st('yellow', 'Publishing order:'));
+		publishing_order.forEach((name, i) => {
+			const node = graph.get_node(name);
+			const version = node ? node.version : 'unknown';
+			log.info(`  ${st('dim', `${i + 1}.`)} ${name} ${st('dim', `(${version})`)}`);
+		});
+		log.info('');
+	}
+
+	// Dependencies summary
+	log.info(st('yellow', 'Dependency relationships:'));
+	for (const node of graph.nodes.values()) {
+		const internal_deps = Array.from(node.dependencies.entries()).filter(([name]) =>
+			graph.nodes.has(name),
+		);
+		if (internal_deps.length > 0) {
+			log.info(`  ${st('cyan', node.name)}`);
+			for (const [dep_name, spec] of internal_deps) {
+				const type_color = spec.type === 'peer' ? 'magenta' : spec.type === 'dev' ? 'dim' : 'white';
+				log.info(
+					`    ${st(type_color, '→')} ${dep_name} ${st('dim', `(${spec.type}: ${spec.version})`)}`,
+				);
+			}
+		}
+	}
+	log.info('');
+
+	// Dependency analysis
+	for (const line of format_wildcard_dependencies(analysis)) {
+		log.info(line);
+	}
+	for (const line of format_production_cycles(analysis)) {
+		log.info(line);
+	}
+	for (const line of format_dev_cycles(analysis)) {
+		log.info(line);
+	}
+
+	// Success message based on cycle detection
+	const has_prod_cycles = analysis.production_cycles.length > 0;
+	const has_dev_cycles = analysis.dev_cycles.length > 0;
+
+	if (!has_prod_cycles && !has_dev_cycles) {
+		log.info(st('green', '✅ No circular dependencies detected'));
+	} else if (!has_prod_cycles) {
+		log.info(st('green', '✓ Publishing order computed successfully (dev deps excluded)'));
+	}
+
+	// Summary
+	const {total_deps, internal_deps} = calculate_stats(graph);
+
+	log.info('');
+	log.info(st('cyan', 'Summary:'));
+	log.info(`  Total packages: ${repos.length}`);
+	log.info(`  Total dependencies: ${total_deps}`);
+	log.info(`  Internal dependencies: ${internal_deps}`);
+	log.info(`  Wildcard dependencies: ${analysis.wildcard_deps.length}`);
+	log.info(`  Production/peer circular dependencies: ${analysis.production_cycles.length}`);
+	log.info(`  Dev circular dependencies: ${analysis.dev_cycles.length}`);
+};

package/src/lib/gitops_config.ts

@@ -0,0 +1,123 @@
+/**
+ * Configuration types and normalization for gitops multi-repo management.
+ *
+ * Two-phase configuration system:
+ * - `RawGitopsConfig` - User-friendly format with optional fields and flexible types
+ * - `GitopsConfig` - Internal format with required fields and strict types
+ *
+ * This allows users to provide minimal configs (e.g., just URLs as strings) while
+ * the system works with normalized configs internally for type safety.
+ */
+
+import type {Url} from '@fuzdev/fuz_util/url.js';
+import {existsSync} from 'node:fs';
+import {strip_end} from '@fuzdev/fuz_util/string.js';
+import type {GitBranch} from '@fuzdev/fuz_util/git.js';
+
+import {DEFAULT_REPOS_DIR} from './paths.js';
+
+export interface GitopsConfig {
+	repos: Array<GitopsRepoConfig>;
+	repos_dir: string;
+}
+
+export type CreateGitopsConfig = (
+	base_config: GitopsConfig,
+) => RawGitopsConfig | Promise<RawGitopsConfig>;
+
+export interface RawGitopsConfig {
+	repos?: Array<Url | RawGitopsRepoConfig>;
+	repos_dir?: string;
+}
+
+export interface GitopsRepoConfig {
+	/**
+	 * The HTTPS URL to the repo. Does not include a `.git` suffix.
+	 * @example 'https://github.com/fuzdev/fuz_ui'
+	 */
+	repo_url: Url;
+
+	/**
+	 * Relative or absolute path to the repo's local directory.
+	 * If `null`, the directory is inferred from the URL and cwd.
+	 * @example 'relative/path/to/repo'
+	 * @example '/absolute/path/to/repo'
+	 */
+	repo_dir: string | null;
+
+	/**
+	 * The branch name to use when fetching the repo. Defaults to `main`.
+	 */
+	branch: GitBranch;
+}
+
+export interface RawGitopsRepoConfig {
+	repo_url: Url;
+	repo_dir?: string | null;
+	branch?: GitBranch;
+}
+
+export const create_empty_gitops_config = (): GitopsConfig => ({
+	repos: [],
+	repos_dir: DEFAULT_REPOS_DIR,
+});
+
+/**
+ * Transforms a `RawGitopsConfig` to the more strict `GitopsConfig`.
+ * This allows users to provide a more relaxed config.
+ */
+export const normalize_gitops_config = (raw_config: RawGitopsConfig): GitopsConfig => {
+	const empty_config = create_empty_gitops_config();
+	// All of the raw config properties are optional,
+	// so fall back to the empty values when `undefined`.
+	const {repos, repos_dir} = raw_config;
+	return {
+		repos: repos ? repos.map((r) => parse_fuz_repo_config(r)) : empty_config.repos,
+		// Default to two dirs up from config if not specified
+		repos_dir: repos_dir ?? DEFAULT_REPOS_DIR,
+	};
+};
+
+const parse_fuz_repo_config = (r: Url | RawGitopsRepoConfig): GitopsRepoConfig => {
+	if (typeof r === 'string') {
+		return {repo_url: r, repo_dir: null, branch: 'main' as GitBranch}; // TODO @zts use flavored for GitBranch
+	}
+	return {
+		repo_url: strip_end(r.repo_url, '.git'),
+		repo_dir: r.repo_dir ?? null,
+		branch: r.branch ?? ('main' as GitBranch), // TODO @zts use flavored for GitBranch
+	};
+};
+
+export interface GitopsConfigModule {
+	readonly default: RawGitopsConfig | CreateGitopsConfig;
+}
+
+export const load_gitops_config = async (config_path: string): Promise<GitopsConfig | null> => {
+	if (!existsSync(config_path)) {
+		// No user config file found.
+		return null;
+	}
+	// Import the user's `gitops.config.ts`.
+	const config_module = await import(config_path);
+	validate_gitops_config_module(config_module, config_path);
+	return normalize_gitops_config(
+		typeof config_module.default === 'function'
+			? await config_module.default(create_empty_gitops_config())
+			: config_module.default,
+	);
+};
+
+export const validate_gitops_config_module: (
+	config_module: any,
+	config_path: string,
+) => asserts config_module is GitopsConfigModule = (config_module, config_path) => {
+	const config = config_module.default;
+	if (!config) {
+		throw Error(`Invalid Fuz config module at ${config_path}: expected a default export`);
+	} else if (!(typeof config === 'function' || typeof config === 'object')) {
+		throw Error(
+			`Invalid Fuz config module at ${config_path}: the default export must be a function or object`,
+		);
+	}
+};

package/src/lib/gitops_plan.task.ts

@@ -0,0 +1,272 @@
+import type {Task} from '@ryanatkn/gro';
+import {z} from 'zod';
+import {styleText as st} from 'node:util';
+
+import {get_gitops_ready} from './gitops_task_helpers.js';
+import {
+	generate_publishing_plan,
+	log_publishing_plan,
+	type PublishingPlan,
+	type LogPlanOptions,
+} from './publishing_plan.js';
+import {format_and_output, type OutputFormatters} from './output_helpers.js';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	path: z
+		.string()
+		.meta({description: 'path to the gitops config file, absolute or relative to the cwd'})
+		.default('gitops.config.ts'),
+	dir: z
+		.string()
+		.meta({description: 'path containing the repos, defaults to the parent of the `path` dir'})
+		.optional(),
+	format: z
+		.enum(['stdout', 'json', 'markdown'])
+		.meta({description: 'output format'})
+		.default('stdout'),
+	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
+	verbose: z.boolean().meta({description: 'show additional details'}).default(false),
+});
+export type Args = z.infer<typeof Args>;
+
+/**
+ * Generate a publishing plan showing what would happen during multi-repo publishing.
+ * Shows version changes, dependency updates, and breaking change cascades.
+ *
+ * Usage:
+ *   gro gitops_plan
+ *   gro gitops_plan --dir ../repos
+ *   gro gitops_plan --path ./custom.config.ts
+ *
+ * @nodocs
+ */
+export const task: Task<Args> = {
+	summary: 'generate a publishing plan based on changesets',
+	Args,
+	run: async ({args, log}): Promise<void> => {
+		const {dir, path, format, outfile, verbose} = args;
+
+		log.info(st('cyan', 'Generating multi-repo publishing plan...'));
+
+		// Load local repos
+		const {local_repos} = await get_gitops_ready({
+			path,
+			dir,
+			download: false, // Don't download if missing
+			log,
+		});
+
+		if (local_repos.length === 0) {
+			log.error('No local repos found');
+			return;
+		}
+
+		log.info(`  Found ${local_repos.length} local repos`);
+
+		// Generate publishing plan
+		const plan = await generate_publishing_plan(local_repos, {log, verbose});
+
+		// Format and output using output_helpers
+		await format_and_output(plan, create_plan_formatters({verbose}), {format, outfile, log});
+
+		// Exit with error if there are blocking issues
+		if (plan.errors.length > 0) {
+			throw new Error('Publishing plan found errors that would block publishing');
+		}
+	},
+};
+
+const create_plan_formatters = (
+	options: LogPlanOptions = {},
+): OutputFormatters<PublishingPlan> => ({
+	json: (plan) => {
+		const output = {
+			publishing_order: plan.publishing_order,
+			version_changes: plan.version_changes,
+			dependency_updates: plan.dependency_updates,
+			breaking_cascades: Object.fromEntries(plan.breaking_cascades),
+			warnings: plan.warnings,
+			info: plan.info,
+			errors: plan.errors,
+		};
+		return JSON.stringify(output, null, 2);
+	},
+	markdown: (plan) => format_plan_as_markdown(plan),
+	stdout: (plan, log) => log_publishing_plan(plan, log, options),
+});
+
+const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
+	const lines: Array<string> = [];
+	const {
+		publishing_order,
+		version_changes,
+		dependency_updates,
+		breaking_cascades,
+		warnings,
+		info,
+		errors,
+	} = plan;
+
+	lines.push('# Publishing Plan');
+	lines.push('');
+
+	// Errors
+	if (errors.length > 0) {
+		lines.push('## ❌ Errors');
+		lines.push('');
+		for (const error of errors) {
+			lines.push(`- ${error}`);
+		}
+		lines.push('');
+	}
+
+	// Publishing order
+	if (publishing_order.length > 0) {
+		lines.push('## Publishing Order');
+		lines.push('');
+		lines.push(publishing_order.map((p) => `\`${p}\``).join(' → '));
+		lines.push('');
+	}
+
+	// Version changes
+	if (version_changes.length > 0) {
+		const with_changesets = version_changes.filter(
+			(vc) => vc.has_changesets && !vc.needs_bump_escalation,
+		);
+		const with_escalation = version_changes.filter((vc) => vc.needs_bump_escalation);
+		const with_auto_changesets = version_changes.filter((vc) => vc.will_generate_changeset);
+
+		if (with_changesets.length > 0) {
+			lines.push('## Version Changes (from changesets)');
+			lines.push('');
+			lines.push('| Package | From | To | Bump | Major |');
+			lines.push('|---------|------|----|------|-------|');
+			for (const change of with_changesets) {
+				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				lines.push(
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${is_major} |`,
+				);
+			}
+			lines.push('');
+		}
+
+		if (with_escalation.length > 0) {
+			lines.push('## Version Changes (bump escalation required)');
+			lines.push('');
+			lines.push('| Package | From | To | Changesets Bump | Required Bump | Major |');
+			lines.push('|---------|------|-----|-----------------|---------------|-------|');
+			for (const change of with_escalation) {
+				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				lines.push(
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.existing_bump} | ${change.required_bump} | ${is_major} |`,
+				);
+			}
+			lines.push('');
+			lines.push(
+				'> ⬆️ These packages have changesets, but dependencies require a larger version bump.',
+			);
+			lines.push('');
+		}
+
+		if (with_auto_changesets.length > 0) {
+			lines.push('## Version Changes (auto-generated for dependency updates)');
+			lines.push('');
+			lines.push('| Package | From | To | Bump | Major |');
+			lines.push('|---------|------|-----|------|-------|');
+			for (const change of with_auto_changesets) {
+				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				lines.push(
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${is_major} |`,
+				);
+			}
+			lines.push('');
+		}
+	} else {
+		lines.push('## No Packages to Publish');
+		lines.push('');
+		lines.push('No packages have changesets to publish.');
+		lines.push('');
+	}
+
+	// Dependency cascades
+	if (breaking_cascades.size > 0) {
+		lines.push('## Dependency Cascades');
+		lines.push('');
+		for (const [pkg, affected] of breaking_cascades) {
+			lines.push(`- \`${pkg}\` affects: ${affected.map((a) => `\`${a}\``).join(', ')}`);
+		}
+		lines.push('');
+	}
+
+	// Dependency updates - show diff-style
+	if (dependency_updates.length > 0) {
+		// Group by package
+		const updates_by_package: Map<string, typeof dependency_updates> = new Map();
+		for (const update of dependency_updates) {
+			const updates = updates_by_package.get(update.dependent_package) || [];
+			updates.push(update);
+			updates_by_package.set(update.dependent_package, updates);
+		}
+
+		lines.push('## Dependency Updates');
+		lines.push('');
+		for (const [pkg, updates] of updates_by_package) {
+			const has_version_change = version_changes.some((vc) => vc.package_name === pkg);
+			const label = has_version_change ? '' : ' (no republish)';
+			lines.push(`### ${pkg}${label}`);
+			lines.push('');
+			lines.push('```diff');
+			for (const update of updates) {
+				const type_label =
+					update.type === 'dependencies'
+						? 'prod'
+						: update.type === 'peerDependencies'
+							? 'peer'
+							: 'dev';
+				lines.push(
+					`- "${update.updated_dependency}": "${update.current_version}"  # ${type_label}`,
+				);
+				lines.push(`+ "${update.updated_dependency}": "${update.new_version}"  # ${type_label}`);
+			}
+			lines.push('```');
+			lines.push('');
+		}
+	}
+
+	// Warnings (actual issues requiring attention)
+	if (warnings.length > 0) {
+		lines.push('## ⚠️ Warnings');
+		lines.push('');
+		lines.push('*Issues that require attention:*');
+		lines.push('');
+		for (const warning of warnings) {
+			lines.push(`- ${warning}`);
+		}
+		lines.push('');
+	}
+
+	// Info (packages with no changes - normal status)
+	if (info.length > 0) {
+		lines.push('## ℹ️ No Changes to Publish');
+		lines.push('');
+		lines.push('*These packages have no changesets and no dependency updates:*');
+		lines.push('');
+		for (const pkg of info) {
+			lines.push(`- \`${pkg}\``);
+		}
+		lines.push('');
+	}
+
+	// Summary
+	const major_bump_count = version_changes.filter((vc) => vc.bump_type === 'major').length;
+	lines.push('## Summary');
+	lines.push('');
+	lines.push(`- **Packages to publish**: ${version_changes.length}`);
+	lines.push(`- **Dependency updates**: ${dependency_updates.length}`);
+	lines.push(`- **Major version bumps**: ${major_bump_count}`);
+	lines.push(`- **Warnings**: ${warnings.length}`);
+	lines.push(`- **Errors**: ${errors.length}`);
+
+	return lines;
+};