[file-diet] Refactor Large Go File: pkg/cli/logs.go

[agentic-workflows-dev]

Overview

The file pkg/cli/logs.go has grown to 1,354 lines, significantly exceeding the healthy 800-line threshold. This makes it difficult to navigate, maintain, and test effectively. The file contains the core gh aw logs command implementation with multiple distinct functional areas that should be split into focused modules.

Current State

• File: pkg/cli/logs.go
• Size: 1,354 lines (69% over threshold)
• Test Coverage: 1,646 lines of tests (1.22 ratio - excellent coverage to preserve!)
• Complexity: High - handles CLI command setup, GitHub API interactions, concurrent downloads, metrics extraction, output rendering, and workflow discovery

Functional Analysis

The file contains these distinct functional areas:

1. CLI Command Setup (lines 121-282): Cobra command definition with extensive flags
2. Core Download Orchestration (lines 283-689): Main DownloadWorkflowLogs function with pagination logic
3. Concurrent Download Operations (lines 690-948): Artifact downloading with progress tracking
4. GitHub API Integration (lines 949-1089): Workflow run listing and job status fetching
5. Output & Display (lines 1090-1272): Table rendering and metrics formatting
6. Utility Functions (lines 1273-1354): Workflow name discovery and helper functions

Refactoring Strategy

Proposed File Splits

1. logs_command.go (CLI Command Definition)

Responsibility: Cobra command setup, flag definitions, and command entry point
Functions to move:

• NewLogsCommand() (lines 121-282)

Estimated LOC: ~200 lines

Rationale: Separates the CLI interface layer from business logic

---

2. logs_orchestrator.go (Download Orchestration)

Responsibility: Main download workflow coordination, pagination, iteration logic
Functions to move:

• DownloadWorkflowLogs() (lines 283-689)

Estimated LOC: ~450 lines

Rationale: Core orchestration logic is complex enough to warrant its own file

---

3. logs_download.go (Concurrent Download Operations)

Responsibility: Artifact downloading, concurrent processing, cache management
Functions to move:

• downloadRunArtifactsConcurrent() (lines 690-948)
• Related download helper functions

Estimated LOC: ~300 lines

Rationale: Isolates concurrent operations and artifact handling logic

---

4. logs_github_api.go (GitHub API Integration)

Responsibility: GitHub API calls for workflow runs, jobs, and statuses
Functions to move:

• listWorkflowRunsWithPagination() (lines 949-1089)
• fetchJobStatuses() (lines 26-71)
• fetchJobDetails() (lines 74-119)

Estimated LOC: ~250 lines

Rationale: Encapsulates all GitHub API interactions in one place

---

5. logs_display.go (Output & Rendering)

Responsibility: Table formatting, metrics display, console output
Functions to move:

• displayLogsOverview() (lines 1090-1272)

Estimated LOC: ~200 lines

Rationale: Separates presentation logic from data operations

---

6. logs_utils.go (Utility Functions)

Responsibility: Helper functions for workflow discovery and common operations
Functions to move:

• getAgenticWorkflowNames() (lines 1273-1332)
• contains() (lines 1335-1342)
• Other utility functions

Estimated LOC: ~100 lines

Rationale: Keeps utilities separate and easily reusable

---

Shared Types & Constants

Create logs_types.go to hold:

• All struct definitions (WorkflowRun, ProcessedRun, DownloadResult, LogMetrics, etc.)
• Constants (BatchSize, MaxConcurrentDownloads, MaxIterations)
• The logger: var logsLog = logger.New("cli:logs")

Estimated LOC: ~100 lines

Test Coverage Plan

The existing test file logs_test.go (1,646 lines) already provides excellent coverage. When splitting the file:

Testing Strategy

1. Preserve Existing Tests: All 1,646 lines of existing tests remain valid
2. Run Tests Frequently: After each file split, verify make test-unit passes
3. No Test Rewrite Needed: Since we're preserving public APIs, existing tests continue to work

Optional Test Organization

Consider splitting logs_test.go to match the new structure (optional, not required):

• logs_command_test.go - Command flag parsing tests
• logs_orchestrator_test.go - Main workflow tests
• logs_download_test.go - Concurrent download tests
• logs_github_api_test.go - API integration tests
• logs_display_test.go - Output formatting tests

Target Coverage: Maintain current >80% coverage for all new files

Implementation Guidelines

Phase 1: Create Shared Types File

1. Create pkg/cli/logs_types.go
2. Move all struct definitions, constants, and the logger
3. Update imports in logs.go
4. Verify make test-unit passes

Phase 2: Extract Utility Functions (Smallest Impact)

1. Create pkg/cli/logs_utils.go
2. Move getAgenticWorkflowNames(), contains() and other helpers
3. Update imports
4. Verify tests pass

Phase 3: Extract Display Logic

1. Create pkg/cli/logs_display.go
2. Move displayLogsOverview() and related rendering functions
3. Verify tests pass

Phase 4: Extract GitHub API Layer

1. Create pkg/cli/logs_github_api.go
2. Move all GitHub API interaction functions
3. Verify tests pass

Phase 5: Extract Download Operations

1. Create pkg/cli/logs_download.go
2. Move downloadRunArtifactsConcurrent() and related functions
3. Verify tests pass

Phase 6: Extract Orchestrator

1. Create pkg/cli/logs_orchestrator.go
2. Move DownloadWorkflowLogs() function
3. Verify tests pass

Phase 7: Simplify Command File

1. Verify logs_command.go only contains NewLogsCommand()
2. Rename logs.go to logs_command.go (or keep as is)
3. Final verification of all tests

Critical Rules

1. Preserve Behavior: Ensure all existing functionality works identically
2. Maintain Exports: Keep public API unchanged (NewLogsCommand() and DownloadWorkflowLogs())
3. Add Comments: Document module boundaries at the top of each new file
4. Run Tests After Each Split: Verify make test-unit passes after each phase
5. Update Imports: Ensure all internal function calls work across new file boundaries
6. Keep Logger Shared: Use the same logsLog logger across all files via logs_types.go

Acceptance Criteria

• Original file is split into 7 focused files (6 new + 1 types file)
• Each new file is under 500 lines
• All tests pass (make test-unit)
• Test coverage remains ≥80%
• No breaking changes to public API (NewLogsCommand(), DownloadWorkflowLogs())
• Code passes linting (make lint)
• Build succeeds (make build)
• Each file has a clear comment at the top explaining its purpose

Additional Context

• Repository Guidelines: Follow patterns in AGENTS.md - prefer many smaller files grouped by functionality
• Code Organization: Review existing multi-file patterns in pkg/workflow/ for consistency
• Testing: Match existing test patterns in pkg/cli/*_test.go
• Console Output: All user-facing messages already use console.Format*Message() helpers

Campaign Context

This refactoring is part of the go-file-size-reduction-20330678188 campaign to maintain a healthy, modular codebase.

Current Status:

• Date: 2025-12-18
• Largest File: pkg/cli/logs.go (1,354 lines)
• Files Over Threshold: 21 files in the codebase exceed 800 lines

---

Priority: Medium
Effort: Large (7 files to create, extensive function moves, careful testing required)
Expected Impact: Significantly improved maintainability, easier navigation, clearer module boundaries, better testability

AI generated by Daily File Diet