@lumenflow/cli 2.3.2 → 2.5.0

package/dist/__tests__/wu-validate-strict.test.js

@@ -0,0 +1,113 @@
+/**
+ * @file wu-validate-strict.test.ts
+ * Test suite for wu:validate strict validation behavior (WU-1329)
+ *
+ * WU-1329: Make wu:validate treat warnings as errors by default
+ *
+ * Tests:
+ * - Default strict mode behavior (warnings treated as errors)
+ * - --no-strict flag restores original behavior (warnings advisory)
+ * - Help text documents strict default
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { WU_OPTIONS, NEGATED_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+describe('wu:validate strict validation (WU-1329)', () => {
+    describe('WU_OPTIONS.noStrict configuration', () => {
+        // WU-1329: Verify the noStrict option is properly configured
+        it('should have noStrict option defined in WU_OPTIONS', () => {
+            expect(WU_OPTIONS.noStrict).toBeDefined();
+            expect(WU_OPTIONS.noStrict.name).toBe('noStrict');
+            expect(WU_OPTIONS.noStrict.flags).toBe('--no-strict');
+            expect(WU_OPTIONS.noStrict.isNegated).toBe(true);
+        });
+        it('should include description about bypassing strict validation', () => {
+            expect(WU_OPTIONS.noStrict.description).toContain('Bypass strict validation');
+        });
+        // WU-1329: Verify 'strict' is in NEGATED_OPTIONS array
+        it('should include strict in NEGATED_OPTIONS array', () => {
+            expect(NEGATED_OPTIONS).toContain('strict');
+        });
+    });
+    describe('strict mode logic', () => {
+        // WU-1329: Verify the strict mode conversion pattern
+        it('should default to strict=true when noStrict is undefined', () => {
+            const args = { noStrict: undefined };
+            const strict = !args.noStrict;
+            expect(strict).toBe(true);
+        });
+        it('should set strict=false when noStrict is true (--no-strict flag)', () => {
+            const args = { noStrict: true };
+            const strict = !args.noStrict;
+            expect(strict).toBe(false);
+        });
+        it('should set strict=true when noStrict is false (explicit)', () => {
+            const args = { noStrict: false };
+            const strict = !args.noStrict;
+            expect(strict).toBe(true);
+        });
+    });
+    describe('--no-strict logging behavior', () => {
+        let consoleSpy;
+        beforeEach(() => {
+            consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => { });
+        });
+        afterEach(() => {
+            consoleSpy.mockRestore();
+        });
+        // WU-1329: The logging behavior is implemented in main() functions
+        // This test documents the expected behavior pattern using the spy
+        it('should log when --no-strict bypass is used', () => {
+            // Simulate the logging pattern from wu-validate.ts main()
+            const noStrict = true;
+            const LOG_PREFIX = '[wu:validate]';
+            const message = `${LOG_PREFIX} WARNING: strict validation bypassed (--no-strict). Warnings will be advisory only.`;
+            if (noStrict) {
+                // Use the spy to simulate logging
+                consoleSpy(message);
+            }
+            expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('strict validation bypassed'));
+        });
+        it('should not log when strict mode is active', () => {
+            // When noStrict is false, no logging should occur
+            const noStrict = false;
+            if (noStrict) {
+                consoleSpy('This should not be called');
+            }
+            expect(consoleSpy).not.toHaveBeenCalled();
+        });
+    });
+    describe('validateSingleWU strict mode behavior', () => {
+        // WU-1329: These tests document the expected behavior
+        // The actual validation is done by calling the CLI command
+        it('should treat warnings as errors by default (strict=true)', () => {
+            // In strict mode, any warnings from completeness validation
+            // should become errors and cause validation to fail
+            const strict = true;
+            const warnings = ['Missing recommended field: notes'];
+            const errors = [];
+            if (strict && warnings.length > 0) {
+                errors.push(...warnings.map((w) => `[STRICT] ${w}`));
+            }
+            expect(errors.length).toBeGreaterThan(0);
+            expect(errors[0]).toContain('[STRICT]');
+        });
+        it('should allow warnings when strict=false (--no-strict)', () => {
+            // In non-strict mode, warnings should remain warnings
+            // and validation should pass
+            const strict = false;
+            const warnings = ['Missing recommended field: notes'];
+            const errors = [];
+            if (strict && warnings.length > 0) {
+                errors.push(...warnings.map((w) => `[STRICT] ${w}`));
+            }
+            expect(errors.length).toBe(0);
+        });
+    });
+    describe('help text documentation', () => {
+        // WU-1329: Verify help text documents strict default
+        it('should document that --no-strict bypasses strict validation', () => {
+            const expectedDescription = 'Bypass strict validation';
+            expect(WU_OPTIONS.noStrict.description).toContain(expectedDescription);
+        });
+    });
+});

package/dist/flow-bottlenecks.js

@@ -15,8 +15,9 @@
  */
 import { Command } from 'commander';
 import { getBottleneckAnalysis, } from '@lumenflow/metrics';
