@fuzdev/fuz_util 0.48.2 → 0.48.4

package/dist/sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sort.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/sort.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,QAAQ,IACjD;IAAC,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAA;CAAC,GAC5B;IAAC,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAA;CAAC,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EAClD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,QAAO,MAAe,KACpB,qBAAqB,CAAC,CAAC,CAuEzB,CAAC"}

package/dist/sort.js

@@ -0,0 +1,123 @@
+/**
+ * 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
+ */
+/**
+ * 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 = (items, label = 'item') => {
+    // Build id -> item map
+    const item_map = 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 = 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 = [];
+    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 = [];
+    const visited = 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 = (item_map, unvisited) => {
+    const unvisited_set = new Set(unvisited);
+    // DFS to find cycle
+    const path = [];
+    const in_path = new Set();
+    const dfs = (id) => {
+        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/dist/source_json.d.ts

@@ -16,10 +16,10 @@ import { z } from 'zod';
 export declare const DeclarationKind: z.ZodEnum<{
     function: "function";
     type: "type";
-    constructor: "constructor";
     json: "json";
     variable: "variable";
     class: "class";
+    constructor: "constructor";
     component: "component";
     css: "css";
 }>;
@@ -80,10 +80,10 @@ export declare const DeclarationJson: z.ZodObject<{
     kind: z.ZodEnum<{
         function: "function";
         type: "type";
-        constructor: "constructor";
         json: "json";
         variable: "variable";
         class: "class";
+        constructor: "constructor";
         component: "component";
         css: "css";
     }>;
@@ -172,10 +172,10 @@ export declare const ModuleJson: z.ZodObject<{
         kind: z.ZodEnum<{
             function: "function";
             type: "type";
-            constructor: "constructor";
             json: "json";
             variable: "variable";
             class: "class";
+            constructor: "constructor";
             component: "component";
             css: "css";
         }>;
@@ -279,10 +279,10 @@ export declare const SourceJson: z.ZodObject<{
             kind: z.ZodEnum<{
                 function: "function";
                 type: "type";
-                constructor: "constructor";
                 json: "json";
                 variable: "variable";
                 class: "class";
+                constructor: "constructor";
                 component: "component";
                 css: "css";
             }>;

package/dist/string.d.ts

@@ -70,4 +70,13 @@ export declare const pad_width: (str: string, target_width: number, align?: "lef
  * @returns The edit distance between the strings
  */
 export declare const levenshtein_distance: (a: string, b: string) => number;
+/**
+ * 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 declare const is_binary: (content: string) => boolean;
 //# sourceMappingURL=string.d.ts.map

package/dist/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAuClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,cAAc,MAAM,EACpB,QAAO,MAAM,GAAG,OAAgB,KAC9B,MAQF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAmC3D,CAAC"}
+{"version":3,"file":"string.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/string.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,EAAE,WAAW,MAAM,EAAE,eAAc,KAAG,MAMzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,UAAU,MAAM,KAAG,MAK/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,QAAQ,MAAM,EAAE,SAAS,MAAM,KAAG,MAG5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,QAAQ,GAAI,KAAK,MAAM,KAAG,MAK1B,CAAC;AAEd;;GAEG;AACH,eAAO,MAAM,MAAM,GAAI,OAAO,MAAM,GAAG,SAAS,GAAG,IAAI,EAAE,eAAY,KAAG,MAC9C,CAAC;AAE3B;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,KAAK,MAAM,KAAG,MACI,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAsD,CAAC;AAEhG;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,OAAO,KAAG,MACwC,CAAC;AAEpF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,KAAG,MAuClD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACrB,KAAK,MAAM,EACX,cAAc,MAAM,EACpB,QAAO,MAAM,GAAG,OAAgB,KAC9B,MAQF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAmC3D,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,KAAG,OAG3C,CAAC"}

package/dist/string.js

@@ -191,3 +191,15 @@ export const levenshtein_distance = (a, b) => {
     }
     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) => {
+    const sample = content.slice(0, 8192);
+    return sample.includes('\0');
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_util",
-  "version": "0.48.2",
+  "version": "0.48.4",
   "description": "utility belt for JS",
   "glyph": "🦕",
   "logo": "logo.svg",
@@ -61,11 +61,11 @@
   },
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
-    "@fuzdev/fuz_code": "^0.40.0",
-    "@fuzdev/fuz_css": "^0.44.1",
-    "@fuzdev/fuz_ui": "^0.179.0",
+    "@fuzdev/fuz_code": "^0.41.0",
+    "@fuzdev/fuz_css": "^0.47.0",
+    "@fuzdev/fuz_ui": "^0.181.1",
     "@ryanatkn/eslint-config": "^0.9.0",
-    "@ryanatkn/gro": "^0.189.3",
+    "@ryanatkn/gro": "^0.190.0",
     "@sveltejs/adapter-static": "^3.0.10",
     "@sveltejs/kit": "^2.50.1",
     "@sveltejs/package": "^2.5.7",
@@ -79,8 +79,8 @@
     "fast-deep-equal": "^3.1.3",
     "prettier": "^3.7.4",
     "prettier-plugin-svelte": "^3.4.1",
-    "svelte": "^5.48.2",
-    "svelte-check": "^4.3.4",
+    "svelte": "^5.49.1",
+    "svelte-check": "^4.3.6",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.48.1",

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