docs: document make-run, fix paths stale since 0.2.0, and gate both - #25
Merged
Conversation
Every `uv run` rewrote uv.lock in place, because the committed file was produced by an older uv that omitted the resolution markers this one writes out. Nothing about the resolved versions changed — only how the markers are spelled. The cost was not cosmetic: `make lint` runs mdformat through `uv run`, so the hook mutated a file while pre-commit was watching, which reads as "files were modified by this hook". Every commit failed and rolled back its own fixes until the lockfile was rewritten by hand. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
make-run shipped in 0.4.0 as the headline feature with no page, no nav entry, and no mention in the README — so the one tool whose purpose is ending hand-transcribed commands could only be found by reading its source. The new page covers all five functions, the rule that an undefined variable is an error and never an empty string, and why the queries go through a sentinel makefile rather than --eval. Every documented source path had also been wrong since 0.2.0. Scripts moved to src/just_bashit/ for Python packaging and the docs kept saying src/, so `. just-bashit/src/datetime.sh` failed for anyone who copied it — including out of an unpacked release tarball, which carries the current layout. The README additionally described a package layout that no longer existed and never mentioned installation or the entry points. The gate is what keeps this from recurring. Two invariants, one per way it went unnoticed: every file in src/just_bashit/ is named somewhere in the docs, and every page under docs/ is reachable from zensical.toml's nav, since an unlinked page builds cleanly and looks exactly like one that was never written. docs/changelog.md is excluded as a mention source — it records every script ever added, so counting it would pass everything the moment it was released. Dispatched from pre-commit rather than DOCS_CHECK_PRE_CMDS because CI runs make test, make coverage and make lint, not make docs-check; a gate hung off docs-check would be local-only. always_run rather than types: [markdown] because what breaks it is adding a script, and that commit touches no markdown at all. Both failure modes were verified red before the fixes went in. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
make-runshipped in 0.4.0 as the headline feature and was documentednowhere — no page, no nav entry, no line in the README. The tool whose
entire purpose is ending hand-transcribed commands could only be found by
reading its source.
What's here
A page for
make-run(docs/libraries/make-run.md, Libraries nav)covering
mk-var,mk-vars,mk-run,mk-has,mk-origin, theundefined-is-not-empty rule, and why the queries use a sentinel makefile
instead of
--eval(3.82+, and macOS ships 3.81).Source paths, wrong since 0.2.0. Scripts moved to
src/just_bashit/for Python packaging; the docs kept saying
src/. Every. just-bashit/src/datetime.shin the README, the getting-started guide,and all ten library pages failed for anyone who copied one — including out
of an unpacked release tarball, which carries the current layout.
README described a package layout that no longer existed, and never
mentioned
uv tool install, thejb/jbx/jb-inspectentry points,or
make-run. It is the PyPI long description, so it is also the project'sfront page there.
A gate, so this cannot recur.
make docs-coverageasserts two things:src/just_bashit/is named somewhere in the docs;docs/is reachable fromzensical.toml's nav — anunlinked page builds cleanly and looks exactly like one never written.
docs/changelog.mdis excluded as a mention source: it records every scriptever added, so counting it would pass everything the moment it was released.
It dispatches from pre-commit rather than
DOCS_CHECK_PRE_CMDS, because CIruns
make test,make coverageandmake lint— notmake docs-check—and a gate CI never reaches is a local-only gate.
always_runrather thantypes: [markdown], because what breaks it is adding a script, and thatcommit touches no markdown at all.
A lockfile relock, in its own commit. Every
uv runrewroteuv.lockin place — the committed file predates the marker normalisation this uv
writes — so mdformat mutated a file mid-hook and pre-commit rolled back every
commit. Resolved versions are unchanged; only marker spelling.
Verification
nav entry removed → fails), green after.
make lintclean, including the newdocs-coveragehook.make docs-check(strict build) clean: "No issues found".🤖 Generated with Claude Code