diff --git a/pkg/workflow/close_entity_helpers.go b/pkg/workflow/close_entity_helpers.go index 433d807dd8c..e752ac26baa 100644 --- a/pkg/workflow/close_entity_helpers.go +++ b/pkg/workflow/close_entity_helpers.go @@ -1,3 +1,52 @@ +// Package workflow provides helper functions for closing GitHub entities. +// +// This file contains shared utilities for building close entity jobs (issues, +// pull requests, discussions). These helpers extract common patterns used across +// the three close entity implementations to reduce code duplication and ensure +// consistency in configuration parsing and job generation. +// +// # Organization Rationale +// +// These close entity helpers are grouped here because they: +// - Provide generic close entity functionality used by 3 entity types +// - Share common configuration patterns (target, filters, max) +// - Follow a consistent entity registry pattern +// - Enable DRY principles for close operations +// +// This follows the helper file conventions documented in the developer instructions. +// See skills/developer/SKILL.md#helper-file-conventions for details. +// +// # Key Functions +// +// Configuration Parsing: +// - parseCloseEntityConfig() - Generic close entity configuration parser +// - parseCloseIssuesConfig() - Parse close-issue configuration +// - parseClosePullRequestsConfig() - Parse close-pull-request configuration +// - parseCloseDiscussionsConfig() - Parse close-discussion configuration +// +// Entity Registry: +// - closeEntityRegistry - Central registry of all close entity definitions +// - closeEntityDefinition - Definition structure for close entity types +// +// # Usage Patterns +// +// The close entity helpers follow a registry pattern where each entity type +// (issue, pull request, discussion) is defined with its specific parameters +// (config keys, environment variables, permissions, scripts). This allows: +// - Consistent configuration parsing across entity types +// - Easy addition of new close entity types +// - Centralized entity type definitions +// +// # When to Use vs Alternatives +// +// Use these helpers when: +// - Implementing close operations for GitHub entities +// - Parsing close entity configurations from workflow YAML +// - Building close entity jobs with consistent patterns +// +// For create/update operations, see: +// - create_*.go files for entity creation logic +// - update_entity_helpers.go for entity update logic package workflow import ( diff --git a/pkg/workflow/git_helpers.go b/pkg/workflow/git_helpers.go index c63f58e5b13..df43312bf4f 100644 --- a/pkg/workflow/git_helpers.go +++ b/pkg/workflow/git_helpers.go @@ -1,3 +1,31 @@ +// Package workflow provides Git repository utilities for workflow compilation. +// +// This file contains helper functions for interacting with Git repositories +// to extract metadata such as tags and version information. These helpers are +// used during workflow compilation to determine release contexts and versioning. +// +// # Organization Rationale +// +// These Git utilities are grouped in a helper file because they: +// - Provide Git-specific functionality (tags, versions) +// - Are used by multiple workflow compilation modules +// - Encapsulate Git command execution and error handling +// - Have a clear domain focus (Git repository metadata) +// +// This follows the helper file conventions documented in the developer instructions. +// See skills/developer/SKILL.md#helper-file-conventions for details. +// +// # Key Functions +// +// Tag Detection: +// - GetCurrentGitTag() - Detect current Git tag from environment or repository +// +// # Usage Patterns +// +// These functions are primarily used during workflow compilation to: +// - Detect release contexts (tags vs. regular commits) +// - Extract version information for releases +// - Support conditional workflow behavior based on Git state package workflow import ( diff --git a/pkg/workflow/prompt_step_helper.go b/pkg/workflow/prompt_step_helper.go index 9f9ab9ab23e..6b732eab29f 100644 --- a/pkg/workflow/prompt_step_helper.go +++ b/pkg/workflow/prompt_step_helper.go @@ -1,3 +1,71 @@ +// Package workflow provides helper functions for generating prompt workflow steps. +// +// This file contains utilities for building GitHub Actions workflow steps that +// append prompt text to prompt files used by AI engines. These helpers extract +// common patterns used across multiple prompt generators (XPIA, temp folder, +// playwright, edit tool, etc.) to reduce code duplication and ensure security. +// +// # Organization Rationale +// +// These prompt step helpers are grouped here because they: +// - Provide common patterns for prompt text generation used by 5+ generators +// - Handle GitHub Actions expression extraction for security +// - Ensure consistent prompt step formatting across engines +// - Centralize template injection prevention logic +// +// This follows the helper file conventions documented in the developer instructions. +// See skills/developer/SKILL.md#helper-file-conventions for details. +// +// # Key Functions +// +// Static Prompt Generation: +// - generateStaticPromptStep() - Generate steps for static prompt text +// - generateStaticPromptStepWithExpressions() - Generate steps with secure expression handling +// +// # Usage Patterns +// +// These helpers are used when generating workflow steps that append text to +// prompt files. They follow two patterns: +// +// 1. **Static Text** (no GitHub Actions expressions): +// ```go +// generateStaticPromptStep(yaml, +// "Append XPIA security instructions to prompt", +// xpiaPromptText, +// data.SafetyPrompt) +// ``` +// +// 2. **Text with Expressions** (contains ${{ ... }}): +// ```go +// generateStaticPromptStepWithExpressions(yaml, +// "Append dynamic context to prompt", +// promptWithExpressions, +// shouldInclude) +// ``` +// +// The expression-aware helper extracts GitHub Actions expressions into +// environment variables to prevent template injection vulnerabilities. +// +// # Security Considerations +// +// Always use generateStaticPromptStepWithExpressions() when prompt text +// contains GitHub Actions expressions (${{ ... }}). This ensures: +// - Expressions are evaluated in controlled env: context +// - No inline shell script interpolation (prevents injection) +// - Safe placeholder substitution via JavaScript +// +// See specs/template-injection-prevention.md for security details. +// +// # When to Use vs Alternatives +// +// Use these helpers when: +// - Generating workflow steps that append text to prompt files +// - Working with static or expression-containing prompt text +// - Need consistent prompt step formatting across engines +// +// For other prompt-related functionality, see: +// - *_engine.go files for engine-specific prompt generation +// - engine_helpers.go for shared engine utilities package workflow import ( diff --git a/pkg/workflow/update_entity_helpers.go b/pkg/workflow/update_entity_helpers.go index 4500b17cd91..b74eedb3a9b 100644 --- a/pkg/workflow/update_entity_helpers.go +++ b/pkg/workflow/update_entity_helpers.go @@ -1,3 +1,63 @@ +// Package workflow provides helper functions for updating GitHub entities. +// +// This file contains shared utilities for building update entity jobs (issues, +// pull requests, discussions, releases). These helpers extract common patterns +// used across the four update entity implementations to reduce code duplication +// and ensure consistency in configuration parsing and job generation. +// +// # Organization Rationale +// +// These update entity helpers are grouped here because they: +// - Provide generic update entity functionality used by 4 entity types +// - Share common configuration patterns (target, max, field updates) +// - Support two field parsing modes (key existence vs. bool value) +// - Enable DRY principles for update operations +// +// This follows the helper file conventions documented in the developer instructions. +// See skills/developer/SKILL.md#helper-file-conventions for details. +// +// # Key Functions +// +// Configuration Parsing: +// - parseUpdateEntityConfig() - Generic update entity configuration parser +// - parseUpdateEntityBase() - Parse base configuration (max, target, target-repo) +// - parseUpdateEntityConfigWithFields() - Parse config with entity-specific fields +// - parseUpdateEntityBoolField() - Generic boolean field parser with mode support +// +// Field Parsing Modes: +// - FieldParsingKeyExistence - Field presence indicates it can be updated (issues, discussions) +// - FieldParsingBoolValue - Field's boolean value determines update permission (pull requests) +// +// # Usage Patterns +// +// The update entity helpers support two parsing strategies: +// +// 1. **Key Existence Mode** (for issues and discussions): +// Fields are enabled if the key exists in config, regardless of value: +// ```yaml +// update-issue: +// title: null # Can update title (key exists) +// body: null # Can update body (key exists) +// ``` +// +// 2. **Bool Value Mode** (for pull requests): +// Fields are enabled based on explicit boolean values: +// ```yaml +// update-pull-request: +// title: true # Can update title +// body: false # Cannot update body +// ``` +// +// # When to Use vs Alternatives +// +// Use these helpers when: +// - Implementing update operations for GitHub entities +// - Parsing update entity configurations from workflow YAML +// - Building update entity jobs with consistent patterns +// +// For create/close operations, see: +// - create_*.go files for entity creation logic +// - close_entity_helpers.go for entity close logic package workflow import (