Skip to content

docs: document make-run, fix paths stale since 0.2.0, and gate both - #25

Merged
hunterdsp merged 2 commits into
mainfrom
docs/make-run
Aug 7, 2026
Merged

docs: document make-run, fix paths stale since 0.2.0, and gate both#25
hunterdsp merged 2 commits into
mainfrom
docs/make-run

Conversation

@hunterdsp

Copy link
Copy Markdown
Contributor

make-run shipped in 0.4.0 as the headline feature and was documented
nowhere — 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, the
undefined-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.sh in 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, the jb / jbx / jb-inspect entry points,
or make-run. It is the PyPI long description, so it is also the project's
front page there.

A gate, so this cannot recur. make docs-coverage asserts two things:

  1. every file shipped in src/just_bashit/ is named somewhere in the docs;
  2. every page under docs/ is reachable from zensical.toml's nav — an
    unlinked page builds cleanly and looks exactly like one 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.

It dispatches from pre-commit rather than DOCS_CHECK_PRE_CMDS, because CI
runs make test, make coverage and make lint — not make docs-check
and a gate CI never reaches is a local-only gate. always_run rather than
types: [markdown], because what breaks it is adding a script, and that
commit touches no markdown at all.

A lockfile relock, in its own commit. Every uv run rewrote uv.lock
in 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

  • Both gate failure modes verified red before the fixes (page removed → fails;
    nav entry removed → fails), green after.
  • make lint clean, including the new docs-coverage hook.
  • make docs-check (strict build) clean: "No issues found".

🤖 Generated with Claude Code

hunterdsp and others added 2 commits August 6, 2026 20:43
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>
@hunterdsp
hunterdsp merged commit 4d8c016 into main Aug 7, 2026
11 checks passed
@hunterdsp
hunterdsp deleted the docs/make-run branch August 7, 2026 00:50
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.

1 participant