Implement Phase 2 validation helpers to consolidate duplicate patterns

[Copilot]

Semantic analysis of pkg/workflow/ identified 70+ duplicate validation patterns across 252 files. This implements the 6 helper functions previously documented as Phase 2 refactoring targets.

Implementation

Map field extraction helpers:

• getMapFieldAsString(map, key, default) - Type-safe string extraction with fallback
• getMapFieldAsMap(map, key) - Nested map extraction, returns nil on type mismatch
• getMapFieldAsBool(map, key, default) - Boolean extraction with default
• getMapFieldAsInt(map, key, default) - Integer extraction, delegates to parseIntValue for multi-type support

Validation utilities:

• isEmptyOrNil(value) - Unified emptiness check for nil, empty strings, zero numerics, false booleans, empty collections
• dirExists(path) - Directory existence check with validation

Usage Example

Before:

// Duplicated across 70+ locations
val, exists := configMap["max-size"]
if !exists {
    return 100  // default
}
intVal, ok := val.(int)
if !ok {
    log.Printf("Field max-size is not an int: got %T", val)
    return 100
}

After:

maxSize := getMapFieldAsInt(configMap, "max-size", 100)

Design

All helpers follow consistent patterns:

• Return sensible defaults on extraction failure (empty string, nil, false, 0)
• Log type mismatches via validationHelpersLog for debugging
• Match conventions from existing config_helpers.go utilities

Existing code continues working unchanged. New validators can adopt these helpers to reduce duplication.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[refactor] Semantic Function Clustering Analysis - 2026-02-07</issue_title>
<issue_description>### Executive Summary

Comprehensive semantic analysis of 252 Go source files in pkg/workflow/ identified 1,309 functions with strong semantic organization by naming conventions. The analysis reveals excellent code organization with clear naming patterns, but identifies specific refactoring opportunities around validation helpers and configuration parsing utilities.

Key Findings:

• 140 functions with Get prefix (excellent accessor organization)
• 123 functions ending in Config (configuration parsing/handling - opportunity for consolidation)
• 113 functions with parse prefix (parsing layer well-organized)
• 97 functions with generate prefix (generation pattern well-structured)
• Phase 2 validation helpers already documented in validation_helpers.go:183-190

Critical Discovery: The codebase already identifies 70+ duplicate validation patterns in pkg/workflow/validation_helpers.go lines 183-190, providing a clear roadmap for Phase 2 refactoring.

---

Analysis Methodology

1. Discovered 492 non-test Go files across entire pkg/ directory
2. Focused analysis on pkg/workflow/ (252 files, 1,309 functions)
3. Clustered functions by semantic naming patterns (prefix/suffix analysis)
4. Identified duplicate patterns using grep and Serena semantic code analysis
5. Evaluated file organization against Go best practices

---

Function Inventory

By Semantic Clusters

Top 15 Prefix Clusters:

• Get: 140 functions (accessors, getters)
• parse: 113 functions (parsing operations)
• generate: 97 functions (generation/creation)
• build: 76 functions (builders)
• extract: 76 functions (extraction operations)
• get: 61 functions (lowercase accessors - potential inconsistency)
• validate: 61 functions (validation operations)
• New: 48 functions (constructors - excellent Go idiom)
• Build: 36 functions (uppercase builders)
• is: 34 functions (predicates)
• create: 31 functions (creation operations)
• format: 28 functions (formatting operations)
• compute: 23 functions (computation operations)
• apply: 21 functions (application operations)
• add: 19 functions (addition operations)

Top 15 Suffix Clusters:

• Config: 123 functions (configuration handling - high consolidation opportunity)
• Step: 53 functions (workflow step generation)
• Steps: 47 functions (multiple step generation)
• Script: 40 functions (script generation)
• Job: 28 functions (job building)
• Mode: 19 functions (mode handling)
• Map: 18 functions (map operations)
• Trigger: 17 functions (trigger handling)
• Name: 17 functions (name extraction/formatting)
• Version: 16 functions (version handling)
• Domains: 11 functions (domain handling)
• Engine: 11 functions (engine abstraction)
• Args: 10 functions (argument processing)
• Expression: 10 functions (expression parsing)
• Permissions: 10 functions (permissions handling)

---

Identified Refactoring Opportunities

1. Phase 2 Validation Helpers (HIGH PRIORITY - Already Documented)

Status: 🎯 Clear actionable plan already exists
Location: pkg/workflow/validation_helpers.go:183-190

The codebase already documents Phase 2 refactoring needs:

// The following helper functions are planned for Phase 2 refactoring and will
// consolidate 70+ duplicate validation patterns identified in the semantic analysis:
// - isEmptyOrNil() - Check if a value is empty, nil, or zero
// - getMapFieldAsString() - Safely extract a string field from a map[string]any
// - getMapFieldAsMap() - Safely extract a nested map from a map[string]any
// - getMapFieldAsBool() - Safely extract a boolean field from a map[string]any
// - getMapFieldAsInt() - Safely extract an integer field from a map[string]any
// - dirExists() - Check if a directory exists at the given path

Existing Partial Implementations Found:

• ParseBoolFromConfig in config_helpers.go:208
• ParseIntFromConfig in config_helpers.go:189
• extractStringFromMap in config_helpers.go:87
• ExtractStringField in frontmatter_types.go:438
• ExtractIntField in frontmatter_types.go:449
• parseUpdateEntityBoolField in update_entity_helpers.go:216

Issue: Multiple implementations with different signatures and behaviors exist across files. This creates:

• Inconsistent error handling
• Difficult code navigation
• Duplication of similar logic

Recommendation:

1. Implement the 6 Phase 2 helpers in validation_helpers.go
2. Create a migration guide for existing code
3. Gradually migrate calling code to use centralized helpers
4. Add comprehensive unit tests for new helpers

Estimated Impact:

• Consolidates 70+ duplicate patterns
• Reduces code duplication by 10-15%
• Provides consistent validation...

• Fixes [refactor] Semantic Function Clustering Analysis - 2026-02-07 #14309

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[github-actions]

🔍 PR Triage Results

Category: refactor | Risk: medium | Priority: 60/100

Scores Breakdown

• Impact: 35/50 - Major refactoring consolidating 70+ duplicate validation patterns across the codebase. Significant improvement to code quality and maintainability. Reduces code duplication by 10-15%.
• Urgency: 9/30 - Tech debt reduction (4.1 hours old). Draft status with extensive changes (586 additions). CI unstable needs attention.
• Quality: 16/20 - Excellent rationale documenting the consolidation of 70+ duplicate patterns. Comprehensive test coverage with 83 test cases. Draft status appropriate for this size of refactoring.

📋 Recommended Action: batch_review

This high-value refactoring should be reviewed together with PRs #14313 and #14301 as part of the code quality improvements batch (batch-code-quality-001). The changes consolidate duplicate validation patterns and provide reusable helper functions that will benefit the entire codebase.

Batch Context: Review with other code quality PRs to ensure consistent patterns and identify any overlapping changes.

---

Triaged by PR Triage Agent on 2026-02-07

AI generated by PR Triage Agent

[Copilot]

Pull request overview

Adds Phase 2 validation helper utilities to pkg/workflow to centralize common “map field extraction” and “emptiness / filesystem existence” checks, backed by new unit tests.

Changes:

• Implemented Phase 2 helpers: isEmptyOrNil, getMapFieldAsString, getMapFieldAsMap, getMapFieldAsBool, getMapFieldAsInt, and dirExists.
• Added comprehensive unit tests covering the new helper behaviors across multiple input types.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
pkg/workflow/validation_helpers.go	Adds the Phase 2 helper implementations (emptiness checks, safe map field extraction, directory existence).
pkg/workflow/validation_helpers_test.go	Adds new unit tests validating the new helper behaviors.

Comments suppressed due to low confidence (1)

pkg/workflow/validation_helpers.go:242

• The doc comment says empty “collections (slices, maps)” return true, but the implementation only checks []any and map[string]any. Passing []string, []int, map[string]string, etc. will currently return false even when empty. Either extend the implementation to handle any slice/map type (reflection-based) or tighten the comment to match the actual supported types.

	case []any:
		return len(typedValue) == 0
	case map[string]any:
		return len(typedValue) == 0
	}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

isEmptyOrNil only treats a nil interface as empty; typed-nil values (e.g., a nil *T stored in an interface) will not hit the candidate == nil check and will be treated as non-empty. If this helper is meant to represent “absent” values broadly, consider adding a typed-nil check (typically via reflection) so nil pointers/interfaces/maps/slices are handled consistently, or narrow the doc to the supported inputs.

This issue also appears on line 238 of the same file.

[Copilot]

TestDirExists uses a hard-coded absolute POSIX path ("/nonexistent/path/to/directory") to assert non-existence. This makes the test less portable (e.g., Windows paths) and could theoretically exist in some environments. Prefer constructing a guaranteed-missing path using t.TempDir() + filepath.Join(...) so the test is OS-agnostic and deterministic.