[Sprint] sprint-loop-31

[scealiontach]

Sprint plan — 2026-05-03 — sprint-loop-31

Sprint goal

Raise reliability of operator-facing scripts and generated docs: fix a non-portable bashadoc extraction path that can silently drop @doc/@arg on BSD/macOS grep, correct widespread Apache 2.0 header URLs under bash/, close two high-severity behavioral bugs in k8s-support-collector and release-images, and lock in regression coverage for release-images and k8s-support-collector so CI and local runs stay aligned with Linux and non-GNU environments.

Selected issues

SUR-2176 — Anti-pattern: bashadoc uses grep \s* for @doc/@arg lines (non-portable)

• Title: Anti-pattern: bashadoc uses grep \s* for @doc/@arg lines (non-portable)
• Description summary: bash/bashadoc filters declare -f with grep patterns using \s* for leading whitespace before @doc / @arg. POSIX/BSD grep does not treat \s like GNU grep; doc extraction can fail on macOS while CI on Linux passes.
• Rationale: Urgent priority; doc drift across platforms blocks trustworthy bashadoc output and downstream packaging.
• Definition of Done
  • @doc and @arg detection uses a POSIX-safe pattern (e.g. ^[[:space:]]*@doc / @arg ) or documented grep -E with explicit character classes.
  • Behavior verified on the project’s supported environments (at minimum: existing CI plus rationale in code or issue if platform-specific).
  • pre-commit / shellcheck clean for touched regions.
  • No regression in generated markdown for representative libraries (smoke via bash/bashadoc on a known file).
• Dependencies / ordering: No Linear blockers. Should land early so doc generation is trustworthy before or alongside SUR-2170 header sweeps that rely on tooling perception.

SUR-2170 — Docs: Apache 2.0 license comment blocks use malformed URL http:#www.apache.org/...

• Title: Docs: Apache 2.0 license comment blocks use malformed URL http:#www.apache.org/...
• Description summary: Many bash/* files use http:#www.apache.org/licenses/LICENSE-2.0 instead of a valid https:// (or http://) URL in the standard Apache header block.
• Rationale: High priority; compliance copy-paste and audit trust; mechanical fix with broad footprint.
• Definition of Done
  • All affected bash/ headers use https://www.apache.org/licenses/LICENSE-2.0 (or repo-agreed SPDX-only alternative if explicitly chosen and consistent).
  • Grep/spot-check shows no remaining http:#www.apache.org typo in tracked bash/ sources targeted by the issue.
  • Single logical commit (or minimal commits per repo convention) without unrelated edits.
• Dependencies / ordering: Independent of code behavior; schedule after SUR-2176 if the same files touch bashadoc headers, to reduce churn ordering (optional).

SUR-2171 — Bug: k8s-support-collector logs() sets pod_sname without local

• Title: Bug: k8s-support-collector logs() sets pod_sname without local
• Description summary: In logs(), pod_sname is assigned without local, leaking into global shell scope during collection runs.
• Rationale: High priority; environment pollution breaks composability and debugging for a support tool.
• Definition of Done
  • pod_sname is scoped with local (or equivalent safe reuse) before use in bash/k8s-support-collector.
  • No new shellcheck warnings in the edited function.
  • Covered by new or extended bats where practical (see SUR-2177 pairing in implementation plan).
• Dependencies / ordering: None. Prefer completing before or in parallel with SUR-2177 so tests can assert the fixed surface.

SUR-2173 — Bug: release-images IMAGES_FILE mode passes blank lines to docker::pull / docker::cp

• Title: Bug: release-images IMAGES_FILE mode passes blank lines to docker::pull / docker::cp
• Description summary: -f IMAGES_FILE path uses grep -v '^ *#' only; blank and whitespace-only lines reach docker::pull / docker::cp as malformed refs.
• Rationale: High priority; release automation errors are high blast radius.
• Definition of Done
  • Empty and whitespace-only lines are skipped (and optionally invalid tokens rejected with clear errors).
  • Existing comment-only filtering preserved.
  • Behavior aligned with issue’s suggested approaches (grep pipeline or read discipline).
• Dependencies / ordering: Precedes SUR-2178 so new bats can assert blank-line handling.

SUR-2178 — Test: add bats coverage for release-images

• Title: Test: add bats coverage for release-images
• Description summary: Add tests/release-images.bats with SIMULATE=true, stubbed docker::* functions, assertions on flags and file-driven loops; references SUR-2173-class bugs.
• Rationale: Medium priority; guards high-impact release path after functional fix.
• Definition of Done
  • New tests/release-images.bats following setup() { load 'helpers.bash'; helpers::isolate_home; } and existing bats patterns.
  • Cases for option parsing, SIMULATE/DRY_RUN, and IMAGES_FILE loop including blank-line / comment behavior per SUR-2173 fix.
  • tests/bats/bin/bats tests/release-images.bats passes; make test_bats or make test passes as appropriate.
• Dependencies / ordering: After SUR-2173 (or same PR) so expectations match production filtering.

SUR-2177 — Test: add bats coverage for k8s-support-collector

• Title: Test: add bats coverage for k8s-support-collector
• Description summary: Add bats for bash/k8s-support-collector: options, OUT_DIR, tarball naming; mock k8s::, exec, dirs via stubs under BATS_TEST_TMPDIR.
• Rationale: Medium priority; script has recent fragile pipeline fixes; tests reduce regression risk.
• Definition of Done
  • New tests/k8s-support-collector.bats with isolated home and stubs per repo helpers conventions.
  • Assertions on option exports and critical path construction described in the issue.
  • Bats suite passes locally and in CI conventions (make test).
• Dependencies / ordering: Pair with SUR-2171; implement or extend tests once collector behavior is stable for the sprint branch.

Risks + mitigations

• Wide SUR-2170 diff: Many files touched → rebase/merge friction. Mitigation: dedicated commit, avoid mixing with logic changes; run full test suite once.
• Platform grep variance: SUR-2176 must not assume GNU extensions elsewhere in the same tool. Mitigation: POSIX character classes; add a bats or script-level smoke if available.
• Release-images tests flakiness: Stub ordering or global overrides if tests source real docker helpers. Mitigation: follow tests/docker.bats / registry-cp.bats patterns; isolate PATH and temp dirs.
• k8s-support-collector test complexity: Heavy external behavior. Mitigation: scope first slice to options and pure functions; mock k8s:: as issue describes.
• Sprint scope creep: on-change / minikube tests (SUR-2179 / SUR-2184) deferred. Mitigation: explicit out-of-scope list below.

Out of scope

• Linear issues SUR-2179 (on-change bats) and SUR-2184 (minikube-test-environment bats): remain Backlog for a later sprint.
• Issues outside project shell-scripts or team Surinis, and any issue not in Backlog at planning time.
• Triage / In Progress / Done work not listed above.
• Changes unrelated to the six selected tickets (no drive-by refactors).

Linear Evidence

• Linear team verified: Surinis (ce9ebfde-ff2b-4f54-90f1-c388591ca110, key SUR)
• Linear project used: shell-scripts (a43901a0-b02b-4009-aae1-a6e8903d127d)
• Query / filter used: list_issues with project=shell-scripts, state=Backlog, team=Surinis, limit=250, includeArchived=false; per-issue get_issue with includeRelations=true; list_comments per candidate; list_issues with parentId=<each candidate> to confirm no blocking sub-issue trees.
• Approx. count of Backlog issues reviewed: 8
• Approx. count of manual-labelled Backlog issues skipped: 0
• Issues skipped due to unmerged blockers: 0 — []
• Issues skipped due to open-PR file overlap: 0 — [] (open PR file list was empty)

Sub-issue Status

No candidate or selected issue in project shell-scripts had Linear child issues under parentId queries (all parent sub-queries returned empty). No parent was skipped for incomplete sub-issues.

Parent Issue	Sub-issue	Sub-issue Status	Eligible?
—	—	—	N/A (no sub-issues on reviewed Backlog set)

Linear State Transitions

Issue ID	Previous State	New State
SUR-2176	Backlog	Todo
SUR-2170	Backlog	Todo
SUR-2171	Backlog	Todo
SUR-2173	Backlog	Todo
SUR-2178	Backlog	Todo
SUR-2177	Backlog	Todo