scripts/lib: define the comment-stripped list format once in read-list.sh

[claude]

Parent

Refs #2914

Context

Roughly ten scripts/*.txt data files share one line format — comment lines, blank lines, and inline trailing comments are stripped; what remains is one active entry per line. Five bespoke parsers implement that format, and check-shell-portability.sh alone parses it two different ways in the same file.

Because the format lives only in its parsers, each one independently decides the edge cases: whether # inside an entry starts a comment, whether a backslash escapes it, whether surrounding whitespace is trimmed, and whether a blank-after-strip line is dropped. A token or allowlist entry that is read as active by one parser and inert by another is a silent disagreement — and for these particular files (portability tokens, docs-only prefixes, baselines) "inert" means a gate quietly stops enforcing something.

Route-lane finding 7 of 7 from the first /coupling:reduce dogfood run (#2914). Reproduced against the tree at dff0942: 15 scripts/*.txt files, no scripts/lib/read-list.sh.

Proposed work

• Add scripts/lib/read-list.sh exposing read_active_lines, defining the comment / escape / trim semantics once — sourced-only, matching the scripts/lib/ precedent.
• Return entries through a nameref rather than stdout, and prefix every internal local (_rl_*): a nameref resolves in the scope where it is used, so an unprefixed local sharing the caller's out-var name shadows it silently. See refactor(scripts): extract the shared changed-file and awk-operand seams #3144, where exactly that produced two silently-empty results.
• Replace the five bespoke parsers, including both of check-shell-portability.sh's.
• Write down the format's edge cases as tests: inline #, escaped \#, leading/trailing whitespace, blank-after-strip, and a line that is only a comment.
• Fail loudly on an unreadable file rather than returning an empty list — an empty token list means a gate that enforces nothing (the ci: harden shell-portability-lint detection precision (sed -i spellings, portability-scope precision, awk operand edge case) #1513 class).

Acceptance criteria

• scripts/lib/read-list.sh defines the format once and is sourced by every consumer.
• No scripts/*.sh carries its own comment/blank-stripping parser; check-shell-portability.sh parses the format one way, not two.
• Every edge case above is covered by a test of the library.
• An unreadable or missing list file is a loud non-zero return, never an empty active-entry set.
• Every internal local in a nameref-taking function is _rl_-prefixed, with a test that a caller may name its out-array anything.

References

• Parent umbrella: coupling: route-lane findings from /coupling:reduce dry-run over scripts/ #2914 (route-lane finding 7 of 7)
• scripts/check-shell-portability.sh — the two in-file parsers
• scripts/*.txt — the ~10 data files sharing the format
• refactor(scripts): extract the shared changed-file and awk-operand seams #3144 — the scripts/lib/ extraction precedent, the nameref-prefix requirement, and the ci: harden shell-portability-lint detection precision (sed -i spellings, portability-scope precision, awk operand edge case) #1513 empty-token-list fail-open

Metadata

Field	Value
Category	unspecified
Area	unspecified
Ecosystem	unspecified

---

Generated by Claude Code

[claude]

Correction to this item's premise, found while scoping it. It is not one format with five parsers — it is two formats, and collapsing them into one read_active_lines would break a gate.

The two live shapes:

A — inline-stripping (scripts/check-shell-portability.sh:241 for the skill-md baseline; scripts/check-docs-only.sh for the allowlist):

sed -E 's/#.*//; s/^[[:space:]]+//; s/[[:space:]]+$//' "$FILE" | grep -v '^$'

# starts a comment anywhere on the line.

B — leading-#-only (the awk FNR == NR loader in both portability scanners, check-shell-portability.sh:1536 and check-skill-portability.sh:319):

sub(/^[[:space:]]+/, "", line); sub(/[[:space:]]+$/, "", line)
if (line == "" || line ~ /^#/) next

A line is a comment only if # is the first character. An inline # is kept as data.

They disagree on exactly one input: a line containing # that does not start with one. And B is not a bug — token-list entries are EREs, and a regex may legitimately contain #. Applying A's s/#.*// to a token list would silently truncate such a pattern, or empty it entirely; an emptied pattern in a token list is the #1513 shape again, a gate that enforces nothing while exiting 0. So the correct move is not "pick one", it is to make the choice explicit per call site — the same conclusion #3144 reached for --include-deleted in changed-files.sh, where two callers genuinely needed opposite deletion semantics.

Is it live today? No — measured against dff0942, zero active lines in shell-portability-tokens.txt, skill-portability-tokens.txt, docs-only-paths.txt, or shell-portability-skill-md-baseline.txt contain a non-leading #. The divergence is latent. That is worth stating plainly rather than overselling: nothing is broken right now, and the value of this item is that the two semantics currently exist only inside their parsers, so nothing stops a future ERE with a # in it from being silently truncated by whichever consumer happens to use shape A.

Revised acceptance criteria (superseding the single-format assumption in the body):

• read-list.sh exposes both comment modes explicitly — an inline-stripping mode and a leading-only mode — with each call site naming which it wants. No default that silently suits one family and corrupts the other.
• A token-list entry containing a non-leading # survives intact through the leading-only mode, asserted by a test.
• The same entry is truncated by the inline-stripping mode, also asserted — so the two modes are provably different and neither is a dead alias.
• check-shell-portability.sh reaches both of its current shapes through the library, still with the two different semantics its two files require.
• Whether escaping (\#) should exist in the inline mode is a decision this item records, not one it leaves to the parser.

The rest of the filed body still stands, including the nameref-prefix requirement.

---

Generated by Claude Code