@lumenflow/core 3.2.0 → 3.2.1

package/dist/lumenflow-home.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Environment variable name for LumenFlow home directory
+ */
+export declare const LUMENFLOW_HOME_ENV = "LUMENFLOW_HOME";
+/**
+ * Default LumenFlow home directory name
+ */
+export declare const DEFAULT_LUMENFLOW_DIR = ".lumenflow";
+/**
+ * Plans subdirectory name
+ */
+export declare const PLANS_SUBDIR = "plans";
+/**
+ * Custom protocol for external LumenFlow paths
+ */
+export declare const LUMENFLOW_PROTOCOL = "lumenflow://";
+/**
+ * Environment variable prefix for spec_refs
+ */
+export declare const LUMENFLOW_HOME_VAR_PREFIX = "$LUMENFLOW_HOME";
+/**
+ * Get the LumenFlow home directory path
+ *
+ * Resolution order:
+ * 1. $LUMENFLOW_HOME environment variable (with ~ expansion)
+ * 2. ~/.lumenflow/ default
+ *
+ * @returns {string} Absolute path to LumenFlow home directory
+ *
+ * @example
+ * // With LUMENFLOW_HOME=/custom/path
+ * getLumenflowHome() // '/custom/path'
+ *
+ * @example
+ * // With LUMENFLOW_HOME=~/.custom-lumenflow
+ * getLumenflowHome() // '/home/user/.custom-lumenflow'
+ *
+ * @example
+ * // Without LUMENFLOW_HOME set
+ * getLumenflowHome() // '/home/user/.lumenflow'
+ */
+export declare function getLumenflowHome(): string;
+/**
+ * Get the plans directory path
+ *
+ * Plans are stored in $LUMENFLOW_HOME/plans/
+ *
+ * @returns {string} Absolute path to plans directory
+ *
+ * @example
+ * getPlansDir() // '/home/user/.lumenflow/plans'
+ */
+export declare function getPlansDir(): string;
+/**
+ * Check if a path is an external (non-repo) path
+ *
+ * External paths include:
+ * - Paths starting with ~/
+ * - Paths starting with $LUMENFLOW_HOME
+ * - Paths using lumenflow:// protocol
+ * - Absolute paths (starting with /)
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is external
+ *
+ * @example
+ * isExternalPath('~/.lumenflow/plans/plan.md') // true
+ * isExternalPath('$LUMENFLOW_HOME/plans/plan.md') // true
+ * isExternalPath('lumenflow://plans/plan.md') // true
+ * isExternalPath('/home/user/.lumenflow/plans/plan.md') // true
+ * isExternalPath('docs/04-operations/plans/plan.md') // false
+ */
+export declare function isExternalPath(path: string): boolean;
+/**
+ * Normalize a spec_ref path by expanding variables and protocols
+ *
+ * Expands:
+ * - lumenflow://path -> $LUMENFLOW_HOME/path
+ * - ~/path -> /home/user/path
+ * - $LUMENFLOW_HOME/path -> actual LUMENFLOW_HOME value
+ *
+ * Repo-relative paths are returned unchanged.
+ *
+ * @param {string} specRef - Spec reference path
+ * @returns {string} Normalized absolute path or unchanged relative path
+ *
+ * @example
+ * normalizeSpecRef('lumenflow://plans/WU-1062-plan.md')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ *
+ * @example
+ * normalizeSpecRef('docs/04-operations/plans/plan.md')
+ * // 'docs/04-operations/plans/plan.md' (unchanged)
+ */
+export declare function normalizeSpecRef(specRef: string): string;
+/**
+ * Get the full path for a plan file given a WU ID
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Full path to the plan file
+ *
+ * @example
+ * getPlanPath('WU-1062')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ */
+export declare function getPlanPath(wuId: string): string;
+/**
+ * Get the lumenflow:// protocol reference for a plan
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Protocol reference (e.g., 'lumenflow://plans/WU-1062-plan.md')
+ *
+ * @example
+ * getPlanProtocolRef('WU-1062')
+ * // 'lumenflow://plans/WU-1062-plan.md'
+ */
+export declare function getPlanProtocolRef(wuId: string): string;
+//# sourceMappingURL=lumenflow-home.d.ts.map

