Skip to content

Nothing states which rung of checking exists for which language: a languages by rungs matrix, native or bundled or external or not covered #215

Description

@HackingGate

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).

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions