Refactor: Split permissions.go into focused modules (928→133 lines)

[Copilot]

Problem

pkg/workflow/permissions.go was a 928-line monolithic file mixing parsing, factory methods, and operations - making navigation and maintenance difficult.

Changes

Split into 4 focused modules by semantic responsibility:

permissions.go (133 lines)

• Type definitions: PermissionLevel, PermissionScope, Permissions
• Utility functions: GetAllPermissionScopes(), ContainsCheckout(), convertStringToPermissionScope()

permissions_parser.go (346 lines)

• PermissionsParser type and methods
• YAML/frontmatter parsing logic
• NewPermissionsParser(), ToPermissions(), IsAllowed(), HasContentsReadAccess()

permissions_factory.go (193 lines)

• 25+ New* factory methods
• Shorthand constructors: NewPermissionsReadAll(), NewPermissionsWriteAll()
• Combination constructors: NewPermissionsContentsReadIssuesWrite(), etc.

permissions_operations.go (247 lines)

• Operations: Set(), Get(), Merge()
• Rendering: RenderToYAML()
• Helper: mergePermissionMaps() (eliminates duplication)

Impact

• 86% reduction in main file size
• Each file has single, clear responsibility
• Zero API changes
• Net -10 lines from deduplication

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[refactor] Semantic Function Clustering Analysis - Code Organization Opportunities</issue_title>
<issue_description>Semantic analysis of Go codebase to identify refactoring opportunities through function clustering, outlier detection, and code organization patterns

Executive Summary

Analyzed 483 Go source files across the pkg/ directory (247 in workflow, 160 in CLI, 76 in supporting packages). The codebase demonstrates strong semantic organization with consistent naming conventions, but several high-impact refactoring opportunities exist:

• Large monolithic files: 10+ files exceed 750 lines with mixed responsibilities
• Helper file accumulation: 13 helper files with varying levels of cohesion
• Factory method concentration: Files like permissions.go (928 lines, 36+ factory methods)
• Validation pattern duplication: 76+ similar validation patterns across 32 files
• Configuration parsing patterns: Multiple parse*Config functions with similar logic

Impact: Improved maintainability, testability, and reduced cognitive overhead for developers.

---

Function Inventory by Package

Primary Packages Analysis

Package	Files	Lines (Est.)	Primary Purpose	Organization Quality
workflow	247	117K+	Core compilation/execution engine	⚠️ Some large files need splitting
cli	160	38K+	Command-line interface	⚠️ 4 files exceed 1000 lines
parser	30	Unknown	Parsing utilities	✅ Well organized
campaign	14	Unknown	Campaign management	✅ Focused scope
console	11	Unknown	UI/Output rendering	✅ Clean separation

Utility Packages (Well Organized ✅)

Small, focused packages with clear responsibilities:

• stringutil (5 files), logger (4 files), types (2 files)
• Single-file utilities: tty, timeutil, testutil, styles, sliceutil, repoutil, mathutil, gitutil, envutil, constants

---

Clustering Results

The codebase follows semantic underscore-separated naming with clear verb-prefix patterns:

File Naming Patterns (Semantic Grouping)

Pattern	Count	Purpose	Organization
compiler_*	26	Compilation orchestration	✅ Clear grouping
safe_outputs*	20	Safety boundary outputs	✅ Well organized
mcp_*	16	Model Context Protocol	✅ Cohesive cluster
create_*	8	GitHub entity creation	✅ One per entity type
update_*	7	GitHub entity updates	✅ Parallel to create_*
*_validation.go	31	Validation logic	✅ Separated from main logic
*_helpers.go	13	Helper functions	⚠️ Varying cohesion
*_config*.go	Multiple	Configuration parsing	⚠️ Some overlap

Function Naming Patterns

Workflow Package - Top Patterns:

59 parse*        (parseWorkflow, parseExpression, parseIssuesConfig)
56 get*          (getPermissions, getRequiredSecrets, getAllowedDomains)
50 generate*     (generateWorkflowHeader, generateSafeOutputsConfig)
37 extract*      (extractExpressions, extractSecrets, extractMetadata)
34 validate*     (validateExpression, validateSandbox, validateRuntimeMode)
32 is*           (isAllowed, isEnabled, isValid)
24 build*        (buildJob, buildStep, buildCopilotAssignmentStep)
14 render*       (renderYAML, renderSharedMCPConfig, renderGitHubMCP)
```

**CLI Package - Top Patterns:**
```
64 get*          (getConfig, getWorkflows, getStatus)
29 parse*        (parseFlags, parseWorkflow)
27 extract*      (extractLogs, extractMetrics)
25 ensure*       (ensureDirectory, ensureConfig)
20 run*          (runWorkflow, runCommand)
19 create*       (createCommand, createPR, createIssue)

Observation: Consistent camelCase for unexported functions, PascalCase for exported (idiomatic Go). No mixed patterns.

---

Identified Issues

1. Large Monolithic Files (Refactoring Priority: High)

Files with multiple semantic concerns that should be split:

Top 10 Largest Files

Rank	File	Lines	Package	Functions	Issues
1	add_command.go	1,218	cli	18	Combines workflow resolution, UI, addition, compilation, PR creation, file tracking
2	add_interactive.go	1,025	cli	23	Interactive UI + workflow operations + file operations mixed
3	trial_command.go	1,000	cli	Unknown	Trial execution command
4	mcp_server.go	1,000	cli	Unknown	MCP server management
5	safe_outputs_config_generation.go	978	workflow	5	Configuration generation from workflow data
6	permissions.go	928	workflow	36	36 factory methods + parsing + operators
7	init.go	868	cli	Unknown	Initialization logic
8	audit.go	864	cli	Unknow...

• Fixes [refactor] Semantic Function Clustering Analysis - Code Organization Opportunities #12291

---

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