@lumenflow/core 1.0.0

package/dist/date-utils.js

@@ -0,0 +1,140 @@
+/**
+ * @file date-utils.mjs
+ * @description Date formatting utilities using date-fns library
+ * WU-1082: Extract shared utilities (eliminate date formatting duplication)
+ *
+ * Replaces manual date formatting in:
+ * - tools/wu-block.mjs (todayISO)
+ * - tools/wu-unblock.mjs (todayISO)
+ * - tools/wu-done.mjs (todayISO - already uses date-fns)
+ */
+import { format } from 'date-fns';
+/**
+ * Get current date in ISO format (YYYY-MM-DD)
+ * @returns {string} Current date in YYYY-MM-DD format
+ * @example
+ * todayISO(); // "2025-11-12"
+ */
+export function todayISO() {
+    return format(new Date(), 'yyyy-MM-dd');
+}
+/**
+ * Format a date with a custom format string
+ * @param {Date|string|number} date - Date to format
+ * @param {string} formatString - date-fns format string
+ * @returns {string} Formatted date string
+ * @example
+ * formatDate(new Date(), 'yyyy-MM-dd HH:mm:ss');
+ * formatDate('2025-11-12', 'MMMM d, yyyy'); // "November 12, 2025"
+ */
+export function formatDate(date, formatString) {
+    return format(new Date(date), formatString);
+}
+/**
+ * Date format constant for YYYY-MM-DD
+ * @constant {string}
+ */
+const DATE_FORMAT_ISO = 'yyyy-MM-dd';
+/**
+ * Normalize a Date object or ISO timestamp string to YYYY-MM-DD format
+ *
+ * WU-1442: Fix date corruption when js-yaml parses YYYY-MM-DD as Date objects
+ * Library-First: Uses date-fns for date formatting (no manual parsing)
+ *
+ * Use case: js-yaml parses `created: 2025-12-04` (unquoted) as a Date object.
+ * When yaml.dump() serializes it back, it outputs `2025-12-04T00:00:00.000Z`.
+ * This function normalizes Date objects back to YYYY-MM-DD string format.
+ *
+ * Handles:
+ * - Date objects → YYYY-MM-DD string
+ * - ISO timestamp strings → YYYY-MM-DD string (date portion)
+ * - YYYY-MM-DD strings → preserved as-is
+ * - undefined/null → preserved as undefined
+ *
+ * @param {Date|string|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} Date in YYYY-MM-DD format or undefined
+ *
+ * @example
+ * normalizeToDateString(new Date('2025-12-04')); // '2025-12-04'
+ * normalizeToDateString('2025-12-04T00:00:00.000Z'); // '2025-12-04'
+ * normalizeToDateString('2025-12-04'); // '2025-12-04'
+ * normalizeToDateString(undefined); // undefined
+ */
+export function normalizeToDateString(value) {
+    // Preserve undefined/null
+    if (value == null) {
+        return undefined;
+    }
+    // If already a YYYY-MM-DD string, return as-is
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+        return value;
+    }
+    // Convert Date objects or timestamp strings to YYYY-MM-DD
+    if (value instanceof Date) {
+        return format(value, DATE_FORMAT_ISO);
+    }
+    // Handle ISO timestamp strings (e.g., '2025-12-04T00:00:00.000Z')
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        return format(new Date(value), DATE_FORMAT_ISO);
+    }
+    // Fallback: try to parse and format
+    try {
+        const date = new Date(value);
+        if (!isNaN(date.getTime())) {
+            return format(date, DATE_FORMAT_ISO);
+        }
+    }
+    catch {
+        // Invalid date - return undefined
+    }
+    return undefined;
+}
+/**
+ * Normalize various date formats to ISO 8601 datetime (YYYY-MM-DDTHH:mm:ss.sssZ)
+ *
+ * WU-1337: Auto-repair date fields in WU YAML to consistent format
+ * Library-First: Uses date-fns for date handling (no manual parsing)
+ *
+ * Handles:
+ * - ISO date strings (YYYY-MM-DD) → midnight UTC
+ * - ISO datetime strings (already valid) → preserved
+ * - Unix timestamps (milliseconds) → converted
+ * - undefined/null → preserved as undefined
+ *
+ * @param {string|number|undefined|null} value - Date value to normalize
+ * @returns {string|undefined} ISO datetime string or undefined
+ *
+ * @example
+ * normalizeISODateTime('2025-11-29'); // '2025-11-29T00:00:00.000Z'
+ * normalizeISODateTime('2025-11-29T14:30:00.000Z'); // '2025-11-29T14:30:00.000Z'
+ * normalizeISODateTime(1732896000000); // '2024-11-29T16:00:00.000Z'
+ * normalizeISODateTime(undefined); // undefined
+ */
+export function normalizeISODateTime(value) {
+    // Preserve undefined/null (optional fields)
+    if (value == null) {
+        return undefined;
+    }
+    // If already a valid ISO datetime format, preserve it
+    // Pattern: YYYY-MM-DDTHH:mm:ss.sssZ
+    if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)) {
+        return value;
+    }
+    // Handle Unix timestamps as strings (convert to number first)
+    let dateInput = value;
+    if (typeof value === 'string' && /^\d+$/.test(value)) {
+        // Numeric string - treat as Unix timestamp in milliseconds
+        dateInput = Number(value);
+    }
+    // Parse and convert to ISO datetime
+    // date-fns/Date handles: ISO dates, ISO datetimes, Unix timestamps
+    const date = new Date(dateInput);
+    // Check for invalid date
+    if (isNaN(date.getTime())) {
+        // Fallback: return undefined for unparseable dates
+        // Zod schema will catch invalid dates separately
+        return undefined;
+    }
+    // Convert to ISO 8601 datetime format
+    return date.toISOString();
+}

package/dist/dependency-graph.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 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(): Map<any, any>;
+/**
+ * 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: any, wuId: any, maxDepth?: number): any[];
+/**
+ * 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: any, wuId: any, maxDepth?: number): any[];
+/**
+ * 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: any, rootId: any, 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: any, 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: any): {
+    hasCycle: boolean;
+    cycles: string[][];
+    orphans: any[];
+};
+/**
+ * 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: any): any[] | {
+    order: any[];
+    warning: string;
+    cycleNodes: any[];
+};
+/**
+ * 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: any): {
+    path: any[];
+    length: number;
+    warning: string;
+} | {
+    path: any[];
+    length: number;
+    warning?: undefined;
+};
+/**
+ * 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: any, wuId: any): 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: any, limit: any): any[];