@fuzdev/fuz_gitops 0.57.0

package/src/lib/repo_ops.ts

@@ -0,0 +1,213 @@
+/**
+ * Generic repository operations for scripts that work across repos.
+ *
+ * Provides lightweight utilities for:
+ * - Getting repo paths from gitops config (without full git sync)
+ * - Walking files in repos with sensible exclusions
+ * - Common exclusion patterns for node/svelte projects
+ *
+ * For full git sync/clone functionality, use `get_gitops_ready()` from gitops_task_helpers.
+ */
+
+import {existsSync} from 'node:fs';
+import {readdir, stat} from 'node:fs/promises';
+import {join, resolve, dirname} from 'node:path';
+
+import {load_gitops_config} from './gitops_config.js';
+import {DEFAULT_REPOS_DIR} from './paths.js';
+
+/** Default directories to exclude from file walking */
+export const DEFAULT_EXCLUDE_DIRS = [
+	'node_modules',
+	'.git',
+	'.gro',
+	'.svelte-kit',
+	'.deno',
+	'.vscode',
+	'.idea',
+	'dist',
+	'build',
+	'coverage',
+	'.cache',
+	'.turbo',
+] as const;
+
+/** Default binary/non-text extensions to exclude from content processing */
+export const DEFAULT_EXCLUDE_EXTENSIONS = [
+	'.png',
+	'.jpg',
+	'.jpeg',
+	'.gif',
+	'.svg',
+	'.ico',
+	'.webp',
+	'.woff',
+	'.woff2',
+	'.ttf',
+	'.eot',
+	'.mp4',
+	'.webm',
+	'.mp3',
+	'.wav',
+	'.ogg',
+	'.zip',
+	'.tar',
+	'.gz',
+	'.lock',
+	'.pdf',
+] as const;
+
+export interface WalkOptions {
+	/** Additional directories to exclude (merged with defaults) */
+	exclude_dirs?: Array<string>;
+	/** Additional extensions to exclude (merged with defaults) */
+	exclude_extensions?: Array<string>;
+	/** Maximum file size in bytes (default: 10MB) */
+	max_file_size?: number;
+	/** Include directories in output (default: false) */
+	include_dirs?: boolean;
+	/** Use only provided exclusions, ignoring defaults */
+	no_defaults?: boolean;
+}
+
+export interface RepoPath {
+	name: string;
+	path: string;
+	url: string;
+}
+
+/**
+ * Get repo paths from gitops config without full git sync.
+ * Lighter weight than `get_gitops_ready()` - just resolves paths.
+ *
+ * @param config_path Path to gitops.config.ts (defaults to ./gitops.config.ts)
+ * @returns Array of repo info with name, path, and url
+ */
+export const get_repo_paths = async (config_path?: string): Promise<Array<RepoPath>> => {
+	const resolved_config_path = resolve(config_path ?? 'gitops.config.ts');
+	const config = await load_gitops_config(resolved_config_path);
+
+	if (!config) {
+		throw new Error(`No gitops config found at ${resolved_config_path}`);
+	}
+
+	const config_dir = dirname(resolved_config_path);
+	const repos_dir = resolve(config_dir, config.repos_dir || DEFAULT_REPOS_DIR);
+
+	const repos: Array<RepoPath> = [];
+
+	for (const repo_config of config.repos) {
+		const url = repo_config.repo_url;
+		const name = url.split('/').at(-1);
+		if (!name) continue;
+
+		const path = repo_config.repo_dir
+			? resolve(config_dir, repo_config.repo_dir)
+			: join(repos_dir, name);
+
+		if (existsSync(path)) {
+			repos.push({name, path, url});
+		}
+	}
+
+	return repos;
+};
+
+/**
+ * Check if a path should be excluded based on options.
+ */
+export const should_exclude_path = (file_path: string, options?: WalkOptions): boolean => {
+	const exclude_dirs = options?.no_defaults
+		? (options.exclude_dirs ?? [])
+		: [...DEFAULT_EXCLUDE_DIRS, ...(options?.exclude_dirs ?? [])];
+
+	const exclude_extensions = options?.no_defaults
+		? (options.exclude_extensions ?? [])
+		: [...DEFAULT_EXCLUDE_EXTENSIONS, ...(options?.exclude_extensions ?? [])];
+
+	const normalized = file_path.toLowerCase();
+
+	// Check excluded directories
+	for (const dir of exclude_dirs) {
+		// Must match as a full directory component, not a prefix
+		if (normalized.includes(`/${dir}/`) || normalized.endsWith(`/${dir}`)) {
+			return true;
+		}
+	}
+
+	// Check excluded extensions
+	for (const ext of exclude_extensions) {
+		if (normalized.endsWith(ext)) {
+			return true;
+		}
+	}
+
+	return false;
+};
+
+/**
+ * Walk files in a directory, respecting common exclusions.
+ * Yields absolute paths to files (and optionally directories).
+ *
+ * @param dir Directory to walk
+ * @param options Walk options for exclusions and filtering
+ */
+export async function* walk_repo_files(
+	dir: string,
+	options?: WalkOptions,
+): AsyncGenerator<string, void, undefined> {
+	const max_file_size = options?.max_file_size ?? 10 * 1024 * 1024;
+	const include_dirs = options?.include_dirs ?? false;
+
+	async function* walk(current_dir: string): AsyncGenerator<string, void, undefined> {
+		let entries;
+		try {
+			entries = await readdir(current_dir, {withFileTypes: true});
+		} catch {
+			// Skip directories we can't read
+			return;
+		}
+
+		for (const entry of entries) {
+			const full_path = join(current_dir, entry.name);
+
+			if (should_exclude_path(full_path, options)) {
+				continue;
+			}
+
+			if (entry.isDirectory()) {
+				if (include_dirs) {
+					yield full_path;
+				}
+				yield* walk(full_path);
+			} else if (entry.isFile()) {
+				// Check file size
+				try {
+					const file_stat = await stat(full_path); // eslint-disable-line no-await-in-loop
+					if (file_stat.size <= max_file_size) {
+						yield full_path;
+					}
+				} catch {
+					// Skip files we can't stat
+				}
+			}
+		}
+	}
+
+	yield* walk(dir);
+}
+
+/**
+ * Collect all files from walk_repo_files into an array.
+ * Convenience function for when you need all paths upfront.
+ */
+export const collect_repo_files = async (
+	dir: string,
+	options?: WalkOptions,
+): Promise<Array<string>> => {
+	const files: Array<string> = [];
+	for await (const file of walk_repo_files(dir, options)) {
+		files.push(file);
+	}
+	return files;
+};

