Skip to content

Write the V1 semantics and name their tests - #21

Merged
VirtualMachinist merged 5 commits into
mainfrom
v1/semantics
Nov 14, 2026
Merged

VirtualMachinist merged 5 commits into
mainfrom
v1/semantics

Conversation

@VirtualMachinist

Copy link
Copy Markdown
Member

V1 checkpoint G4a: docs/semantics.md.

  • New sections cover:
    • the bounded HTTP client and the shared per-backend limit;
    • named-query rules;
    • the address scrub on targets and query output;
    • the Grafana health rule;
    • the CLI JSON, --now and error contract;
    • the per-command exit table;
    • the overlay host map and backend vantage;
    • the sources listing.
  • Every rule names the test or fixture that proves it. The schema count is corrected.
  • internal/exitcode/semantics_names_test.go fails if the page names a test, fuzz target or tracked path that doesn't exist, and a planted case proves the guard bites.

🤖 Generated with Claude Code

Work in progress, held until the Grafana, sources and renderer steps land so
the page can name real tests and fixtures. Not pushed.

Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com>
Unhealthy Grafana is exit 4 with an error line and empty stdout; the health
document prints only when healthy, and sources shows the unhealthy state as
data. A missing or unexpected --host is exit 3. An empty query result is an
answer. Not pushed: held until the Grafana, sources and renderer steps land.

Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com>
Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com>
Each V1 rule in docs/semantics.md now names the test that proves it and the
fixture or recorded answer it runs on: the bounded client and its shared
limiter, the named-query rules, what the Prometheus commands may print, the
Grafana health table, the CLI contract, the per-command exit table and the
overlay. A new section describes the sources listing, which the page lacked:
one row per configured backend, how a row is checked, a down backend as data
with exit 0, last_ok null in V1, and authority rows deferred to V2 and V5. The
fixture index gains a table of the V1 fixture directories.

The page follows the PM rulings: an unhealthy Grafana is exit 4 with one error
line and empty stdout, a missing or unexpected --host is exit 3, an empty
query result is an answer, and the schema count is nine.

A new test fails if the page names a test, a fuzz target or a tracked path
that the tree does not have, and a second test plants a renamed test and a
moved fixture to show the check bites.

Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com>
Signed-off-by: VirtualMachinist <252028890+VirtualMachinist@users.noreply.github.com>
@VirtualMachinist
VirtualMachinist merged commit ca205bf into main Nov 14, 2026
4 checks passed
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