@lumenflow/cli 4.24.0 → 5.0.0

package/packs/software-delivery/src/policy/gates-coverage.ts

@@ -0,0 +1,247 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Gates Coverage Policy Resolution
+ *
+ * WU-2037: Extracted from gates-config.ts
+ *
+ * Resolves coverage configuration and test policy from methodology settings.
+ * Uses resolvePolicy() to derive thresholds and modes from workspace.yaml.
+ *
+ * @module gates-coverage
+ */
+
+import { asRecord, isBoolean, isNumber } from '../constants/object-guards.js';
+import {
+  resolvePolicy,
+  getDefaultPolicy,
+  MethodologyConfigSchema,
+  TddDiffEvidenceConfigSchema,
+  TddOrderingConfigSchema,
+  type TddDiffEvidenceConfig,
+  type TddDiffEvidencePolicy,
+  type TddOrderingConfig,
+  type TddOrderingPolicy,
+} from './resolve-policy.js';
+import type { CoverageConfig, TestPolicy } from './gates-schemas.js';
+import {
+  GATES_RUNTIME_DEFAULTS,
+  SOFTWARE_DELIVERY_FIELDS,
+  GATES_FIELDS,
+  loadSoftwareDeliveryConfig,
+} from './gates-config-internal.js';
+
+// ---------------------------------------------------------------------------
+// Private helpers for reading typed fields from raw config
+// ---------------------------------------------------------------------------
+
+function readNumberField(
+  source: Record<string, unknown> | undefined,
+  primaryKey: string,
+  secondaryKey: string,
+): number | undefined {
+  const primary = source?.[primaryKey];
+  if (isNumber(primary)) {
+    return primary;
+  }
+  const secondary = source?.[secondaryKey];
+  return isNumber(secondary) ? secondary : undefined;
+}
+
+function readBooleanField(
+  source: Record<string, unknown> | undefined,
+  primaryKey: string,
+  secondaryKey: string,
+): boolean | undefined {
+  const primary = source?.[primaryKey];
+  if (isBoolean(primary)) {
+    return primary;
+  }
+  const secondary = source?.[secondaryKey];
+  return isBoolean(secondary) ? secondary : undefined;
+}
+
+function readGateMinCoverage(gatesRaw: Record<string, unknown> | undefined): number | undefined {
+  return readNumberField(gatesRaw, GATES_FIELDS.MIN_COVERAGE, GATES_FIELDS.MIN_COVERAGE_SNAKE);
+}
+
+function readGateEnableCoverage(
+  gatesRaw: Record<string, unknown> | undefined,
+): boolean | undefined {
+  return readBooleanField(
+    gatesRaw,
+    GATES_FIELDS.ENABLE_COVERAGE,
+    GATES_FIELDS.ENABLE_COVERAGE_SNAKE,
+  );
+}
+
+function readTddDiffEvidenceConfig(
+  gatesRaw: Record<string, unknown> | undefined,
+): TddDiffEvidenceConfig | undefined {
+  const raw = asRecord(gatesRaw?.[GATES_FIELDS.TDD_DIFF_EVIDENCE]) ?? undefined;
+  return TddDiffEvidenceConfigSchema.optional().parse(raw);
+}
+
+function readTddOrderingConfig(
+  gatesRaw: Record<string, unknown> | undefined,
+): TddOrderingConfig | undefined {
+  const raw = asRecord(gatesRaw?.[GATES_FIELDS.TDD_ORDERING]) ?? undefined;
+  return TddOrderingConfigSchema.optional().parse(raw);
+}
+
+// ---------------------------------------------------------------------------
+// Shared policy resolution helper (DRY: used by both public functions)
+// ---------------------------------------------------------------------------
+
+function resolvePolicyFromConfig(rawConfig: Record<string, unknown>) {
+  const methodologyRaw = asRecord(rawConfig[SOFTWARE_DELIVERY_FIELDS.METHODOLOGY]) ?? undefined;
+  const gatesRaw = asRecord(rawConfig[SOFTWARE_DELIVERY_FIELDS.GATES]) ?? undefined;
+  const minCoverage = readGateMinCoverage(gatesRaw);
+  const enableCoverage = readGateEnableCoverage(gatesRaw);
+  const tddDiffEvidence = readTddDiffEvidenceConfig(gatesRaw);
+  const tddOrdering = readTddOrderingConfig(gatesRaw);
+
+  // Parse methodology with Zod to get defaults
+  const methodology = MethodologyConfigSchema.parse(methodologyRaw ?? {});
+
+  // Build the config structure that resolvePolicy expects
+  const minimalConfig = {
+    methodology: methodologyRaw, // Pass raw methodology for explicit detection
+    gates: {
+      minCoverage,
+      enableCoverage,
+      tdd_diff_evidence: tddDiffEvidence,
+      tdd_ordering: tddOrdering,
+    },
+  };
+
+  // Resolve policy using the methodology configuration
+  // Pass rawConfig to detect explicit gates.* settings vs Zod defaults
+  return resolvePolicy(
+    {
+      methodology,
+      gates: {
+        // Default gates values from schema
+        maxEslintWarnings: GATES_RUNTIME_DEFAULTS.MAX_ESLINT_WARNINGS,
+        enableCoverage: enableCoverage ?? GATES_RUNTIME_DEFAULTS.DEFAULT_ENABLE_COVERAGE,
+        minCoverage: minCoverage ?? GATES_RUNTIME_DEFAULTS.DEFAULT_MIN_COVERAGE,
+        enableSafetyCriticalTests: true,
+        enableInvariants: true,
+        tdd_diff_evidence: tddDiffEvidence,
+        tdd_ordering: tddOrdering,
+      },
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Minimal type for config
+    } as unknown as Parameters<typeof resolvePolicy>[0],
+    {
+      rawConfig: minimalConfig,
+    },
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * WU-1262: Resolve coverage configuration from methodology policy
+ *
+ * Uses resolvePolicy() to determine coverage defaults based on methodology.testing:
+ * - tdd: 90% threshold, block mode
+ * - test-after: 70% threshold, warn mode
+ * - none: 0% threshold, off mode
+ *
+ * Precedence (highest to lowest):
+ * 1. Explicit gates.minCoverage / gates.enableCoverage
+ * 2. methodology.overrides.coverage_threshold / coverage_mode
+ * 3. methodology.testing template defaults
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved coverage configuration
+ */
+export function resolveCoverageConfig(projectRoot: string): CoverageConfig {
+  const rawConfig = loadSoftwareDeliveryConfig(projectRoot) ?? {};
+
+  // If no config file, use default policy
+  if (Object.keys(rawConfig).length === 0) {
+    const defaultPolicy = getDefaultPolicy();
+    return {
+      threshold: defaultPolicy.coverage_threshold,
+      mode: defaultPolicy.coverage_mode,
+    };
+  }
+
+  const policy = resolvePolicyFromConfig(rawConfig);
+
+  return {
+    threshold: policy.coverage_threshold,
+    mode: policy.coverage_mode,
+  };
+}
+
+/**
+ * WU-1280: Resolve test policy from methodology configuration
+ *
+ * Returns the full test policy including coverage config AND tests_required.
+ * This is used by gates to determine whether test failures should block or warn.
+ *
+ * Methodology mapping:
+ * - tdd: 90% threshold, block mode, tests_required=true
+ * - test-after: 70% threshold, warn mode, tests_required=true
+ * - none: 0% threshold, off mode, tests_required=false
+ *
+ * When tests_required=false:
+ * - Test failures produce WARNINGS instead of FAILURES
+ * - Gates continue but log the test failures
+ * - Coverage gate is effectively skipped (mode='off')
+ *
+ * @param projectRoot - Project root directory
+ * @returns Resolved test policy including tests_required
+ */
+export function resolveTestPolicy(projectRoot: string): TestPolicy {
+  const rawConfig = loadSoftwareDeliveryConfig(projectRoot) ?? {};
+
+  // If no config file, use default policy (TDD)
+  if (Object.keys(rawConfig).length === 0) {
+    const defaultPolicy = getDefaultPolicy();
+    return {
+      threshold: defaultPolicy.coverage_threshold,
+      mode: defaultPolicy.coverage_mode,
+      tests_required: defaultPolicy.tests_required,
+    };
+  }
+
+  const policy = resolvePolicyFromConfig(rawConfig);
+
+  return {
+    threshold: policy.coverage_threshold,
+    mode: policy.coverage_mode,
+    tests_required: policy.tests_required,
+  };
+}
+
+export function resolveTddDiffEvidencePolicy(projectRoot: string): TddDiffEvidencePolicy {
+  const rawConfig = loadSoftwareDeliveryConfig(projectRoot) ?? {};
+
+  if (Object.keys(rawConfig).length === 0) {
+    return getDefaultPolicy().tdd_diff_evidence;
+  }
+
+  return resolvePolicyFromConfig(rawConfig).tdd_diff_evidence;
+}
+
+/**
+ * WU-2650: Resolve the commit-order (RED-first) policy.
+ *
+ * Mirrors resolveTddDiffEvidencePolicy. Enforces only for feature/bug WUs
+ * under TDD methodology by default; docs/chore/process/tooling WUs bypass.
+ */
+export function resolveTddOrderingPolicy(projectRoot: string): TddOrderingPolicy {
+  const rawConfig = loadSoftwareDeliveryConfig(projectRoot) ?? {};
+
+  if (Object.keys(rawConfig).length === 0) {
+    return getDefaultPolicy().tdd_ordering;
+  }
+
+  return resolvePolicyFromConfig(rawConfig).tdd_ordering;
+}

package/packs/software-delivery/src/policy/gates-presets.ts

@@ -0,0 +1,134 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Gates Presets
+ *
+ * WU-2037: Extracted from gates-config.ts
+ *
+ * Language ecosystem preset definitions and expansion logic.
+ *
+ * @module gates-presets
+ */
+
+import type { GatesExecutionConfig } from './gates-schemas.js';
+
+/**
+ * Gate preset definitions
+ *
+ * These provide sensible defaults for common language ecosystems.
+ * Users can override fields via workspace.yaml software_delivery
+ */
+export const GATE_PRESETS: Record<string, Partial<GatesExecutionConfig>> = {
+  node: {
+    setup: 'npm ci || npm install',
+    format: 'npx prettier --check .',
+    lint: 'npx eslint .',
+    typecheck: 'npx tsc --noEmit',
+    test: 'npm test',
+  },
+  python: {
+    setup: 'pip install -e ".[dev]" || pip install -r requirements.txt',
+    format: 'ruff format --check .',
+    lint: 'ruff check .',
+    typecheck: 'mypy .',
+    test: 'pytest',
+  },
+  go: {
+    format: 'gofmt -l . | grep -v "^$" && exit 1 || exit 0',
+    lint: 'golangci-lint run',
+    typecheck: 'go vet ./...',
+    test: 'go test ./...',
+  },
+  rust: {
+    format: 'cargo fmt --check',
+    lint: 'cargo clippy -- -D warnings',
+    typecheck: 'cargo check',
+    test: 'cargo test',
+  },
+  dotnet: {
+    setup: 'dotnet restore',
+    format: 'dotnet format --verify-no-changes',
+    lint: 'dotnet build --no-restore -warnaserror',
+    test: 'dotnet test --no-restore',
+  },
+  // WU-1118: Java/JVM, Ruby, and PHP presets
+  java: {
+    format: 'mvn spotless:check || ./gradlew spotlessCheck',
+    lint: 'mvn checkstyle:check || ./gradlew checkstyleMain',
+    typecheck: 'mvn compile -DskipTests || ./gradlew compileJava',
+    test: 'mvn test || ./gradlew test',
+  },
+  ruby: {
+    setup: 'bundle install',
+    format: 'bundle exec rubocop --format simple --fail-level W',
+    lint: 'bundle exec rubocop',
+    test: 'bundle exec rspec',
+  },
+  php: {
+    setup: 'composer install',
+    format: 'vendor/bin/php-cs-fixer fix --dry-run --diff',
+    lint: 'vendor/bin/phpstan analyse',
+    test: 'vendor/bin/phpunit',
+  },
+};
+
+/**
+ * Expand a preset name into its default gate commands
+ *
+ * @param preset - Preset name (node, python, go, rust, dotnet) or undefined
+ * @returns Partial gates config with preset defaults, or empty object if unknown
+ */
+export function expandPreset(preset: string | undefined): Partial<GatesExecutionConfig> {
+  if (!preset) {
+    return {};
+  }
+
+  return GATE_PRESETS[preset] ?? {};
+}
+
+/**
+ * WU-2547: Preset-specific format-fix remediation commands.
+ *
+ * The `format` key in GATE_PRESETS above is the *verification* command used
+ * by gates (e.g. `dotnet format --verify-no-changes`). When an agent or
+ * user needs to actually fix a formatting failure they need the mutating
+ * equivalent of that command — `dotnet format`, `cargo fmt`, etc.
+ *
+ * Onboarding templates used to hardcode `pnpm prettier --write <file>`,
+ * which silently teaches agents the wrong habit in non-JS repos. init.ts
+ * now resolves this map against the chosen preset and substitutes the
+ * result into the `{{format_fix_command}}` placeholder.
+ */
+export const PRESET_FIX_COMMANDS: Record<string, string> = {
+  node: 'pnpm prettier --write <file>',
+  python: 'ruff format <file>',
+  go: 'gofmt -w <file>',
+  rust: 'cargo fmt',
+  dotnet: 'dotnet format',
+  java: 'mvn spotless:apply',
+  ruby: 'bundle exec rubocop -a <file>',
+  php: 'vendor/bin/php-cs-fixer fix <file>',
+};
+
+/**
+ * WU-2547: Safe fallback when a caller passes an unknown preset.
+ * Mirrors PRESET_FIX_COMMANDS.node so the two always match; kept as its own
+ * constant to satisfy noUncheckedIndexedAccess without a non-null assertion.
+ */
+const DEFAULT_FORMAT_FIX_COMMAND = 'pnpm prettier --write <file>';
+
+/**
+ * WU-2547: Resolve the format-fix remediation command for a preset.
+ *
+ * Used by init.ts to populate the `{{format_fix_command}}` token in
+ * onboarding templates so a .NET repo gets `dotnet format` guidance
+ * instead of `pnpm prettier --write`.
+ *
+ * @param preset - Gate preset name (node, dotnet, python, etc.)
+ * @returns The remediation command for the preset, or the node default
+ *          if the preset is unknown (never returns empty).
+ */
+export function getFormatFixCommand(preset: string): string {
+  return PRESET_FIX_COMMANDS[preset] ?? DEFAULT_FORMAT_FIX_COMMAND;
+}

package/packs/software-delivery/src/policy/gates-schemas.ts

@@ -0,0 +1,173 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Gates Schemas and Types
+ *
+ * WU-2037: Extracted from gates-config.ts
+ *
+ * Zod schema definitions, TypeScript types, and interfaces for gates configuration.
+ * This module contains only shape definitions -- no runtime logic.
+ *
+ * @module gates-schemas
+ */
+
+import { z } from 'zod';
+import type { CoverageMode } from './resolve-policy.js';
+
+// ---------------------------------------------------------------------------
+// Gate command schemas
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for a gate command object with options
+ */
+const GateCommandObjectSchema = z.object({
+  /** The shell command to execute */
+  command: z.string(),
+  /** Whether to continue if this gate fails (default: false) */
+  continueOnError: z.boolean().optional(),
+  /** Timeout in milliseconds */
+  timeout: z.number().int().positive().optional(),
+});
+
+/**
+ * Schema for a gate command - either a string or an object with options
+ */
+export const GateCommandConfigSchema = z.union([z.string(), GateCommandObjectSchema]);
+
+/**
+ * Type for parsed gate command configuration
+ */
+export type GateCommandConfig = z.infer<typeof GateCommandConfigSchema>;
+
+/**
+ * Schema for the gates execution configuration section
+ */
+export const GatesExecutionConfigSchema = z.object({
+  /** Preset to use for default commands (node, python, go, rust, dotnet) */
+  preset: z.string().optional(),
+  /** Setup command (e.g., install dependencies) */
+  setup: GateCommandConfigSchema.optional(),
+  /** Format check command */
+  format: GateCommandConfigSchema.optional(),
+  /** Lint command */
+  lint: GateCommandConfigSchema.optional(),
+  /** Type check command */
+  typecheck: GateCommandConfigSchema.optional(),
+  /** Test command */
+  test: GateCommandConfigSchema.optional(),
+  /** Coverage configuration */
+  coverage: z
+    .union([
+      z.string(),
+      z.object({
+        command: z.string(),
+        threshold: z.number().min(0).max(100).optional(),
+      }),
+    ])
+    .optional(),
+});
+
+/**
+ * Type for gates execution configuration
+ */
+export type GatesExecutionConfig = z.infer<typeof GatesExecutionConfigSchema>;
+
+// ---------------------------------------------------------------------------
+// Parsed gate command interface
+// ---------------------------------------------------------------------------
+
+/**
+ * Parsed gate command ready for execution
+ */
+export interface ParsedGateCommand {
+  /** The shell command to execute */
+  command: string;
+  /** Whether to continue if this gate fails */
+  continueOnError: boolean;
+  /** Timeout in milliseconds */
+  timeout: number;
+}
+
+// ---------------------------------------------------------------------------
+// Lane health types
+// ---------------------------------------------------------------------------
+
+/**
+ * WU-1191: Lane health gate mode
+ * Controls how lane health check behaves during gates
+ */
+export type LaneHealthMode = 'warn' | 'error' | 'off';
+
+/**
+ * Schema for lane health mode validation
+ */
+export const LaneHealthModeSchema = z.enum(['warn', 'error', 'off']);
+
+/**
+ * Default lane health mode (advisory by default)
+ */
+export const DEFAULT_LANE_HEALTH_MODE: LaneHealthMode = 'warn';
+
+// ---------------------------------------------------------------------------
+// Coverage / test policy interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * WU-1262: Resolved coverage configuration
+ * Contains threshold and mode derived from methodology policy
+ */
+export interface CoverageConfig {
+  /** Coverage threshold (0-100) */
+  threshold: number;
+  /** Coverage mode (block, warn, or off) */
+  mode: CoverageMode;
+}
+
+/**
+ * WU-2020: Focused coverage policy interface (ISP-compliant).
+ * Single-responsibility: coverage threshold and enforcement mode.
+ */
+export interface CoveragePolicy {
+  /** Coverage threshold (0-100) */
+  threshold: number;
+  /** Coverage mode (block, warn, or off) */
+  mode: CoverageMode;
+}
+
+/**
+ * WU-2020: Focused test runner policy interface (ISP-compliant).
+ * Single-responsibility: whether tests are mandatory for completion.
+ */
+export interface TestRunnerPolicy {
+  /** Whether tests are required for completion (from methodology.testing) */
+  tests_required: boolean;
+}
+
+/**
+ * WU-1280: Resolved test policy configuration
+ * Extends CoverageConfig with tests_required from methodology policy.
+ *
+ * WU-2020: Now defined as the intersection of CoveragePolicy and
+ * TestRunnerPolicy. Consumers that only need coverage or test-runner
+ * semantics should prefer the focused interfaces.
+ */
+export interface TestPolicy extends CoveragePolicy, TestRunnerPolicy {}
+
+// ---------------------------------------------------------------------------
+// Gates commands interface
+// ---------------------------------------------------------------------------
+
+/**
+ * WU-1356: Gates commands configuration type
+ */
+export interface GatesCommands {
+  test_full: string;
+  test_docs_only: string;
+  test_incremental: string;
+  lint?: string;
+  typecheck?: string;
+  format?: string;
+  migration_verify: string;
+}

package/packs/software-delivery/src/policy/index.ts

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * Software Delivery Pack — Policy Barrel
+ *
+ * WU-2674 (INIT-058 L3): Cohesion-closed policy bundle moved from
+ * @lumenflow/core/src/. These modules share tight internal coupling
+ * (CoverageMode crosses them) and evolve together.
+ *
+ * @module packs/software-delivery/policy
+ */
+
+export * from './gates-schemas.js';
+export * from './resolve-policy.js';
+export * from './coverage-gate.js';
+export * from './gates-config.js';
+export * from './gates-presets.js';
+export * from './gates-config-internal.js';
+export * from './gates-agent-mode.js';
+export * from './gates-coverage.js';
+export * from './package-manager-resolver.js';