[repository-quality] Repository Quality Improvement Report — context.Background() Call-Chain Leakage

[github-actions[bot]]

🎯 Repository Quality Improvement Report — context.Background() Call-Chain Leakage

Analysis Date: 2026-07-27
Focus Area: context.Background() Call-Chain Leakage — Uncancellable Sub-calls Despite Cobra Signal Context at Entry Points
Strategy Type: Custom
Custom Area: Yes — distinct from prior context-propagation runs (2026-06-03/09/22) which targeted exec.Command; this run targets wrappers and helper functions that hard-code context.Background() even when caller context exists

Executive Summary

The repository's entry-point commands consistently capture a cancellable context via signal.NotifyContext(context.Background(), ...) and thread it through cobra RunE handlers. However, 40 context.Background() calls exist in non-test production code below the entry points, many inside functions that are already called with a live context — or whose callers hold one. This creates silent cancellation dead zones: when a user presses Ctrl+C, the signal context is cancelled and most work stops cleanly, but calls routed through the affected helpers continue running until they time out or finish naturally.

The most impactful cluster is in pkg/workflow/github_cli.go: three convenience wrappers (ExecGH, RunGH, RunGHCombined) discard their callers' contexts and hard-code context.Background(), affecting 92 downstream call sites. Context-aware siblings (ExecGHContext, RunGHContext, RunGHCombinedContext) already exist and are the correct fix path. A secondary cluster in pkg/parser/remote_workflow_spec.go has three context.Background() network calls with an existing TODO comment acknowledging the gap.

Five high-value fixes would eliminate the largest leakage surface, propagate cancellation signals through compiler pipelines, validation helpers, and log-download flows, and bring the codebase closer to fully honouring its own signal-aware lifecycle contract.

Full Analysis Report

Focus Area: context.Background() Call-Chain Leakage

Current State Assessment

Entry points (cmd/gh-aw/main.go, pkg/cli/forecast.go) correctly anchor a signal-aware context:

// cmd/gh-aw/main.go
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)

This context flows through cobra's cmd.Context() into RunE handlers and option structs. However, deeper helpers bypass it.

Metrics Collected:

Metric	Value	Status
context.Background() calls in non-test production code	40	⚠️
Calls inside functions that accept context.Context param (ctxbackground violations)	~8	❌
Non-context gh wrappers (ExecGH, RunGH, RunGHCombined)	3 functions	❌
Downstream call sites of non-context gh wrappers	92	❌
Parser remote fetch calls with TODO acknowledgement	3	⚠️
Legitimate uses (option-struct nil-ctx fallbacks, WASM, entry points)	~20	✅
context.TODO() calls in production code	4	⚠️

Findings

Strengths

• Entry-point signal context wiring is consistently correct
• Context-aware siblings exist for all problematic gh wrappers
• Most option-struct nil-ctx fallbacks are intentional and documented
• The ctxbackground linter exists and catches in-function violations — but doesn't catch wrapper functions that create the context before delegating

Areas for Improvement

• [HIGH] pkg/workflow/github_cli.go:106,191,213 — ExecGH, RunGH, RunGHCombined each call their *Context siblings with a hard-coded context.Background(). Any caller that has a valid context and uses the non-context variant loses cancellation for all gh CLI network I/O
• [HIGH] pkg/parser/remote_workflow_spec.go:91,93,156 — Three downloadFileFromGitHub / resolveRefToSHA calls hard-code context.Background(). The enclosing functions are called during compilation; an in-progress compile cannot be cancelled at this step. A TODO comment at line 71 already acknowledges this
• [MEDIUM] pkg/cli/logs_orchestrator_filters.go:167 — fetchJobStatusesForProcessedRun(context.Background(), ...) inside buildRunsModel; the enclosing flow is called from log-download commands that carry a live context
• [MEDIUM] pkg/cli/update_extension_check.go:49 — upgradeExtensionIfOutdated creates no context parameter; its only caller (runUpgradeCommand at line 245) holds opts.ctx from cobra. GitHub API call for the latest release is fully uncancellable
• [LOW] pkg/cli/syft.go:67 — RunSyftOnLockFiles is called from compilePipeline which checks ctx.Err() right before the call, but runSyftScans creates a fresh context.Background() internally and never propagates cancellation into the image-scan loop

