@fuzdev/fuz_util 0.48.3 → 0.49.0

package/src/lib/async.ts

@@ -249,3 +249,36 @@ export const map_concurrent_settled = async <T, R>(
 		run_next();
 	});
 };
+
+/**
+ * Async semaphore for concurrency limiting.
+ *
+ * With `Infinity` permits, `acquire()` always resolves immediately.
+ */
+export class AsyncSemaphore {
+	#permits: number;
+	#waiters: Array<() => void> = [];
+
+	constructor(permits: number) {
+		this.#permits = permits;
+	}
+
+	async acquire(): Promise<void> {
+		if (this.#permits > 0) {
+			this.#permits--;
+			return;
+		}
+		return new Promise<void>((resolve) => {
+			this.#waiters.push(resolve);
+		});
+	}
+
+	release(): void {
+		const next = this.#waiters.shift();
+		if (next) {
+			next();
+		} else {
+			this.#permits++;
+		}
+	}
+}

package/src/lib/dag.ts

@@ -0,0 +1,240 @@
+/**
+ * Generic concurrent DAG executor.
+ *
+ * Executes nodes in a dependency graph with configurable concurrency,
+ * failure handling, and skip semantics. Nodes without dependency edges
+ * run in parallel (up to max_concurrency). Dependencies are respected
+ * via per-node deferreds.
+ *
+ * @module
+ */
+
+import {AsyncSemaphore, create_deferred, type Deferred} from './async.js';
+import {topological_sort, type Sortable} from './sort.js';
+
+/**
+ * Minimum shape for a DAG node.
+ */
+export interface DagNode extends Sortable {
+	id: string;
+	depends_on?: Array<string>;
+}
+
+/**
+ * Options for running a DAG.
+ */
+export interface DagOptions<T extends DagNode> {
+	/** Nodes to execute. */
+	nodes: Array<T>;
+	/** Execute a node. Throw on failure. */
+	execute: (node: T) => Promise<void>;
+	/** Called after a node fails. For observability — the error is already recorded. */
+	on_error?: (node: T, error: Error) => Promise<void>;
+	/** Called when a node is skipped (pre-skip or dependency failure). */
+	on_skip?: (node: T, reason: string) => Promise<void>;
+	/** Return true to skip a node without executing. Dependents still proceed. */
+	should_skip?: (node: T) => boolean;
+	/** Maximum concurrent executions. Default: Infinity. */
+	max_concurrency?: number;
+	/** Stop starting new nodes on first failure. Default: true. */
+	stop_on_failure?: boolean;
+	/** Skip internal graph validation (caller already validated). */
+	skip_validation?: boolean;
+}
+
+/**
+ * Result for a single node.
+ */
+export interface DagNodeResult {
+	id: string;
+	status: 'completed' | 'failed' | 'skipped';
+	error?: string;
+	duration_ms: number;
+}
+
+/**
+ * Result of a DAG execution.
+ */
+export interface DagResult {
+	/** Whether all executed nodes succeeded. */
+	success: boolean;
+	/** Per-node results. */
+	results: Map<string, DagNodeResult>;
+	/** Number of nodes that completed successfully. */
+	completed: number;
+	/** Number of nodes that failed. */
+	failed: number;
+	/** Number of nodes that were skipped. */
+	skipped: number;
+	/** Total execution time in milliseconds. */
+	duration_ms: number;
+	/** Error message if any nodes failed. */
+	error?: string;
+}
+
+/**
+ * Execute nodes in a dependency graph concurrently.
+ *
+ * Independent nodes (no unmet dependencies) run in parallel up to
+ * `max_concurrency`. When a node completes, its dependents become
+ * eligible to start. Failure cascading and stop-on-failure are handled
+ * per the options.
+ *
+ * @param options - DAG execution options.
+ * @returns Aggregated result with per-node details.
+ */
+export const run_dag = async <T extends DagNode>(options: DagOptions<T>): Promise<DagResult> => {
+	const {
+		nodes,
+		execute,
+		on_error,
+		on_skip,
+		should_skip,
+		max_concurrency = Infinity,
+		stop_on_failure = true,
+		skip_validation = false,
+	} = options;
+
+	const start_time = Date.now();
+
+	// Empty graph
+	if (nodes.length === 0) {
+		return {
+			success: true,
+			results: new Map(),
+			completed: 0,
+			failed: 0,
+			skipped: 0,
+			duration_ms: 0,
+		};
+	}
+
+	// Validate graph (cycle detection, duplicate IDs, missing deps)
+	if (!skip_validation) {
+		const sort_result = topological_sort(nodes, 'node');
+		if (!sort_result.ok) {
+			return {
+				success: false,
+				results: new Map(),
+				completed: 0,
+				failed: 0,
+				skipped: 0,
+				duration_ms: Date.now() - start_time,
+				error: sort_result.error,
+			};
+		}
+	}
+
+	// Build deferreds and tracking maps
+	const deferreds: Map<string, Deferred<void>> = new Map();
+	const outcomes: Map<string, 'ok' | 'fail'> = new Map();
+	const results: Map<string, DagNodeResult> = new Map();
+
+	for (const node of nodes) {
+		deferreds.set(node.id, create_deferred());
+	}
+
+	let stopping = false;
+	const semaphore = new AsyncSemaphore(max_concurrency);
+
+	// Skip a node, record outcome, notify dependents
+	const skip_node = async (node: T, outcome: 'ok' | 'fail', reason: string): Promise<void> => {
+		outcomes.set(node.id, outcome);
+		results.set(node.id, {id: node.id, status: 'skipped', duration_ms: 0});
+		if (on_skip) await on_skip(node, reason);
+		deferreds.get(node.id)!.resolve();
+	};
+
+	// Per-node async task
+	const run_node = async (node: T): Promise<void> => {
+		const deps = node.depends_on ?? [];
+
+		// Wait for all dependencies to resolve
+		if (deps.length > 0) {
+			await Promise.all(deps.map((d) => deferreds.get(d)!.promise));
+		}
+
+		// Pre-skip check (e.g., pipeline step.skip or change.action === 'skip')
+		if (should_skip?.(node)) {
+			return skip_node(node, 'ok', 'pre-skipped');
+		}
+
+		// Check if any dependency failed — skip this node too
+		if (deps.some((d) => outcomes.get(d) === 'fail')) {
+			return skip_node(node, 'fail', 'dependency failed');
+		}
+
+		// Check if we're stopping (some other node failed with stop_on_failure)
+		if (stopping) {
+			return skip_node(node, 'fail', 'stopped');
+		}
+
+		// Acquire concurrency slot
+		await semaphore.acquire();
+
+		// Double-check stopping after acquiring slot
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+		if (stopping) {
+			semaphore.release();
+			return skip_node(node, 'fail', 'stopped');
+		}
+
+		// Execute
+		const exec_start = Date.now();
+		try {
+			await execute(node);
+			outcomes.set(node.id, 'ok');
+			results.set(node.id, {
+				id: node.id,
+				status: 'completed',
+				duration_ms: Date.now() - exec_start,
+			});
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			outcomes.set(node.id, 'fail');
+			results.set(node.id, {
+				id: node.id,
+				status: 'failed',
+				error: error.message,
+				duration_ms: Date.now() - exec_start,
+			});
+			if (stop_on_failure) stopping = true;
+			if (on_error) await on_error(node, error);
+		} finally {
+			semaphore.release();
+			deferreds.get(node.id)!.resolve();
+		}
+	};
+
+	// Launch all nodes — they naturally wait for their deps via deferreds
+	await Promise.all(nodes.map(run_node));
+
+	// Aggregate results
+	let completed = 0;
+	let failed = 0;
+	let skipped = 0;
+	for (const result of results.values()) {
+		switch (result.status) {
+			case 'completed':
+				completed++;
+				break;
+			case 'failed':
+				failed++;
+				break;
+			case 'skipped':
+				skipped++;
+				break;
+		}
+	}
+
+	const success = failed === 0;
+	return {
+		success,
+		results,
+		completed,
+		failed,
+		skipped,
+		duration_ms: Date.now() - start_time,
+		error: success ? undefined : `${failed} node(s) failed`,
+	};
+};

