Skip to content

chore: accumulated crumbs pass — README counts, format list, extra naming, smoke -q, bench comment - #502

Merged
JArmandoAnaya merged 1 commit into
mainfrom
docs/crumbs-pass
Aug 10, 2026
Merged

chore: accumulated crumbs pass — README counts, format list, extra naming, smoke -q, bench comment#502
JArmandoAnaya merged 1 commit into
mainfrom
docs/crumbs-pass

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

Docs, comments and one workflow flag. No behaviour changes — no file under
src/ or frontend/ is touched, and the one workflow edit that is not a comment
is a dropped -q.

Each item below was re-verified against b7dd21d before editing; two of the
seven turned out to need nothing, and the verification of a third found three
separate staleness bugs the item had not named.

1. README — visionset ui was already gone; three counts were not

git grep "visionset ui" over README.md and docs/ returns nothing at HEAD:
the visionset server rename (#329) is fully landed, the quickstart is correct,
and the install snippet reflects reality. Nothing to do for the item as
written.

Verifying it did surface three stale facts in the same file, all fixed here:

Claim at HEAD Reality, verified Now reads
"Export | YOLO, COCO and Pascal VOC" nine plugins in [project.entry-points."visionset.formats"], including the five-plugin lane family "YOLO, COCO, Pascal VOC and the lane family"
"39 MCP tools an agent can drive" docs/mcp-tools.md lists 40 — 38 always offered, 2 gated "an MCP server an agent can drive" — the count is gone, the generated reference is already linked two paragraphs down
"plus one that is offered only when the server is started with --allow-destructive" two: delete_batch and delete_project "plus the two deletions that are offered only when…"

The two numbers were removed rather than corrected: a count in prose beside a
generated listing is a second encoding, and it had already drifted twice.

2. docs/install.md — the format count

The block showed visionset format list # coco, dummy, voc, yolo. Actual
output, read from installed entry-point metadata at HEAD:

9 ['bdd100k-lane', 'coco', 'culane', 'curvelanes', 'dummy', 'openlane-2d', 'tusimple', 'voc', 'yolo']

Replaced with prose that cannot go stale, since the honest answer is not a fixed
list at all — third-party distributions register into the same entry-point group,
so what a given installation can write is a property of that installation.

3. docs/architecture/backend/inference.md — extra, not dependency group

"The optional dependency group is local-inference" → an extra, with the
one-clause reason pyproject.toml gives: a group is for developing this
repository, an extra is something a user installs.

4. format-smoke ran at -qq

pyproject.toml sets addopts = "-q" and the step added another, which
suppresses the N passed, M skipped line. The explicit -q is dropped, with a
comment carrying the reason — the same choice inference-smoke made and for the
same reason: the count line is what shows a smoke job quietly shrinking to
nothing. cf. #490.

5. The annotator-bench comment is reunited with its job

Its first half sat above the wheel job and its second half above
annotator-bench, with wheel and format-smoke in between — a sentence broken
across ~250 lines, one half ending "was taken on a" and the other opening
"developer machine". Moved as a block; the wheel comment now begins cleanly at
its own job.

Proof the move is inert. Both revisions of the file were parsed and their job
trees compared:

job names identical: True
jobs whose parsed content changed: ['format-smoke']
    -"run": "…test_coco_smoke.py -q"}]}
    +"run": "…test_coco_smoke.py"}]}
top-level keys equal: True

Exactly one string differs across the whole workflow, and it is item 4. Every
comment change is invisible to the parser.

6. The order-dependent test — filed as #501

No issue existed. Filed, and it is worse than "order-dependent": it is a
current, reproducible failure, not a latent one.

test_configuring_a_connection_reaches_no_model_runtime ends with
assert not {"torch","transformers","huggingface_hub"} & set(sys.modules), a
process-global fact. tests/inference sorts before tests/kernel, and
provider_for on a ready connection calls _extra.require(), which imports all
five modules. Verified at b7dd21d with the extra installed:

$ uv run pytest
FAILED tests/kernel/test_inference_connections.py::test_configuring_a_connection_reaches_no_model_runtime
1 failed, 3137 passed, 14 skipped in 201.40s

$ uv run pytest tests/kernel/…::test_configuring_a_connection_reaches_no_model_runtime
1 passed in 0.27s

So uv run pytest cannot be run green by any contributor carrying the extra —
the one environment where the assertion means anything. CI is unaffected, which
is why it went unnoticed: the python job installs no extra and
inference-smoke runs a directory subset excluding tests/kernel. Not fixed
here
, per this pass's bounds.

7. The Docker CPU-inference overlay — verified landed, no action

Present and documented at HEAD:

  • docker/compose.cpu-inference.yaml and docker/api-cpu-inference.Dockerfile
    both exist.
  • The three modes are documented twice: in docs/inference.md (the three
    docker compose -f … invocations side by side) and in the overlay's own header
    comment, which tabulates plain / +compose.gpu.yaml / +compose.cpu-inference.yaml
    and notes all three share one workspace-data/.

Test plan

Ran in the worktree; exit codes verbatim.

Stage Result
uv run pytest (base environment, VISIONSET_REQUIRE_FFMPEG=1) 3139 passed, 13 skipped — exit 0
ruff check . / ruff format --check . exit 0 / exit 0
mypy src/visionset/kernel / mypy src/visionset exit 0 / exit 0
lint-imports 4 contracts kept, 0 broken — exit 0
export_openapi.py + git diff --exit-code openapi.json no drift — exit 0
export_mcp_tools.py --check no drift — exit 0
pnpm -r build exit 0
pnpm test 77 node tests pass — exit 0
pnpm -r lint exit 0

pnpm test is the load-bearing one here, and deliberately so: it carries
docs_links.test.mjs, which resolves every internal link and #anchor across
the tracked Markdown — including the new docs/releases.md#the-lane-formats
anchor in the README — and cooldown.test.mjs, which reads
.github/workflows/ci.yml and asserts every uv sync line is --locked.

The two browser suites were not run, and the justification is the same shape
as #490's: the diff is four files — one README, two docs, one workflow — and
touches no frontend source, no bundle, no route, no generated artifact and no
Python. Neither suite has an input that moved. CI's annotator-e2e and
cycle-e2e jobs are the arbiter.

A note on the title

The dispatch specified docs/ci: as the type. That is not a Conventional Commit
type, so this uses bare chore: — the precedent being #476, a docs-and-tooling
pass under the same type. The words are otherwise the dispatch's.

Found, not fixed

cf. #490, #500, #501

…ming, smoke -q, bench comment

Docs, comments and one workflow flag. No behaviour changes.

- README carried three counts that had gone stale: the export list named three
  formats where nine plugins are registered, "39 MCP tools" against a generated
  reference listing forty, and "one" destructive tool where two are gated. The
  numbers are gone rather than corrected where a count was never the point.
- docs/install.md showed a four-entry `format list` output as a comment. The
  set is a property of an installation — third-party distributions register
  into the same entry-point group — so the prose now says to run it.
- docs/architecture/backend/inference.md called `local-inference` a dependency
  group. It is an extra, a distinction pyproject.toml spends a paragraph on.
- `format-smoke` passed `-q` on top of pyproject's `addopts = "-q"`, running at
  `-qq` and suppressing the count line that would show it shrinking to nothing.
- The `annotator-bench` comment was split across ~250 lines, with two whole jobs
  between a sentence's halves. Rejoined above the job it describes.
@JArmandoAnaya
JArmandoAnaya merged commit cda32e9 into main Aug 10, 2026
14 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the docs/crumbs-pass branch August 10, 2026 10:03
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