tests: one source-assertion helper, so the prose trap can't recur

The trap I hit twice today — a file-wide DoesNotContain matching the doc
comment that explains the ban — was possible because three tests each
hand-rolled their own File.ReadAllText + path-walker, two of them mine. Fixed
at the root rather than per-test: SourceAssert now owns path walking and
literal extraction, with Literal(memberName, params parts) and Scopes() that
assert on the parsed VALUE. Tests that genuinely assert structure (the #if
DEBUG arm in InstanceIsolationTests, the absence of a whole API in the
locator) still read the file themselves, because those claims cannot be
reduced to a value — the helper is for literal facts only.

Shipping the fix introduced two defects, both caught by the build: a method
named Path shadowed System.IO.Path and broke the error message that names the
missing file, and Literal(fileName, memberName) invited a call that silently
resolved to a nonexistent path. Argument order is now required-context-first
so a wrong path is visible at the call site.

Suite 380/380, 0 warnings. LayerReorderPersistenceTests.RealMouseDrag flaked
once mid-session with no ytLive instance running and passed in isolation and
on re-run — the environment flake already recorded in HANDOFF.md, not a
regression from this change.
This commit is contained in:
2026-09-28 11:53:52 -07:00
parent b3edc2e42e
commit 967df83925
5 changed files with 101 additions and 53 deletions
+22
View File
@@ -1340,3 +1340,25 @@ while actively documenting it. Repeating a documented mistake is not a knowledge
knowledge was fine — it is a *check* failure. The check that would have caught it: when a
`DoesNotContain` is aimed at a file, ask "does this file's own documentation have a legitimate
reason to contain the string?" If yes, the assertion is aimed at the wrong target.
### Extracting the duplicated helper created two fresh bugs in the same commit (2026-09-28)
Pulling the three hand-rolled `RepoFile` path-walkers into one `SourceAssert` helper — the fix for
the repeated prose-matching trap — shipped with two defects of its own, both caught by the build:
- **A method named `Path` shadowed `System.IO.Path` inside the class**, so the failure message that
wanted to *name the missing file* was itself a compile error (`CS0119`). Renamed to `RepoPath`.
A helper whose name collides with a BCL type is a trap for the next reader, not just for me.
- **The signature invited the bug it was meant to prevent.** `Literal(string fileName, string
memberName)` looked like it took a file name, but the body resolved the path from the repo root,
so the only legal call was a full directory path — and the call site passed
`"YouTubeAuthService.cs"`, which resolves to a path that does not exist. The failure was a
bare `FileNotFoundException` with no hint. Flipping the argument order to
`Literal(memberName, params string[] parts)` makes a wrong path *visible at the call site*
instead of buried in a resolved path.
**The generalisation:** a parameter shape that cannot express the common legal call is a defect
even when the compiler accepts it. `fileName` + `memberName` looks fine and is wrong; the honest
shape puts the variable part last and the required context first. This is the same family as the
prose-matching lesson — **the aim is to make the wrong thing hard to write, not to detect it
afterward** — and I got it wrong in the very commit written to apply that idea.