Detailed Analysis

pkg/workflow/github_cli.go — Non-context gh wrappers (92 downstream callers)

The three context-less wrappers exist for convenience but create a systemic leakage:

// Line 106 — drops caller context
func ExecGH(args ...string) *exec.Cmd {
    return setupGHCommand(context.Background(), args...)  // should use caller-provided ctx
}

// Line 191
func RunGH(spinnerMessage string, args ...string) ([]byte, error) {
    return RunGHContext(context.Background(), spinnerMessage, args...)
}

// Line 213
func RunGHCombined(spinnerMessage string, args ...string) ([]byte, error) {
    return RunGHCombinedContext(context.Background(), spinnerMessage, args...)
}

All 92 call sites of these functions could inherit caller context if the functions were removed and callers migrated to the *Context variants.

pkg/parser/remote_workflow_spec.go — Acknowledged TODO

// Line 71 — comment acknowledges the gap
// packages is tracked as a follow-up task; context.Background() is used in the interim.

// Line 91/93/156
content, err = downloadFileFromGitHub(context.Background(), owner, repo, filePath, ref)
content, err = downloadFileFromGitHubWithDepth(context.Background(), ...)
resolvedSHA, err := resolveRefToSHA(context.Background(), ...)

The calling functions accept no ctx parameter, so fixing requires a signature change to propagate the compiler's context.

pkg/cli/logs_orchestrator_filters.go:167

