What
uphold runs on Rust, Go, Python, TypeScript and shell trees across the fleet,
and nothing states which rung of checking exists for which language. The
answer is scattered: the comment_regexp row of the rule table in
docs/REFERENCE.md names Rust, Python and Go; ADR 0005 has a cost table with
no language column; Cargo.toml links three grammars. A consumer with a
TypeScript tree reads all three and still does not know whether a rung is
there for them, is a gate they own themselves, or is nobody's job.
Why it matters
A claim in policy/upheld.toml names a rule and the seam it runs at. The
matrix is the same claim one level up: for this language, at this rung, what
enforces it and where. Without it, "uphold covers the repository" means one
thing on a Go tree and a different thing on a TypeScript tree, and neither
reader knows which.
Proposed
A docs page, docs/COVERAGE.md, linked from the README beside REFERENCE.md
and DESIGN.md. Rows are rungs, columns are languages, and every cell holds
exactly one of three states:
The rungs, with the hook-ladder rung each belongs to by cost class:
| rung |
what |
ladder |
| text |
regex over bytes: regexp, comment_regexp, prose_regexp, require_regexp |
commit |
| syntax |
a tree-sitter query over the parse tree |
commit |
| semantic |
compiler and linter |
push |
| proof |
a verifier over a stated core |
push, or manual where it runs longer than minutes |
Cells as they stand today, before any of the linked issues land:
| rung |
Rust |
Go |
Python |
TypeScript |
shell |
| text |
native |
native |
native |
native |
native |
| syntax |
not covered (see #212) |
not covered (see #216) |
not covered (see #216) |
not covered (see #216) |
not covered (see #216) |
| semantic |
consumer-owned: clippy |
consumer-owned: go vet, staticcheck |
consumer-owned: mypy, ruff |
consumer-owned: tsc, eslint |
consumer-owned: shellcheck |
| proof |
consumer-owned: Verus |
consumer-owned: Gobra |
consumer-owned: CrossHair, Nagini |
not covered |
not covered |
Dafny, compiled to Go or Python for a verified core, is a fifth proof entry
that is not per language; it gets its own line under the table, in the same
consumer-owned state.
The Rust proof cell is about a consumer's Rust tree. #213 runs Verus over this
binary's own evaluator core, which is this repository being its own consumer,
and it does not put a proof rung into anyone else's tree.
Every cell that describes a state the repository does not have yet is marked
aspirational, with the issue number, and the table above is the "today" table.
A second table, "after", is not on this page: the page states what is, and the
issues state what will be.
The comment_regexp and trivial_comments checks parse Rust, Python and Go
and read # lines in shell; they are a text-rung check with a parsed comment
extractor, not a syntax rung, and the page should say so once rather than let
the row imply a syntax rung exists.
What would close it
Related: #212 (syntax rung, Rust), #213 (proof over this binary's own core),
#216 (syntax rung beyond Rust), #217 (the four Go wrappers).
What
uphold runs on Rust, Go, Python, TypeScript and shell trees across the fleet,
and nothing states which rung of checking exists for which language. The
answer is scattered: the
comment_regexprow of the rule table indocs/REFERENCE.mdnames Rust, Python and Go; ADR 0005 has a cost table withno language column;
Cargo.tomllinks three grammars. A consumer with aTypeScript tree reads all three and still does not know whether a rung is
there for them, is a gate they own themselves, or is nobody's job.
Why it matters
A claim in
policy/upheld.tomlnames a rule and the seam it runs at. Thematrix is the same claim one level up: for this language, at this rung, what
enforces it and where. Without it, "uphold covers the repository" means one
thing on a Go tree and a different thing on a TypeScript tree, and neither
reader knows which.
Proposed
A docs page,
docs/COVERAGE.md, linked from the README besideREFERENCE.mdand
DESIGN.md. Rows are rungs, columns are languages, and every cell holdsexactly one of three states:
native: this binary evaluates it. Today that is the text rules; thesyntax rules of A text rule sees bytes, so no bundled rule can say "no unwrap outside cfg(test)"; a rule form over the parse tree the binary already builds #212 and The syntax and proof rungs stop at Rust: Go, Python, TypeScript and Bash need a grammar, an example rule and a gate recipe each #216 join when they land.
consumer-owned external gate: the compiler, linter or verifier theconsumer already wires into its own hook config. uphold's part is at most a
pointer on this page naming the tool and the rung; it ships nothing that
runs the tool. One tool per job: a wrapper of the consumer's own toolchain
shipped from here is a second copy of the consumer's gate (see uphold-gofmt, uphold-go-vet, uphold-go-build and uphold-go-test wrap the consumer toolchain, so 31 consumers run their Go gate from an uphold release instead of their own config #217).
not covered.The rungs, with the hook-ladder rung each belongs to by cost class:
regexp,comment_regexp,prose_regexp,require_regexpCells as they stand today, before any of the linked issues land:
Dafny, compiled to Go or Python for a verified core, is a fifth proof entry
that is not per language; it gets its own line under the table, in the same
consumer-owned state.
The Rust proof cell is about a consumer's Rust tree. #213 runs Verus over this
binary's own evaluator core, which is this repository being its own consumer,
and it does not put a proof rung into anyone else's tree.
Every cell that describes a state the repository does not have yet is marked
aspirational, with the issue number, and the table above is the "today" table.
A second table, "after", is not on this page: the page states what is, and the
issues state what will be.
The
comment_regexpandtrivial_commentschecks parse Rust, Python and Goand read
#lines in shell; they are a text-rung check with a parsed commentextractor, not a syntax rung, and the page should say so once rather than let
the row imply a syntax rung exists.
What would close it
docs/COVERAGE.mdexists and the README links it.uphold-gofmt,uphold-go-vet,uphold-go-buildoruphold-go-test; those are uphold-gofmt, uphold-go-vet, uphold-go-build and uphold-go-test wrap the consumer toolchain, so 31 consumers run their Go gate from an uphold release instead of their own config #217's to remove.present tense.
lefthook.ymland.pre-commit-config.yamlfor every rung this repository runs on itself.Related: #212 (syntax rung, Rust), #213 (proof over this binary's own core),
#216 (syntax rung beyond Rust), #217 (the four Go wrappers).