@fuzdev/fuz_gitops 0.78.0 → 0.79.0

package/src/lib/gitops_analyze.task.ts

@@ -1,42 +1,47 @@
-import type {Task} from '@fuzdev/gro';
-import {z} from 'zod';
-import {styleText as st} from 'node:util';
-import type {Logger} from '@fuzdev/fuz_util/log.ts';
-
-import {get_gitops_ready} from './gitops_task_helpers.ts';
-import type {DependencyGraph} from './dependency_graph.ts';
-import {repo_is_npm} from './local_repo.ts';
-import {analyze_repos, type DependencyAnalysis} from './graph_validation.ts';
+import type { Task } from '@fuzdev/gro';
+import { z } from 'zod';
+import { styleText as st } from 'node:util';
+import type { Logger } from '@fuzdev/fuz_util/log.ts';
+
+import {
+	get_gitops_ready,
+	log_readiness_block,
+	type ResolveGitopsReposOptions
+} from './gitops_task_helpers.ts';
+import type { DependencyAnalysis, DependencyGraph } from './dependency_graph.ts';
+import { repo_is_npm, type LocalRepo } from './local_repo.ts';
+import { analyze_repos } from './graph_validation.ts';
 import {
 	format_wildcard_dependencies,
 	format_dev_cycles,
-	format_production_cycles,
+	format_production_cycles
 } from './log_helpers.ts';
-import {format_and_output, type OutputFormatters} from './output_helpers.ts';
-import {GITOPS_CONFIG_PATH_DEFAULT} from './gitops_constants.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 */
 export const Args = z.strictObject({
 	config: z
 		.string()
-		.meta({description: 'path to the gitops config file, absolute or relative to the cwd'})
+		.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'})
+		.meta({ description: 'output format' })
 		.default('stdout'),
-	outfile: z.string().meta({description: 'write output to file instead of logging'}).optional(),
-	sync: z
-		.boolean()
-		.meta({
-			description:
-				'sync repos (switch branch, pull, install) before analyzing instead of reading the working tree as-is',
-		})
-		.default(false),
+	outfile: z.string().meta({ description: 'write output to file instead of logging' }).optional()
 });
 export type Args = z.infer<typeof Args>;
 
@@ -44,37 +49,70 @@ export type Args = z.infer<typeof Args>;
 export const task: Task<Args> = {
 	Args,
 	summary: 'analyze dependency structure and relationships across repos',
-	run: async ({args, log}) => {
-		const {config, dir, format, outfile, sync} = args;
-
-		// Get repos ready (without downloading); read the working tree as-is unless `--sync`
-		const {local_repos} = await get_gitops_ready({config, dir, download: false, sync, log});
-
-		// Only npm packages form the dependency graph; note any non-npm repos (e.g. cargo)
-		// that are excluded so the omission isn't silent.
-		const non_npm_repos = local_repos.filter((r) => !repo_is_npm(r));
-		if (non_npm_repos.length > 0) {
-			log.info(
-				st(
-					'dim',
-					`excluding ${non_npm_repos.length} non-npm repo(s) from analysis (dashboard-only): ` +
-						non_npm_repos.map((r) => r.library.name).join(', '),
-				),
-			);
-		}
+	run: async ({ args, log }) => {
+		await run_gitops_analyze(args, log);
+	}
+};
 
-		// Build the dependency graph and analyze cycles/wildcards (tolerating cycles)
-		const {graph, analysis, publishing_order} = analyze_repos(local_repos);
+/**
+ * The side effects `run_gitops_analyze` reaches through, injectable for tests.
+ *
+ * @nodocs
+ */
+export interface GitopsAnalyzeDeps {
+	/** Loads the configured repos as they sit (`get_gitops_ready`). */
+	load_repos: (options: ResolveGitopsReposOptions) => Promise<{ local_repos: Array<LocalRepo> }>;
+}
 
-		// Format and output using output_helpers
-		const data = {
-			graph,
-			analysis,
-			publishing_order,
-		};
+const default_gitops_analyze_deps: GitopsAnalyzeDeps = {
+	load_repos: get_gitops_ready
+};
 
-		await format_and_output(data, create_formatters(), {format, outfile, log});
-	},
+/**
+ * Runs `gro gitops_analyze`: loads the repos as they sit, logs the readiness
+ * block, and outputs the dependency analysis. Under `--format json` or
+ * `markdown` without `--outfile`, the log goes to stderr and stdout carries
+ * the document alone (`route_human_output`).
+ *
+ * @nodocs
+ */
+export const run_gitops_analyze = async (
+	args: Args,
+	log: Logger,
+	deps: Partial<GitopsAnalyzeDeps> = {}
+): Promise<void> => {
+	const { load_repos } = { ...default_gitops_analyze_deps, ...deps };
+	const { config, registry, format, outfile } = args;
+	const write_stdout = route_human_output(log, output_is_machine(format, outfile));
+
+	// Read the working trees 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);
+
+	// Only npm packages form the dependency graph; note any non-npm repos (e.g. cargo)
+	// that are excluded so the omission isn't silent.
+	const non_npm_repos = local_repos.filter((r) => !repo_is_npm(r));
+	if (non_npm_repos.length > 0) {
+		log.info(
+			st(
+				'dim',
+				`excluding ${non_npm_repos.length} non-npm repo(s) from analysis (dashboard-only): ` +
+					non_npm_repos.map((r) => r.library.name).join(', ')
+			)
+		);
+	}
+
+	// Build the dependency graph and analyze cycles/wildcards (tolerating cycles)
+	const { graph, analysis, publishing_order } = analyze_repos(local_repos);
+
+	// Format and output using output_helpers
+	const data = {
+		graph,
+		analysis,
+		publishing_order
+	};
+
+	await format_and_output(data, create_formatters(), { format, outfile, log, write_stdout });
 };
 
 // Data type for analysis output
