[repository-quality] Repository Quality: Library Robustness (Panics & Context)

[github-actions[bot]]

🎯 Repository Quality Improvement Report - Library Robustness: Panics & Context Propagation

Analysis Date: 2026-10-14
Focus Area: Library Robustness (panics in library code, context.Background() roots)
Strategy Type: Custom
Custom Area: Yes — the repo ships a panic-in-library-code linter yet ~30 non-test panic() sites and ~73 context.Background() roots remain in pkg/, so enforcement/gap analysis is repo-specific.

Executive Summary

Non-test pkg/ and cmd/ code contains 71 panic( matches (including testdata fixtures; roughly 30 in real library code). Most are BUG: init-time invariants (engine registration, Pi config encoding), which are defensible, but a few take runtime input (cache_config.go:46, domains.go:695, actionpins/references.go:29, parser/virtual_fs.go, model_aliases.go:94,154) and could crash the CLI or WASM build rather than return an error.

Roughly 73 context.Background() calls in non-test code (e.g. pkg/cli/copilot_agents.go:202, run_workflow_validation.go:314, branch_file_reader.go:19, logs_parsing_persisted.go:44, zizmor.go:173, poutine.go:180, syft.go:66) sever cancellation (Ctrl-C, timeouts) from the command. Error wrapping is healthy: no %v-wrapped errors outside linter testdata.

Full Analysis Report

Focus Area: Library Robustness

Current State Assessment

Metrics Collected:

Metric	Value	Status
panic( matches, non-test (incl. testdata)	71	⚠️
Non-BUG: panics in real library code	~15	⚠️
context.Background() in non-test code	73	⚠️
%v error wrapping in prod code	0	✅
_ = x.Close() in prod code	1 (pkg/cli/edit_command.go:154)	✅
TODO/FIXME (real)	~38, mostly generated-template text	✅
Test/source LOC	651k / 352k	✅

Findings

Strengths

• Linters (errorfwrapv, panic-in-library-code, closeerrorunchecked) are already enforced.
• Very high test ratio; consistent error wrapping.

Areas for Improvement

• 🟠 Runtime-input panics: pkg/workflow/cache_config.go:46, pkg/workflow/domains.go:695, pkg/actionpins/references.go:29, pkg/parser/virtual_fs.go:37,44, pkg/workflow/model_aliases.go:94,154.
• 🟡 Init-time panics with no documented policy: pkg/actionpins/data.go:76-101, pkg/workflow/agentic_engine.go:614-626, pi_engine_config.go.
• 🟡 Uncancellable context roots in pkg/cli/* helpers.
• ⚪ Panic-policy not documented, so the linter's allowed exceptions are unclear.

Detailed Analysis

The BUG: prefix convention is a good marker for invariant violations. The weaker cases are those where the invariant depends on user-provided frontmatter (cache IDs, models), which validation is supposed to catch earlier but is not type-enforced.

---

🤖 Tasks for Copilot Agent

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

Improvement Tasks

Task 1: Replace input-dependent panics with errors

Priority: High
Estimated Effort: Medium
Focus Area: Library Robustness

Description: Convert panics reachable from user input to returned errors.

Acceptance Criteria:

• cacheMemoryDirFor, domains.go:695, FormatPinnedActionReference, RegisterBuiltinVirtualFile, model_aliases.go return errors
• Callers propagate errors; tests added for invalid input
• make test-unit and make fmt pass

Code Region: pkg/workflow/cache_config.go, pkg/workflow/domains.go, pkg/actionpins/references.go, pkg/parser/virtual_fs.go, pkg/workflow/model_aliases.go

Convert the listed panic() calls that can be triggered by user-supplied workflow frontmatter into returned errors with actionable messages (see error-messages skill). Update callers and add tests.

---

Task 2: Thread context through pkg/cli helpers

Priority: Medium
Estimated Effort: Medium
Focus Area: Library Robustness

Description: Replace context.Background() in CLI helpers with a caller-supplied context.

Acceptance Criteria:

• copilot_agents.go:202, run_workflow_validation.go:314, branch_file_reader.go:19, zizmor.go:173, poutine.go:180, syft.go:66, logs_parsing_*.go accept ctx
• Cobra commands pass cmd.Context()
• Tests pass

Code Region: pkg/cli/*.go

Add a ctx parameter to the listed functions, pass cmd.Context() from commands, keep Background only at true roots (main, shutdown paths).

---

Task 3: Document and enforce panic policy

Priority: Medium
Estimated Effort: Small
Focus Area: Library Robustness

Description: Document that panics are only allowed for init-time BUG: invariants and ensure the linter allows exactly that.

Acceptance Criteria:

• Policy documented in pkg/linters/doc.go / developer skill
• Remaining panics prefixed BUG: or annotated (nolint/redacted):panicinlibrarycode with reason
• engine_definition_loader.go:153 and actionpins/data.go reviewed

Code Region: pkg/linters/panic-in-library-code/, pkg/actionpins/data.go, pkg/workflow/engine_definition_loader.go

Document the panic policy and annotate/convert the remaining non-BUG panics accordingly.

---

Task 4: Add a context.Background() linter check for non-root code

Priority: Low
Estimated Effort: Small
Focus Area: Library Robustness

Description: Ensure ctxbackground linter coverage matches Task 2 and prevents regressions.

Acceptance Criteria:

• Linter flags new context.Background() in functions that already have a ctx
• Existing allowed roots annotated

Code Region: pkg/linters/ctxbackground/

Review ctxbackground analyzer coverage and annotate legitimate roots.

---

📊 Historical Context

Previous Focus Areas

Date	Focus Area	Type	Custom	Key Outcomes
2026-10-13	Large Source File Decomposition	Custom	Y	Split 800+ LOC files, 4 tasks
2026-10-14	Library Robustness	Custom	Y	Panic/context audit, 4 tasks

---

🎯 Recommendations

Immediate Actions (This Week)

1. Remove input-dependent panics — Priority: High

Short-term Actions (This Month)

1. Thread contexts through CLI helpers — Priority: Medium

Long-term Actions (This Quarter)

1. Lock in policy via linters — Priority: Low

---

📈 Success Metrics

• Input-dependent panics: ~7 → 0
• context.Background() in non-root code: 73 → <20

---

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 month

---

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

Generated by ⚡ Repository Quality Improvement Agent · copilot · auto · 20.4 AIC · ⌖ 0.662 AIC · ⊞ 9.8K · ◷

• expires on Oct 15, 2026, 5:02 AM UTC-08:00

[github-actions[bot]]

This discussion has been marked as outdated by Repository Quality Improvement Agent.

A newer discussion is available at Discussion #69038.