@fuzdev/fuz_gitops 0.78.1 → 0.79.0

package/src/lib/gitops_config.ts

@@ -1,162 +1,113 @@
 /**
- * Configuration types and normalization for gitops multi-repo management.
+ * The gitops config: which repos a project's gitops tasks work over, as a flat
+ * list of `repos.toml` registry keys.
  *
- * 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.
+ * Every other fact about a repo — its dir, URL, branch, visibility, `ci`, and
+ * `archived` — comes from the registry, through `repos status --json`, so the
+ * config declares nothing that could drift from it.
  *
  * @module
  */
 
-import type { Url } from '@fuzdev/fuz_util/url.ts';
 import { existsSync } from 'node:fs';
-import { strip_end } from '@fuzdev/fuz_util/string.ts';
-import type { GitBranch } from '@fuzdev/fuz_util/git.ts';
+import { z } from 'zod';
 
-import { DEFAULT_REPOS_DIR } from './paths.ts';
+import type { ReposEntryStatus } from './repos_status.ts';
 
-export interface GitopsConfig {
-	repos: Array<GitopsRepoConfig>;
-	repos_dir: string;
-}
+/** A project's gitops config. */
+export const GitopsConfig = z.strictObject({
+	repos: z
+		.array(z.string().min(1))
+		.meta({ description: 'repos.toml registry keys of owned repos, in the order tasks list them' })
+});
+export type GitopsConfig = z.infer<typeof GitopsConfig>;
 
-export type CreateGitopsConfig = (
-	base_config: GitopsConfig
-) => RawGitopsConfig | Promise<RawGitopsConfig>;
+/** A config module's default export in function form. */
+export type CreateGitopsConfig = () => GitopsConfig | Promise<GitopsConfig>;
 
