[repository-quality] Repository Quality Improvement: Options Struct Pattern Adoption for High-Arity Functions (2026-07-16)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Options Struct Pattern Adoption for High-Arity Functions

Analysis Date: 2026-07-16
Focus Area: Options Struct Pattern Adoption for High-Arity Functions
Strategy Type: Custom
Custom Area: Yes — the excessivefuncparams linter (DefaultMaxParams=8) already enforces this boundary, yet 2 functions actively violate the threshold and 21 sit exactly at the limit. A repeating owner, repo, hostname, verbose quad appears verbatim in 4+ functions across logs_download.go, a clear options-struct extraction opportunity.

Executive Summary

The excessivefuncparams linter is configured but not fully effective: 2 production functions (9 parameters each) escape enforcement with //nolint:excessivefuncparams suppressions, and 21 functions sit exactly at the 8-parameter limit — at threshold but not yet over. The most concentrated problem is in pkg/cli/logs_download.go where four sibling functions repeat an identical (ctx, runID, outputDir, verbose, owner, repo, hostname, artifactFilter) signature, making every call-site update expensive and error-prone.

Beyond logs_download.go, the pattern recurs in update_actions.go (both public and private variants carry workflowsDir, engineOverride, verbose, disableReleaseBump, noCompile, coolDown, approve), workflow/copilot_engine_execution.go (boolean-flag explosion with 4 bool positionals), and workflow/nodejs.go (8 primitive positionals with no grouping).

Introducing options structs at these hotspots reduces parameter count at call sites, improves readability, enables future extension without signature churn, and allows the nolint suppressions to be deleted.

Full Analysis Report

Focus Area: Options Struct Pattern Adoption for High-Arity Functions

Current State Assessment

Metrics Collected:

Metric	Value	Status
Functions > 8 params (linter threshold)	2	❌
Functions = 8 params (at threshold)	21	⚠️
//nolint:excessivefuncparams suppressions	0 in pkg/ (inline per-line)	⚠️
Sibling functions sharing identical owner, repo, hostname, verbose quad	4 in logs_download.go	❌
Repeated verbose, disableReleaseBump, noCompile, coolDown, approve group	2 in update_actions.go	⚠️
Boolean positional parameter density (≥3 consecutive bools)	5 functions	⚠️
Functions already using opts/options/options struct	scattered (e.g., TrialOptions, AddOptions)	✅

Highest-priority violators:

File	Function	Params	Issue
pkg/cli/logs_run_processor.go:104	downloadRunArtifactsConcurrent	9	Exceeds linter limit
pkg/cli/update_actions.go:606	updateActionsInWorkflowFiles	9	Exceeds linter limit
pkg/cli/logs_download.go:551,598,649,968	4 sibling download fns	8	Identical param quad repeated
pkg/workflow/copilot_engine_execution.go:463	buildCopilotStepEnv	8	3 consecutive bool positionals
pkg/workflow/nodejs.go:270	GenerateNpmInstallStepsWithScope	8	4 bool primitives at end

Findings

Strengths

• excessivefuncparams linter exists, is registered in spec_test.go, and has a configurable max-params flag.
• Many commands already use options structs: AddOptions, TrialOptions, UpdateWorkflowsOptions, AuditOptions.
• The 9-param functions are isolated (only 2 violations), making surgical fixes tractable.

Areas for Improvement

• [HIGH] 2 functions violate the enforced 8-param linter threshold.
• [HIGH] 4 sibling functions in logs_download.go share an identical (ctx, runID, outputDir, verbose, owner, repo, hostname, artifactFilter) signature — a downloadArtifactsOptions struct would collapse these call sites.
• [MEDIUM] buildCopilotStepEnv (method on CopilotEngine) passes isBYOKMode, sandboxEnabled, modelConfigured bool as three consecutive positional booleans — swapping argument order silently changes behavior.
• [MEDIUM] GenerateNpmInstallStepsWithScope ends with includeNodeSetup, isGlobal, runInstallScripts, cooldownEnabled bool — four booleans with no names at call sites.
• [LOW] RunWorkflowInteractively (public API in run_interactive.go) exposes 7 non-context parameters; an options struct would ease future extension without a breaking API change.

