[repository-quality] Repository Quality: Package-Level Mutable State & init() Side Effects

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Package-Level Mutable State & init() Side Effects

Analysis Date: 2026-10-30
Focus Area: Package-Level Mutable State & init() Side Effects
Strategy Type: Custom
Custom Area: Yes — prior runs covered panics, errors, tests, nolint, HTTP; none examined hidden global state and init-order coupling, which affects test isolation and WASM builds.

Executive Summary

Non-linter production code has only 5 init() functions, which is a healthy baseline. The riskiest is pkg/workflow/cooldown.go:14, which mutates ghAwOnSectionKeys (declared in event_validation.go:83) from another file. Correctness depends on Go file init order, and the map is read during validation elsewhere (event_validation.go:146, github_app_requirements.go:217).

Several exported package-level slices and maps can be mutated by any importer: DefaultGitHubToolsets, ActionFriendlyGitHubToolsets, DefaultEndorsementReactions, DefaultMarshalOptions, BuiltinGraderRegistry, ValidationConfig and others. There are also about 243 package-level map/slice vars, plus test-seam function vars in engine_definition.go:399-413 guarded by a mutex that production code does not hold when reading them.

Full Analysis Report

Focus Area: Package-Level Mutable State & init()

Metrics Collected:

Metric	Value	Status
Non-linter, non-test init() funcs	5 (workflow x2, parser wasm, styles, cmd/main)	✅
init() mutating another file's global	1 (cooldown.go)	⚠️
init() building derived maps	1 (runtime_definitions.go:185)	⚠️
Exported mutable slice/map vars in pkg/workflow	≥9	⚠️
Package-level map/slice/pointer vars (all non-test)	~243	⚠️
Test-seam func/URL vars in prod code	knownEngineImports* (9 refs)	⚠️
os.Getenv in non-test pkg code	68 calls / 37 files	⚠️
Mutex-guarded globals	~15	✅

Findings

Strengths

• Very few init() functions; linters (packagelevelmutableslicemap) already exist.
• Mutable singletons such as the spinner and timezone are mutex-guarded.

Areas for Improvement

• 🟠 cooldown.go:14 mutates ghAwOnSectionKeys at init; the key belongs in the literal.
• 🟡 Exported mutable slices and maps (see above) can be changed by any importer and cannot be made const.
• 🟡 runtime_definitions.go:185 builds commandToRuntime and actionRepoToRuntime in init(); these can use sync.OnceValue or an initializer function.
• ⚪ os.Getenv is scattered (engine_secrets.go 7, shell_completion.go 6); envutil exists but is not used consistently.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Remove cross-file init() mutation of ghAwOnSectionKeys

Priority: High
Estimated Effort: Small
Focus Area: Package-Level Mutable State

Description: Move the cooldown key into the ghAwOnSectionKeys literal and delete init() in cooldown.go.

Acceptance Criteria:

• No init() in pkg/workflow/cooldown.go
• go test ./pkg/workflow/... passes

Code Region: pkg/workflow/cooldown.go, pkg/workflow/event_validation.go

Add "cooldown": true to ghAwOnSectionKeys in event_validation.go and remove init() from cooldown.go. Run make fmt and targeted tests.

---

Task 2: Replace init()-built runtime lookup maps with lazy builders

Priority: Medium
Estimated Effort: Small
Focus Area: Package-Level Mutable State

Description: Replace init() in runtime_definitions.go with sync.OnceValue-based accessors, or a var initializer function.

Acceptance Criteria:

• commandToRuntime and actionRepoToRuntime are not assigned in init()
• Existing tests pass

Code Region: pkg/workflow/runtime_definitions.go

Refactor commandToRuntime/actionRepoToRuntime into var X = func() map[string]*Runtime {...}() initializers (pattern used in permissions.go:12). Keep behavior identical.

---

Task 3: Harden exported mutable defaults

Priority: Medium
Estimated Effort: Medium
Focus Area: Package-Level Mutable State

Description: Convert exported slice/map defaults into accessor functions returning copies (slices.Clone/maps.Clone), or unexport them, for DefaultGitHubToolsets, ActionFriendlyGitHubToolsets, GitHubToolsetsExcludedFromAll, DefaultEndorsementReactions, DefaultDisapprovalReactions, DefaultGraderIDs, DefaultMarshalOptions.

Acceptance Criteria:

• Callers updated; no external mutation possible
• Build and tests pass

Code Region: pkg/workflow/github_toolsets.go, mcp_github_config.go, graders_config.go, yaml_options.go

Unexport each listed var and add a func returning a clone. Update all references with grep. Run make fmt and go test ./pkg/workflow/....

---

Task 4: Encapsulate knownEngineImports test seams

Priority: Low
Estimated Effort: Medium
Focus Area: Package-Level Mutable State

Description: Group URL/client/download seams in engine_definition.go:399-413 into a struct with a constructor, so tests inject it instead of overwriting globals while production reads occur without the mutex.

Acceptance Criteria:

• No mutable package-level function vars for the loader
• Tests use injected config and can run in parallel

Code Region: pkg/workflow/engine_definition.go

Introduce a knownEngineImportsLoader struct holding base URLs, HTTP client factory and download func; keep a default instance. Update tests.

---

📊 Historical Context

14 runs recorded; all were custom areas (most recent: Runtime Panic Surface, Lint Suppression Debt, HTTP Server Hardening).

---

🎯 Recommendations

Immediate Actions (This Week)

1. Task 1 — Priority: High

Short-term Actions (This Month)

1. Tasks 2 and 3 — Priority: Medium

Long-term Actions (This Quarter)

1. Task 4 — Priority: Low

---

📈 Success Metrics

• Production init() funcs: 5 → 3
• Exported mutable slice/map vars in pkg/workflow: ≥9 → 0

---

Next Steps

1. Review and prioritise the tasks above
2. Assign tasks to Copilot coding agent via planner agent
3. Track progress
4. Re-evaluate in 1 quarter

---

Generated by Repository Quality Improvement Agent
Next analysis: 2026-10-31 — Focus area selected by diversity algorithm

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · ~19 AIC · ⌖ ~1 AIC · ⊞ 9.8K · ◷

• expires on Oct 31, 2026, 4:56 AM UTC-08:00