// Inside buildRunsModel — function has access to outer ctx through enclosing pipeline
if failedJobCount, err := fetchJobStatusesForProcessedRun(context.Background(), run.DatabaseID, verbose); err == nil {

The fetchJobStatusesForProcessedRun function accepts a context.Context; only the call site supplies the wrong one.

pkg/cli/update_extension_check.go:49 + pkg/cli/upgrade_command.go:245

// upgradeExtensionIfOutdated has no ctx parameter
func upgradeExtensionIfOutdated(verbose bool, includePrereleases bool) (bool, string, error) {
    // ...
    latestVersion, err := getLatestRelease(context.Background(), includePrereleases)  // line 63

The fix requires adding ctx context.Context to upgradeExtensionIfOutdated and threading it from opts.ctx in runUpgradeCommand.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Deprecate Non-Context gh Wrappers and Migrate Top Call Sites

Priority: High
Estimated Effort: Medium
Focus Area: context.Background() Call-Chain Leakage

Description: The three context-less wrapper functions ExecGH, RunGH, and RunGHCombined in pkg/workflow/github_cli.go (lines 106, 191, 213) hard-code context.Background() while calling their context-aware siblings. Identify all call sites using grep -rn 'ExecGH\|RunGH\|RunGHCombined' pkg/ cmd/ (excluding the *Context variants), add a // Deprecated: doc comment to each wrapper, and migrate call sites inside pkg/cli/ that already have a ctx variable in scope to the corresponding *Context variant.

Acceptance Criteria:

• ExecGH, RunGH, RunGHCombined each have a // Deprecated: use the *Context variant doc comment
• Call sites in pkg/cli/ that have a local ctx context.Context in scope are migrated to pass that context
• make fmt passes
• make test-unit passes

Code Region: pkg/workflow/github_cli.go, pkg/cli/

In pkg/workflow/github_cli.go, add Deprecated doc comments to ExecGH (line 100), RunGH (line 186), and RunGHCombined (line 207).

Then, find every caller in pkg/cli/ that already has a `ctx` variable in scope (use grep or static analysis) and replace:
- ExecGH(...) → ExecGHContext(ctx, ...)
- RunGH(msg, ...) → RunGHContext(ctx, msg, ...)
- RunGHCombined(msg, ...) → RunGHCombinedContext(ctx, msg, ...)

Do not change call sites that genuinely have no context (e.g., fire-and-forget helpers); leave those with the deprecated wrapper for a follow-up.

---

Task 2: Propagate Caller Context Through Remote Workflow Spec Fetchers

Priority: High
Estimated Effort: Medium
Focus Area: context.Background() Call-Chain Leakage

Description: pkg/parser/remote_workflow_spec.go contains three context.Background() network calls on lines 91, 93, and 156 with a TODO comment at line 71 acknowledging the gap. The enclosing functions (downloadRemoteFileForImport, resolveRemoteRef) lack ctx parameters. Add ctx context.Context parameters to these functions and propagate the compiler's context from callers in pkg/parser/ and pkg/cli/.

Acceptance Criteria:

• downloadRemoteFileForImport and resolveRemoteRef (or equivalent enclosing functions) accept ctx context.Context
• All three context.Background() calls on lines 91/93/156 are replaced with the propagated ctx
• The TODO comment at line 71 is removed
• All callers in pkg/parser/ and pkg/cli/ are updated to pass context
• make test-unit passes

Code Region: pkg/parser/remote_workflow_spec.go

In pkg/parser/remote_workflow_spec.go:
1. Find the functions enclosing lines 91, 93, and 156 — they currently lack a `ctx` parameter.
2. Add `ctx context.Context` as the first parameter to each.
3. Replace the three `context.Background()` arguments with `ctx`.
4. Remove the TODO comment block around line 71.
5. Trace all call sites in pkg/parser/ and pkg/cli/ and update them to pass an appropriate context (typically the compiler's ctx or the cobra cmd.Context()).
6. Run `make fmt && make test-unit`.

---

Task 3: Thread Context Through upgradeExtensionIfOutdated

Priority: Medium
Estimated Effort: Small
Focus Area: context.Background() Call-Chain Leakage

Description: upgradeExtensionIfOutdated in pkg/cli/update_extension_check.go (line 49) has no ctx context.Context parameter, so its internal call to getLatestRelease(context.Background(), ...) (line 63) cannot be cancelled. Its only production caller runUpgradeCommand in pkg/cli/upgrade_command.go (line 245) holds opts.ctx. Add a ctx parameter and thread it.

Acceptance Criteria:

• upgradeExtensionIfOutdated signature becomes func upgradeExtensionIfOutdated(ctx context.Context, verbose bool, includePrereleases bool) (bool, string, error)
• getLatestRelease call at line 63 uses the passed-in ctx
• runUpgradeCommand at line 245 passes opts.ctx
• Any test doubles or mock callers in _test.go files are updated
• make test-unit passes

Code Region: pkg/cli/update_extension_check.go, pkg/cli/upgrade_command.go

In pkg/cli/update_extension_check.go:
- Change `func upgradeExtensionIfOutdated(verbose bool, includePrereleases bool)` to accept `ctx context.Context` as the first parameter.
- On line 63, replace `context.Background()` with `ctx`.

In pkg/cli/upgrade_command.go:
- Update the call at line 245 to: `upgraded, installPath, err := upgradeExtensionIfOutdated(opts.ctx, opts.verbose, opts.preReleases)`

Update any test stubs in pkg/cli/*_test.go that call upgradeExtensionIfOutdated directly.
Run `make fmt && make test-unit`.

---

Task 4: Fix context.Background() in logs_orchestrator_filters and syft scan loop

Priority: Medium
Estimated Effort: Small
Focus Area: context.Background() Call-Chain Leakage

Description: Two related context-leakage points in the log/scan pipeline: (a) pkg/cli/logs_orchestrator_filters.go:167 calls fetchJobStatusesForProcessedRun(context.Background(), ...) inside buildRunsModel — the outer pipeline carries a live context that should flow here; (b) pkg/cli/syft.go:67 creates a standalone context.Background() for runSyftOnImage calls inside an image-scan loop, while compile_pipeline.go checks ctx.Err() right before calling RunSyftOnLockFiles but the ctx never reaches the loop.

Acceptance Criteria:

• buildRunsModel (or its enclosing function) in pkg/cli/logs_orchestrator_filters.go receives a ctx parameter and passes it to fetchJobStatusesForProcessedRun
• RunSyftOnLockFiles / runSyftScans in pkg/cli/syft.go and pkg/cli/compile_external_tools.go accept ctx context.Context and the scan loop uses it
• compile_pipeline.go call sites pass their local ctx to the syft function
• make test-unit passes

Code Region: pkg/cli/logs_orchestrator_filters.go, pkg/cli/syft.go, pkg/cli/compile_external_tools.go, pkg/cli/compile_pipeline.go

Fix A — logs_orchestrator_filters.go:
1. Locate `buildRunsModel` (or whichever function contains line 167).
2. Add `ctx context.Context` parameter.
3. Replace `context.Background()` on line 167 with `ctx`.
4. Update all callers to pass their live context.

Fix B — syft.go:
1. Change `RunSyftOnLockFiles` in compile_external_tools.go to accept `ctx context.Context` as first param.
2. Pass `ctx` through to `runSyftScans` in syft.go.
3. In `runSyftScans`, replace `ctx := context.Background()` (line 67) with the passed-in ctx.
4. Update call sites in compile_pipeline.go to pass `ctx`.
Run `make fmt && make test-unit`.

---

Task 5: Add ctxbackground Linter Coverage for Wrapper Functions That Synthesise Background Context

Priority: Low
Estimated Effort: Small
Focus Area: context.Background() Call-Chain Leakage

Description: The existing ctxbackground linter in pkg/linters/ctxbackground/ flags context.Background() inside functions that already receive a context parameter — but it does not flag wrapper functions whose only purpose is to call a *Context sibling with context.Background() (e.g. ExecGH, RunGH, RunGHCombined). Extend the linter or add a new lint rule to detect this pattern: a function with no context.Context parameter that calls an identically-named *Context sibling with a hardcoded context.Background() as first argument.

Acceptance Criteria:

• A new analyzer or an extension to ctxbackground flags the pattern: func Foo(args) { return FooContext(context.Background(), args) }
• The three existing wrappers in github_cli.go (once deprecated) trigger the new rule or are excluded via nolint with rationale
• The linter is registered in pkg/linters/all.go (if a new analyzer)
• make test-unit passes including pkg/linters/... tests

Code Region: pkg/linters/ctxbackground/, pkg/linters/all.go

In pkg/linters/ctxbackground/, add a new check (or extend the existing `run` function) to detect the pattern:
  - Function body is a single return/expression statement
  - That statement calls a function whose name is `<ThisFunctionName>Context`
  - The first argument to that call is `context.Background()`
  - The outer function has no `context.Context` parameter

Flag such functions with: "wrapper function synthesises context.Background(); consider adding a ctx parameter and delegating to the *Context variant".

Add a testdata file covering positive and negative cases.
Register the updated/new analyzer, run `make fmt && make test-unit`.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-07-22	Output Stream Abstraction Gap	Custom	Y	167 os.Stdout refs, 5 renderLogs* tasks
2026-07-17	Error Chain Transparency & Non-Wrapping fmt.Errorf Gap	Custom	Y	788 non-wrapping calls, 5 tasks
2026-07-16	Options Struct Pattern Adoption for High-Arity Functions	Custom	Y	2 linter violations, 5 tasks
2026-07-15	Compile-Time Interface Satisfaction Assertions	Custom	Y	Zero var _ guards in 21 interfaces
2026-07-14	Logger Name Collision & Instantiation Hygiene	Custom	Y	3 duplicate names, 6 var log shadows

---

🎯 Recommendations

Immediate Actions (This Week)

1. Deprecate non-context gh wrappers (Task 1) — Priority: High; 92 call sites unblocked for progressive migration
2. Add ctx to upgradeExtensionIfOutdated (Task 3) — Priority: High; smallest change, highest signal/noise ratio

Short-term Actions (This Month)

1. Propagate context through remote workflow spec fetchers (Task 2) — Priority: High; resolves the acknowledged TODO
2. Fix logs + syft context leakage (Task 4) — Priority: Medium

Long-term Actions (This Quarter)

1. Add ctxbackground linter coverage for wrapper pattern (Task 5) — Priority: Low; prevents regressions

---

📈 Success Metrics

• context.Background() count in non-test production code: 40 → ≤ 20 (legitimate nil-fallbacks and entry-points)
• Non-context gh wrapper call sites: 92 → 0 (all migrated to *Context variants)
• Parser remote fetch functions with propagated context: 0 → 3

---

Next Steps

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

---

References:

• [§30271523540] — workflow run that generated this report

Generated by Repository Quality Improvement Agent

Generated by ⚡ Repository Quality Improvement Agent · sonnet46 · 123 AIC · ⌖ 6.66 AIC · ⊞ 6.7K · ◷

• expires on Jul 28, 2026, 5:54 AM UTC-08:00