Detailed Analysis

pkg/cli/logs_download.go — shared owner/repo/hostname/verbose quad

The four functions downloadArtifactsByName, retryCriticalArtifacts, downloadRunArtifacts, and ensureUsageAwInfoFallback all accept (ctx, runID, outputDir, verbose bool, owner, repo, hostname string, artifactFilter []string). Every internal call thread passes all eight arguments individually. A small struct:

type downloadArtifactsOptions struct {
    RunID          int64
    OutputDir      string
    Verbose        bool
    Owner          string
    Repo           string
    Hostname       string
    ArtifactFilter []string
}

would collapse each signature to (ctx context.Context, opts downloadArtifactsOptions) — well under the 8-param limit.

pkg/cli/update_actions.go — public+private mirror pair

UpdateActionsInWorkflowFiles (public, 8 params) delegates to updateActionsInWorkflowFiles (private, 9 params). Both carry workflowsDir, engineOverride string, verbose, disableReleaseBump bool, noCompile bool, coolDown time.Duration, approve bool. An UpdateActionsOptions struct already follows the established XxxOptions convention.

pkg/workflow/copilot_engine_execution.go:463 — boolean positional explosion

buildCopilotStepEnv passes isBYOKMode, sandboxEnabled, modelConfigured bool as three consecutive booleans. If a caller swaps any two, the compiler accepts it silently.

---

🤖 Tasks for Copilot Agent

NOTE TO PLANNER AGENT: Split the following tasks into individual work items.

Improvement Tasks

Task 1: Introduce downloadArtifactsOptions struct in logs_download.go

Priority: High
Estimated Effort: Medium
Focus Area: Options Struct Pattern Adoption

Description: Four sibling functions in pkg/cli/logs_download.go — downloadArtifactsByName (line 551), retryCriticalArtifacts (line 598), downloadRunArtifacts (line 649), and ensureUsageAwInfoFallback (line 968) — all share the parameter quad (verbose bool, owner, repo, hostname string) alongside runID int64 and artifactFilter []string. Introduce an unexported downloadArtifactsOptions struct carrying RunID, OutputDir, Verbose, Owner, Repo, Hostname, and ArtifactFilter, and refactor all four functions to accept (ctx context.Context, opts downloadArtifactsOptions). Update all internal call sites. This brings all four functions below the 8-param linter threshold.

Acceptance Criteria:

• downloadArtifactsOptions struct defined in pkg/cli/logs_download.go
• All four functions refactored to (ctx, opts downloadArtifactsOptions) signatures
• All internal call sites in logs_download.go updated
• Also update pkg/cli/forecast_compute.go:248 (forecastDownloadUsageArtifact) and pkg/cli/audit_diff.go:930 (loadRunSummaryForDiff) which share the same owner, repo, hostname, verbose pattern
• make fmt && make lint pass with no new suppressions
• All existing tests pass (make test)

Code Region: pkg/cli/logs_download.go, pkg/cli/forecast_compute.go, pkg/cli/audit_diff.go

In `pkg/cli/logs_download.go`, introduce an unexported struct:

type downloadArtifactsOptions struct {
    RunID          int64
    OutputDir      string
    Verbose        bool
    Owner          string
    Repo           string
    Hostname       string
    ArtifactFilter []string
}

Refactor these four functions to accept `(ctx context.Context, opts downloadArtifactsOptions)` instead of their current 8-parameter signatures:
- `downloadArtifactsByName` (line 551)
- `retryCriticalArtifacts` (line 598)
- `downloadRunArtifacts` (line 649)
- `ensureUsageAwInfoFallback` (line 968)

Also apply the same struct to `forecastDownloadUsageArtifact` in `pkg/cli/forecast_compute.go:248` and `loadRunSummaryForDiff` in `pkg/cli/audit_diff.go:930` — both share the identical `(ctx, runID, outputDir, verbose, owner, repo, hostname, ...)` pattern.

Update every call site within the affected files. Do not change public API signatures. Run `make fmt && make lint && make test` before finishing.

---

Task 2: Extract UpdateActionsOptions to fix the 9-param updateActionsInWorkflowFiles

Priority: High
Estimated Effort: Small
Focus Area: Options Struct Pattern Adoption

