fix(build): key embed markers on repo-relative paths so src/ can hold module dirs

[Chemaclass]

Summary

build.sh labels every embedded file with # <basename>. That label is both the
dedupe key and the only thing test_built_binary_embeds_each_src_file_exactly_once
inspects. Keying on a basename hides a real double-embed bug and blocks any
subdirectory under src/.

Fix: key the dedupe and the marker on a repo-relative path. This is a
prerequisite for splitting large src/ files into module directories
(src/runner/, src/coverage/), but it stands on its own as a bug fix.

Current behavior

Two defects, both reproduced on main (94933c0).

1. The dedupe key is relative from the top-level loop and absolute from the recursion.

build::dependencies yields src/state.sh; build::process_file's recursion
yields /abs/path/src/state.sh (build.sh:92 expands $BASHUNIT_ROOT_DIR). The
case at build.sh:73-75 compares those as strings, so they never match. Add one
cross-module source and the file is bundled twice:

mkdir -p src/runner
printf '#!/usr/bin/env bash\nsource "$BASHUNIT_ROOT_DIR/src/state.sh"\n\nfunction bashunit::runner::_x() { :; }\n' > src/runner/exec.sh
# add: source "$BASHUNIT_ROOT_DIR/src/runner/exec.sh" to src/runner.sh
bash build.sh bin

grep -c '^# state\.sh$' bin/bashunit # => 2
grep -c '^function bashunit::state::reset_test_title()' bin/bashunit # => 2
grep -oE '^function bashunit::[a-zA-Z_:]+\(\)' bin/bashunit | sort | uniq -d | wc -l # => 42