package/src/lib/resolved_gitops_config.ts

@@ -0,0 +1,27 @@
+import type {GitopsConfig} from './gitops_config.js';
+import {local_repo_locate, type LocalRepoPath, type LocalRepoMissing} from './local_repo.js';
+
+export interface ResolvedGitopsConfig {
+	local_repos: Array<LocalRepoPath | LocalRepoMissing> | null;
+	local_repo_paths: Array<LocalRepoPath> | null;
+	local_repos_missing: Array<LocalRepoMissing> | null;
+}
+
+export const resolve_gitops_config = (
+	gitops_config: GitopsConfig,
+	repos_dir: string,
+): ResolvedGitopsConfig => {
+	const local_repos = gitops_config.repos.map((r) =>
+		local_repo_locate({repo_config: r, repos_dir}),
+	);
+
+	const local_repo_paths = local_repos.filter((r) => r.type === 'local_repo_path');
+	const local_repos_missing = local_repos.filter((r) => r.type === 'local_repo_missing');
+
+	const config: ResolvedGitopsConfig = {
+		local_repos: local_repos.length ? local_repos : null,
+		local_repo_paths: local_repo_paths.length ? local_repo_paths : null,
+		local_repos_missing: local_repos_missing.length ? local_repos_missing : null,
+	};
+	return config;
+};

package/src/lib/semver.ts