package/src/lib/diff.ts

@@ -0,0 +1,234 @@
+/**
+ * Line-based diff utilities using LCS (Longest Common Subsequence).
+ *
+ * @module
+ */
+
+import {string_is_binary} from './string.js';
+
+/** Line diff result */
+export interface DiffLine {
+	type: 'same' | 'add' | 'remove';
+	line: string;
+}
+
+/**
+ * Generate a line-based diff between two strings using LCS algorithm.
+ *
+ * @param a - The original/current content.
+ * @param b - The new/desired content.
+ * @returns Array of diff lines with type annotations.
+ */
+export const diff_lines = (a: string, b: string): Array<DiffLine> => {
+	const a_lines = a.split('\n');
+	const b_lines = b.split('\n');
+	const result: Array<DiffLine> = [];
+
+	const lcs = compute_lcs(a_lines, b_lines);
+	let ai = 0;
+	let bi = 0;
+	let li = 0;
+
+	while (ai < a_lines.length || bi < b_lines.length) {
+		if (li < lcs.length && ai < a_lines.length && a_lines[ai] === lcs[li]) {
+			if (bi < b_lines.length && b_lines[bi] === lcs[li]) {
+				result.push({type: 'same', line: a_lines[ai]!});
+				ai++;
+				bi++;
+				li++;
+			} else {
+				result.push({type: 'add', line: b_lines[bi]!});
+				bi++;
+			}
+		} else if (ai < a_lines.length && (li >= lcs.length || a_lines[ai] !== lcs[li])) {
+			result.push({type: 'remove', line: a_lines[ai]!});
+			ai++;
+		} else if (bi < b_lines.length) {
+			result.push({type: 'add', line: b_lines[bi]!});
+			bi++;
+		}
+	}
+
+	return result;
+};
+
+/**
+ * Compute longest common subsequence of two string arrays.
+ *
+ * Uses dynamic programming with O(m*n) time and space complexity.
+ */
+const compute_lcs = (a: Array<string>, b: Array<string>): Array<string> => {
+	const m = a.length;
+	const n = b.length;
+	const dp: Array<Array<number>> = Array.from({length: m + 1}, () => Array(n + 1).fill(0));
+
+	for (let i = 1; i <= m; i++) {
+		for (let j = 1; j <= n; j++) {
+			if (a[i - 1] === b[j - 1]) {
+				dp[i]![j] = dp[i - 1]![j - 1]! + 1;
+			} else {
+				dp[i]![j] = Math.max(dp[i - 1]![j]!, dp[i]![j - 1]!);
+			}
+		}
+	}
+
+	// Backtrack to find LCS
+	const lcs: Array<string> = [];
+	let i = m;
+	let j = n;
+	while (i > 0 && j > 0) {
+		if (a[i - 1] === b[j - 1]) {
+			lcs.unshift(a[i - 1]!);
+			i--;
+			j--;
+		} else if (dp[i - 1]![j]! > dp[i]![j - 1]!) {
+			i--;
+		} else {
+			j--;
+		}
+	}
+
+	return lcs;
+};
+
+/**
+ * Filter diff to only include lines within N lines of context around changes.
+ *
+ * @param diff - The full diff lines.
+ * @param context_lines - Number of context lines to show around changes (default: 3).
+ * @returns Filtered diff with ellipsis markers for skipped regions.
+ */
+export const filter_diff_context = (diff: Array<DiffLine>, context_lines = 3): Array<DiffLine> => {
+	if (diff.length === 0) return [];
+
+	// Find indices of all changed lines
+	const changed_indices: Array<number> = [];
+	for (let i = 0; i < diff.length; i++) {
+		if (diff[i]!.type !== 'same') {
+			changed_indices.push(i);
+		}
+	}
+
+	if (changed_indices.length === 0) return [];
+
+	// Build set of indices to include (changed lines + context)
+	const include_indices: Set<number> = new Set();
+	for (const idx of changed_indices) {
+		for (
+			let i = Math.max(0, idx - context_lines);
+			i <= Math.min(diff.length - 1, idx + context_lines);
+			i++
+		) {
+			include_indices.add(i);
+		}
+	}
+
+	// Build result with ellipsis markers for gaps
+	const result: Array<DiffLine> = [];
+	let last_included = -1;
+
+	for (let i = 0; i < diff.length; i++) {
+		if (include_indices.has(i)) {
+			// Add ellipsis if there's a gap
+			if (last_included >= 0 && i > last_included + 1) {
+				result.push({type: 'same', line: '...'});
+			}
+			result.push(diff[i]!);
+			last_included = i;
+		}
+	}
+
+	return result;
+};
+
+/** ANSI color codes */
+const colors = {
+	red: '\x1b[31m',
+	green: '\x1b[32m',
+	reset: '\x1b[0m',
+} as const;
+
+/**
+ * Format options for diff output.
+ */
+export interface FormatDiffOptions {
+	/** Prefix for each line (for indentation in plan output). */
+	prefix?: string;
+	/** Whether to use ANSI colors. */
+	use_color?: boolean;
+	/** Maximum number of diff lines to show (0 = unlimited). */
+	max_lines?: number;
+}
+
+/**
+ * Format a diff for display.
+ *
+ * @param diff - The diff lines to format.
+ * @param current_path - Path label for "current" content.
+ * @param desired_path - Path label for "desired" content.
+ * @param options - Formatting options.
+ * @returns Formatted diff string.
+ */
+export const format_diff = (
+	diff: Array<DiffLine>,
+	current_path: string,
+	desired_path: string,
+	options: FormatDiffOptions = {},
+): string => {
+	const {prefix = '', use_color = true, max_lines = 50} = options;
+
+	const lines: Array<string> = [
+		`${prefix}--- ${current_path} (current)`,
+		`${prefix}+++ ${desired_path} (desired)`,
+	];
+
+	let count = 0;
+	for (const d of diff) {
+		if (max_lines > 0 && count >= max_lines) {
+			const remaining = diff.length - count;
+			lines.push(`${prefix}... (${remaining} more lines)`);
+			break;
+		}
+
+		const line_prefix = d.type === 'add' ? '+' : d.type === 'remove' ? '-' : ' ';
+
+		if (use_color && d.type !== 'same') {
+			const color = d.type === 'add' ? colors.green : colors.red;
+			lines.push(`${prefix}${color}${line_prefix}${d.line}${colors.reset}`);
+		} else {
+			lines.push(`${prefix}${line_prefix}${d.line}`);
+		}
+
+		count++;
+	}
+
+	return lines.join('\n');
+};
+
+/**
+ * Generate a formatted diff between two strings.
+ *
+ * Combines diff_lines, filter_diff_context, and format_diff for convenience.
+ * Returns null if content is binary.
+ *
+ * @param current - Current content.
+ * @param desired - Desired content.
+ * @param path - File path for labels.
+ * @param options - Formatting options.
+ * @returns Formatted diff string, or null if binary.
+ */
+export const generate_diff = (
+	current: string,
+	desired: string,
+	path: string,
+	options: FormatDiffOptions = {},
+): string | null => {
+	// Skip binary files
+	if (string_is_binary(current) || string_is_binary(desired)) {
+		return null;
+	}
+
+	const diff = diff_lines(current, desired);
+	const filtered = filter_diff_context(diff);
+	return format_diff(filtered, path, path, options);
+};

