@lumenflow/core 1.0.0

package/dist/lane-checker.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+/**
+ * Lane Occupancy Checker
+ *
+ * Enforces one-WU-per-lane rule by checking status.md for active WUs in a given lane.
+ * Used by wu-claim.mjs and wu-unblock.mjs to prevent WIP violations.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { getSubLanesForParent } from './lane-inference.js';
+import { createError, ErrorCodes } from './error-handler.js';
+import { isInProgressHeader, WU_LINK_PATTERN } from './constants/backlog-patterns.js';
+import { CONFIG_FILES, STRING_LITERALS } from './wu-constants.js';
+import { WU_PATHS } from './wu-paths.js';
+import { findProjectRoot } from './lumenflow-config.js';
+// Re-export for test access
+export { getSubLanesForParent };
+/** Log prefix for lane-checker messages */
+const PREFIX = '[lane-checker]';
+/** Status.md marker for empty In Progress section */
+const NO_ITEMS_MARKER = 'No items currently in progress';
+/**
+ * Extract parent lane from sub-lane or parent-only format
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling" or "Operations")
+ * @returns {string} Parent lane name
+ */
+export function extractParent(lane) {
+    const trimmed = lane.trim();
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) {
+        // Parent-only format
+        return trimmed;
+    }
+    // Sub-lane format: extract parent before colon
+    return trimmed.substring(0, colonIndex).trim();
+}
+/**
+ * Check if a parent lane has sub-lane taxonomy defined
+ * @param {string} parent - Parent lane name
+ * @returns {boolean} True if parent has sub-lanes in lane-inference config
+ */
+function hasSubLaneTaxonomy(parent) {
+    const projectRoot = findProjectRoot();
+    const taxonomyPath = path.join(projectRoot, CONFIG_FILES.LANE_INFERENCE);
+    if (!existsSync(taxonomyPath)) {
+        return false;
+    }
+    try {
+        const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
+        const taxonomy = yaml.load(taxonomyContent);
+        // Check if parent exists as top-level key in taxonomy
+        const normalizedParent = parent.trim();
+        return Object.keys(taxonomy).some((key) => key.toLowerCase().trim() === normalizedParent.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a sub-lane exists for a given parent in lane-inference config
+ * @param {string} parent - Parent lane name
+ * @param {string} subdomain - Sub-lane name
+ * @returns {boolean} True if sub-lane exists
+ */
+function isValidSubLane(parent, subdomain) {
+    const projectRoot = findProjectRoot();
+    const taxonomyPath = path.join(projectRoot, CONFIG_FILES.LANE_INFERENCE);
+    if (!existsSync(taxonomyPath)) {
+        return false;
+    }
+    try {
+        const taxonomyContent = readFileSync(taxonomyPath, { encoding: 'utf-8' });
+        const taxonomy = yaml.load(taxonomyContent);
+        // Find parent key (case-insensitive)
+        const normalizedParent = parent.trim().toLowerCase();
+        const parentKey = Object.keys(taxonomy).find((key) => key.toLowerCase().trim() === normalizedParent);
+        if (!parentKey) {
+            return false;
+        }
+        // Check if subdomain exists under parent
+        const subLanes = taxonomy[parentKey];
+        if (!subLanes || typeof subLanes !== 'object') {
+            return false;
+        }
+        // Exact match on subdomain (case-sensitive per Codex spec)
+        return Object.keys(subLanes).includes(subdomain.trim());
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Count occurrences of a character in a string
+ * @param {string} str - String to search
+ * @param {string} char - Character to count
+ * @returns {number} Number of occurrences
+ */
+function countChar(str, char) {
+    let count = 0;
+    for (const c of str) {
+        if (c === char)
+            count++;
+    }
+    return count;
+}
+/** Lane format separator character */
+const LANE_SEPARATOR = ':';
+/** Space character for format validation */
+const SPACE = ' ';
+/**
+ * Validation mode options
+ * @typedef {Object} ValidateLaneOptions
+ * @property {boolean} [strict=true] - When true, throws error for parent-only lanes with taxonomy.
+ *                                     When false, only warns (for existing WU validation).
+ */
+/**
+ * Validate lane format and parent existence
+ * @param {string} lane - Lane name (e.g., "Operations: Tooling" or "Operations")
+ * @param {string} configPath - Path to config file (optional, defaults to project root)
+ * @param {ValidateLaneOptions} options - Validation options
+ * @returns {{ valid: boolean, parent: string, error: string | null }}
+ */
+export function validateLaneFormat(lane, configPath = null, options = {}) {
+    const { strict = true } = options;
+    const trimmed = lane.trim();
+    // Check for multiple colons
+    const colonCount = countChar(trimmed, LANE_SEPARATOR);
+    if (colonCount > 1) {
+        throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" contains multiple colons. Expected format: "Parent: Subdomain" or "Parent"`, { lane });
+    }
+    // Check for colon
+    const colonIndex = trimmed.indexOf(LANE_SEPARATOR);
+    if (colonIndex !== -1) {
+        // Sub-lane format validation
+        // Check for space before colon
+        if (colonIndex > 0 && trimmed[colonIndex - 1] === SPACE) {
+            throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" has space before colon. Expected format: "Parent: Subdomain" (space AFTER colon only)`, { lane });
+        }
+        // Check for space after colon
+        if (colonIndex + 1 >= trimmed.length || trimmed[colonIndex + 1] !== SPACE) {
+            throw createError(ErrorCodes.INVALID_LANE, `Invalid lane format: "${lane}" is missing space after colon. Expected format: "Parent: Subdomain"`, { lane });
+        }
+        // Extract parent and subdomain (colonIndex + 2 = skip colon and space)
+        const parent = trimmed.substring(0, colonIndex).trim();
+        const subdomain = trimmed.substring(colonIndex + LANE_SEPARATOR.length + SPACE.length).trim();
+        // Validate parent exists in config
+        if (!isValidParentLane(parent, configPath)) {
+            throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${parent}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { parent, lane });
+        }
+        // Validate sub-lane exists in taxonomy
+        if (hasSubLaneTaxonomy(parent)) {
+            // Parent has taxonomy - validate sub-lane
+            if (!isValidSubLane(parent, subdomain)) {
+                const validSubLanes = getSubLanesForParent(parent);
+                throw createError(ErrorCodes.INVALID_LANE, `Unknown sub-lane: "${subdomain}" for parent lane "${parent}".\n\n` +
+                    `Valid sub-lanes: ${validSubLanes.join(', ')}`, { parent, subdomain, validSubLanes });
+            }
+        }
+        else {
+            // Parent has no taxonomy - reject sub-lane format
+            throw createError(ErrorCodes.INVALID_LANE, `Parent lane "${parent}" does not support sub-lanes. Use parent-only format or extend ${CONFIG_FILES.LANE_INFERENCE}.`, { parent, lane });
+        }
+        return { valid: true, parent, error: null };
+    }
+    else {
+        // Parent-only format
+        if (!isValidParentLane(trimmed, configPath)) {
+            throw createError(ErrorCodes.INVALID_LANE, `Unknown parent lane: "${trimmed}". Check ${CONFIG_FILES.LUMENFLOW_CONFIG} for valid lanes.`, { lane: trimmed });
+        }
+        // Block if parent has sub-lane taxonomy (sub-lane required)
+        if (hasSubLaneTaxonomy(trimmed)) {
+            const validSubLanes = getSubLanesForParent(trimmed);
+            const message = `Parent-only lane "${trimmed}" blocked. Sub-lane required. ` +
+                `Valid: ${validSubLanes.join(', ')}. ` +
+                `Format: "${trimmed}: <sublane>"`;
+            if (strict) {
+                // Strict mode (default): throw error for new WUs
+                throw createError(ErrorCodes.INVALID_LANE, message, { lane: trimmed, validSubLanes });
+            }
+            else {
+                // Non-strict mode: warn only for existing WU validation
+                console.warn(`${PREFIX} ⚠️  ${message}`);
+            }
+        }
+        return { valid: true, parent: trimmed, error: null };
+    }
+}
+/**
+ * Check if a parent lane exists in LumenFlow config
+ * @param {string} parent - Parent lane name to check
+ * @param {string} configPath - Path to config file (optional)
+ * @returns {boolean} True if parent lane exists
+ */
+function isValidParentLane(parent, configPath = null) {
+    // Determine config path
+    let resolvedConfigPath = configPath;
+    if (!resolvedConfigPath) {
+        const projectRoot = findProjectRoot();
+        resolvedConfigPath = path.join(projectRoot, CONFIG_FILES.LUMENFLOW_CONFIG);
+    }
+    // Read and parse config
+    if (!existsSync(resolvedConfigPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Config file not found: ${resolvedConfigPath}`, {
+            path: resolvedConfigPath,
+        });
+    }
+    const configContent = readFileSync(resolvedConfigPath, { encoding: 'utf-8' });
+    const config = yaml.load(configContent);
+    // Extract all lane names - handle both flat array and nested engineering/business formats
+    const allLanes = [];
+    if (config.lanes) {
+        if (Array.isArray(config.lanes)) {
+            // Flat array format: lanes: [{name: "Core"}, {name: "CLI"}, ...]
+            allLanes.push(...config.lanes.map((l) => l.name));
+        }
+        else {
+            // Nested format: lanes: {engineering: [...], business: [...]}
+            if (config.lanes.engineering) {
+                allLanes.push(...config.lanes.engineering.map((l) => l.name));
+            }
+            if (config.lanes.business) {
+                allLanes.push(...config.lanes.business.map((l) => l.name));
+            }
+        }
+    }
+    // Case-insensitive comparison
+    const normalizedParent = parent.toLowerCase().trim();
+    return allLanes.some((lane) => lane.toLowerCase().trim() === normalizedParent);
+}
+/**
+ * Check if a lane is free (no in_progress WU currently in that lane)
+ * @param {string} statusPath - Path to status.md
+ * @param {string} lane - Lane name (e.g., "Operations", "Intelligence")
+ * @param {string} wuid - WU ID being claimed (e.g., "WU-419")
+ * @returns {{ free: boolean, occupiedBy: string | null, error: string | null }}
+ */
+export function checkLaneFree(statusPath, lane, wuid) {
+    /** Section heading marker for H2 headings */
+    const SECTION_HEADING_PREFIX = '## ';
+    try {
+        // Read status.md
+        if (!existsSync(statusPath)) {
+            return { free: false, occupiedBy: null, error: `status.md not found: ${statusPath}` };
+        }
+        const content = readFileSync(statusPath, { encoding: 'utf-8' });
+        const lines = content.split(/\r?\n/);
+        // Find "## In Progress" section
+        const inProgressIdx = lines.findIndex((l) => isInProgressHeader(l));
+        if (inProgressIdx === -1) {
+            return {
+                free: false,
+                occupiedBy: null,
+                error: 'Could not find "## In Progress" section in status.md',
+            };
+        }
+        // Find end of In Progress section (next ## heading or end of file)
+        let endIdx = lines
+            .slice(inProgressIdx + 1)
+            .findIndex((l) => l.startsWith(SECTION_HEADING_PREFIX));
+        if (endIdx === -1)
+            endIdx = lines.length - inProgressIdx - 1;
+        else
+            endIdx = inProgressIdx + 1 + endIdx;
+        // Extract WU links from In Progress section
+        const section = lines.slice(inProgressIdx + 1, endIdx).join(STRING_LITERALS.NEWLINE);
+        // Check for "No items" marker
+        if (section.includes(NO_ITEMS_MARKER)) {
+            return { free: true, occupiedBy: null, error: null };
+        }
+        // Extract WU IDs from links like [WU-334 — Title](wu/WU-334.yaml)
+        WU_LINK_PATTERN.lastIndex = 0; // Reset global regex state
+        const matches = [...section.matchAll(WU_LINK_PATTERN)];
+        if (matches.length === 0) {
+            return { free: true, occupiedBy: null, error: null };
+        }
+        // Get project root from statusPath (docs/04-operations/tasks/status.md)
+        // Use path.dirname 4 times: status.md -> tasks -> 04-operations -> docs -> root
+        const projectRoot = path.dirname(path.dirname(path.dirname(path.dirname(statusPath))));
+        for (const match of matches) {
+            const activeWuid = match[1]; // e.g., "WU-334"
+            // Skip if it's the same WU we're trying to claim (shouldn't happen, but be safe)
+            if (activeWuid === wuid)
+                continue;
+            // Use WU_PATHS to build the path consistently
+            const wuPath = path.join(projectRoot, WU_PATHS.WU(activeWuid));
+            if (!existsSync(wuPath)) {
+                console.warn(`${PREFIX} Warning: ${activeWuid} referenced in status.md but ${wuPath} not found`);
+                continue;
+            }
+            try {
+                const wuContent = readFileSync(wuPath, { encoding: 'utf-8' });
+                const wuDoc = yaml.load(wuContent);
+                if (!wuDoc || !wuDoc.lane) {
+                    console.warn(`${PREFIX} Warning: ${activeWuid} has no lane field`);
+                    continue;
+                }
+                // Normalize lane names for comparison (case-insensitive, trim whitespace)
+                const activeLane = wuDoc.lane.toString().trim().toLowerCase();
+                const targetLane = lane.toString().trim().toLowerCase();
+                if (activeLane === targetLane) {
+                    // Lane is occupied!
+                    return { free: false, occupiedBy: activeWuid, error: null };
+                }
+            }
+            catch (e) {
+                const errMessage = e instanceof Error ? e.message : String(e);
+                console.warn(`${PREFIX} Warning: Failed to parse ${activeWuid} YAML: ${errMessage}`);
+                continue;
+            }
+        }
+        // No WUs found in target lane
+        return { free: true, occupiedBy: null, error: null };
+    }
+    catch (error) {
+        const errMessage = error instanceof Error ? error.message : String(error);
+        return { free: false, occupiedBy: null, error: `Unexpected error: ${errMessage}` };
+    }
+}

package/dist/lane-inference.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lane Inference Module (WU-906)
+ *
+ * Provides automated sub-lane suggestion based on WU code_paths and description.
+ * Uses config-driven pattern matching with confidence scoring.
+ *
+ * Inference is suggestion only (not enforcement). Track accuracy for future tuning.
+ *
+ * Uses industry-standard libraries:
+ * - micromatch for robust glob matching (28x faster than minimatch)
+ * - yaml for modern YAML parsing (actively maintained, YAML 1.2 compliant)
+ */
+import { extractParent } from './lane-checker.js';
+/**
+ * Infer sub-lane from WU code paths and description
+ * @param {string[]} codePaths - Array of file paths modified/created by this WU
+ * @param {string} description - WU description/title text
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {{ lane: string, confidence: number }} Suggested sub-lane and confidence (0-100)
+ * @throws {Error} If config cannot be loaded
+ */
+export declare function inferSubLane(codePaths: any, description: any, configPath?: any): {
+    lane: any;
+    confidence: any;
+};
+/**
+ * Get all valid sub-lanes from config
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {string[]} Array of all sub-lane names (format: "Parent: Subdomain")
+ */
+export declare function getAllSubLanes(configPath?: any): any[];
+/**
+ * Get valid sub-lanes for a specific parent lane
+ * @param {string} parent - Parent lane name (e.g., "Operations", "Core Systems")
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {string[]} Array of sub-lane names for that parent (e.g., ["Tooling", "CI/CD", ...])
+ */
+export declare function getSubLanesForParent(parent: any, configPath?: any): string[];
+export { extractParent };

package/dist/lane-inference.js

@@ -0,0 +1,195 @@
+/**
+ * Lane Inference Module (WU-906)
+ *
+ * Provides automated sub-lane suggestion based on WU code_paths and description.
+ * Uses config-driven pattern matching with confidence scoring.
+ *
+ * Inference is suggestion only (not enforcement). Track accuracy for future tuning.
+ *
+ * Uses industry-standard libraries:
+ * - micromatch for robust glob matching (28x faster than minimatch)
+ * - yaml for modern YAML parsing (actively maintained, YAML 1.2 compliant)
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml'; // Modern YAML library (not js-yaml)
+import micromatch from 'micromatch'; // Industry-standard glob matching (CommonJS)
+import { extractParent } from './lane-checker.js'; // Shared utility (WU-1137: consolidation)
+import { createError, ErrorCodes } from './error-handler.js';
+import { WEIGHTS, CONFIDENCE } from './wu-validation-constants.js';
+/**
+ * Load lane inference config from project root
+ * @param {string|null} configPath - Optional path to config file (defaults to project root)
+ * @returns {object} Parsed config object
+ * @throws {Error} If config file not found or YAML parsing fails
+ */
+function loadConfig(configPath = null) {
+    if (!configPath) {
+        // Default to project root
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const projectRoot = path.resolve(currentDir, '../..');
+        configPath = path.join(projectRoot, '.lumenflow.lane-inference.yaml');
+    }
+    if (!existsSync(configPath)) {
+        throw createError(ErrorCodes.FILE_NOT_FOUND, `Lane inference config not found: ${configPath}\n\nRun WU-906 to create infrastructure files.`, { path: configPath });
+    }
+    try {
+        const configContent = readFileSync(configPath, { encoding: 'utf-8' });
+        return YAML.parse(configContent);
+    }
+    catch (err) {
+        throw createError(ErrorCodes.YAML_PARSE_ERROR, `Failed to parse lane inference config: ${configPath}\n\n${err.message}\n\n` +
+            `Ensure config is valid YAML.`, { path: configPath, originalError: err.message });
+    }
+}
+/**
+ * Check if a code path matches a glob pattern using micromatch
+ * @param {string} codePath - Actual code path from WU
+ * @param {string} pattern - Glob pattern from config (e.g., "tools/**", "*.ts")
+ * @returns {boolean} True if path matches pattern
+ */
+function matchesPattern(codePath, pattern) {
+    // Use micromatch for robust, fast glob matching (industry standard)
+    // 28x faster than minimatch, used by webpack/babel/jest
+    return micromatch.isMatch(codePath, pattern, { nocase: true });
+}
+/**
+ * Check if description contains a keyword (case-insensitive match)
+ * @param {string} description - WU description text
+ * @param {string} keyword - Keyword to search for
+ * @returns {boolean} True if keyword found in description
+ */
+function containsKeyword(description, keyword) {
+    const normalizedDesc = description.toLowerCase().trim();
+    const normalizedKeyword = keyword.toLowerCase().trim();
+    // Simple substring match (sufficient for keyword detection)
+    return normalizedDesc.includes(normalizedKeyword);
+}
+/**
+ * Calculate confidence score for a sub-lane match
+ *
+ * WU-2438: Changed from percentage-based to absolute scoring.
+ * Previously, confidence = (score / maxPossibleScore) * 100, which penalized
+ * lanes with more patterns/keywords even when they had MORE matches.
+ *
+ * Now, confidence = raw score, so lanes with more matches win.
+ * This is more intuitive: 4 signals beats 1 signal, regardless of config size.
+ *
+ * @param {string[]} codePaths - WU code paths
+ * @param {string} description - WU description
+ * @param {object} subLaneConfig - Sub-lane config (code_paths, keywords)
+ * @returns {number} Confidence score (raw score, higher = better match)
+ */
+function calculateConfidence(codePaths, description, subLaneConfig) {
+    let score = 0;
+    // Score code path matches
+    const patterns = subLaneConfig.code_paths || [];
+    for (const pattern of patterns) {
+        const hasMatch = codePaths.some((cp) => matchesPattern(cp, pattern));
+        if (hasMatch) {
+            score += WEIGHTS.CODE_PATH_MATCH;
+        }
+    }
+    // Score keyword matches
+    const keywords = subLaneConfig.keywords || [];
+    for (const keyword of keywords) {
+        if (containsKeyword(description, keyword)) {
+            score += WEIGHTS.KEYWORD_MATCH;
+        }
+    }
+    return score;
+}
+/**
+ * Infer sub-lane from WU code paths and description
+ * @param {string[]} codePaths - Array of file paths modified/created by this WU
+ * @param {string} description - WU description/title text
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {{ lane: string, confidence: number }} Suggested sub-lane and confidence (0-100)
+ * @throws {Error} If config cannot be loaded
+ */
+export function inferSubLane(codePaths, description, configPath = null) {
+    // Validate inputs
+    if (!Array.isArray(codePaths)) {
+        throw createError(ErrorCodes.VALIDATION_ERROR, 'codePaths must be an array of strings', {
+            codePaths,
+            type: typeof codePaths,
+        });
+    }
+    if (typeof description !== 'string') {
+        throw createError(ErrorCodes.VALIDATION_ERROR, 'description must be a string', {
+            description,
+            type: typeof description,
+        });
+    }
+    // Load config
+    const config = loadConfig(configPath);
+    // Score all sub-lanes
+    const scores = [];
+    for (const [parentLane, subLanes] of Object.entries(config)) {
+        for (const [subLane, subLaneConfig] of Object.entries(subLanes)) {
+            const confidence = calculateConfidence(codePaths, description, subLaneConfig);
+            const fullLaneName = `${parentLane}: ${subLane}`;
+            scores.push({
+                lane: fullLaneName,
+                confidence,
+                parent: parentLane,
+                subLane,
+            });
+        }
+    }
+    // Sort by confidence (descending)
+    scores.sort((a, b) => b.confidence - a.confidence);
+    // Return highest scoring sub-lane
+    const best = scores[0];
+    if (!best || best.confidence < CONFIDENCE.THRESHOLD) {
+        // No good matches found, return parent-only suggestion
+        // This shouldn't happen with CONFIDENCE.THRESHOLD=0, but keep for future tuning
+        return {
+            lane: best ? best.parent : 'Operations', // Default to Operations if all else fails
+            confidence: CONFIDENCE.MIN,
+        };
+    }
+    return {
+        lane: best.lane,
+        confidence: best.confidence,
+    };
+}
+/**
+ * Get all valid sub-lanes from config
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {string[]} Array of all sub-lane names (format: "Parent: Subdomain")
+ */
+export function getAllSubLanes(configPath = null) {
+    const config = loadConfig(configPath);
+    const subLanes = [];
+    for (const [parentLane, subLaneConfigs] of Object.entries(config)) {
+        for (const subLane of Object.keys(subLaneConfigs)) {
+            subLanes.push(`${parentLane}: ${subLane}`);
+        }
+    }
+    return subLanes.sort();
+}
+/**
+ * Get valid sub-lanes for a specific parent lane
+ * @param {string} parent - Parent lane name (e.g., "Operations", "Core Systems")
+ * @param {string|null} configPath - Optional path to config file
+ * @returns {string[]} Array of sub-lane names for that parent (e.g., ["Tooling", "CI/CD", ...])
+ */
+export function getSubLanesForParent(parent, configPath = null) {
+    const config = loadConfig(configPath);
+    // Find parent key (case-insensitive)
+    const normalizedParent = parent.trim().toLowerCase();
+    const parentKey = Object.keys(config).find((key) => key.toLowerCase().trim() === normalizedParent);
+    if (!parentKey) {
+        return [];
+    }
+    // Return sub-lane names for this parent
+    const subLanes = config[parentKey];
+    if (!subLanes || typeof subLanes !== 'object') {
+        return [];
+    }
+    return Object.keys(subLanes);
+}
+// Re-export extractParent from lane-checker for backward compatibility (WU-1137: consolidation)
+export { extractParent };