@@ -0,0 +1,166 @@
+/**
+ * Semantic Versioning 2.0.0 utilities
+ * @see https://semver.org/
+ */
+
+export type BumpType = 'major' | 'minor' | 'patch';
+
+export interface Semver {
+	major: number;
+	minor: number;
+	patch: number;
+	prerelease?: string;
+	build?: string;
+}
+
+/**
+ * SemVer 2.0.0 validation regex.
+ * @see https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+ */
+const SEMVER_REGEX =
+	/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/**
+ * Parses a semver version string.
+ * Accepts optional 'v' prefix for convenience.
+ */
+const semver_parse = (version: string): Semver => {
+	// Remove leading 'v' if present (common in git tags)
+	const clean = version.replace(/^v/, '');
+
+	// Validate the cleaned version
+	if (!SEMVER_REGEX.test(clean)) {
+		throw new Error(`Invalid semver: ${version}`);
+	}
+
+	const match = SEMVER_REGEX.exec(clean)!;
+	return {
+		major: parseInt(match[1]!, 10),
+		minor: parseInt(match[2]!, 10),
+		patch: parseInt(match[3]!, 10),
+		prerelease: match[4],
+		build: match[5],
+	};
+};
+
+const semver_to_string = (semver: Semver): string => {
+	let version = `${semver.major}.${semver.minor}.${semver.patch}`;
+	if (semver.prerelease) {
+		version += `-${semver.prerelease}`;
+	}
+	if (semver.build) {
+		version += `+${semver.build}`;
+	}
+	return version;
+};
+
+/**
+ * Compares two prerelease versions according to SemVer 2.0.0 spec.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ */
+const semver_compare_prerelease = (a: string | undefined, b: string | undefined): number => {
+	// Handle missing prereleases
+	if (!a && !b) return 0;
+	if (!a) return 1; // normal version > prerelease
+	if (!b) return -1; // prerelease < normal version
+
+	// Split into identifiers
+	const a_parts = a.split('.');
+	const b_parts = b.split('.');
+
+	// Compare each identifier
+	const min_length = Math.min(a_parts.length, b_parts.length);
+	for (let i = 0; i < min_length; i++) {
+		const a_part = a_parts[i]!;
+		const b_part = b_parts[i]!;
+
+		// Check if numeric
+		const a_is_numeric = /^\d+$/.test(a_part);
+		const b_is_numeric = /^\d+$/.test(b_part);
+
+		if (a_is_numeric && b_is_numeric) {
+			// Both numeric - compare numerically
+			const a_num = parseInt(a_part, 10);
+			const b_num = parseInt(b_part, 10);
+			if (a_num !== b_num) {
+				return a_num < b_num ? -1 : 1;
+			}
+		} else if (a_is_numeric && !b_is_numeric) {
+			// Numeric identifiers always have lower precedence
+			return -1;
+		} else if (!a_is_numeric && b_is_numeric) {
+			// Numeric identifiers always have lower precedence
+			return 1;
+		} else {
+			// Both alphanumeric - compare lexically
+			const cmp = a_part.localeCompare(b_part);
+			if (cmp !== 0) {
+				return cmp < 0 ? -1 : 1;
+			}
+		}
+	}
+
+	// All identifiers equal - larger set has higher precedence
+	if (a_parts.length !== b_parts.length) {
+		return a_parts.length < b_parts.length ? -1 : 1;
+	}
+
+	return 0;
+};
+
+/**
+ * Compares two semver versions according to SemVer 2.0.0 spec.
+ * Returns -1 if a < b, 0 if a === b, 1 if a > b.
+ * Build metadata is ignored in precedence comparison.
+ */
+export const semver_compare_versions = (a: string, b: string): number => {
+	const v1 = semver_parse(a);
+	const v2 = semver_parse(b);
+
+	// Compare major
+	if (v1.major !== v2.major) {
+		return v1.major < v2.major ? -1 : 1;
+	}
+
+	// Compare minor
+	if (v1.minor !== v2.minor) {
+		return v1.minor < v2.minor ? -1 : 1;
+	}
+
+	// Compare patch
+	if (v1.patch !== v2.patch) {
+		return v1.patch < v2.patch ? -1 : 1;
+	}
+
+	// Compare prerelease (build metadata is ignored)
+	return semver_compare_prerelease(v1.prerelease, v2.prerelease);
+};
+
+/**
+ * Bumps a version according to the specified type.
+ * Resets lower version numbers per SemVer spec.
+ */
+export const semver_bump_version = (version: string, type: BumpType): string => {
+	const semver = semver_parse(version);
+
+	switch (type) {
+		case 'major':
+			semver.major++;
+			semver.minor = 0;
+			semver.patch = 0;
+			break;
+		case 'minor':
+			semver.minor++;
+			semver.patch = 0;
+			break;
+		case 'patch':
+			semver.patch++;
+			break;
+	}
+
+	// Remove prerelease and build when bumping
+	semver.prerelease = undefined;
+	semver.build = undefined;
+
+	return semver_to_string(semver);
+};