@@ -88,32 +126,32 @@ interface AnalysisData {
 const create_formatters = (): OutputFormatters<AnalysisData> => ({
 	json: (data) => format_json(data.graph, data.analysis, data.publishing_order),
 	markdown: (data) => format_markdown(data.graph, data.analysis, data.publishing_order),
-	stdout: (data, log) => format_stdout(data.graph, data.analysis, data.publishing_order, log),
+	stdout: (data, log) => format_stdout(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,
+		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,
+		0
 	);
-	return {total_deps, internal_deps};
+	return { total_deps, internal_deps };
 };
 
 const format_json = (
 	graph: DependencyGraph,
 	analysis: DependencyAnalysis,
-	publishing_order: Array<string> | null,
+	publishing_order: Array<string> | null
 ): string => {
 	const output = {
 		graph: graph.toJSON(),
 		analysis,
-		publishing_order,
+		publishing_order
 	};
 	return JSON.stringify(output, null, 2);
 };
@@ -121,12 +159,12 @@ const format_json = (
 const format_markdown = (
 	graph: DependencyGraph,
 	analysis: DependencyAnalysis,
-	publishing_order: Array<string> | null,
+	publishing_order: Array<string> | null
 ): Array<string> => {
 	const lines: Array<string> = ['# Dependency Analysis'];
 
 	// Summary stats
-	const {total_deps, internal_deps} = calculate_stats(graph);
+	const { total_deps, internal_deps } = calculate_stats(graph);
 
 	lines.push('', '## Summary', '');
 	lines.push(`- **Total packages**: ${graph.nodes.size}`);
@@ -170,7 +208,7 @@ const format_markdown = (
 		lines.push('', '## ⚠️ Wildcard Dependencies', '');
 		lines.push('| Package | Dependency | Version |');
 		lines.push('|---------|------------|---------|');
-		for (const {pkg, dep, version} of analysis.wildcard_deps) {
+		for (const { pkg, dep, version } of analysis.wildcard_deps) {
 			lines.push(`| \`${pkg}\` | \`${dep}\` | \`${version}\` |`);
 		}
 	}
@@ -179,7 +217,7 @@ const format_markdown = (
 	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),
+			graph.nodes.has(name)
 		);
 		if (internal_deps.length > 0) {
 			lines.push(`- **${node.name}**`);
@@ -197,7 +235,7 @@ const format_stdout = (
 	graph: DependencyGraph,
 	analysis: DependencyAnalysis,
 	publishing_order: Array<string> | null,
-	log: Logger,
+	log: Logger
 ): void => {
 	log.info(st('cyan', `📊 Analyzing ${graph.nodes.size} repositories...`));
 
@@ -216,14 +254,14 @@ const format_stdout = (
 	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),
+			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})`)}`,
+					`    ${st(type_color, '→')} ${dep_name} ${st('dim', `(${spec.type}: ${spec.version})`)}`
 				);
 			}
 		}
@@ -252,7 +290,7 @@ const format_stdout = (
 	}
 
 	// Summary
-	const {total_deps, internal_deps} = calculate_stats(graph);
+	const { total_deps, internal_deps } = calculate_stats(graph);
 
 	log.info('');
 	log.info(st('cyan', 'Summary:'));

package/src/lib/gitops_config.ts

@@ -1,174 +1,125 @@
 /**
- * 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 { existsSync } from 'node:fs';
+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: (
 	config_module: any,
-	config_path: string,
+	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`);
+		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;