Description: updateActionsInWorkflowFiles at pkg/cli/update_actions.go:606 has 9 parameters (ctx, deps, workflowsDir, engineOverride, verbose, disableReleaseBump, noCompile, coolDown, approve) and violates the excessivefuncparams linter threshold. Its public wrapper UpdateActionsInWorkflowFiles (line 602) has 8 parameters. Introduce an UpdateActionsOptions struct (following the established XxxOptions pattern in the package) carrying the non-context fields, collapse both signatures, and update all call sites.

Acceptance Criteria:

• UpdateActionsOptions struct defined in pkg/cli/update_actions.go (or update_actions_options.go)
• Both UpdateActionsInWorkflowFiles (public) and updateActionsInWorkflowFiles (private) refactored
• All call sites in pkg/cli/ updated
• No //nolint:excessivefuncparams suppressions needed
• make fmt && make lint && make test pass

Code Region: pkg/cli/update_actions.go

In `pkg/cli/update_actions.go`, create an `UpdateActionsOptions` struct:

type UpdateActionsOptions struct {
    WorkflowsDir       string
    EngineOverride     string
    Verbose            bool
    DisableReleaseBump bool
    NoCompile          bool
    CoolDown           time.Duration
    Approve            bool
}

Refactor `UpdateActionsInWorkflowFiles` (line 602, public) and `updateActionsInWorkflowFiles` (line 606, private) to accept `(ctx context.Context, deps actionUpdateDeps, opts UpdateActionsOptions)`. The public function can omit `deps` if it constructs it internally. Update all callers in `pkg/cli/`. Run `make fmt && make lint && make test` before finishing.

---

Task 3: Replace boolean positionals in buildCopilotStepEnv with a config struct

Priority: Medium
Estimated Effort: Small
Focus Area: Options Struct Pattern Adoption

Description: (e *CopilotEngine) buildCopilotStepEnv at pkg/workflow/copilot_engine_execution.go:463 takes 3 consecutive bool positionals (isBYOKMode, sandboxEnabled, modelConfigured) plus a string copilotSDKServerArgsJSON. Swapping any two booleans compiles silently. Introduce an unexported copilotStepEnvConfig struct and refactor the method to accept it as a single config argument.

Acceptance Criteria:

• copilotStepEnvConfig struct introduced in pkg/workflow/copilot_engine_execution.go
• buildCopilotStepEnv signature simplified to (workflowData *WorkflowData, llmProvider, modelEnvVar, timeoutValue string, cfg copilotStepEnvConfig) map[string]string
• All call sites within pkg/workflow/ updated
• make fmt && make lint && make test pass

Code Region: pkg/workflow/copilot_engine_execution.go

In `pkg/workflow/copilot_engine_execution.go`, introduce:

type copilotStepEnvConfig struct {
    IsBYOKMode            bool
    SandboxEnabled        bool
    ModelConfigured       bool
    CopilotSDKServerArgsJSON string
}

Refactor `buildCopilotStepEnv` to: `func (e *CopilotEngine) buildCopilotStepEnv(workflowData *WorkflowData, llmProvider, modelEnvVar, timeoutValue string, cfg copilotStepEnvConfig) map[string]string`

Update all callers in the same file. Run `make fmt && make lint && make test` before finishing.

---

Task 4: Refactor GenerateNpmInstallStepsWithScope to use a config struct

Priority: Medium
Estimated Effort: Small
Focus Area: Options Struct Pattern Adoption

Description: GenerateNpmInstallStepsWithScope at pkg/workflow/nodejs.go:270 has 8 parameters ending with four bool values (includeNodeSetup, isGlobal, runInstallScripts, cooldownEnabled). These boolean positionals are indistinguishable at call sites without looking up the signature. Introduce NpmInstallOptions and refactor.

Acceptance Criteria:

• NpmInstallOptions struct (or NpmInstallStepsConfig) defined in pkg/workflow/nodejs.go
• GenerateNpmInstallStepsWithScope refactored to accept the struct
• All call sites in pkg/workflow/ updated
• make fmt && make lint && make test pass

Code Region: pkg/workflow/nodejs.go

In `pkg/workflow/nodejs.go`, introduce:

type NpmInstallOptions struct {
    PackageName      string
    Version          string
    StepName         string
    CacheKeyPrefix   string
    IncludeNodeSetup bool
    IsGlobal         bool
    RunInstallScripts bool
    CooldownEnabled  bool
}

Refactor `GenerateNpmInstallStepsWithScope` to accept `(opts NpmInstallOptions) []GitHubActionStep`. Update all callers within `pkg/workflow/`. Run `make fmt && make lint && make test` before finishing.

---

Task 5: Refactor downloadRunArtifactsConcurrent (9 params) in logs_run_processor.go

Priority: High
Estimated Effort: Small
Focus Area: Options Struct Pattern Adoption

Description: downloadRunArtifactsConcurrent at pkg/cli/logs_run_processor.go:104 has 9 parameters, violating the linter threshold. Parameters outputDir, verbose, maxRuns, repoOverride, artifactFilter, evalsOnly, artifactSets should be grouped into a concurrentDownloadOptions struct (or reuse downloadArtifactsOptions from Task 1 if appropriate).

Acceptance Criteria:

• Struct defined in pkg/cli/logs_run_processor.go (or shared file)
• downloadRunArtifactsConcurrent refactored to (ctx context.Context, runs []WorkflowRun, opts concurrentDownloadOptions) []DownloadResult
• All call sites in pkg/cli/ updated
• No new //nolint:excessivefuncparams suppressions
• make fmt && make lint && make test pass

Code Region: pkg/cli/logs_run_processor.go

In `pkg/cli/logs_run_processor.go`, introduce:

type concurrentDownloadOptions struct {
    OutputDir      string
    Verbose        bool
    MaxRuns        int
    RepoOverride   string
    ArtifactFilter []string
    EvalsOnly      bool
    ArtifactSets   []string
}

Refactor `downloadRunArtifactsConcurrent` to `(ctx context.Context, runs []WorkflowRun, opts concurrentDownloadOptions) []DownloadResult`. Update all callers in `pkg/cli/`. Run `make fmt && make lint && make test` before finishing.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-15	Compile-Time Interface Satisfaction Assertions	Custom	Y	21 unguarded interfaces identified
2026-07-14	Logger Name Collision & Instantiation Hygiene	Custom	Y	3 duplicate logger names, 6 var log shadows
2026-07-08	Deprecated API Alias Proliferation & Zombie Callsite Cleanup	Custom	Y	3 GetGeminiAPITarget callsites, zombie functions
2026-07-07	Environment Variable Access Fragmentation	Custom	Y	45 bare nolint suppressions
2026-07-06	Context-Blind Sleep Gap	Custom	Y	7 time.Sleep calls in context-orphaned helpers

---

🎯 Recommendations

Immediate Actions (This Week)

1. Fix the 2 functions violating the 9-param linter threshold (updateActionsInWorkflowFiles, downloadRunArtifactsConcurrent) — Priority: High
2. Extract downloadArtifactsOptions to collapse the logs_download.go sibling quartet — Priority: High

Short-term Actions (This Month)

1. Apply options structs to the 21 functions at the 8-param boundary, prioritising public APIs — Priority: Medium
2. Eliminate consecutive boolean positionals in buildCopilotStepEnv and GenerateNpmInstallStepsWithScope — Priority: Medium

Long-term Actions (This Quarter)

1. Introduce a linter rule that flags 3+ consecutive bool parameters regardless of total count — Priority: Low

---

📈 Success Metrics

• Functions > 8 params: 2 → 0
• Functions = 8 params: 21 → < 10
• Sibling functions sharing identical param quad: 4 → 0
• Consecutive bool parameter groups (≥3): 5 → 0

---

Next Steps

1. Review and prioritise the 5 tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress on options struct adoption
4. Re-evaluate this focus area in 4 weeks

---

References:

• §29501502642

Generated by Repository Quality Improvement Agent

Generated by ⚡ Repository Quality Improvement Agent · 65.6 AIC · ⌖ 6.3 AIC · ⊞ 6.6K · ◷

• expires on Jul 17, 2026, 5:26 AM UTC-08:00

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-07-17T13:26:46.467Z.

Closed by Workflow