package/src/lib/serialization_types.ts

@@ -0,0 +1,90 @@
+/**
+ * JSON-serializable types for command output formats.
+ *
+ * Gitops commands support `--format json` and `--format markdown` output modes
+ * in addition to styled terminal output. These types define the JSON schema for:
+ * - Dependency graph structures (`SerializedGraph`)
+ * - Publishing plan predictions (`SerializedPublishingPlan`)
+ *
+ * Used by `gitops_analyze`, `gitops_plan`, and `gitops_publish --dry_run` when
+ * `--format json` or `--outfile` is specified.
+ */
+
+import type {DependencyGraph} from './dependency_graph.js';
+
+export interface SerializedNode {
+	name: string;
+	version: string;
+	dependencies: Array<{
+		name: string;
+		type: string;
+		version: string;
+	}>;
+	dependents: Array<string>;
+	publishable: boolean;
+}
+
+export interface SerializedGraph {
+	nodes: Array<SerializedNode>;
+	edges: Array<[string, string]>;
+}
+
+export interface SerializedPublishingPlan {
+	publishing_order: Array<string>;
+	version_changes: Array<{
+		package_name: string;
+		from: string;
+		to: string;
+		bump_type: string;
+		breaking: boolean;
+		has_changesets: boolean;
+		will_generate_changeset?: boolean;
+		needs_bump_escalation?: boolean;
+		existing_bump?: string;
+		required_bump?: string;
+	}>;
+	dependency_updates: Array<{
+		dependent_package: string;
+		updated_dependency: string;
+		new_version: string;
+		type: string;
+		causes_republish: boolean;
+	}>;
+	breaking_cascades: Record<string, Array<string>>;
+	warnings: Array<string>;
+	errors: Array<string>;
+}
+
+/**
+ * Serializes a dependency graph to a JSON-safe format.
+ */
+export const serialize_graph = (graph: DependencyGraph): SerializedGraph => {
+	const nodes: Array<SerializedNode> = [];
+	const edges: Array<[string, string]> = [];
+
+	// Serialize nodes
+	for (const node of graph.nodes.values()) {
+		const dependencies = Array.from(node.dependencies, ([dep_name, spec]) => ({
+			name: dep_name,
+			type: spec.type,
+			version: spec.version,
+		}));
+
+		nodes.push({
+			name: node.name,
+			version: node.version,
+			dependencies,
+			dependents: Array.from(node.dependents),
+			publishable: node.publishable,
+		});
+	}
+
+	// Serialize edges
+	for (const [from, tos] of graph.edges) {
+		for (const to of tos) {
+			edges.push([from, to]);
+		}
+	}
+
+	return {nodes, edges};
+};

package/src/lib/version_utils.ts

