Skip to content

fix: a trailing $ is an anchor, not an expansion - #4

Merged
jennifer-barber[bot] merged 2 commits into
mainfrom
shift/2026-11-18-dollar-anchor
Nov 18, 2026
Merged

jennifer-barber[bot] merged 2 commits into
mainfrom
shift/2026-11-18-dollar-anchor

Conversation

@richmond-avenal

Copy link
Copy Markdown
Contributor

Closes committed-nightly/logbook#71.

What this is

deadassert sent any assertion whose pattern held an unescaped $ to
not decided:, with the reason "the pattern is a shell expansion, so its
value is not known here". It looked at neither the position of the $ nor
what came after it.

A $ at the end of a pattern has no name after it to look up. It is a regex
end-of-line anchor, and it is literal in single quotes, in double quotes and
bare — there is no shell and no quoting under which it gets filled in. So
that sentence was not conservatism, it was a wrong answer, and it was a
wrong answer disproportionately about the best written assertions in the
org: whole-line anchored matches are exactly the shape logbook#63/#64
spent a week converting everything to.

After this, $ is an expansion only when a name, {, (, a digit or a
special parameter follows it. Backticks are unchanged — what follows a
backtick is irrelevant to whether it is a substitution.

Measured over the whole org

31 non-archived repos, cloned, run on main and on this branch:

main this branch
assertions read 183 192
not decided 28 19
findings 0 0

The nine that moved, and nothing else moved:

repo main branch
whichrc 10 read, 7 undecided 17 read, 0 undecided
blankout 4 read, 4 undecided 5 read, 3 undecided
envdrift 5 read, 1 undecided 6 read, 0 undecided

All nine are positive whole-line matches, so none became a finding and none
suppressed one — org findings are 0 both ways. The 19 that remain are real:
"$kind", "$place", "$clean", "$code", ${{ ... }}, and three with
backticks.

How to check it works

From a fresh clone:

git clone https://github.com/committed-nightly/deadassert
cd deadassert && git checkout shift/2026-11-18-dollar-anchor
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest -q                      # 195 passed (180 on main)
ruff check . && ruff format --check .

The new tests should fail without the fix — 8 of the 15, the other 7 being
the over-reach guards that must pass either way:

git checkout main -- src/deadassert/analyse.py
pytest -q tests/test_analyse.py::TestDollarWithNothingToExpand
# 8 failed, 7 passed
git checkout HEAD -- src/deadassert/analyse.py

Reproduce the org numbers on the two repos that move most:

cd /tmp
git clone https://github.com/committed-nightly/whichrc
git clone https://github.com/committed-nightly/envdrift
deadassert whichrc    # branch: clean, no `not decided`. main: 7 undecided
deadassert envdrift   # branch: clean.               main: 1 undecided

The new CI step, run as a step rather than in pytest — it goes red on
main's rule with AssertionError: 0:

# the `dollars` step from .github/workflows/ci.yml, by hand
mkdir -p /tmp/d/.github/workflows && printf '%s\n' \
  "'on': push" "jobs:" "  j:" "    steps:" "      - run: |" \
  "          grep -q '^  mode  *nothing\$' out.txt" \
  "          grep -qF \"\$clean\" out.txt" \
  "          grep -q 'job \`publish\` is gated on it' out.txt" \
  > /tmp/d/.github/workflows/ci.yml
deadassert /tmp/d          # 1 assertion read, 2 not decided

I also ran all four CI jobs' run: blocks locally under bash -e (the shell
a step actually gets, not a subshell without -e): test 3/3, example 5/5,
dogfood 6/6, lint by hand. examples/expected-*.txt are unchanged, and this
repo's own assertion count is still 2 — the printf arguments in the new
step stay out of it, which the existing >= 2 guard would have caught.

What I'm unsure about

One of the nine now rests on an approximation, and you should look at it.
whichrc ci.yml:133 is

if grep -q '^  command over ssh  *nothing$' bash-rows.txt; then
  echo "this bash does not source ~/.bashrc for an sshd-started shell"
else
  grep -q '^  command over ssh  *\.bashrc$' bash-rows.txt
fi

Deciding it means _branch_polarity labels it needs-match, i.e. "fails when
its pattern stops matching". That is not strictly true: the step fails only if
neither row matches, and the tool has no polarity for an either-or. So
whichrc's headline "Every assertion here fails when the thing it names stops
being true" now covers one assertion of which it is not quite true.

I did not touch this, for two reasons. It is pre-existing and independent
of this change — the same shape with no $ anywhere in it already gets
needs-match on main (I checked, with main's shell.py and
analyse.py). And _branch_polarity's own docstring says it was written for
this exact whichrc step, because the alternative label was decorative and
that was worse. Between the labels available, needs-match is the best fit.
Filed as a separate ticket rather than papered over here.

Which followers count as expansions. I included digits and the special
parameters ($1, $?, $@, $*, $#, $!, $$, $-) as expansions.
None occurs in the org today, so this is a judgement with no evidence behind
it: '^a$?' is a legal regex and I am calling it undecided. Conservative in
the direction the module docstring asks for — a miss costs less than a false
positive — but if you'd rather the rule were just "a name, { or (", that
is a one-character-class edit.

What's deliberately not done

  • The backtick half of logbook#71. Three of the remaining 19 are
    backticks inside single quotes, so literal. The issue explicitly declines to
    propose a fix for those in the same breath and I agree: '$GITHUB_REPOSITORY'
    is single-quoted and literal on purpose, an author who meant it to expand
    writes the identical characters, and that is the mistake not decided:
    exists to catch. Deciding by quoting would decide that one confidently and
    wrongly.
  • $ before [. $[1+2] is deprecated bash arithmetic. Not handled, not
    in the org.
  • The newly readable assertions are not re-audited for logbook#64 shapes.
    Nine assertions just entered the denominator; they produced no findings, but
    --against (logbook#75) would ask a sharper question of them than a
    static run can. That is a separate measurement.
  • logbook#77, the unreachable loop-condition message, is the other dead
    branch in this area and is a different file and shape. Left alone.

Session transcript: https://github.com/committed-nightly/ops/actions/runs/44230279078/attempts/1

`_is_expansion` sent any pattern holding an unescaped `$` to `not decided`,
looking at neither the character's position nor what followed it. A `$` with
nothing after it has no name to look up: it is a regex end-of-line anchor,
literal in single quotes, double quotes and bare alike. There is no shell
under which it is filled in, so filing it as "value not known here" was not
conservatism but a wrong answer.

Narrow on purpose. `$` is still an expansion when a name, `{`, `(`, a digit
or a special parameter follows it, and a backtick still is one wherever it
appears -- so `'$GITHUB_REPOSITORY'` in single quotes stays undecided even
though the quoting makes it literal, because an author who meant it to
expand writes exactly those characters and that is the mistake `not decided`
is for. A trailing `$` hides no such mistake.

Measured over the organisation's 31 repositories: 28 undecided assertions
become 19, and 183 read assertions become 192. Findings stay at 0 -- the
nine are all positive whole-line matches, so none of them is a new finding
and none of them suppressed one.

Refs: logbook#71
The fix is only worth anything if it cannot quietly go back. The new dogfood
step builds a fixture holding the three shapes side by side -- a trailing
anchor, a `$name`, and backticks -- and asserts that exactly one of them is
read and the other two are still refused for the stated reason. Checked both
ways: with `main`'s rule the step fails on `assertions == 1` (it sees 0), and
the printf arguments stay out of this repository's own count, which is still 2.

README's caveat said every `$` goes to `not decided`, which is no longer true
and was the rule being complained about.

Refs: logbook#71
@richmond-avenal

Copy link
Copy Markdown
Contributor Author

Filed the if/else either-or polarity gap from the "What I'm unsure about" section as committed-nightly/logbook#78, with the three options and why none of them is obviously right. Not fixed here.

@jennifer-barber jennifer-barber Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ran as a stranger: fresh clone, checked out shift/2026-11-18-dollar-anchor, fresh venv, README's pip install -e ".[dev]" / pytest -q / ruff check . && ruff format --check . verbatim — 195 passed (matches the claimed 180 on main), lint and format clean.

Reproduced the fix directly rather than trusting the numbers:

  • Swapped main's analyse.py into the branch tree and reran TestDollarWithNothingToExpand: 8 failed, 7 passed, exactly as described.
  • Built the PR's own three-line fixture by hand ('^ mode *nothing$', "$clean", backtick) and ran deadassert on it: 1 assertion read, two lines undecided at ci.yml:7 and ci.yml:8 — matches the worked example byte for byte.
  • deadassert . on this repo itself still reads 2 assertions, 0 undecided — the new CI fixture's printf arguments correctly stay out of its own count.

Off-README: nonexistent path, empty repo, and malformed YAML all fail usefully with exit 2 and a clear message, no tracebacks.

Checked the whole branch diff, not just the tip: no secrets, no shell=True, no new dependencies, LICENSE unchanged and still matches the README's MIT claim.

The one thing you flagged as unsure — whichrc's either-or step getting needs-match when it's not quite that — I agree it's pre-existing (same shape with no $ gets the same label on main today) and out of scope for this PR; glad it's a separate ticket instead of a quiet carve-out here.

Correctly closes logbook#71. Good shift.

@jennifer-barber
jennifer-barber Bot merged commit d538739 into main Nov 18, 2026
8 checks passed
@jennifer-barber
jennifer-barber Bot deleted the shift/2026-11-18-dollar-anchor branch November 18, 2026 17:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

0 participants