-import { buildDependencyGraphAsync, renderMermaid, } from '@lumenflow/core/dist/dependency-graph.js';
+import { buildDependencyGraphAsync, renderMermaid } from '@lumenflow/core/dist/dependency-graph.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
+import { getConfig } from '@lumenflow/core/dist/lumenflow-config.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[flow:bottlenecks]';
 /** Default bottleneck limit */
@@ -147,7 +148,8 @@ async function main() {
     const coreGraph = await buildDependencyGraphAsync();
     if (coreGraph.size === 0) {
         console.log(`${LOG_PREFIX} No WUs found in dependency graph.`);
-        console.log(`${LOG_PREFIX} Ensure WU YAML files exist in docs/04-operations/tasks/wu/ with blocked_by/blocks fields.`);
+        // WU-1311: Use config-based WU directory path
+        console.log(`${LOG_PREFIX} Ensure WU YAML files exist in ${getConfig().directories.wuDir}/ with blocked_by/blocks fields.`);
         return;
     }
     console.log(`${LOG_PREFIX} Found ${coreGraph.size} WUs in graph`);

package/dist/flow-report.js

@@ -21,6 +21,7 @@ import { parse as parseYaml } from 'yaml';
 import { Command } from 'commander';
 import { generateFlowReport, TELEMETRY_PATHS, } from '@lumenflow/metrics';
 import { die } from '@lumenflow/core/dist/error-handler.js';
+import { WU_PATHS } from '@lumenflow/core/dist/wu-paths.js';
 /** Log prefix for console output */
 const LOG_PREFIX = '[flow:report]';
 /** Default report window in days */
@@ -30,8 +31,8 @@ const OUTPUT_FORMATS = {
     JSON: 'json',
     TABLE: 'table',
 };
-/** WU directory relative to repo root */
-const WU_DIR = 'docs/04-operations/tasks/wu';
+/** WU directory relative to repo root (WU-1301: uses config-based paths) */
+const WU_DIR = WU_PATHS.WU_DIR();
 /**
  * Parse command line arguments
  */

package/dist/gates.js

@@ -45,6 +45,9 @@ import { access } from 'node:fs/promises';
 import path from 'node:path';
 import { emitGateEvent, getCurrentWU, getCurrentLane } from '@lumenflow/core/dist/telemetry.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
+// WU-1299: Import WU YAML reader to get code_paths for docs-only filtering
+import { readWURaw } from '@lumenflow/core/dist/wu-yaml.js';
+import { createWuPaths } from '@lumenflow/core/dist/wu-paths.js';
 import { getChangedLintableFiles, isLintableFile } from '@lumenflow/core/dist/incremental-lint.js';
 import { buildVitestChangedArgs, isCodeFilePath } from '@lumenflow/core/dist/incremental-test.js';
 import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
@@ -65,6 +68,8 @@ import { runSystemMapValidation } from '@lumenflow/core/dist/system-map-validato
 import { loadLaneHealthConfig, resolveTestPolicy, } from '@lumenflow/core/dist/gates-config.js';
 // WU-1191: Lane health check
 import { runLaneHealthCheck } from './lane-health.js';
+// WU-1315: Onboarding smoke test
+import { runOnboardingSmokeTestGate } from './onboarding-smoke-test.js';
 import { BRANCHES, PACKAGES, PKG_MANAGER, ESLINT_FLAGS, ESLINT_COMMANDS, ESLINT_DEFAULTS, SCRIPTS, CACHE_STRATEGIES, DIRECTORIES, GATE_NAMES, GATE_COMMANDS, CLI_MODES, EXIT_CODES, FILE_SYSTEM, PRETTIER_ARGS, PRETTIER_FLAGS, } from '@lumenflow/core/dist/wu-constants.js';
 /**
  * WU-1087: Gates-specific option definitions for createWUParser.
@@ -250,6 +255,152 @@ export function resolveTestPlan({ isMainBranch, hasUntrackedCode, hasConfigChang
     }
     return { mode: 'incremental' };
 }
+/**
+ * WU-1299: Extract package name from a single code path
+ *
+ * @param codePath - Single code path to parse
+ * @returns Package name or null if not a package/app path
+ */
+function extractPackageFromPath(codePath) {
+    if (!codePath || typeof codePath !== 'string') {
+        return null;
+    }
+    const normalized = codePath.replace(/\\/g, '/');
+    // Handle packages/@scope/name/... or packages/name/...
+    if (normalized.startsWith('packages/')) {
+        const parts = normalized.slice('packages/'.length).split('/');
+        // Scoped package (@scope/name)
+        if (parts[0]?.startsWith('@') && parts[1]) {
+            return `${parts[0]}/${parts[1]}`;
+        }
+        // Unscoped package
+        if (parts[0]) {
+            return parts[0];
+        }
+    }
+    // Handle apps/name/...
+    if (normalized.startsWith('apps/')) {
+        const parts = normalized.slice('apps/'.length).split('/');
+        if (parts[0]) {
+            return parts[0];
+        }
+    }
+    return null;
+}
+/**
+ * WU-1299: Extract package/app names from code_paths
+ *
+ * Parses paths like:
+ * - packages/@lumenflow/cli/src/file.ts -> @lumenflow/cli
+ * - apps/web/src/file.ts -> web
+ *
+ * @param codePaths - Array of code paths from WU YAML
+ * @returns Array of unique package/app names
+ */
+export function extractPackagesFromCodePaths(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return [];
+    }
+    const packages = new Set();
+    for (const codePath of codePaths) {
+        const pkg = extractPackageFromPath(codePath);
+        if (pkg) {
+            packages.add(pkg);
+        }
+    }
+    return Array.from(packages);
+}
+/**
+ * WU-1299: Resolve test plan for docs-only mode
+ *
+ * When --docs-only is passed, this determines whether to:
+ * - Skip tests entirely (no code packages in code_paths)
+ * - Run tests only for packages mentioned in code_paths
+ *
+ * @param options - Options including code_paths from WU YAML
+ * @returns DocsOnlyTestPlan indicating how to handle tests
+ */
+export function resolveDocsOnlyTestPlan({ codePaths }) {
+    const packages = extractPackagesFromCodePaths(codePaths);
+    if (packages.length === 0) {
+        return {
+            mode: 'skip',
+            packages: [],
+            reason: 'no-code-packages',
+        };
+    }
+    return {
+        mode: 'filtered',
+        packages,
+    };
+}
+/**
+ * WU-1299: Format message for docs-only test skipping/filtering
+ *
+ * Provides clear messaging when tests are skipped or filtered in docs-only mode.
+ *
+ * @param plan - The docs-only test plan
+ * @returns Human-readable message explaining what's happening
+ */
+export function formatDocsOnlySkipMessage(plan) {
+    if (plan.mode === 'skip') {
+        return '📝 docs-only mode: skipping all tests (no code packages in code_paths)';
+    }
+    const packageList = plan.packages.join(', ');
+    return `📝 docs-only mode: running tests only for packages in code_paths: ${packageList}`;
+}
+/**
+ * WU-1299: Load code_paths from current WU YAML
+ *
+ * Attempts to read the WU YAML file for the current WU (detected from git branch)
+ * and return its code_paths. Returns empty array if WU cannot be determined or
+ * YAML file doesn't exist.
+ *
+ * @param options - Options including optional cwd
+ * @returns Array of code_paths from WU YAML, or empty array if unavailable
+ */
+export function loadCurrentWUCodePaths(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const wuId = getCurrentWU();
+    if (!wuId) {
+        return [];
+    }
+    try {
+        const wuPaths = createWuPaths({ projectRoot: cwd });
+        const wuYamlPath = wuPaths.WU(wuId);
+        const wuDoc = readWURaw(wuYamlPath);
+        if (wuDoc && Array.isArray(wuDoc.code_paths)) {
+            return wuDoc.code_paths.filter((p) => typeof p === 'string');
+        }
+    }
+    catch {
+        // WU YAML not found or unreadable - return empty array
+    }
+    return [];
+}
+/**
+ * WU-1299: Run filtered tests for docs-only mode
+ *
+ * When --docs-only is passed and code_paths contains packages, this runs tests
+ * only for those specific packages using turbo's --filter flag.
+ *
+ * @param options - Options including packages to test and agent log context
+ * @returns Result object with ok status and duration
+ */
+async function runDocsOnlyFilteredTests({ packages, agentLog, }) {
+    const start = Date.now();
+    const logLine = makeGateLogger({ agentLog, useAgentMode: !!agentLog });
+    if (packages.length === 0) {
+        logLine('📝 docs-only mode: no packages to test, skipping');
+        return { ok: true, duration: Date.now() - start };
+    }
+    logLine(`\n> Tests (docs-only filtered: ${packages.join(', ')})\n`);
+    // Build turbo filter args for each package
+    // turbo supports --filter=@scope/package or --filter=package
+    const filterArgs = packages.map((pkg) => `--filter=${pkg}`);
+    const result = run(pnpmCmd('turbo', 'run', 'test', ...filterArgs), { agentLog });
+    return { ok: result.ok, duration: Date.now() - start };
+}
 export function parsePrettierListOutput(output) {
     if (!output)
         return [];
@@ -935,6 +1086,12 @@ async function executeGates(opts) {
     }
     // Determine effective docs-only mode (explicit flag OR detected from changed files)
     const effectiveDocsOnly = isDocsOnly || (riskTier && riskTier.isDocsOnly);
+    // WU-1299: Load code_paths and compute docs-only test plan
+    let docsOnlyTestPlan = null;
+    if (effectiveDocsOnly) {
+        const codePaths = loadCurrentWUCodePaths({ cwd: process.cwd() });
+        docsOnlyTestPlan = resolveDocsOnlyTestPlan({ codePaths });
+    }
     // Determine which gates to run
     // WU-2252: Invariants gate runs FIRST and is included in both docs-only and regular modes
     const gates = effectiveDocsOnly
@@ -960,6 +1117,30 @@ async function executeGates(opts) {
                 run: (ctx) => runLaneHealthGate({ ...ctx, mode: laneHealthMode }),
                 warnOnly: laneHealthMode !== 'error',
             },
+            // WU-1315: Onboarding smoke test (init + wu:create validation)
+            {
+                name: GATE_NAMES.ONBOARDING_SMOKE_TEST,
+                cmd: GATE_COMMANDS.ONBOARDING_SMOKE_TEST,
+            },
+            // WU-1299: Filtered tests for packages in code_paths (if any)
+            // When docs-only mode has packages in code_paths, run tests only for those packages
+            // This prevents pre-existing failures in unrelated packages from blocking
+            ...(docsOnlyTestPlan && docsOnlyTestPlan.mode === 'filtered'
+                ? [
+                    {
+                        name: GATE_NAMES.TEST,
+                        run: (ctx) => {
+                            // Safe access: docsOnlyTestPlan is guaranteed non-null by the outer conditional
+                            const pkgs = docsOnlyTestPlan.packages;
+                            return runDocsOnlyFilteredTests({
+                                packages: pkgs,
+                                agentLog: ctx.agentLog,
+                            });
+                        },
+                        warnOnly: !testsRequired,
+                    },
+                ]
+                : []),
         ]
         : [
             // WU-2252: Invariants check runs first (non-bypassable)
@@ -989,6 +1170,11 @@ async function executeGates(opts) {
                 run: (ctx) => runLaneHealthGate({ ...ctx, mode: laneHealthMode }),
                 warnOnly: laneHealthMode !== 'error',
             },
+            // WU-1315: Onboarding smoke test (init + wu:create validation)
+            {
+                name: GATE_NAMES.ONBOARDING_SMOKE_TEST,
+                cmd: GATE_COMMANDS.ONBOARDING_SMOKE_TEST,
+            },
             // WU-2062: Safety-critical tests ALWAYS run
             // WU-1280: When tests_required=false (methodology.testing: none), failures only warn
             {
@@ -1021,11 +1207,15 @@ async function executeGates(opts) {
             { name: GATE_NAMES.COVERAGE, cmd: GATE_COMMANDS.COVERAGE_GATE },
         ];
     if (effectiveDocsOnly) {
+        // WU-1299: Show clear messaging about what's being skipped/run in docs-only mode
+        const docsOnlyMessage = docsOnlyTestPlan && docsOnlyTestPlan.mode === 'filtered'
+            ? formatDocsOnlySkipMessage(docsOnlyTestPlan)
+            : '📝 Docs-only mode: skipping lint, typecheck, and all tests (no code packages in code_paths)';
         if (!useAgentMode) {
-            console.log('📝 Docs-only mode: skipping lint, typecheck, and tests\n');
+            console.log(`${docsOnlyMessage}\n`);
         }
         else {
-            writeSync(agentLog.logFd, '📝 Docs-only mode: skipping lint, typecheck, and tests\n');
+            writeSync(agentLog.logFd, `${docsOnlyMessage}\n`);
         }
     }
     // Run all gates sequentially
@@ -1107,6 +1297,16 @@ async function executeGates(opts) {
                     : console,
             });
         }
+        else if (gate.cmd === GATE_COMMANDS.ONBOARDING_SMOKE_TEST) {
+            // WU-1315: Onboarding smoke test (init + wu:create validation)
+            const logLine = useAgentMode
+                ? (line) => writeSync(agentLog.logFd, `${line}\n`)
+                : (line) => console.log(line);
+            logLine('\n> Onboarding smoke test\n');
+            result = await runOnboardingSmokeTestGate({
+                logger: { log: logLine },
+            });
+        }
         else {
             result = run(gate.cmd, { agentLog });
         }