@lumenflow/core 1.0.0 → 1.3.2

package/dist/wu-done-validators.d.ts

@@ -1,411 +1,15 @@
 #!/usr/bin/env node
 /**
- * Validation functions for wu:done workflow
- * Extracted from wu-done.mjs (WU-1215 refactoring)
- */
-import { execSync as execSyncImport } from 'node:child_process';
-import { validateAutomatedTestRequirement } from './manual-test-validator.js';
-import { validatePreflight } from './wu-preflight-validators.js';
-/**
- * Validates command-line inputs and WU ID format
- * @param {string[]} argv - Process arguments
- * @returns {{ args: object, id: string }} Parsed args and validated WU ID
- */
-export declare function validateInputs(argv: any): {
-    args: import("commander").OptionValues;
-    id: any;
-};
-/**
- * Read WU YAML preferring worktree version over main version
- *
- * WU-1584 Fix #4: Added diagnostic logging to confirm which YAML file is being
- * read for code_paths validation. This helps debug issues where worktree YAML
- * differs from main checkout YAML.
- *
- * @param {string} id - WU ID
- * @param {string|null} worktreePath - Worktree path (null if branch-only mode)
- * @param {string} mainWUPath - Path to WU YAML in main checkout
- * @returns {object} Parsed WU document
- */
-export declare function readWUPreferWorktree(id: any, worktreePath: any, mainWUPath: any): any;
-/**
- * Detect if currently running inside a worktree
- * Checks for .git file (not directory) which indicates a worktree
- * @returns {string|null} Current directory path if inside worktree, null otherwise
- */
-export declare function detectCurrentWorktree(): string;
-/**
- * Resolve worktree path from WU YAML
- * Originally implemented in WU-1226, extracted to validators module in WU-1215
- * Priority:
- * 1. Read worktree_path field (set at claim time, immune to lane field changes)
- * 2. Fall back to calculating from lane field (for old WUs without worktree_path)
- * 3. Use git worktree list to find actual path (defensive fallback)
- * @param {object} doc - WU YAML document
- * @returns {Promise<string|null>} - Worktree path or null if not found
- */
-export declare function defaultWorktreeFrom(doc: any): Promise<any>;
-/**
- * Detect workspace mode from WU YAML
- * @param {object} doc - WU YAML document
- * @returns {'worktree' | 'branch-only'}
- */
-export declare function detectWorkspaceMode(doc: any): string;
-/**
- * Calculate lane branch name from WU YAML
- * @param {object} doc - WU YAML document
- * @returns {string|null} Lane branch name (e.g., lane/operations-tooling/wu-1215)
- */
-export declare function defaultBranchFrom(doc: any): string;
-/**
- * Check if a branch exists
- * @param {string} branch - Branch name to check
- * @returns {Promise<boolean>} True if branch exists
- */
-export declare function branchExists(branch: any): Promise<boolean>;
-/**
- * Detect workspace mode and calculate all relevant paths
- * @param {string} id - WU ID
- * @param {object} args - Parsed command-line arguments
- * @returns {Promise<object>} Object containing paths, mode info, and WU document
- */
-export declare function detectModeAndPaths(id: any, args: any): Promise<{
-    WU_PATH: string;
-    STATUS_PATH: string;
-    BACKLOG_PATH: string;
-    STAMPS_DIR: string;
-    docMain: any;
-    workspaceMode: string;
-    isBranchOnly: boolean;
-    derivedWorktree: any;
-    docForValidation: any;
-    isDocsOnly: boolean;
-}>;
-/**
- * Generate commit message for WU completion
- * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
- * @param {string} id - WU ID (e.g., "WU-1215")
- * @param {string} title - WU title
- * @param {number} maxLength - Maximum commit header length from commitlint config
- * @returns {string} Formatted commit message
- * @throws {Error} If generated message exceeds maxLength
- */
-export declare function generateCommitMessage(id: any, title: any, maxLength?: number): string;
-/**
- * Validate that required metadata files exist before updating
- * WU-1275: Fail fast before mutations to prevent partial state
- *
- * @param {object} params - Parameters object
- * @param {string} params.statusPath - Path to status.md file
- * @param {string} params.backlogPath - Path to backlog.md file
- * @throws {WUError} If any required file is missing
- */
-export declare function validateMetadataFilesExist({ statusPath, backlogPath }: {
-    statusPath: any;
-    backlogPath: any;
-}): void;
-/**
- * Update all metadata files for WU completion
- * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
- * WU-1572: Made async for WUStateStore integration
- * @param {object} params - Parameters object
- * @param {string} params.id - WU ID
- * @param {string} params.title - WU title
- * @param {object} params.doc - WU YAML document to update
- * @param {string} params.wuPath - Path to WU YAML file
- * @param {string} params.statusPath - Path to status.md file
- * @param {string} params.backlogPath - Path to backlog.md file
- */
-export declare function updateMetadataFiles({ id, title, doc, wuPath, statusPath, backlogPath }: {
-    id: any;
-    title: any;
-    doc: any;
-    wuPath: any;
-    statusPath: any;
-    backlogPath: any;
-}): Promise<void>;
-/**
- * Collect metadata updates to a transaction (WU-1369: Atomic pattern)
- *
- * This is the atomic version of updateMetadataFiles.
- * Instead of writing files immediately, it collects all changes
- * into a WUTransaction object for atomic commit.
- *
- * Usage:
- * ```js
- * const tx = new WUTransaction(id);
- * collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction: tx });
- * // All changes are now in tx.pendingWrites
- * // Validate, then commit or abort
- * tx.commit();
- * ```
- *
- * @param {object} params - Parameters object
- * @param {string} params.id - WU ID
- * @param {string} params.title - WU title
- * @param {object} params.doc - WU YAML document to update (will be mutated)
- * @param {string} params.wuPath - Path to WU YAML file
- * @param {string} params.statusPath - Path to status.md file
- * @param {string} params.backlogPath - Path to backlog.md file
- * @param {string} params.stampPath - Path to stamp file
- * @param {WUTransaction} params.transaction - Transaction to add writes to
- */
-export declare function collectMetadataToTransaction({ id, title, doc, wuPath, statusPath, backlogPath, stampPath, transaction, }: {
-    id: any;
-    title: any;
-    doc: any;
-    wuPath: any;
-    statusPath: any;
-    backlogPath: any;
-    stampPath: any;
-    transaction: any;
-}): Promise<void>;
-/**
- * Stage and format metadata files
- * Extracted from wu-done.mjs (WU-1215 Phase 2 Extraction #1 Helper)
- * @param {object} params - Parameters object
- * @param {string} params.id - WU ID (for error reporting)
- * @param {string} params.wuPath - Path to WU YAML file
- * @param {string} params.statusPath - Path to status.md file
- * @param {string} params.backlogPath - Path to backlog.md file
- * @param {string} params.stampsDir - Path to stamps directory
- * @throws {Error} If formatting fails
- */
-export declare function stageAndFormatMetadata({ id, wuPath, statusPath, backlogPath, stampsDir }: {
-    id: any;
-    wuPath: any;
-    statusPath: any;
-    backlogPath: any;
-    stampsDir: any;
-}): Promise<void>;
-/**
- * Run cleanup operations after successful merge
- * Removes worktree and optionally deletes lane branch
- * Extracted from wu-done.mjs (WU-1215 Phase 1 Extraction #3)
- *
- * WU-2241: Now wrapped with cleanup lock to prevent concurrent collision
- *          when multiple wu:done commands complete simultaneously.
- *
- * @param {object} docMain - WU YAML document
- * @param {object} args - Parsed CLI arguments
- */
-export declare function runCleanup(docMain: any, args: any): Promise<void>;
-/**
- * WU-1351: Validate code_paths files exist on main branch
- *
- * Prevents false completions by ensuring all code_paths entries
- * actually exist on the target branch (main or lane branch).
- *
- * This guards against:
- * - Stamps being created for WUs where code never merged
- * - Metadata becoming desynchronized from actual code
- *
- * @param {object} doc - WU YAML document
- * @param {string} id - WU ID
- * @param {ValidateCodePathsExistOptions} options - Options
- * @returns {Promise<{ valid: boolean, errors: string[], missing: string[] }>} Validation result
- */
-export interface ValidateCodePathsExistOptions {
-    /** Branch to check files against (default: 'main') */
-    targetBranch?: string;
-    /** Worktree path for worktree mode */
-    worktreePath?: string | null;
-}
-export declare function validateCodePathsExist(doc: any, id: any, options?: ValidateCodePathsExistOptions): Promise<{
-    valid: boolean;
-    errors: any[];
-    missing: any[];
-}>;
-/**
- * Validate WU spec completeness (WU-1162, WU-1280)
- *
- * Ensures WU specifications are complete before allowing wu:done to proceed.
- * Prevents placeholder WUs from being marked as done.
- *
- * WU-1280: Added tests array validation to catch empty tests.manual early
- * (previously only validated in pre-commit hook, causing late failures).
- *
- * @param {object} doc - WU YAML document
- * @param {string} id - WU ID
- * @returns {{ valid: boolean, errors: string[] }} Validation result
- */
-export declare function validateSpecCompleteness(doc: any, _id: any): {
-    valid: boolean;
-    errors: any[];
-};
-export { validateAutomatedTestRequirement };
-/**
- * WU-1617: Post-mutation validation for wu:done
- *
- * Validates that metadata files written by tx.commit() are valid:
- * 1. WU YAML has completed_at field with valid ISO datetime
- * 2. WU YAML has locked: true
- * 3. Stamp file exists
- *
- * This catches schema violations that could persist silently after
- * transaction commit.
- *
- * @param {object} params - Validation parameters
- * @param {string} params.id - WU ID
- * @param {string} params.wuPath - Path to WU YAML file
- * @param {string} params.stampPath - Path to stamp file
- * @returns {{ valid: boolean, errors: string[] }} Validation result
- */
-export declare function validatePostMutation({ id, wuPath, stampPath }: {
-    id: any;
-    wuPath: any;
-    stampPath: any;
-}): {
-    valid: boolean;
-    errors: any[];
-};
-/**
- * WU-1781: Build preflight error message with actionable guidance
- *
- * Creates a formatted error message for preflight validation failures,
- * including specific guidance for stamp-status mismatch errors.
- *
- * @param {string} id - WU ID being completed
- * @param {string[]} errors - List of validation errors
- * @returns {string} Formatted error message with fix options
- */
-export declare function buildPreflightErrorMessage(id: any, errors: any): string;
-/**
- * WU-1805: Execute preflight code_paths and test_paths validation
- *
- * Validates that all code_paths and test file paths specified in the WU YAML
- * actually exist before running gates. This catches YAML mismatches early,
- * saving time compared to discovering issues after a full gate run.
- *
- * This is run as the FIRST validation step in wu:done, before gates.
- *
- * @param {string} id - WU ID being completed
- * @param {object} paths - Path options
- * @param {string} paths.rootDir - Root directory for YAML lookup
- * @param {string} paths.worktreePath - Worktree path for file existence checks
- * @param {ExecutePreflightCodePathValidationOptions} options - Options for testing
- * @returns {Promise<{ valid: boolean, errors: string[], missingCodePaths: string[], missingTestPaths: string[], abortedBeforeGates: boolean }>}
- */
-interface ExecutePreflightCodePathValidationOptions {
-    /** Override validatePreflight for testing */
-    validatePreflightFn?: typeof validatePreflight;
-}
-export declare function executePreflightCodePathValidation(id: any, paths: any, options?: ExecutePreflightCodePathValidationOptions): Promise<{
-    valid: boolean;
-    errors: any[];
-    missingCodePaths: any[];
-    missingTestPaths: any[];
-    abortedBeforeGates: boolean;
-}>;
-/**
- * WU-1805: Build preflight code_paths error message with actionable guidance
- *
- * Creates a formatted error message for preflight code_paths validation failures,
- * including specific guidance for fixing missing files.
- *
- * @param {string} id - WU ID being completed
- * @param {object} result - Preflight validation result
- * @param {string[]} result.errors - List of validation errors
- * @param {string[]} result.missingCodePaths - Missing code_paths files
- * @param {string[]} result.missingTestPaths - Missing test files
- * @returns {string} Formatted error message with fix options
- */
-export declare function buildPreflightCodePathErrorMessage(id: any, result: any): string;
-/**
- * WU-1781: Run tasks:validate as preflight check before any git operations
- *
- * This prevents deadlocks where wu:done completes merge but then pre-push
- * fails on tasks:validate, leaving local main ahead of origin.
- *
- * @param {string} id - WU ID being completed
- * @param {ExecSyncOverrideOptions} options - Options for testing
- * @returns {{ valid: boolean, errors: string[], abortedBeforeMerge: boolean, localMainModified: boolean, hasStampStatusError: boolean }}
- */
-interface ExecSyncOverrideOptions {
-    /** Override execSync for testing (default: child_process.execSync) */
-    execSyncFn?: typeof execSyncImport;
-}
-export declare function runPreflightTasksValidation(id: any, options?: ExecSyncOverrideOptions): {
-    valid: boolean;
-    errors: any;
-    abortedBeforeMerge: boolean;
-    localMainModified: boolean;
-    hasStampStatusError: any;
-};
-/**
- * WU-2308: Validate all pre-commit hooks with worktree context
- *
- * Runs pre-commit validation gates from the worktree directory when provided.
- * This ensures that dependency audits check the worktree's dependencies
- * (with any fixes) rather than main's potentially stale dependencies.
- *
- * @param {string} id - WU ID being completed
- * @param {string|null} worktreePath - Path to worktree (null = run from current dir)
- * @param {ExecSyncOverrideOptions} options - Options for testing
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export declare function validateAllPreCommitHooks(id: any, worktreePath?: any, options?: ExecSyncOverrideOptions): {
-    valid: boolean;
-    errors: any[];
-};
-/**
- * WU-2242: Validate that test_paths is required for non-doc WUs
- *
- * Enforces that WUs with code changes (non-documentation types with code_paths
- * that contain actual code) have at least one test path specified.
- *
- * Returns valid: true in the following cases:
- * - WU type is 'documentation' or 'process'
- * - code_paths is empty or only contains documentation paths
- * - tests object has at least one test (unit, e2e, manual, or integration)
- *
- * @param {object} wu - WU document
- * @param {string} wu.id - WU ID
- * @param {string} wu.type - WU type (feature, bug, documentation, etc.)
- * @param {object} wu.tests - Tests object with unit, e2e, manual, integration arrays
- * @param {string[]} wu.code_paths - Array of code paths
- * @returns {{ valid: boolean, error?: string }}
- */
-export declare function validateTestPathsRequired(wu: any): {
-    valid: boolean;
-    error?: undefined;
-} | {
-    valid: boolean;
-    error: string;
-};
-/**
- * WU-2310: Validate type vs code_paths at preflight (before transaction starts).
- *
- * This catches the documentation WU + code file mismatch BEFORE any transaction
- * begins, preventing the scenario where:
- * 1. Transaction commits files (stamp, status, backlog)
- * 2. Git commit fails due to pre-commit hook (gateDocsOnlyPathEnforcement)
- * 3. Files are left in inconsistent state
- *
- * By running this validation at preflight, we fail fast with a clear error
- * message before any file mutations occur.
- *
- * @param {object} wu - WU document
- * @param {string} wu.id - WU ID
- * @param {string} wu.type - WU type (documentation, feature, bug, etc.)
- * @param {string[]} [wu.code_paths] - Array of code paths
- * @returns {{ valid: boolean, errors: string[], blockedPaths: string[], abortedBeforeTransaction: boolean }}
- */
-export declare function validateTypeVsCodePathsPreflight(wu: any): {
-    valid: boolean;
-    errors: any[];
-    blockedPaths: any[];
-    abortedBeforeTransaction: boolean;
-};
-/**
- * WU-2310: Build error message for type vs code_paths preflight failure.
- *
- * Provides actionable guidance for fixing the mismatch:
- * 1. Change WU type to 'engineering' or appropriate type
- * 2. Update code_paths to only include documentation files
- *
- * @param {string} id - WU ID
- * @param {string[]} blockedPaths - Paths that would be blocked
- * @returns {string} Formatted error message
- */
-export declare function buildTypeVsCodePathsErrorMessage(id: any, blockedPaths: any): string;
+ * wu:done validators - aggregated exports
+ *
+ * WU-1049: Split validators into focused modules while preserving exports.
+ */
+export { validateInputs } from './wu-done-inputs.js';
+export { readWUPreferWorktree, detectCurrentWorktree, defaultWorktreeFrom, detectWorkspaceMode, defaultBranchFrom, branchExists, detectModeAndPaths, } from './wu-done-paths.js';
+export { generateCommitMessage, validateMetadataFilesExist, updateMetadataFiles, collectMetadataToTransaction, stageAndFormatMetadata, } from './wu-done-metadata.js';
+export { runCleanup } from './wu-done-cleanup.js';
+export { applyExposureDefaults, validateCodePathsExist, validateSpecCompleteness, validatePostMutation, validateTestPathsRequired, validateTypeVsCodePathsPreflight, buildTypeVsCodePathsErrorMessage, } from './wu-done-validation.js';
+export { buildPreflightErrorMessage, executePreflightCodePathValidation, buildPreflightCodePathErrorMessage, runPreflightTasksValidation, validateAllPreCommitHooks, } from './wu-done-preflight.js';
+export { validateAutomatedTestRequirement } from './manual-test-validator.js';
+export type { ValidateCodePathsExistOptions } from './wu-done-validation.js';
+export type { ExecutePreflightCodePathValidationOptions, ExecSyncOverrideOptions, } from './wu-done-preflight.js';