@fuzdev/fuz_util 0.48.3 → 0.49.0

package/dist/async.d.ts

@@ -77,4 +77,15 @@ export declare const map_concurrent: <T, R>(items: Array<T>, fn: (item: T, index
  * ```
  */
 export declare const map_concurrent_settled: <T, R>(items: Array<T>, fn: (item: T, index: number) => Promise<R>, concurrency: number) => Promise<Array<PromiseSettledResult<R>>>;
+/**
+ * Async semaphore for concurrency limiting.
+ *
+ * With `Infinity` permits, `acquire()` always resolves immediately.
+ */
+export declare class AsyncSemaphore {
+    #private;
+    constructor(permits: number);
+    acquire(): Promise<void>;
+    release(): void;
+}
 //# sourceMappingURL=async.d.ts.map

package/dist/async.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,aAAa,MAAM,KACjB,OAAO,CAAC,IAAI,CAgDd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAkDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC"}
+{"version":3,"file":"async.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/async.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE;;GAEG;AACH,eAAO,MAAM,IAAI,GAAI,iBAAY,KAAG,OAAO,CAAC,IAAI,CACQ,CAAC;AAEzD;;GAEG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CACI,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,QAAQ,CAAC,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC5B,MAAM,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,OAAK,QAAQ,CAAC,CAAC,CAQ/C,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,eAAe,GAAU,CAAC,EACtC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EAC7C,aAAa,MAAM,KACjB,OAAO,CAAC,IAAI,CAgDd,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAU,CAAC,EAAE,CAAC,EACxC,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAkDlB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,sBAAsB,GAAU,CAAC,EAAE,CAAC,EAChD,OAAO,KAAK,CAAC,CAAC,CAAC,EACf,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAC1C,aAAa,MAAM,KACjB,OAAO,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6CxC,CAAC;AAEF;;;;GAIG;AACH,qBAAa,cAAc;;gBAId,OAAO,EAAE,MAAM;IAIrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9B,OAAO,IAAI,IAAI;CAQf"}

package/dist/async.js

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

package/dist/dag.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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 { 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 declare const run_dag: <T extends DagNode>(options: DagOptions<T>) => Promise<DagResult>;
+//# sourceMappingURL=dag.d.ts.map

package/dist/dag.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dag.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/dag.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAmB,KAAK,QAAQ,EAAC,MAAM,WAAW,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,OAAO;IAC5C,wBAAwB;IACxB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAChB,wCAAwC;IACxC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,sEAAsE;IACtE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,8EAA8E;IAC9E,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IACnC,wDAAwD;IACxD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,iEAAiE;IACjE,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACzB,4CAA4C;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,wBAAwB;IACxB,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACpC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,OAAO,GAAU,CAAC,SAAS,OAAO,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,SAAS,CA0J1F,CAAC"}

package/dist/dag.js

@@ -0,0 +1,156 @@
+/**
+ * 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 } from './async.js';
+import { topological_sort } from './sort.js';
+/**
+ * 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 (options) => {
+    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 = new Map();
+    const outcomes = new Map();
+    const results = 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, outcome, reason) => {
+        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) => {
+        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/dist/diff.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Line-based diff utilities using LCS (Longest Common Subsequence).
+ *
+ * @module
+ */
+/** 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 declare const diff_lines: (a: string, b: string) => Array<DiffLine>;
+/**
+ * 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 declare const filter_diff_context: (diff: Array<DiffLine>, context_lines?: number) => Array<DiffLine>;
+/**
+ * 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 declare const format_diff: (diff: Array<DiffLine>, current_path: string, desired_path: string, options?: FormatDiffOptions) => string;
+/**
+ * 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 declare const generate_diff: (current: string, desired: string, path: string, options?: FormatDiffOptions) => string | null;
+//# sourceMappingURL=diff.d.ts.map

package/dist/diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/diff.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,uBAAuB;AACvB,MAAM,WAAW,QAAQ;IACxB,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,KAAK,CAAC,QAAQ,CA+B/D,CAAC;AAyCF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,KAAK,CAAC,QAAQ,CAAC,EAAE,sBAAiB,KAAG,KAAK,CAAC,QAAQ,CAyC5F,CAAC;AASF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,KAAK,CAAC,QAAQ,CAAC,EACrB,cAAc,MAAM,EACpB,cAAc,MAAM,EACpB,UAAS,iBAAsB,KAC7B,MA6BF,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GACzB,SAAS,MAAM,EACf,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,UAAS,iBAAsB,KAC7B,MAAM,GAAG,IASX,CAAC"}

package/dist/diff.js

@@ -0,0 +1,185 @@
+/**
+ * Line-based diff utilities using LCS (Longest Common Subsequence).
+ *
+ * @module
+ */
+import { string_is_binary } from './string.js';
+/**
+ * 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, b) => {
+    const a_lines = a.split('\n');
+    const b_lines = b.split('\n');
+    const result = [];
+    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, b) => {
+    const m = a.length;
+    const n = b.length;
+    const dp = 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 = [];
+    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, context_lines = 3) => {
+    if (diff.length === 0)
+        return [];
+    // Find indices of all changed lines
+    const changed_indices = [];
+    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 = 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 = [];
+    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',
+};
+/**
+ * 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, current_path, desired_path, options = {}) => {
+    const { prefix = '', use_color = true, max_lines = 50 } = options;
+    const lines = [
+        `${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, desired, path, options = {}) => {
+    // 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/dist/path.d.ts

@@ -53,6 +53,17 @@ export type PathPiece = {
  * @todo maybe rethink this API, it's a bit weird, but fits the usage in `ui/Breadcrumbs.svelte`
  */
 export declare const parse_path_pieces: (raw_path: string) => Array<PathPiece>;
+/**
+ * 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 declare const should_exclude_path: (filename: string | undefined, exclude: Array<string | RegExp>) => boolean;
 /**
  * Converts a string into a URL-compatible slug.
  * @param str the string to convert

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,GAAG,GAAG,KAAG,MACgC,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CAU3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CACH,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAClB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACZ,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,KAAK,CAAC,SAAS,CAgBnE,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,gCAA6B,KAAG,MAYpE,CAAC"}
+{"version":3,"file":"path.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/path.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,YAAY,CAAC;AAEzC;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,QAAQ;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,QAAQ;IAC7C,IAAI,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,YAAY,GAAI,aAAa,MAAM,GAAG,GAAG,KAAG,MACgC,CAAC;AAE1F;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CAU3D,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,MAAM,CACH,CAAC;AAE7D;;GAEG;AACH,MAAM,MAAM,SAAS,GAClB;IACA,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACZ,GACD;IACA,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACZ,CAAC;AAEL;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,MAAM,KAAG,KAAK,CAAC,SAAS,CAgBnE,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC/B,UAAU,MAAM,GAAG,SAAS,EAC5B,SAAS,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,KAC7B,OAKF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,KAAK,MAAM,EAAE,gCAA6B,KAAG,MAYpE,CAAC"}

package/dist/path.js

@@ -42,6 +42,21 @@ export const parse_path_pieces = (raw_path) => {
     }
     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, exclude) => {
+    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/dist/sort.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 declare const topological_sort: <T extends Sortable>(items: Array<T>, label?: string) => TopologicalSortResult<T>;
+//# sourceMappingURL=sort.d.ts.map

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"}