package/src/lib/path.ts

@@ -94,6 +94,26 @@ export const parse_path_pieces = (raw_path: string): Array<PathPiece> => {
 	return pieces;
 };
 
+/**
+ * Checks if a filename matches any exclusion pattern.
+ *
+ * Returns `false` when `filename` is `undefined`, empty string, or `exclude` is empty.
+ * String patterns use substring matching. RegExp patterns use `.test()`.
+ *
+ * @param filename The file path to check, or `undefined` for virtual files.
+ * @param exclude Array of string or RegExp exclusion patterns.
+ * @returns `true` if the file should be excluded from processing.
+ */
+export const should_exclude_path = (
+	filename: string | undefined,
+	exclude: Array<string | RegExp>,
+): boolean => {
+	if (!filename || exclude.length === 0) return false;
+	return exclude.some((pattern) =>
+		typeof pattern === 'string' ? filename.includes(pattern) : pattern.test(filename),
+	);
+};
+
 /**
  * Converts a string into a URL-compatible slug.
  * @param str the string to convert

package/src/lib/sort.ts

@@ -0,0 +1,160 @@
+/**
+ * Generic topological sort using Kahn's algorithm.
+ *
+ * Orders items so that dependencies come before dependents.
+ * Works with any item type that has `id` and optional `depends_on`.
+ *
+ * @module
+ */
+
+/**
+ * Minimum shape required for topological sorting.
+ */
+export interface Sortable {
+	id: string;
+	depends_on?: Array<string>;
+}
+
+/**
+ * Result of topological sort.
+ */
+export type TopologicalSortResult<T extends Sortable> =
+	| {ok: true; sorted: Array<T>}
+	| {ok: false; error: string; cycle?: Array<string>};
+
+/**
+ * Sort items by their dependencies using Kahn's algorithm.
+ *
+ * Returns items ordered so that dependencies come before dependents.
+ * If a cycle is detected, returns an error with the cycle path.
+ *
+ * @param items - Array of items to sort.
+ * @param label - Label for error messages (e.g. "resource", "step").
+ * @returns Sorted items or error if cycle detected.
+ */
+export const topological_sort = <T extends Sortable>(
+	items: Array<T>,
+	label: string = 'item',
+): TopologicalSortResult<T> => {
+	// Build id -> item map
+	const item_map: Map<string, T> = new Map();
+	for (const item of items) {
+		if (item_map.has(item.id)) {
+			return {ok: false, error: `duplicate ${label} id: ${item.id}`};
+		}
+		item_map.set(item.id, item);
+	}
+
+	// Validate all dependencies exist and count dependents per item
+	// dependents_count[X] = how many items list X in their depends_on
+	const dependents_count: Map<string, number> = new Map();
+	for (const item of items) {
+		dependents_count.set(item.id, 0);
+	}
+	for (const item of items) {
+		const deps = item.depends_on ?? [];
+		for (const dep of deps) {
+			if (!item_map.has(dep)) {
+				return {ok: false, error: `${label} "${item.id}" depends on unknown ${label} "${dep}"`};
+			}
+			dependents_count.set(dep, dependents_count.get(dep)! + 1);
+		}
+	}
+
+	// Start from leaf items (nothing depends on them), work toward roots
+	const queue: Array<string> = [];
+	for (const [id, count] of dependents_count) {
+		if (count === 0) {
+			queue.push(id);
+		}
+	}
+
+	// Process leaves first, then items whose dependents are all processed
+	const sorted: Array<T> = [];
+	const visited: Set<string> = new Set();
+
+	while (queue.length > 0) {
+		const id = queue.shift()!;
+		if (visited.has(id)) continue;
+		visited.add(id);
+
+		sorted.push(item_map.get(id)!);
+
+		// This item is processed — decrement its dependencies' dependent counts
+		const deps = item_map.get(id)!.depends_on ?? [];
+		for (const dep of deps) {
+			const new_count = dependents_count.get(dep)! - 1;
+			dependents_count.set(dep, new_count);
+			if (new_count === 0) {
+				queue.push(dep);
+			}
+		}
+	}
+
+	// Check for cycle
+	if (sorted.length !== items.length) {
+		const unvisited = items.filter((item) => !visited.has(item.id)).map((item) => item.id);
+		const cycle = find_cycle(item_map, unvisited);
+		return {
+			ok: false,
+			error: `dependency cycle detected: ${cycle.join(' -> ')}`,
+			cycle,
+		};
+	}
+
+	// Reverse: leaves were processed first, but dependencies must come first in output
+	sorted.reverse();
+
+	return {ok: true, sorted};
+};
+
+/**
+ * Find a cycle in the dependency graph starting from unvisited nodes.
+ * Used for error reporting when a cycle is detected.
+ */
+const find_cycle = <T extends Sortable>(
+	item_map: Map<string, T>,
+	unvisited: Array<string>,
+): Array<string> => {
+	const unvisited_set = new Set(unvisited);
+
+	// DFS to find cycle
+	const path: Array<string> = [];
+	const in_path: Set<string> = new Set();
+
+	const dfs = (id: string): boolean => {
+		if (in_path.has(id)) {
+			path.push(id);
+			return true;
+		}
+		if (!unvisited_set.has(id)) return false;
+
+		in_path.add(id);
+		path.push(id);
+
+		const item = item_map.get(id);
+		const deps = item?.depends_on ?? [];
+		for (const dep of deps) {
+			if (dfs(dep)) return true;
+		}
+
+		in_path.delete(id);
+		path.pop();
+		return false;
+	};
+
+	if (unvisited.length > 0) {
+		dfs(unvisited[0]!);
+	}
+
+	// Extract just the cycle portion
+	if (path.length > 0) {
+		const last = path[path.length - 1]!;
+		const cycle_start = path.indexOf(last);
+		if (cycle_start < path.length - 1) {
+			return path.slice(cycle_start);
+		}
+	}
+
+	return unvisited;
+};