@@ -0,0 +1,150 @@
+import type {BumpType} from './semver.js';
+
+export const is_wildcard = (version: string): boolean => {
+	return version === '*';
+};
+
+/**
+ * Strips version prefix (^, ~, >=, <=, etc) from a version string.
+ */
+export const strip_version_prefix = (version: string): string => {
+	return version.replace(/^(>=|<=|>|<|=|\^|~)/, '');
+};
+
+/**
+ * Gets the version prefix (^, ~, >=, <=, or empty string).
+ */
+export const get_version_prefix = (version: string): string => {
+	const match = /^(>=|<=|>|<|=|\^|~)/.exec(version);
+	return match ? match[1]! : '';
+};
+
+/**
+ * Normalizes version string for comparison.
+ *
+ * Strips prefixes (^, ~, >=) to get bare version number.
+ * Handles wildcards as-is. Used by needs_update to compare versions.
+ *
+ * @example normalize_version_for_comparison('^1.2.3') // '1.2.3'
+ * @example normalize_version_for_comparison('>=2.0.0') // '2.0.0'
+ * @example normalize_version_for_comparison('*') // '*'
+ */
+export const normalize_version_for_comparison = (version: string): string => {
+	// Handle wildcards
+	if (is_wildcard(version)) return version;
+
+	// Handle >= ranges - extract just the version number
+	if (version.startsWith('>=')) {
+		return version.substring(2).trim();
+	}
+
+	// Strip other prefixes
+	return strip_version_prefix(version);
+};
+
+export const needs_update = (current: string, new_version: string): boolean => {
+	// Always update wildcards
+	if (is_wildcard(current)) return true;
+
+	// Compare normalized versions
+	const current_normalized = normalize_version_for_comparison(current);
+	const new_normalized = normalize_version_for_comparison(new_version);
+
+	return current_normalized !== new_normalized;
+};
+
+/**
+ * Determines version prefix to use when updating dependencies.
+ *
+ * Strategy:
+ * - Wildcard (*): Use caret (^) as default
+ * - Has existing prefix: Preserve it (^, ~, >=, <=, etc)
+ * - No prefix: Use default_strategy
+ *
+ * This preserves user intent while handling wildcard replacements sensibly.
+ *
+ * @param default_strategy prefix to use when no existing prefix found
+ */
+export const get_update_prefix = (
+	current_version: string,
+	default_strategy: '^' | '~' | '' | '>=' = '^',
+): string => {
+	// Use caret for wildcard replacements
+	if (is_wildcard(current_version)) {
+		return '^';
+	}
+
+	// Preserve existing prefix if present
+	const existing_prefix = get_version_prefix(current_version);
+	if (existing_prefix) {
+		return existing_prefix;
+	}
+
+	// Use default strategy
+	return default_strategy;
+};
+
+/**
+ * Determines if a bump is a breaking change based on semver rules.
+ * Pre-1.0: minor bumps are breaking
+ * 1.0+: major bumps are breaking
+ */
+export const is_breaking_change = (
+	old_version: string,
+	bump_type: 'major' | 'minor' | 'patch',
+): boolean => {
+	const [major] = old_version.split('.').map(Number);
+	const is_pre_1_0 = major === 0;
+
+	if (is_pre_1_0) {
+		// In 0.x.x, minor bumps are breaking changes
+		return bump_type === 'minor' || bump_type === 'major';
+	} else {
+		// In 1.x.x+, only major bumps are breaking
+		return bump_type === 'major';
+	}
+};
+
+export const detect_bump_type = (
+	old_version: string,
+	new_version: string,
+): 'major' | 'minor' | 'patch' => {
+	const old_parts = old_version.split('.').map(Number);
+	const new_parts = new_version.split('.').map(Number);
+
+	if (new_parts[0]! > old_parts[0]!) return 'major';
+	if (new_parts[1]! > old_parts[1]!) return 'minor';
+	return 'patch';
+};
+
+/**
+ * Compares bump types. Returns positive if a > b, negative if a < b, 0 if equal.
+ */
+export const compare_bump_types = (a: BumpType, b: BumpType): number => {
+	const order: Record<BumpType, number> = {
+		major: 3,
+		minor: 2,
+		patch: 1,
+	};
+	return order[a] - order[b];
+};
+
+export const calculate_next_version = (current_version: string, bump_type: BumpType): string => {
+	const parts = current_version.split('.').map(Number);
+	if (parts.length !== 3 || parts.some((p) => Number.isNaN(p))) {
+		throw new Error(`Invalid version format: ${current_version}`);
+	}
+
+	const [major, minor, patch] = parts;
+
+	switch (bump_type) {
+		case 'major':
+			return `${major! + 1}.0.0`;
+		case 'minor':
+			return `${major!}.${minor! + 1}.0`;
+		case 'patch':
+			return `${major!}.${minor!}.${patch! + 1}`;
+		default:
+			throw new Error(`Invalid bump type: ${bump_type}`);
+	}
+};