package/dist/lumenflow-home.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lumenflow-home.d.ts","sourceRoot":"","sources":["../src/lumenflow-home.ts"],"names":[],"mappings":"AAqBA;;GAEG;AACH,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,YAAY,UAAU,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AAEjD;;GAEG;AACH,eAAO,MAAM,yBAAyB,oBAAoB,CAAC;AA4B3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CASzC;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAsBpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAwBxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGvD"}

package/dist/lumenflow-home.js

@@ -0,0 +1,214 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * LumenFlow Home Directory Resolution
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for resolving the $LUMENFLOW_HOME directory and related paths.
+ * Plans are stored externally in $LUMENFLOW_HOME/plans/ instead of in the repo.
+ *
+ * Default: ~/.lumenflow/
+ * Override: Set $LUMENFLOW_HOME environment variable
+ *
+ * @module
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { PATH_LITERALS, PATH_SLICE_LENGTHS, STRING_LITERALS } from './wu-constants.js';
+/**
+ * Environment variable name for LumenFlow home directory
+ */
+export const LUMENFLOW_HOME_ENV = 'LUMENFLOW_HOME';
+/**
+ * Default LumenFlow home directory name
+ */
+export const DEFAULT_LUMENFLOW_DIR = '.lumenflow';
+/**
+ * Plans subdirectory name
+ */
+export const PLANS_SUBDIR = 'plans';
+/**
+ * Custom protocol for external LumenFlow paths
+ */
+export const LUMENFLOW_PROTOCOL = 'lumenflow://';
+/**
+ * Environment variable prefix for spec_refs
+ */
+export const LUMENFLOW_HOME_VAR_PREFIX = '$LUMENFLOW_HOME';
+/**
+ * Expand ~ to user's home directory
+ *
+ * @param {string} path - Path that may contain ~
+ * @returns {string} Expanded path
+ */
+function expandTilde(path) {
+    if (path.startsWith(PATH_LITERALS.TILDE_PREFIX)) {
+        return join(homedir(), path.slice(PATH_SLICE_LENGTHS.TILDE_PREFIX_LENGTH));
+    }
+    if (path === PATH_LITERALS.TILDE) {
+        return homedir();
+    }
+    return path;
+}
+/**
+ * Remove trailing slashes from path
+ *
+ * @param {string} path - Path that may have trailing slashes
+ * @returns {string} Path without trailing slashes
+ */
+function removeTrailingSlash(path) {
+    return path.replace(PATH_LITERALS.TRAILING_SLASH_REGEX, STRING_LITERALS.EMPTY);
+}
+/**
+ * Get the LumenFlow home directory path
+ *
+ * Resolution order:
+ * 1. $LUMENFLOW_HOME environment variable (with ~ expansion)
+ * 2. ~/.lumenflow/ default
+ *
+ * @returns {string} Absolute path to LumenFlow home directory
+ *
+ * @example
+ * // With LUMENFLOW_HOME=/custom/path
+ * getLumenflowHome() // '/custom/path'
+ *
+ * @example
+ * // With LUMENFLOW_HOME=~/.custom-lumenflow
+ * getLumenflowHome() // '/home/user/.custom-lumenflow'
+ *
+ * @example
+ * // Without LUMENFLOW_HOME set
+ * getLumenflowHome() // '/home/user/.lumenflow'
+ */
+export function getLumenflowHome() {
+    const envValue = process.env[LUMENFLOW_HOME_ENV];
+    if (envValue) {
+        const expanded = expandTilde(envValue);
+        return removeTrailingSlash(expanded);
+    }
+    return join(homedir(), DEFAULT_LUMENFLOW_DIR);
+}
+/**
+ * Get the plans directory path
+ *
+ * Plans are stored in $LUMENFLOW_HOME/plans/
+ *
+ * @returns {string} Absolute path to plans directory
+ *
+ * @example
+ * getPlansDir() // '/home/user/.lumenflow/plans'
+ */
+export function getPlansDir() {
+    return join(getLumenflowHome(), PLANS_SUBDIR);
+}
+/**
+ * Check if a path is an external (non-repo) path
+ *
+ * External paths include:
+ * - Paths starting with ~/
+ * - Paths starting with $LUMENFLOW_HOME
+ * - Paths using lumenflow:// protocol
+ * - Absolute paths (starting with /)
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is external
+ *
+ * @example
+ * isExternalPath('~/.lumenflow/plans/plan.md') // true
+ * isExternalPath('$LUMENFLOW_HOME/plans/plan.md') // true
+ * isExternalPath('lumenflow://plans/plan.md') // true
+ * isExternalPath('/home/user/.lumenflow/plans/plan.md') // true
+ * isExternalPath('docs/04-operations/plans/plan.md') // false
+ */
+export function isExternalPath(path) {
+    // Check for tilde-prefixed paths
+    if (path.startsWith(PATH_LITERALS.TILDE_PREFIX)) {
+        return true;
+    }
+    // Check for environment variable reference
+    if (path.startsWith(LUMENFLOW_HOME_VAR_PREFIX)) {
+        return true;
+    }
+    // Check for lumenflow:// protocol
+    if (path.startsWith(LUMENFLOW_PROTOCOL)) {
+        return true;
+    }
+    // Check for absolute paths (starting with /)
+    if (path.startsWith(STRING_LITERALS.SLASH)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Normalize a spec_ref path by expanding variables and protocols
+ *
+ * Expands:
+ * - lumenflow://path -> $LUMENFLOW_HOME/path
+ * - ~/path -> /home/user/path
+ * - $LUMENFLOW_HOME/path -> actual LUMENFLOW_HOME value
+ *
+ * Repo-relative paths are returned unchanged.
+ *
+ * @param {string} specRef - Spec reference path
+ * @returns {string} Normalized absolute path or unchanged relative path
+ *
+ * @example
+ * normalizeSpecRef('lumenflow://plans/WU-1062-plan.md')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ *
+ * @example
+ * normalizeSpecRef('docs/04-operations/plans/plan.md')
+ * // 'docs/04-operations/plans/plan.md' (unchanged)
+ */
+export function normalizeSpecRef(specRef) {
+    // Handle lumenflow:// protocol
+    if (specRef.startsWith(LUMENFLOW_PROTOCOL)) {
+        const relativePath = specRef.slice(LUMENFLOW_PROTOCOL.length);
+        return join(getLumenflowHome(), relativePath);
+    }
+    // Handle $LUMENFLOW_HOME variable
+    if (specRef.startsWith(LUMENFLOW_HOME_VAR_PREFIX)) {
+        const relativePath = specRef.slice(LUMENFLOW_HOME_VAR_PREFIX.length);
+        // Remove leading slash if present
+        const cleanPath = relativePath.startsWith(STRING_LITERALS.SLASH)
+            ? relativePath.slice(PATH_SLICE_LENGTHS.LEADING_SLASH_LENGTH)
+            : relativePath;
+        return join(getLumenflowHome(), cleanPath);
+    }
+    // Handle tilde expansion
+    if (specRef.startsWith(PATH_LITERALS.TILDE_PREFIX)) {
+        return expandTilde(specRef);
+    }
+    // Return relative paths unchanged
+    return specRef;
+}
+/**
+ * Get the full path for a plan file given a WU ID
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Full path to the plan file
+ *
+ * @example
+ * getPlanPath('WU-1062')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ */
+export function getPlanPath(wuId) {
+    const filename = `${wuId}${PATH_LITERALS.PLAN_FILE_SUFFIX}`;
+    return join(getPlansDir(), filename);
+}
+/**
+ * Get the lumenflow:// protocol reference for a plan
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Protocol reference (e.g., 'lumenflow://plans/WU-1062-plan.md')
+ *
+ * @example
+ * getPlanProtocolRef('WU-1062')
+ * // 'lumenflow://plans/WU-1062-plan.md'
+ */
+export function getPlanProtocolRef(wuId) {
+    const filename = `${wuId}${PATH_LITERALS.PLAN_FILE_SUFFIX}`;
+    return `${LUMENFLOW_PROTOCOL}${PLANS_SUBDIR}${STRING_LITERALS.SLASH}${filename}`;
+}
+//# sourceMappingURL=lumenflow-home.js.map

package/dist/lumenflow-home.js.map

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

package/dist/manual-test-validator.d.ts

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * Manual Test Escape Hatch Validator
+ *
+ * WU-1433: Restricts manual-only tests for WUs touching hex core code.
+ * WU-2332: Require automated tests for all code files, remove lane exemptions.
+ *
+ * Implementation WUs must have at least one automated test (unit/e2e/integration).
+ *
+ * Exemptions:
+ * - type: documentation only
+ * - code_paths containing only documentation/config files (no code files)
+ *
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-done-validators.ts} - Integration point
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
+ */
+/**
+ * Path prefixes for hex core code requiring automated tests.
+ * These are the critical application layer paths.
+ *
+ * WU-1068: Changed from @exampleapp to @lumenflow for framework reusability.
+ * Project-specific patterns should be configured in workspace.yaml.
+ *
+ * @constant {string[]}
+ */
+export declare const HEX_CORE_CODE_PATTERNS: readonly string[];
+/**
+ * @deprecated Lane-based exemptions removed in WU-2332.
+ * Test requirements are now based on file types, not lanes.
+ * Kept for backward compatibility but no longer used.
+ * @constant {string[]}
+ */
+export declare const EXEMPT_LANES: readonly never[];
+/**
+ * WU types exempt from automated test requirement.
+ * Only 'documentation' type is exempt - actual code changes require automated tests.
+ *
+ * @constant {string[]}
+ */
+export declare const EXEMPT_TYPES: readonly string[];
+/**
+ * Determine if a file path represents a code file requiring automated tests.
+ *
+ * Code files are those with extensions like .ts, .ts, .tsx, .js
+ * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
+ *
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if the file is a code file requiring tests
+ */
+export declare function isCodeFile(filePath: UnsafeAny): boolean;
+/**
+ * Check if code_paths contains UnsafeAny hex core code.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if UnsafeAny path is in hex core layer
+ */
+export declare function containsHexCoreCode(codePaths: UnsafeAny): boolean;
+/**
+ * Check if a WU is exempt from automated test requirement.
+ *
+ * WU-2332: Only type: 'documentation' is exempt.
+ * Lane-based exemptions have been removed - test requirements
+ * are now based on file types in code_paths.
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {boolean} True if WU is exempt
+ */
+export declare function isExemptFromAutomatedTests(doc: UnsafeAny): boolean;
+/**
+ * Validate automated test requirement for WU.
+ *
+ * WU-2332: Requirements are based on file types, not lanes.
+ * - WUs with ANY code files in code_paths must have automated tests
+ * - WUs with only docs/config files can use manual-only tests
+ * - type: 'documentation' is always exempt
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export declare function validateAutomatedTestRequirement(doc: UnsafeAny): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=manual-test-validator.d.ts.map

package/dist/manual-test-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-test-validator.d.ts","sourceRoot":"","sources":["../src/manual-test-validator.ts"],"names":[],"mappings":";AAGA;;;;;;;;;;;;;;GAcG;AA4BH;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,mBAIjC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,YAAY,kBAAoB,CAAC;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,mBAA0C,CAAC;AAEpE;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,SAAS,WA0B7C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,WASvD;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,SAAS,WAUxD;AAsCD;;;;;;;;;;GAUG;AACH,wBAAgB,gCAAgC,CAAC,GAAG,EAAE,SAAS;;;EAoC9D"}

package/dist/manual-test-validator.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Manual Test Escape Hatch Validator
+ *
+ * WU-1433: Restricts manual-only tests for WUs touching hex core code.
+ * WU-2332: Require automated tests for all code files, remove lane exemptions.
+ *
+ * Implementation WUs must have at least one automated test (unit/e2e/integration).
+ *
+ * Exemptions:
+ * - type: documentation only
+ * - code_paths containing only documentation/config files (no code files)
+ *
+ * @see {@link packages/@lumenflow/cli/src/lib/wu-done-validators.ts} - Integration point
+ * @see {@link docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md} - TDD requirements
+ */
+import path from 'node:path';
+import { TEST_TYPES, WU_TYPES } from './wu-constants.js';
+/**
+ * Code file extensions that require automated tests.
+ * @constant {string[]}
+ */
+const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.ts']);
+/**
+ * Non-code file extensions (documentation, data, config).
+ * @constant {string[]}
+ */
+const NON_CODE_EXTENSIONS = Object.freeze(['.md', '.yaml', '.yml', '.json']);
+/**
+ * Patterns that indicate a config file (even with code extensions).
+ * @constant {RegExp[]}
+ */
+const CONFIG_PATTERNS = Object.freeze([
+    /config\./i, // vitest.config.ts, eslint.config.js
+    /\.config\./i, // *.config.ts, *.config.js
+    /rc\.[jt]s$/i, // .eslintrc.js, .prettierrc.ts
+    /^\.[a-z]+rc\./i, // .eslintrc.*, .prettierrc.*
+]);
+/**
+ * Path prefixes for hex core code requiring automated tests.
+ * These are the critical application layer paths.
+ *
+ * WU-1068: Changed from @exampleapp to @lumenflow for framework reusability.
+ * Project-specific patterns should be configured in workspace.yaml.
+ *
+ * @constant {string[]}
+ */
+export const HEX_CORE_CODE_PATTERNS = Object.freeze([
+    'packages/@lumenflow/core/',
+    'packages/@lumenflow/cli/',
+    'packages/@lumenflow/agent/',
+]);
+/**
+ * @deprecated Lane-based exemptions removed in WU-2332.
+ * Test requirements are now based on file types, not lanes.
+ * Kept for backward compatibility but no longer used.
+ * @constant {string[]}
+ */
+export const EXEMPT_LANES = Object.freeze([]);
+/**
+ * WU types exempt from automated test requirement.
+ * Only 'documentation' type is exempt - actual code changes require automated tests.
+ *
+ * @constant {string[]}
+ */
+export const EXEMPT_TYPES = Object.freeze([WU_TYPES.DOCUMENTATION]);
+/**
+ * Determine if a file path represents a code file requiring automated tests.
+ *
+ * Code files are those with extensions like .ts, .ts, .tsx, .js
+ * EXCEPT config files (vitest.config.ts, .eslintrc.js, etc.)
+ *
+ * @param {string} filePath - File path to check
+ * @returns {boolean} True if the file is a code file requiring tests
+ */
+export function isCodeFile(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    // Get the filename from the path
+    const fileName = path.basename(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    // Check if it's a non-code extension (docs, data)
+    if (NON_CODE_EXTENSIONS.includes(ext)) {
+        return false;
+    }
+    // Check if it's a code extension
+    if (!CODE_EXTENSIONS.includes(ext)) {
+        return false;
+    }
+    // Check if it's a config file (even with code extension)
+    const isConfig = CONFIG_PATTERNS.some((pattern) => pattern.test(fileName));
+    if (isConfig) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Check if code_paths contains UnsafeAny hex core code.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if UnsafeAny path is in hex core layer
+ */
+export function containsHexCoreCode(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return false;
+    }
+    return codePaths.some((path) => {
+        if (!path || typeof path !== 'string')
+            return false;
+        return HEX_CORE_CODE_PATTERNS.some((pattern) => path.startsWith(pattern));
+    });
+}
+/**
+ * Check if a WU is exempt from automated test requirement.
+ *
+ * WU-2332: Only type: 'documentation' is exempt.
+ * Lane-based exemptions have been removed - test requirements
+ * are now based on file types in code_paths.
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {boolean} True if WU is exempt
+ */
+export function isExemptFromAutomatedTests(doc) {
+    if (!doc)
+        return false;
+    // Only type: documentation is exempt
+    const type = doc.type || '';
+    if (typeof type === 'string' && EXEMPT_TYPES.includes(type)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if WU has at least one automated test.
+ *
+ * @param {object} tests - Tests object from WU YAML
+ * @returns {boolean} True if has at least one automated test
+ */
+function hasAutomatedTest(tests) {
+    if (!tests)
+        return false;
+    const hasItems = (arr) => Array.isArray(arr) && arr.length > 0;
+    return (hasItems(tests[TEST_TYPES.UNIT]) ||
+        hasItems(tests[TEST_TYPES.E2E]) ||
+        hasItems(tests[TEST_TYPES.INTEGRATION]));
+}
+/**
+ * Check if UnsafeAny code_paths contain actual code files (not docs/config).
+ *
+ * @param {string[]} codePaths - Array of file paths from WU YAML
+ * @returns {{ hasCodeFiles: boolean, codeFiles: string[] }} Result with list of code files
+ */
+function analyzeCodePaths(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return { hasCodeFiles: false, codeFiles: [] };
+    }
+    const codeFiles = codePaths.filter((p) => isCodeFile(p));
+    return {
+        hasCodeFiles: codeFiles.length > 0,
+        codeFiles,
+    };
+}
+/**
+ * Validate automated test requirement for WU.
+ *
+ * WU-2332: Requirements are based on file types, not lanes.
+ * - WUs with ANY code files in code_paths must have automated tests
+ * - WUs with only docs/config files can use manual-only tests
+ * - type: 'documentation' is always exempt
+ *
+ * @param {object} doc - WU YAML document
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ */
+export function validateAutomatedTestRequirement(doc) {
+    const errors = [];
+    if (!doc) {
+        return { valid: true, errors: [] };
+    }
+    // Check if WU is exempt by type
+    if (isExemptFromAutomatedTests(doc)) {
+        return { valid: true, errors: [] };
+    }
+    // Analyze code_paths for actual code files
+    const codePaths = doc.code_paths || [];
+    const { hasCodeFiles, codeFiles } = analyzeCodePaths(codePaths);
+    // If no code files, manual tests are fine
+    if (!hasCodeFiles) {
+        return { valid: true, errors: [] };
+    }
+    // WU has code files - require automated tests
+    // Support both tests: (current) and test_paths: (legacy)
+    const tests = doc.tests || doc.test_paths || {};
+    if (!hasAutomatedTest(tests)) {
+        errors.push(`WU modifies code files but has no automated tests.\n` +
+            `  Code files: ${codeFiles.join(', ')}\n` +
+            `  Required: At least one automated test (unit, e2e, or integration)\n` +
+            `  Manual-only tests are not allowed for code changes.\n\n` +
+            `  Fix: Add tests to tests.unit, tests.e2e, or tests.integration in WU YAML.`);
+        return { valid: false, errors };
+    }
+    return { valid: true, errors: [] };
+}
+//# sourceMappingURL=manual-test-validator.js.map

package/dist/manual-test-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manual-test-validator.js","sourceRoot":"","sources":["../src/manual-test-validator.ts"],"names":[],"mappings":";AACA,iCAAiC;AACjC,yCAAyC;AACzC;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;GAGG;AACH,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAE7E;;;GAGG;AACH,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,CAAC;IACpC,WAAW,EAAE,qCAAqC;IAClD,aAAa,EAAE,2BAA2B;IAC1C,aAAa,EAAE,+BAA+B;IAC9C,gBAAgB,EAAE,6BAA6B;CAChD,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,MAAM,CAAC;IAClD,2BAA2B;IAC3B,0BAA0B;IAC1B,4BAA4B;CAC7B,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,QAAmB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iCAAiC;IACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAEjD,kDAAkD;IAClD,IAAI,mBAAmB,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACtC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yDAAyD;IACzD,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC3E,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAoB;IACtD,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7B,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACpD,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAc;IACvD,IAAI,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IAEvB,qCAAqC;IACrC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC;IAC5B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAgB;IACxC,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IAEzB,MAAM,QAAQ,GAAG,CAAC,GAAc,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAE1E,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;QAChC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QAC/B,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CACxC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,SAAoB;IAC5C,IAAI,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC;IAChD,CAAC;IAED,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;IACzD,OAAO;QACL,YAAY,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;QAClC,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gCAAgC,CAAC,GAAc;IAC7D,MAAM,MAAM,GAAG,EAAE,CAAC;IAElB,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACrC,CAAC;IAED,gCAAgC;IAChC,IAAI,0BAA0B,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACrC,CAAC;IAED,2CAA2C;IAC3C,MAAM,SAAS,GAAG,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;IACvC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAEhE,0CAA0C;IAC1C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;IACrC,CAAC;IAED,8CAA8C;IAC9C,yDAAyD;IACzD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,CAAC,IAAI,CACT,sDAAsD;YACpD,iBAAiB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACzC,uEAAuE;YACvE,2DAA2D;YAC3D,6EAA6E,CAChF,CAAC;QACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAClC,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AACrC,CAAC"}