-export interface RawGitopsConfig {
-	repos?: Array<Url | RawGitopsRepoConfig>;
-	repos_dir?: string;
+export interface GitopsConfigModule {
+	readonly default: GitopsConfig | CreateGitopsConfig;
 }
 
 /**
- * Visibility of a repo on its host, mirroring the host's own model
- * (e.g. GitHub's `visibility` field). Named to avoid confusion with the npm
- * `package.json` `private` flag, which is a separate publishing concern.
+ * The private repos a public host package must not publish. `gitops_sync` writes
+ * every configured repo's GitHub metadata into the host project's generated
+ * `repos.json` — a public site's data when the host package is public — so a
+ * private repo in that config would leak. Empty when the host is private.
+ *
+ * @param entries - the configured repos' registry entries
+ * @param host_is_private - whether the host `package.json` sets `private: true`
  */
-export type GitopsRepoVisibility = 'public' | 'private';
-
-export interface GitopsRepoConfig {
-	/**
-	 * The HTTPS URL to the repo. Does not include a `.git` suffix.
-	 * @example
-	 * ```ts
-	 * '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
-	 * ```ts
-	 * 'relative/path/to/repo'
-	 * ```
-	 * @example
-	 * ```ts
-	 * '/absolute/path/to/repo'
-	 * ```
-	 */
-	repo_dir: string | null;
-
-	/**
-	 * The branch name to use when fetching the repo. Defaults to `main`.
-	 */
-	branch: GitBranch;
-
-	/**
-	 * Visibility of the repo on its host. Defaults to `'public'`.
-	 */
-	visibility: GitopsRepoVisibility;
-
-	/**
-	 * Whether the repo runs CI. Defaults to `true` for public repos and `false`
-	 * for private repos, unless set explicitly.
-	 */
-	ci: boolean;
-
-	/**
-	 * Whether the repo is archived (read-only) on its host. Defaults to `false`.
-	 */
-	archived: boolean;
-}
-
-export interface RawGitopsRepoConfig {
-	repo_url: Url;
-	repo_dir?: string | null;
-	branch?: GitBranch;
-	/** Visibility of the repo on its host. Defaults to `'public'`. */
-	visibility?: GitopsRepoVisibility;
-	/** Whether the repo runs CI. Defaults to `true` for public, `false` for private. */
-	ci?: boolean;
-	/** Whether the repo is archived (read-only) on its host. Defaults to `false`. */
-	archived?: boolean;
-}
-
-export const create_empty_gitops_config = (): GitopsConfig => ({
-	repos: [],
-	repos_dir: DEFAULT_REPOS_DIR
-});
+export const gitops_config_leaked_private_repos = (
+	entries: ReadonlyArray<ReposEntryStatus>,
+	host_is_private: boolean
+): Array<ReposEntryStatus> =>
+	host_is_private ? [] : entries.filter((e) => e.visibility === 'private');
 
 /**
- * Transforms a `RawGitopsConfig` to the more strict `GitopsConfig`.
- * This allows users to provide a more relaxed config.
+ * Loads a gitops config module and validates it.
+ *
+ * @returns the config, or `null` when no file exists at `config_path`
+ * @throws {Error} if the module's default export isn't a valid 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
-			visibility: 'public',
-			ci: true,
-			archived: false
-		};
-	}
-	const visibility = r.visibility ?? 'public';
-	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
-		visibility,
-		ci: r.ci ?? visibility === 'public',
-		archived: r.archived ?? false
-	};
-};
-
-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);
+	// Import the user's `gitops.config.ts`. An import or call failure keeps its
+	// stack, which carries the config's file and line; validation errors don't need one.
+	let config_module: unknown;
+	try {
+		config_module = await import(config_path);
+	} catch (err) {
+		throw Error(`Failed to import the gitops config at ${config_path}:\n${error_with_stack(err)}`);
+	}
 	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
-	);
+	let raw: unknown;
+	try {
+		raw =
+			typeof config_module.default === 'function'
+				? await config_module.default()
+				: config_module.default;
+	} catch (err) {
+		throw Error(`The gitops config at ${config_path} threw:\n${error_with_stack(err)}`);
+	}
+	return parse_gitops_config(raw, config_path);
+};
+
+const error_with_stack = (err: unknown): string =>
+	err instanceof Error ? (err.stack ?? err.message) : String(err);
+
+/**
+ * Validates a loaded config value: registry keys, each listed once.
+ *
+ * @throws {Error} naming the config and what's wrong with it
+ */
+export const parse_gitops_config = (raw: unknown, config_path: string): GitopsConfig => {
+	const parsed = GitopsConfig.safeParse(raw);
+	if (!parsed.success) {
+		const hint =
+			"\n  `repos` lists repos.toml registry keys; a repo's url, dir, branch, visibility, ci, and archived come from the registry";
+		throw Error(
+			`Invalid gitops config at ${config_path}:\n${z.prettifyError(parsed.error)}${hint}`
+		);
+	}
+	const config = parsed.data;
+	const problems: Array<string> = [];
+	const seen: Set<string> = new Set();
+	for (const key of config.repos) {
+		if (key.includes('/')) {
+			problems.push(`\`${key}\` isn't a registry key — list repos by their repos.toml key`);
+		} else if (seen.has(key)) {
+			problems.push(`\`${key}\` is listed more than once`);
+		}
+		seen.add(key);
+	}
+	if (problems.length) {
+		throw Error(`Invalid gitops config at ${config_path}:\n  ${problems.join('\n  ')}`);
+	}
+	return config;
 };
 
 export const validate_gitops_config_module: (
@@ -165,10 +116,10 @@ export const validate_gitops_config_module: (
 ) => 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`);
+		throw Error(`Invalid gitops 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`
+			`Invalid gitops config module at ${config_path}: the default export must be a function or object`
 		);
 	}
 };

package/src/lib/gitops_constants.ts

@@ -7,11 +7,13 @@
  */
 
 /**
- * Maximum number of iterations for fixed-point iteration during publishing.
- * Used in both plan generation and actual publishing to resolve transitive dependency cascades.
+ * Maximum number of fixed-point iterations plan generation runs to resolve
+ * transitive dependency cascades. Publishing executes the frozen plan in a
+ * single pass and doesn't iterate.
  *
- * In practice, most repos converge in 2-3 iterations.
- * Deep dependency chains may require more iterations.
+ * Each iteration reaches at least one more level of dependents, so a deep dependency
+ * chain needs more; a plan that hits the limit still changing warns, naming
+ * the packages left.
  */
 export const GITOPS_MAX_ITERATIONS_DEFAULT = 10;
 

package/src/lib/gitops_plan.task.ts

@@ -1,15 +1,28 @@
 import type { Task } from '@fuzdev/gro';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { z } from 'zod';
 import { styleText as st } from 'node:util';
 
-import { get_gitops_ready } from './gitops_task_helpers.ts';
+import {
+	get_gitops_ready,
+	log_readiness_block,
+	type ResolveGitopsReposOptions
+} from './gitops_task_helpers.ts';
+import type { LocalRepo } from './local_repo.ts';
+import type { ChangesetOperations } from './operations.ts';
+import { default_changeset_operations } from './operations_defaults.ts';
 import {
 	generate_publishing_plan,
-	log_publishing_plan,
-	type PublishingPlan,
-	type LogPlanOptions
+	version_change_kind,
+	type PublishingPlan
 } from './publishing_plan.ts';
-import { format_and_output, type OutputFormatters } from './output_helpers.ts';
+import { log_publishing_plan, type LogPlanOptions } from './publishing_plan_logging.ts';
+import {
+	format_and_output,
+	output_is_machine,
+	route_human_output,
+	type OutputFormatters
+} from './output_helpers.ts';
 import { GITOPS_CONFIG_PATH_DEFAULT } from './gitops_constants.ts';
 
 /** @nodocs */
@@ -18,23 +31,19 @@ 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' })
+		.meta({
+			description:
+				'path to the repos.toml registry, when `repos` would not find it walking up from the cwd'
+		})
 		.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),
-	sync: z
-		.boolean()
-		.meta({
-			description:
-				'sync repos (switch branch, pull, install) before planning instead of reading the working tree as-is'
-		})
-		.default(false)
+	verbose: z.boolean().meta({ description: 'show additional details' }).default(false)
 });
 export type Args = z.infer<typeof Args>;
 
@@ -44,7 +53,7 @@ export type Args = z.infer<typeof Args>;
  *
  * Usage:
  *   `gro gitops_plan`
- *   `gro gitops_plan --dir ../repos`
+ *   `gro gitops_plan --registry ../repos.toml`
  *   `gro gitops_plan --config ./custom.config.ts`
  *
  * @nodocs
@@ -53,36 +62,67 @@ export const task: Task<Args> = {
 	summary: 'generate a publishing plan based on changesets',
 	Args,
 	run: async ({ args, log }): Promise<void> => {
-		const { dir, config, format, outfile, verbose, sync } = args;
+		await run_gitops_plan(args, log);
+	}
+};
+
+/**
+ * The side effects `run_gitops_plan` reaches through, injectable for tests.
+ *
+ * @nodocs
+ */
+export interface GitopsPlanDeps {
+	/** Loads the configured repos as they sit (`get_gitops_ready`). */
+	load_repos: (options: ResolveGitopsReposOptions) => Promise<{ local_repos: Array<LocalRepo> }>;
+	/** Reads each repo's changesets for the plan. */
+	changeset_ops: ChangesetOperations;
+}
 
-		log.info(st('cyan', 'Generating multi-repo publishing plan...'));
+const default_gitops_plan_deps: GitopsPlanDeps = {
+	load_repos: get_gitops_ready,
+	changeset_ops: default_changeset_operations
+};
 
-		// Load local repos; read the working tree as-is unless `--sync`
-		const { local_repos } = await get_gitops_ready({
-			config,
-			dir,
-			download: false, // Don't download if missing
-			sync,
-			log
-		});
+/**
+ * Runs `gro gitops_plan`: loads the repos as they sit, logs the readiness
+ * block, generates the plan, and outputs it. Under `--format json` or
+ * `markdown` without `--outfile`, the log goes to stderr and stdout carries
+ * the document alone (`route_human_output`).
+ *
+ * @throws {Error} when the plan has errors that would block publishing, after outputting it
+ * @nodocs
+ */
+export const run_gitops_plan = async (
+	args: Args,
+	log: Logger,
+	deps: Partial<GitopsPlanDeps> = {}
+): Promise<void> => {
+	const { load_repos, changeset_ops } = { ...default_gitops_plan_deps, ...deps };
+	const { config, registry, format, outfile, verbose } = args;
+	const write_stdout = route_human_output(log, output_is_machine(format, outfile));
 
-		if (local_repos.length === 0) {
-			log.error('No local repos found');
-			return;
-		}
+	log.info(st('cyan', 'Generating multi-repo publishing plan...'));
 
-		log.info(`  Found ${local_repos.length} local repos`);
+	// Load local repos as they sit, and say which aren't at rest
+	const { local_repos } = await load_repos({ config, registry, log });
+	log_readiness_block(local_repos, log);
 
-		// Generate publishing plan
-		const plan = await generate_publishing_plan(local_repos, { log, verbose });
+	log.info(`  Found ${local_repos.length} local repos`);
 
-		// Format and output using output_helpers
-		await format_and_output(plan, create_plan_formatters({ verbose }), { format, outfile, log });
+	// Generate publishing plan
+	const plan = await generate_publishing_plan(local_repos, { log, verbose, ops: changeset_ops });
 
-		// Exit with error if there are blocking issues
-		if (plan.errors.length > 0) {
-			throw new Error('Publishing plan found errors that would block publishing');
-		}
+	// Format and output using output_helpers
+	await format_and_output(plan, create_plan_formatters({ verbose }), {
+		format,
+		outfile,
+		log,
+		write_stdout
+	});
+
+	// Exit with error if there are blocking issues
+	if (plan.errors.length > 0) {
+		throw new Error('Publishing plan found errors that would block publishing');
 	}
 };
 
@@ -97,6 +137,7 @@ const create_plan_formatters = (
 			breaking_cascades: Object.fromEntries(plan.breaking_cascades),
 			warnings: plan.warnings,
 			info: plan.info,
+			no_changes: plan.no_changes,
 			errors: plan.errors
 		};
 		return JSON.stringify(output, null, 2);
@@ -114,6 +155,7 @@ const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
 		breaking_cascades,
 		warnings,
 		info,
+		no_changes,
 		errors
 	} = plan;
 
@@ -140,21 +182,21 @@ const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
 
 	// Version changes
 	if (version_changes.length > 0) {
-		const with_changesets = version_changes.filter(
-			(vc) => vc.has_changesets && !vc.needs_bump_escalation
+		const with_changesets = version_changes.filter((vc) => version_change_kind(vc) === 'explicit');
+		const with_escalation = version_changes.filter(
+			(vc) => version_change_kind(vc) === 'escalation'
 		);
-		const with_escalation = version_changes.filter((vc) => vc.needs_bump_escalation);
-		const with_auto_changesets = version_changes.filter((vc) => vc.will_generate_changeset);
+		const with_auto_changesets = version_changes.filter((vc) => version_change_kind(vc) === 'auto');
 
 		if (with_changesets.length > 0) {
 			lines.push('## Version Changes (from changesets)');
 			lines.push('');
-			lines.push('| Package | From | To | Bump | Major |');
-			lines.push('|---------|------|----|------|-------|');
+			lines.push('| Package | From | To | Bump | Breaking |');
+			lines.push('|---------|------|----|------|----------|');
 			for (const change of with_changesets) {
-				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				const breaking = change.breaking ? '💥 Yes' : 'No';
 				lines.push(
-					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${is_major} |`
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${breaking} |`
 				);
 			}
 			lines.push('');
@@ -163,12 +205,12 @@ const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
 		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('|---------|------|-----|-----------------|---------------|-------|');
+			lines.push('| Package | From | To | Changesets Bump | Required Bump | Breaking |');
+			lines.push('|---------|------|-----|-----------------|---------------|----------|');
 			for (const change of with_escalation) {
-				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				const breaking = change.breaking ? '💥 Yes' : 'No';
 				lines.push(
-					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.existing_bump} | ${change.required_bump} | ${is_major} |`
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.existing_bump} | ${change.required_bump} | ${breaking} |`
 				);
 			}
 			lines.push('');
@@ -181,12 +223,12 @@ const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
 		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('|---------|------|-----|------|-------|');
+			lines.push('| Package | From | To | Bump | Breaking |');
+			lines.push('|---------|------|-----|------|----------|');
 			for (const change of with_auto_changesets) {
-				const is_major = change.bump_type === 'major' ? '💥 Yes' : 'No';
+				const breaking = change.breaking ? '💥 Yes' : 'No';
 				lines.push(
-					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${is_major} |`
+					`| \`${change.package_name}\` | ${change.from} | ${change.to} | ${change.bump_type} | ${breaking} |`
 				);
 			}
 			lines.push('');