42 framework functions defined twice in the distributable. build.sh:10-12 already
warns about exactly this hazard ("one added cross-source would otherwise silently
bundle a file twice") — the guard is just ineffective for the absolute form.

2. A basename marker false-positives across directories.

src/parallel.sh and src/runner/parallel.sh both emit # parallel.sh, so
test_built_binary_embeds_each_src_file_exactly_once reports a duplicate for two
genuinely different files.

3. Relative source joins accumulate /. segments.

build.sh:97 does "$(dirname "$file")/$sourced_file" without stripping a leading
./, so each recursion level appends another /.: $dir/././common.sh. The same
file can therefore reach the dedupe under two spellings. Latent today; only masked
because the marker is a basename.

Expected behavior

• A file sourced from more than one place is embedded exactly once, regardless of
  whether the path arrives relative or absolute.
• Two files with the same basename in different directories are embedded as two
  distinct entries with distinct markers.
• The built artifact defines every bashunit::* function exactly once.

Scope

build.sh

1. In build::process_file, derive local marker="${file#"$BASHUNIT_ROOT_DIR"/}"
   and use it for both the case dedupe key and the emitted comment
   (echo "# $marker"). Leave $file itself untouched — tail -n +2 "$file" and
   dirname "$file" must keep working on whichever form the caller passed (the
   top-level loop's relative paths already require cwd = repo root).
2. In the relative-path join, strip a leading ./:
   sourced_file="$(dirname "$file")/${sourced_file#./}".
3. Update the stale _BUILD_EMBEDDED_FILES comment at build.sh:10-12 — the source
   graph is no longer described as "a tree today".

tests/unit/build_test.sh

4. New test (this is the RED test — write it first). Assert the artifact defines
   no bashunit::* function twice:

   duplicated=$(grep -oE '^function bashunit::[a-zA-Z_:]+\(\)' "$build_dir/bashunit" | sort | uniq -d)
   assert_empty "$duplicated"

   Verified to fail with 42 entries on current main once a cross-module source
   exists, and to pass after the fix. Restrict the pattern to bashunit:: — an
   unnamespaced ^function pattern also matches the example code inside the
   embedded docs/assertions.md heredoc and reports 19 false positives on a clean
   main build.

5. Line 135 regex → ^# src/[a-z_0-9/]+\.sh$. Without this the existing duplicate
   guard still passes but matches zero lines — silently vacuous once markers
   become paths.

6. Line 103 → assert_equals "1" "$(grep -cFx "# $dir/common.sh" "$dir/out.tmp")".
   test_build_process_file_embeds_a_file_only_once feeds absolute temp paths
   outside the repo root, so its marker is the full path, not common.sh.

7. Add a regression test for the basename collision: a fixture module file whose
   basename matches an existing top-level src/*.sh, asserting both are embedded
   with distinct markers. Without this, nothing stops the collision from
   reappearing.

No change needed

build::dependencies stays as-is — it reads only bashunit's own source lines,
so it remains the single source of truth and module children arrive via recursion.
test_build_bundles_{every,only}_src_file_sourced_by_entrypoint keep passing
untouched: they compare that list against itself, and nested files appear on
neither side.

Acceptance criteria

• The new duplicate-bashunit::*-function test fails before the build.sh fix
  and passes after it
• A cross-module source embeds the target file exactly once
• Two same-basename files in different src/ dirs get distinct markers
• ./bashunit tests/ green
• ./bashunit --parallel tests/ green
• make sa && make lint green
• bash build.sh bin -v prints ✅ Build verified ✅
• Bash 3.0+ compatible (${var#prefix} only; no printf -v, no [[, no +=)
• No CHANGELOG entry — internal, no user-visible behavior change

Verification: artifact order must not change

The artifact must place files in the exact order bash sources them at runtime.
build::process_file emits a file's body and then recurses, which equals runtime
order provided an aggregator holds only source lines and comments. Confirmed
against a 3-module prototype (cross-module sources, two deliberately colliding
basenames): an independent DFS over the source graph matched the artifact's marker
order exactly, 46/46 files. src/assertions.sh already satisfies the aggregator
rule (zero non-comment, non-source top-level lines).

Worth stating in .claude/rules/architecture-map.md as part of this PR, since the
follow-up module splits depend on it:

A module aggregator (src/<module>.sh) contains only source lines and
comments. Anything else at top level would make the built artifact's execution
order diverge from dev-mode source order.

Also note for anyone adding files: tail -n +2 strips line 1, so every new src
file's first line must be the shebang.

Do not

• Do not add src/ globbing to build::dependencies — the entrypoint's own source
  list is deliberately the single source of truth (regressions: bench #0.31.0,
  watch Watch subcommand fails with "bashunit::watch::run: command not found" (src/watch.sh missing from release build) #735)
• Do not run shfmt -w — it fights .editorconfig; make lint is the format gate
• Do not split any src/ file in this PR. This PR only enables it.

References

• build.sh:10-12 (stale tree comment), :70-84 (marker + dedupe), :91-101 (path join)
• tests/unit/build_test.sh:92-104, :128-138
• Existing nested-src precedent: src/dev/debug.sh, excluded from the build at build.sh:113

[Chemaclass]

Verified prototype patch

This exact diff was applied to a scratch clone and validated against a 3-module
demo (src/runner/ + a second module, cross-module source lines, and two
deliberately colliding basenames src/runner/parallel.sh / src/runner/state.sh):

duplicate markers: none
duplicate bashunit:: functions: none (42 before the fix)
src/state.sh embedded: 1 (2 before the fix)
colliding basenames: # src/parallel.sh + # src/runner/parallel.sh
independent DFS order vs artifact: 46/46 exact match

bash build.sh bin -v
 Tests: 1550 passed, 9 skipped, 7 incomplete, 2 snapshot, 1568 total
 ✅ Build verified ✅

A control run on an unmodified copy was also green, so that is a real comparison.

The build.sh changes, as verified:

@@ -7,9 +7,9 @@
 BASHUNIT_ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export BASHUNIT_ROOT_DIR
 
-# Files already embedded by build::process_file. The source graph is a tree
-# today, but one added cross-source would otherwise silently bundle a file
-# twice (duplicate function definitions and double top-level execution).
+# Files already embedded by build::process_file, keyed by repo-relative path.
+# Without the dedupe a cross-module source would bundle a file twice (duplicate
+# function definitions and double top-level execution).
 _BUILD_EMBEDDED_FILES=""
 
 function build() {
@@ -70,13 +70,20 @@
 local file=$1
 local temp=$2
 
+ # Key the dedupe and the embed marker on a repo-relative path, never a
+ # basename: the top-level loop passes `src/x.sh` while the recursion passes an
+ # absolute path, and two modules can hold the same basename
+ # (src/parallel.sh vs src/runner/parallel.sh). `$file` itself stays untouched
+ # so the `tail` and `dirname` below work on whichever form the caller passed.
+ local marker="${file#"$BASHUNIT_ROOT_DIR"/}"
+
 case " $_BUILD_EMBEDDED_FILES " in
- *" $file "*) return ;;
+ *" $marker "*) return ;;
 esac
- _BUILD_EMBEDDED_FILES="$_BUILD_EMBEDDED_FILES $file"
+ _BUILD_EMBEDDED_FILES="$_BUILD_EMBEDDED_FILES $marker"
 
 {
- echo "# $(basename "$file")"
+ echo "# $marker"
 tail -n +2 "$file"
 echo ""
 } >>"$temp"
@@ -91,10 +98,12 @@
 # Expand the literal $BASHUNIT_ROOT_DIR prefix without eval
 sourced_file="${sourced_file/\$BASHUNIT_ROOT_DIR/$BASHUNIT_ROOT_DIR}"
 
- # Handle relative paths if necessary
+ # Handle relative paths if necessary. Strip a leading `./` first, or each
+ # recursion level appends another `/.` segment and the same file reaches the
+ # dedupe under two spellings.
 local _absolute_path_pattern='^/'
 if [[ ! "$sourced_file" =~ $_absolute_path_pattern ]]; then
- sourced_file="$(dirname "$file")/$sourced_file"
+ sourced_file="$(dirname "$file")/${sourced_file#./}"
 fi
 
 # Recursively process the sourced file if it exists

[Chemaclass]

Done in #926 (merged).