@fuzdev/fuz_gitops 0.78.1 → 0.79.0

package/src/lib/git_operations.ts

@@ -1,14 +1,6 @@
 import { spawn_out, spawn_result_to_message } from '@fuzdev/fuz_util/process.ts';
 import type { SpawnOptions } from 'node:child_process';
-import {
-	git_check_clean_workspace as gro_git_check_clean_workspace,
-	git_checkout as gro_git_checkout,
-	git_pull as gro_git_pull,
-	git_current_branch_name as gro_git_current_branch_name,
-	git_current_commit_hash as gro_git_current_commit_hash,
-	type GitBranch,
-	type GitOrigin
-} from '@fuzdev/fuz_util/git.ts';
+import { git_current_commit_hash as gro_git_current_commit_hash } from '@fuzdev/fuz_util/git.ts';
 
 /**
  * Adds files to git staging area and throws if anything goes wrong.
@@ -27,201 +19,37 @@ export const git_add = async (
 };
 
 /**
- * Commits staged changes with a message and throws if anything goes wrong.
+ * Commits `files` alone with a message, leaving anything else staged out of
+ * the commit, and throws if anything goes wrong. `files` must be non-empty:
+ * an empty list would commit the whole index.
  */
-export const git_commit = async (message: string, options?: SpawnOptions): Promise<void> => {
-	const { result, stderr } = await spawn_out('git', ['commit', '-m', message], options);
-	if (!result.ok) {
-		throw Error(
-			`git_commit failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
-		);
-	}
-};
-
-/**
- * Adds files and commits in one operation and throws if anything goes wrong.
- */
-export const git_add_and_commit = async (
-	files: string | Array<string>,
+export const git_commit = async (
 	message: string,
+	files: Array<string>,
 	options?: SpawnOptions
 ): Promise<void> => {
-	await git_add(files, options);
-	await git_commit(message, options);
-};
-
-/**
- * Creates a git tag and throws if anything goes wrong.
- */
-export const git_tag = async (
-	tag_name: string,
-	message?: string,
-	options?: SpawnOptions
-): Promise<void> => {
-	const args = message ? ['tag', '-a', tag_name, '-m', message] : ['tag', tag_name];
-
-	const { result, stderr } = await spawn_out('git', args, options);
-	if (!result.ok) {
-		throw Error(
-			`git_tag failed for tag '${tag_name}' with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
-		);
-	}
-};
-
-/**
- * Pushes a tag to origin and throws if anything goes wrong.
- */
-export const git_push_tag = async (
-	tag_name: string,
-	origin: GitOrigin = 'origin' as GitOrigin,
-	options?: SpawnOptions
-): Promise<void> => {
-	const { result, stderr } = await spawn_out('git', ['push', origin, tag_name], options);
-	if (!result.ok) {
-		throw Error(
-			`git_push_tag failed for tag '${tag_name}' with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
-		);
+	if (files.length === 0) {
+		throw Error('git_commit needs at least one file: an empty list would commit the whole index');
 	}
-};
-
-/**
- * Returns `true` if the working tree has any changes — staged, unstaged, or
- * untracked (`git status --porcelain`). Broader than `git_list_uncommitted_files`,
- * which reports only tracked working-tree changes relative to HEAD.
- */
-export const git_has_changes = async (options?: SpawnOptions): Promise<boolean> => {
-	const { stdout } = await spawn_out('git', ['status', '--porcelain'], options);
-	return stdout ? stdout.trim().length > 0 : false;
-};
-
-/**
- * Lists uncommitted files in the working tree (`git diff --name-only HEAD`).
- */
-export const git_list_uncommitted_files = async (
-	options?: SpawnOptions
-): Promise<Array<string>> => {
-	const { stdout } = await spawn_out('git', ['diff', '--name-only', 'HEAD'], options);
-	if (!stdout) return [];
-
-	return stdout
-		.split('\n')
-		.map((f) => f.trim())
-		.filter(Boolean);
-};
-
-export const git_has_file_changed = async (
-	from_commit: string,
-	to_commit: string,
-	file_path: string,
-	options?: SpawnOptions
-): Promise<boolean> => {
-	const { stdout } = await spawn_out(
+	const { result, stderr } = await spawn_out(
 		'git',
-		['diff', '--name-only', from_commit, to_commit, '--', file_path],
+		['commit', '-m', message, '--', ...files],
 		options
 	);
-	return stdout ? stdout.trim().length > 0 : false;
-};
-
-/**
- * Stashes current changes and throws if anything goes wrong.
- */
-export const git_stash = async (message?: string, options?: SpawnOptions): Promise<void> => {
-	const args = message ? ['stash', 'push', '-m', message] : ['stash', 'push'];
-
-	const { result, stderr } = await spawn_out('git', args, options);
 	if (!result.ok) {
 		throw Error(
-			`git_stash failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
-		);
-	}
-};
-
-/**
- * Applies stashed changes and throws if anything goes wrong.
- */
-export const git_stash_pop = async (options?: SpawnOptions): Promise<void> => {
-	const { result, stderr } = await spawn_out('git', ['stash', 'pop'], options);
-	if (!result.ok) {
-		throw Error(
-			`git_stash_pop failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
+			`git_commit failed with ${spawn_result_to_message(result)}${stderr ? ': ' + stderr.trim() : ''}`
 		);
 	}
 };
 
 /**
- * Switches to a branch with safety checks and throws if workspace is not clean.
+ * Wrapper for gro's `git_current_commit_hash` that reads `HEAD` and throws if null.
  */
-export const git_switch_branch = async (
-	branch: GitBranch,
-	pull: boolean = true,
-	options?: SpawnOptions
-): Promise<void> => {
-	// Check if workspace is clean first
-	const error = await gro_git_check_clean_workspace(options);
-	if (error) {
-		throw Error(`Cannot switch branch: ${error}`);
-	}
-
-	// Checkout the branch
-	await gro_git_checkout(branch, options);
-
-	// Pull latest changes if requested
-	if (pull) {
-		await gro_git_pull(undefined, undefined, options);
-	}
-
-	// Verify workspace is still clean
-	const error_after = await gro_git_check_clean_workspace(options);
-	if (error_after) {
-		throw Error(`Workspace unclean after switching to ${branch}: ${error_after}`);
-	}
-};
-
-/**
- * Wrapper for gro's `git_current_branch_name` that throws if null.
- */
-export const git_current_branch_name_required = async (options?: SpawnOptions): Promise<string> => {
-	const branch = await gro_git_current_branch_name(options);
-	if (!branch) {
-		throw new Error('Failed to get current branch name');
-	}
-	return branch;
-};
-
-/**
- * Wrapper for gro's `git_current_commit_hash` that throws if null.
- */
-export const git_current_commit_hash_required = async (
-	branch?: string,
-	options?: SpawnOptions
-): Promise<string> => {
-	const hash = await gro_git_current_commit_hash(branch, options);
+export const git_current_commit_hash_required = async (options?: SpawnOptions): Promise<string> => {
+	const hash = await gro_git_current_commit_hash(undefined, options);
 	if (!hash) {
-		throw new Error(`Failed to get commit hash for branch: ${branch || 'current'}`);
+		throw new Error('Failed to get the current commit hash');
 	}
 	return hash;
 };
-
-/**
- * Wrapper for gro's `git_check_clean_workspace` that returns a boolean.
- */
-export const git_check_clean_workspace_as_boolean = async (
-	options?: SpawnOptions
-): Promise<boolean> => {
-	const error = await gro_git_check_clean_workspace(options);
-	return error === null;
-};
-
-export const git_has_remote = async (
-	remote: string = 'origin',
-	options?: SpawnOptions
-): Promise<boolean> => {
-	const { stdout } = await spawn_out('git', ['remote'], options);
-	if (!stdout) return false;
-	const remotes = stdout
-		.split('\n')
-		.map((r) => r.trim())
-		.filter(Boolean);
-	return remotes.includes(remote);
-};

package/src/lib/github.ts

@@ -1,9 +1,10 @@
 import type { Logger } from '@fuzdev/fuz_util/log.ts';
 import { z } from 'zod';
 import { fetch_value, type FetchValueCache } from '@fuzdev/fuz_util/fetch.ts';
+import type { Result } from '@fuzdev/fuz_util/result.ts';
 
 /**
- * Minimal interface for GitHub API calls - works with both `Pkg` and `Repo`.
+ * Minimal interface for GitHub API calls, satisfied structurally by fuz_ui's `Library`.
  */
 export interface GithubRepoInfo {
 	owner_name: string | null;
@@ -35,9 +36,10 @@ export const fetch_github_pull_requests = async (
 		log?: Logger;
 		token?: string;
 		api_version?: string;
+		fetch?: typeof globalThis.fetch;
 	} = {}
 ): Promise<GithubPullRequests | null> => {
-	const { cache, log, token, api_version } = options;
+	const { cache, log, token, api_version, fetch } = options;
 	if (!repo_info.owner_name) throw Error('owner_name is required');
 	const headers = api_version ? new Headers({ 'x-github-api-version': api_version }) : undefined;
 	const url = `https://api.github.com/repos/${repo_info.owner_name}/${repo_info.repo_name}/pulls`;
@@ -46,7 +48,8 @@ export const fetch_github_pull_requests = async (
 		parse: GithubPullRequests.parse,
 		token,
 		cache,
-		log
+		log,
+		fetch
 	});
 	if (!fetched.ok) {
 		// TODO @many this is messy but I think it's the main case we need to worry about?
@@ -77,6 +80,13 @@ export const GithubCheckRuns = z.object({
 export type GithubCheckRuns = z.infer<typeof GithubCheckRuns>;
 
 /**
+ * Fetches the check runs on `ref` and reduces them to one overall status and
+ * conclusion.
+ *
+ * @param repo_info - the repo's GitHub owner and name
+ * @param options - the cache, logger, token, API version, ref (`main` by default), and `fetch`
+ * @returns the reduced check runs, `null` for a ref with none (a repo without CI, or a commit CI skipped), or a failure when the request or its parse failed
+ * @throws {Error} on a 401 response (check `SECRET_GITHUB_API_TOKEN`) or a repo without an owner
  * @see https://docs.github.com/en/rest/checks/runs?apiVersion=2022-11-28#list-check-runs-for-a-git-reference
  */
 export const fetch_github_check_runs = async (
@@ -87,9 +97,10 @@ export const fetch_github_check_runs = async (
 		token?: string;
 		api_version?: string;
 		ref?: string;
+		fetch?: typeof globalThis.fetch;
 	} = {}
-): Promise<GithubCheckRunsItem | null> => {
-	const { cache, log, token, api_version, ref = 'main' } = options;
+): Promise<Result<{ value: GithubCheckRunsItem | null }, { status: number; message: string }>> => {
+	const { cache, log, token, api_version, ref = 'main', fetch } = options;
 	if (!repo_info.owner_name) throw Error('owner_name is required');
 	const headers = api_version ? new Headers({ 'x-github-api-version': api_version }) : undefined;
 	const url = `https://api.github.com/repos/${repo_info.owner_name}/${repo_info.repo_name}/commits/${ref}/check-runs`;
@@ -98,16 +109,17 @@ export const fetch_github_check_runs = async (
 		parse: (v) => reduce_check_runs(GithubCheckRuns.parse(v).check_runs),
 		token,
 		cache,
-		log
+		log,
+		fetch
 	});
 	if (!fetched.ok) {
 		// TODO @many this is messy but I think it's the main case we need to worry about?
 		if (fetched.status === 401) {
 			throw Error('401 response fetching github CI status - check your SECRET_GITHUB_API_TOKEN');
 		}
-		return null;
+		return { ok: false, status: fetched.status, message: fetched.message };
 	}
-	return fetched.value;
+	return { ok: true, value: fetched.value };
 };
 
 const reduce_check_runs = (check_runs: Array<GithubCheckRunsItem>): GithubCheckRunsItem | null => {

package/src/lib/github_helpers.ts

@@ -14,18 +14,11 @@ export const to_pull_requests = (
 	repos: Array<Repo>,
 	filter_pull_request?: FilterPullRequest
 ): Array<PullRequestMeta> =>
-	repos
-		.flatMap((repo) => {
-			if (!repo.pull_requests) return null;
-			// TODO hacky, figure out the data structure
-			return repo.pull_requests.map((pull_request) =>
-				repo.package_json.homepage &&
-				(!filter_pull_request || filter_pull_request(pull_request, repo))
-					? { repo, pull_request }
-					: null
-			);
-		})
-		.filter((v) => v !== null);
+	repos.flatMap((repo) =>
+		(repo.pull_requests ?? [])
+			.filter((pull_request) => !filter_pull_request || filter_pull_request(pull_request, repo))
+			.map((pull_request) => ({ repo, pull_request }))
+	);
 
 export const to_pull_url = (repo_url: string, pull: GithubPullRequest): string =>
 	ensure_end(repo_url, '/') + 'pull/' + pull.number;

package/src/lib/gitops_analyze.task.ts

@@ -3,16 +3,25 @@ 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 {
+	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
 } from './log_helpers.ts';
-import { format_and_output, type OutputFormatters } from './output_helpers.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 */
@@ -21,22 +30,18 @@ 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(),
-	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>;
 
@@ -45,36 +50,69 @@ 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(', ')
-				)
-			);
-		}
+		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> }>;
+}
+
+const default_gitops_analyze_deps: GitopsAnalyzeDeps = {
+	load_repos: get_gitops_ready
+};
 
-		// Format and output using output_helpers
-		const data = {
-			graph,
-			analysis,
-			publishing_order
-		};
+/**
+ * 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));
 
-		await format_and_output(data, create_formatters(), { format, outfile, log });
+	// 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