@@ -255,25 +297,35 @@ const format_plan_as_markdown = (plan: PublishingPlan): Array<string> => {
 		lines.push('');
 	}
 
-	// Info (packages with no changes - normal status)
+	// Info (normal status, not warnings)
 	if (info.length > 0) {
-		lines.push('## ℹ️ No Changes to Publish');
+		lines.push('## ℹ️ Info');
+		lines.push('');
+		for (const line of info) {
+			lines.push(`- ${line}`);
+		}
+		lines.push('');
+	}
+
+	// Packages with nothing to publish (normal status)
+	if (no_changes.length > 0) {
+		lines.push('## No Changes to Publish');
 		lines.push('');
-		lines.push('*These packages have no changesets and no dependency updates:*');
+		lines.push('*These packages have no changesets and nothing to publish:*');
 		lines.push('');
-		for (const pkg of info) {
+		for (const pkg of no_changes) {
 			lines.push(`- \`${pkg}\``);
 		}
 		lines.push('');
 	}
 
 	// Summary
-	const major_bump_count = version_changes.filter((vc) => vc.bump_type === 'major').length;
+	const breaking_count = version_changes.filter((vc) => vc.breaking).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(`- **Breaking changes**: ${breaking_count}`);
 	lines.push(`- **Warnings**: ${warnings.length}`);
 	lines.push(`- **Errors**: ${errors.length}`);