perf(runner): static header pre-count without the sourcing subshell

[Chemaclass]

🎯 Goal

Drop the throwaway $() subshell that bashunit::helper::find_total_tests uses to source every test file just to print "Running N tests" in the header. Compute the header total with a lightweight static scan × the already-cached provider multipliers, so each file is parsed once (at run time) instead of twice (pre-count + run).

📍 Where

• bashunit::helper::find_total_tests — src/helpers.sh:533-575. It builds the provider map in the main shell first (so the counting subshell + later runner both hit the cache — the provider-map double-build was already fixed in perf(runner): build the provider map once per file, not twice #817), then enters a subshell that sources each file to discover/count test functions and expand provider counts.
• The runner then sources each file again in the main shell at run time (.claude/rules/architecture-map.md → "source "$test_file" in the MAIN shell").
• Header consumer: bashunit::console_header::print_header (reads the total via the return slot written by find_total_tests, src/helpers.sh:529).

💡 Rationale

Sourcing is parse-time-dominated (perf-fork-budget.md: "parse time dominates, file opens don't"), so parsing all N files an extra time is the cost. Test discovery does not need the file executed — it needs the test_* function names, which a static scan can extract without a source, and the provider multipliers, which already come from the cached provider map (one awk pass per file, bashunit::helper::build_provider_map, src/helpers.sh:406).

🔧 Approach

1. Replace the sourcing subshell with a static per-file scan of test-function declarations, e.g. match ^[[:space:]]*(function[[:space:]]+)?test_[A-Za-z0-9_]+[[:space:]]*\(\). Prefer a single pass (the existing awk/grep file-scan machinery already used for duplicate-check and provider-map — reuse it rather than adding a new fork class).
2. Multiply each discovered test_* by its provider row count from the cached provider map (bashunit::helper::provider_for_function / the map globals). Functions with no provider count as 1.
3. Write the total into the existing return slot (_BASHUNIT_HELPER_TOTAL_TESTS_OUT) — keep the public contract identical.

✅ Acceptance criteria

• Header total matches the current behaviour for: plain tests, data-provider tests (single + multi-row), filtered runs (--filter/--tag/--exclude-tag), and empty files.
• Each test file is parsed once per run (the pre-count subshell that sources files is gone).
• No new per-file fork class beyond the scan already used for discovery.

🧪 TDD / measurement

• RED: add a tests/unit/helpers_test.sh case pinning find_total_tests output for a fixture with N plain tests + a provider test with K rows → expects N + K; assert it drives the header count. Then a fork/parse census showing the pre-count no longer sources files.
• Guard the known trade-off: dynamically-defined tests (a test_* created at source time by a loop/eval rather than a literal function test_…()) will not be counted by a static scan. Confirm the repo's own suite has none, document the limitation in the function header, and if any fixture relies on it, keep a source-based fallback gated behind detection of non-literal definitions.
• Full gate: ./bashunit tests/, ./bashunit --parallel --simple --strict tests/, make sa, make lint. Regenerate any header snapshot if counts render identically (they should).

⛓️ Constraints

• Bash 3.0+ (.claude/rules/bash-style.md). Reuse pinned $GREP/$AWK; don't add a while read loop over big files (measured slower than one awk in perf-fork-budget.md).
• Update perf-fork-budget.md cold-start notes if the per-run parse count drops.

📈 Impact

Removes N extra file parses per run (N = file count). Cold-ish path (once per run), most visible on large suites (e.g. bashunit's own 63-file unit suite).

⚠️ Note

Medium confidence / medium risk because it changes the counting mechanism from dynamic (source) to static (scan). Land behind tests that pin provider-multiplier and filter behaviour. If static discovery proves lossy for any supported pattern, close as wontfix rather than shipping a wrong header count.

[Chemaclass]

Closing as wontfix after a feasibility probe — the static-scan approach is lossy for this repo.

Evidence: compared an anchored static scan (^\s*(function\s+)?test…\(\)) against the authoritative sourced count (source file; compgen -A function | grep ^test) across all 140 test files. 4 diverge, all because acceptance tests embed heredoc fixture test files whose function test_…() sits at line-start and is indistinguishable from a real declaration by regex:

custom_assertions_test.sh static=12 sourced=11
bashunit_lifecycle_visibility_test.sh static=8 sourced=4
bashunit_lifecycle_verbose_test.sh static=4 sourced=2
bashunit_bashunitrc_test.sh static=5 sourced=4

A static scan would over-count fixture strings as real tests, producing a wrong "Running N tests" header (and breaking the total-pinning snapshots). Distinguishing a real top-level declaration from one inside a heredoc/quoted string requires actually parsing Bash — i.e. sourcing, which is what find_total_tests already does. The double-source is inherent to "print an exact total upfront" + "source each file fresh in isolation".

Not worth re-implementing a heredoc-aware parser for a cold-path (once-per-run) optimization. The provider-map double-build — the part that actually mattered — was already fixed in #817.