@lumenflow/core 3.1.3 → 3.2.1

package/dist/delegation-tree.js

@@ -0,0 +1,205 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Delegation Tree Builder (WU-1674)
+ *
+ * Builds and formats delegation trees for visualization.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYAML } from 'yaml';
+import { DelegationRegistryStore } from './delegation-registry-store.js';
+import { DelegationStatus } from './delegation-registry-schema.js';
+/**
+ * Status indicators for terminal output.
+ */
+export const STATUS_INDICATORS = Object.freeze({
+    [DelegationStatus.PENDING]: '\u25CB', // ○
+    [DelegationStatus.COMPLETED]: '\u2713', // ✓
+    [DelegationStatus.TIMEOUT]: '\u23F1', // ⏱
+    [DelegationStatus.CRASHED]: '\u2717', // ✗
+    [DelegationStatus.ESCALATED]: '!',
+});
+const TREE_CHARS = Object.freeze({
+    VERTICAL: '\u2502',
+    BRANCH: '\u251C',
+    LAST_BRANCH: '\u2514',
+    HORIZONTAL: '\u2500',
+});
+function toDelegationRecord(record) {
+    return {
+        id: record.id,
+        parentWuId: record.parentWuId,
+        targetWuId: record.targetWuId,
+        lane: record.lane,
+        status: record.status,
+        delegatedAt: record.delegatedAt,
+        completedAt: record.completedAt,
+        pickedUpAt: record.pickedUpAt,
+        pickedUpBy: record.pickedUpBy,
+    };
+}
+/**
+ * Builds a delegation tree from flat delegation events.
+ */
+export function buildDelegationTree(delegations, rootWuId) {
+    const root = {
+        wuId: rootWuId,
+        delegationId: null,
+        status: null,
+        lane: null,
+        delegatedAt: null,
+        children: [],
+    };
+    if (delegations.length === 0) {
+        return root;
+    }
+    const delegationsByParent = new Map();
+    for (const delegation of delegations) {
+        const existing = delegationsByParent.get(delegation.parentWuId) ?? [];
+        existing.push(delegation);
+        delegationsByParent.set(delegation.parentWuId, existing);
+    }
+    const buildChildren = (parentWuId) => {
+        const childDelegations = delegationsByParent.get(parentWuId) ?? [];
+        return childDelegations.map((delegation) => ({
+            wuId: delegation.targetWuId,
+            delegationId: delegation.id,
+            status: delegation.status,
+            lane: delegation.lane,
+            delegatedAt: delegation.delegatedAt,
+            children: buildChildren(delegation.targetWuId),
+        }));
+    };
+    root.children = buildChildren(rootWuId);
+    return root;
+}
+/**
+ * Formats a delegation tree for terminal display.
+ */
+export function formatDelegationTree(tree) {
+    const lines = [];
+    lines.push(`${tree.wuId} (root)`);
+    if (tree.children.length === 0) {
+        lines.push('  (no delegations)');
+        return lines.join('\n');
+    }
+    const formatChildren = (children, prefix) => {
+        children.forEach((child, index) => {
+            const isLast = index === children.length - 1;
+            const branch = isLast
+                ? `${TREE_CHARS.LAST_BRANCH}${TREE_CHARS.HORIZONTAL}${TREE_CHARS.HORIZONTAL}`
+                : `${TREE_CHARS.BRANCH}${TREE_CHARS.HORIZONTAL}${TREE_CHARS.HORIZONTAL}`;
+            const indicator = child.status ? (STATUS_INDICATORS[child.status] ?? '?') : '?';
+            const delegationInfo = child.delegationId ? ` [${child.delegationId}]` : '';
+            const laneInfo = child.lane ? ` (${child.lane})` : '';
+            lines.push(`${prefix}${branch} ${indicator} ${child.wuId}${delegationInfo}${laneInfo}`);
+            const childPrefix = prefix + (isLast ? '    ' : `${TREE_CHARS.VERTICAL}   `);
+            formatChildren(child.children, childPrefix);
+        });
+    };
+    formatChildren(tree.children, '');
+    return lines.join('\n');
+}
+/**
+ * Gets all delegations for a WU (direct + descendants).
+ */
+export async function getDelegationsByWU(wuId, baseDir) {
+    const store = new DelegationRegistryStore(baseDir);
+    try {
+        await store.load();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    const allRecords = store.getAllDelegations();
+    if (allRecords.length === 0) {
+        return [];
+    }
+    const result = [];
+    const seenDelegationIds = new Set();
+    const visitedWuIds = new Set();
+    const queue = [wuId];
+    while (queue.length > 0) {
+        const currentWuId = queue.shift();
+        if (!currentWuId || visitedWuIds.has(currentWuId)) {
+            continue;
+        }
+        visitedWuIds.add(currentWuId);
+        const childRecords = store.getByParent(currentWuId);
+        for (const child of childRecords) {
+            if (!seenDelegationIds.has(child.id)) {
+                result.push(toDelegationRecord(child));
+                seenDelegationIds.add(child.id);
+            }
+            queue.push(child.targetWuId);
+        }
+    }
+    return result;
+}
+/**
+ * Gets all delegations for an initiative.
+ */
+export async function getDelegationsByInitiative(initiativeId, registryDir, wuDir) {
+    const initiativeWuIds = await getWUsForInitiative(initiativeId, wuDir);
+    if (initiativeWuIds.size === 0) {
+        return [];
+    }
+    const store = new DelegationRegistryStore(registryDir);
+    try {
+        await store.load();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+    return store.getAllDelegations()
+        .filter((record) => initiativeWuIds.has(record.parentWuId))
+        .map(toDelegationRecord);
+}
+async function getWUsForInitiative(initiativeId, wuDir) {
+    const wuIds = new Set();
+    let files;
+    try {
+        files = await fs.readdir(wuDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return wuIds;
+        }
+        throw error;
+    }
+    const wuFiles = files.filter((file) => file.startsWith('WU-') && file.endsWith('.yaml'));
+    for (const file of wuFiles) {
+        try {
+            const content = await fs.readFile(path.join(wuDir, file), 'utf-8');
+            const doc = parseYAML(content);
+            if (doc.initiative === initiativeId && typeof doc.id === 'string') {
+                wuIds.add(doc.id);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return wuIds;
+}
+/**
+ * Converts a delegation tree to JSON.
+ */
+export function treeToJSON(tree) {
+    return {
+        wuId: tree.wuId,
+        delegationId: tree.delegationId,
+        status: tree.status,
+        lane: tree.lane,
+        delegatedAt: tree.delegatedAt,
+        children: tree.children.map((child) => treeToJSON(child)),
+    };
+}
+//# sourceMappingURL=delegation-tree.js.map

package/dist/delegation-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-tree.js","sourceRoot":"","sources":["../src/delegation-tree.ts"],"names":[],"mappings":"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"}

package/dist/dependency-graph.d.ts

@@ -0,0 +1,169 @@
+export interface DependencyNode {
+    id: string;
+    title: string;
+    status: string;
+    blocks: string[];
+    blockedBy: string[];
+}
+export type DependencyGraph = Map<string, DependencyNode>;
+interface DependencyTraversalEntry {
+    id: string;
+    depth: number;
+    path: string[];
+}
+interface TopologicalSortCycleWarning {
+    order: string[];
+    warning: string;
+    cycleNodes: string[];
+}
+interface CriticalPathResult {
+    path: string[];
+    length: number;
+    warning?: string;
+}
+interface BottleneckScore {
+    id: string;
+    score: number;
+    title?: string;
+}
+/**
+ * Dependency Graph Module (WU-1247, WU-1568)
+ *
+ * Provides graph building, visualization, and analysis for WU dependencies.
+ * Supports ASCII tree and Mermaid diagram output formats.
+ * Includes graph algorithms for operational insights: topological sort,
+ * critical path, impact scoring, and bottleneck detection.
+ *
+ * @example
+ * import { buildDependencyGraph, renderASCII, renderMermaid, topologicalSort, criticalPath, bottlenecks } from './lib/dependency-graph.js';
+ *
+ * const graph = buildDependencyGraph();
+ * console.log(renderASCII(graph, 'WU-1247'));
+ * console.log(renderMermaid(graph, { direction: 'TD' }));
+ *
+ * // Graph analysis (WU-1568)
+ * const sorted = topologicalSort(graph);
+ * const critical = criticalPath(graph);
+ * const topBottlenecks = bottlenecks(graph, 10);
+ */
+/**
+ * Build a dependency graph from all WU YAML files.
+ *
+ * @returns {Map<string, {id: string, title: string, status: string, blocks: string[], blockedBy: string[]}>}
+ */
+export declare function buildDependencyGraph(): DependencyGraph;
+/**
+ * Build a dependency graph from all WU YAML files asynchronously.
+ *
+ * @returns {Promise<Map<string, {id: string, title: string, status: string, blocks: string[], blockedBy: string[]}>>}
+ */
+export declare function buildDependencyGraphAsync(): Promise<DependencyGraph>;
+/**
+ * Get all dependencies (upstream: blocked_by) for a WU.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {string} wuId - WU ID to get dependencies for
+ * @param {number} [maxDepth=10] - Maximum traversal depth
+ * @returns {Array<{id: string, depth: number, path: string[]}>}
+ */
+export declare function getUpstreamDependencies(graph: DependencyGraph, wuId: string, maxDepth?: number): DependencyTraversalEntry[];
+/**
+ * Get all dependents (downstream: blocks) for a WU.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {string} wuId - WU ID to get dependents for
+ * @param {number} [maxDepth=10] - Maximum traversal depth
+ * @returns {Array<{id: string, depth: number, path: string[]}>}
+ */
+export declare function getDownstreamDependents(graph: DependencyGraph, wuId: string, maxDepth?: number): DependencyTraversalEntry[];
+/**
+ * Options for rendering ASCII tree
+ */
+export interface RenderASCIIOptions {
+    /** Direction to traverse: 'up', 'down', or 'both' */
+    direction?: 'up' | 'down' | 'both';
+    /** Maximum depth to traverse */
+    depth?: number;
+}
+/**
+ * Render dependency graph as ASCII tree.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {string} rootId - Root WU ID
+ * @param {RenderASCIIOptions} [options] - Render options
+ * @returns {string} ASCII tree representation
+ */
+export declare function renderASCII(graph: DependencyGraph, rootId: string, options?: RenderASCIIOptions): string;
+/**
+ * Options for rendering Mermaid diagram
+ */
+export interface RenderMermaidOptions {
+    /** Optional root WU ID to focus on */
+    rootId?: string;
+    /** Diagram direction: 'TD', 'LR', 'BT', 'RL' */
+    direction?: 'TD' | 'LR' | 'BT' | 'RL';
+    /** Maximum depth from root */
+    depth?: number;
+}
+/**
+ * Render dependency graph as Mermaid diagram.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {RenderMermaidOptions} [options] - Render options
+ * @returns {string} Mermaid diagram syntax
+ */
+export declare function renderMermaid(graph: DependencyGraph, options?: RenderMermaidOptions): string;
+/**
+ * Validate dependency graph for cycles and orphans.
+ *
+ * @param {Map} graph - Dependency graph
+ * @returns {{hasCycle: boolean, cycles: string[][], orphans: Array<{wuId: string, ref: string}>}}
+ */
+export declare function validateGraph(graph: DependencyGraph): {
+    hasCycle: boolean;
+    cycles: string[][];
+    orphans: Array<{
+        wuId: string;
+        ref: string;
+    }>;
+};
+/**
+ * Perform topological sort on non-done WUs using Kahn's algorithm.
+ * Returns valid execution ordering where dependencies come before dependents.
+ * Handles cycles gracefully by returning partial ordering with warning.
+ *
+ * @param {Map} graph - Dependency graph
+ * @returns {string[]|{order: string[], warning: string, cycleNodes: string[]}} Sorted WU IDs or warning object
+ */
+export declare function topologicalSort(graph: DependencyGraph): string[] | TopologicalSortCycleWarning;
+/**
+ * Find the critical path (longest dependency chain) in the graph.
+ * Uses dynamic programming on the DAG to find the longest path.
+ * Excludes done WUs from the path.
+ *
+ * @param {Map} graph - Dependency graph
+ * @returns {{path: string[], length: number, warning?: string}} Critical path info
+ */
+export declare function criticalPath(graph: DependencyGraph): CriticalPathResult;
+/**
+ * Calculate the impact score for a WU.
+ * Impact score is the count of all downstream dependents (recursive).
+ * Excludes done WUs from the count.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {string} wuId - WU ID to score
+ * @returns {number} Count of downstream dependents
+ */
+export declare function impactScore(graph: DependencyGraph, wuId: string): number;
+/**
+ * Find the top N bottleneck WUs by impact score.
+ * A bottleneck is a WU that blocks many other WUs.
+ * Excludes done WUs from results.
+ *
+ * @param {Map} graph - Dependency graph
+ * @param {number} limit - Maximum number of bottlenecks to return
+ * @returns {Array<{id: string, score: number, title?: string}>} Bottlenecks sorted by score descending
+ */
+export declare function bottlenecks(graph: DependencyGraph, limit: number): BottleneckScore[];
+export {};
+//# sourceMappingURL=dependency-graph.d.ts.map

package/dist/dependency-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-graph.d.ts","sourceRoot":"","sources":["../src/dependency-graph.ts"],"names":[],"mappings":"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"}