@fuzdev/fuz_util 0.48.2 → 0.48.4

package/src/lib/diff.ts

@@ -0,0 +1,234 @@
+/**
+ * Line-based diff utilities using LCS (Longest Common Subsequence).
+ *
+ * @module
+ */
+
+import {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 (is_binary(current) || 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/hash.ts

@@ -0,0 +1,73 @@
+/**
+ * Hash utilities for content comparison and cache invalidation.
+ *
+ * Provides both secure (cryptographic) and insecure (fast) hash functions.
+ *
+ * @module
+ */
+
+const encoder = new TextEncoder();
+
+// Lazily computed lookup table for byte to hex conversion
+let byte_to_hex: Array<string> | undefined;
+const get_byte_to_hex = (): Array<string> => {
+	if (byte_to_hex === undefined) {
+		byte_to_hex = new Array(256); // 256 possible byte values (0x00-0xff)
+		for (let i = 0; i < 256; i++) {
+			byte_to_hex[i] = i.toString(16).padStart(2, '0');
+		}
+	}
+	return byte_to_hex;
+};
+
+/**
+ * Computes a cryptographic hash using Web Crypto API.
+ *
+ * @param data - String or binary data to hash. Strings are UTF-8 encoded.
+ * @param algorithm - Hash algorithm. Defaults to SHA-256.
+ * @returns Hexadecimal hash string.
+ */
+export const hash_secure = async (
+	data: BufferSource | string,
+	algorithm: 'SHA-256' | 'SHA-384' | 'SHA-512' = 'SHA-256',
+): Promise<string> => {
+	const buffer = typeof data === 'string' ? encoder.encode(data) : data;
+	const digested = await crypto.subtle.digest(algorithm, buffer);
+	const bytes = new Uint8Array(digested);
+	const lookup = get_byte_to_hex();
+	let hex = '';
+	for (const byte of bytes) {
+		hex += lookup[byte];
+	}
+	return hex;
+};
+
+/**
+ * Computes a fast non-cryptographic hash using DJB2 algorithm.
+ * Use for content comparison and cache keys, not security.
+ *
+ * Note: Strings use UTF-16 code units, buffers use raw bytes.
+ * For non-ASCII, `hash_insecure(str) !== hash_insecure(encoder.encode(str))`.
+ *
+ * @param data - String or binary data to hash.
+ * @returns 8-character hex-encoded unsigned 32-bit hash.
+ */
+export const hash_insecure = (data: BufferSource | string): string => {
+	let hash = 5381; // DJB2 initial value, chosen empirically for good distribution
+	if (typeof data === 'string') {
+		for (let i = 0; i < data.length; i++) {
+			hash = (hash << 5) - hash + data.charCodeAt(i);
+		}
+	} else {
+		const bytes: Uint8Array =
+			data instanceof Uint8Array
+				? data
+				: data instanceof ArrayBuffer
+					? new Uint8Array(data)
+					: new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+		for (const byte of bytes) {
+			hash = (hash << 5) - hash + byte;
+		}
+	}
+	return (hash >>> 0).toString(16).padStart(8, '0');
+};

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;
+};

package/src/lib/string.ts

@@ -208,3 +208,16 @@ export const levenshtein_distance = (a: string, b: string): number => {
 
 	return prev[short_len]!;
 };
+
+/**
+ * Check if content appears to be binary.
+ *
+ * Checks for null bytes in the first 8KB of content.
+ *
+ * @param content - Content to check.
+ * @returns True if content appears to be binary.
+ */
+export const is_binary = (content: string): boolean => {
+	const sample = content.slice(0, 8192);
+	return sample.includes('\0');
+};