56 lines
6.5 KiB
Markdown
56 lines
6.5 KiB
Markdown
# The instruments
|
|
|
|
Generated by `tools/tool_map.py` from the tree it is asked to read. Do not
|
|
edit by hand: `python3 tools/tool_map.py --repo . --write docs/TOOLS.md`
|
|
re-renders it, and `--check` grades it (rc 1 when the document and the tree
|
|
disagree). Every cell below is derived, never typed -- purpose from the
|
|
module docstring, flags from the tool's own `--help`, probe rows from
|
|
`selftest_sweep.py`'s tables, the gate leg from `verify.py`'s `LEGS`.
|
|
|
|
**21 tools, 21 with a `--help` oracle.** Probes are read as `read-refusal / not-utf8 / malformed-input` rows; a `-` means that axis does not name the tool.
|
|
|
|
| tool | what it grades | flags | probes | gate leg |
|
|
|---|---|---|---|---|
|
|
| `append_only_audit.py` | measure the repo-wide append-only invariant from git objects. | `--repo` `--json` `--selftest` `--progress` | 1 / 0 / 1 | - |
|
|
| `append_only_owners.py` | the SECOND instrument for the append-only invariant: was a replaced line ANOTHER party's line? | `--json` `--selftest` | 1 / 1 / 2 | - |
|
|
| `census_row_delta.py` | row-level diff of two doc_census_check.py censuses. | `--key` `--keys` `--verbose` `--selftest` `--json` | 1 / 1 / 2 | - |
|
|
| `check_lint.py` | grade a Ralph-loop `CHECK:` line before it is run. | `--selftest` `--ralph-dir` `--log` `--check` `--json` `--quiet` `--verbose` `--all` `--fail-on-fault` | 1 / 0 / 2 | - |
|
|
| `checkin_check.py` | the gate on the check-in contract, which nothing measured. | `--repo` `--dir` `--roster` `--today` `--gaps` `--since` `--json` `--baseline` `--emit-baseline` `--fail` `--selftest` | 1 / 1 / 1 | `checkin` |
|
|
| `citation_hash_class.py` | resolve every hex token in a corpus to its hash family, and flag the tokens that carry no stated class. | `--repo` `--rev` `--corpus` `--json` `--window` `--min-len` `--only` `--context` `--siblings` `--selftest` | 1 / 0 / 1 | - |
|
|
| `citation_resolve_check.py` | does every `<file>:<line>` citation in this archive's prose actually resolve, and to which file? | `--repo` `--rev` `--corpus` `--json` `--only` `--context` `--selftest` | 1 / 0 / 1 | - |
|
|
| `doc_census_check.py` | does a tool's own docstring census match the census that tool PRINTS? | `--repo` `--rev` `--tools` `--json` `--no-run` `--fail` `--vocab` `--save-vocab` `--selftest` | 1 / 0 / 1 | - |
|
|
| `doc_command_check.py` | a command a docstring tells you to run must be a command the tool still accepts. | `--repo` `--rev` `--tools` `--json` `--fail` `--selftest` | 1 / 0 / 1 | `doc-commands` |
|
|
| `gate_blame.py` | which landing turned a gate leg red? | `--repo` `--leg` `--range` `--ref` `--queue` `--index` `--timeout` `--json` `--quiet` `--selftest` | 1 / 0 / 1 | - |
|
|
| `landing_check.py` | is every file at this revision actually served by the forge? | `--repo` `--rev` `--branch` `--base-url` `--path` `--max-bytes` `--timeout` `--json` `--quiet` `--selftest` | 1 / 0 / 1 | - |
|
|
| `path_claim_check.py` | does every in-namespace path this archive names exist at this revision? | `--repo` `--rev` `--corpus` `--json` `--only` `--context` `--fail-on-missing` `--baseline` `--selftest` | 1 / 0 / 1 | `path-claims` |
|
|
| `queue_append_audit.py` | was the queue's index current IN THE TREE of every commit that touched the queue? | `--repo` `--queue` `--index` `--from` `--to` `--all` `--guard` `--timeout` `--json` `--selftest` | 1 / 0 / 1 | `append-audit` |
|
|
| `queue_claim_check.py` | the claim check for `WORK-QUEUE.md`, shipped with its tests. | `--queue` `--json` `--git` `--validate` `--selftest` `--fail-on-stale` `--explain` `--census` | 1 / 1 / 1 | - |
|
|
| `queue_index.py` | the work queue's table of contents, and the gate that it is current. | `--repo` `--queue` `--index` `--json` `--write` `--check` `--outside` `--selftest` | 1 / 1 / 1 | `index-current` |
|
|
| `reply_check.py` | does every reply file's own header agree with its own name? | `--repo` `--dir` `--roster` `--head-lines` `--json` `--baseline` `--emit-baseline` | 1 / 0 / 1 | `reply-headings` |
|
|
| `selftest_sweep.py` | every instrument proves itself, in one command, and the number it advertises is the number it prints. | `--repo` `--tools-dir` `--timeout` `--json` `--baseline` `--no-baseline` `--write-baseline` `--quiet` `--verbose` `--selftest` | 1 / 0 / 1 | `selftest-sweep` |
|
|
| `served_drift_check.py` | does the host actually serve the tree at this revision? | `--root` `--rev` `--base-url` `--prefix` `--exclude` `--max-bytes` `--timeout` `--json` `--quiet` `--selftest` | 1 / 0 / 1 | - |
|
|
| `tool_map.py` | the instruments get a map, and the map is generated from the tree. | `--repo` `--rev` `--write` `--check` `--json` `--selftest` | 1 / 0 / 1 | - |
|
|
| `verify.py` | the HOME the index gate did not have: one command, eight legs, one exit code, and a row per leg so a partial run cannot look like a clean one. | `--repo` `--queue` `--index` `--checkin-day` `--fast` `--timeout` `--json` `--quiet` `--selftest` | 1 / 0 / 1 | - |
|
|
| `write_probe.py` | Measure the WRITE end of every tool in tools/: `--json PATH` at a target the host cannot write. | `--repo` `--only` `--timeout` `--json` `--selftest` `--verbose` | 1 / 0 / 1 | `write-axis` |
|
|
|
|
## The gate
|
|
|
|
`python3 tools/verify.py --repo .` runs the legs below and prints one line
|
|
each; a leg resolves its tool inside the repo it grades. The `slow` legs are
|
|
dropped by `--fast`.
|
|
|
|
| leg | tool | slow | what it grades |
|
|
|---|---|---|---|
|
|
| `checkin` | `checkin_check.py` | no | grade the newest day's check-ins against the naming and duplicate rules |
|
|
| `path-claims` | `path_claim_check.py` | no | every path the archive's prose names, graded at the tree about to be committed (index inventory, disk bytes), against the ledger that states the readings already reviewed |
|
|
| `reply-headings` | `reply_check.py` | no | grade every reply's heading against its own filename |
|
|
| `index-current` | `queue_index.py` | no | render the index and byte-compare it with the document |
|
|
| `append-audit` | `queue_append_audit.py` | no | grade the newest queue-touching commit in its own tree |
|
|
| `doc-commands` | `doc_command_check.py` | no | every command a tool's docstring tells a reader to run: its flags must be options that tool's --help accepts |
|
|
| `selftest-sweep` | `selftest_sweep.py` | yes | every tool's --selftest and both read-refusal axes |
|
|
| `write-axis` | `write_probe.py` | no | a --json target this host cannot write: rc 2, one line naming it, never a traceback -- and the same rule for every caller-path write flag (--write, --save-vocab) |
|
|
|
|
A tool that appears in no leg is still graded by `selftest-sweep`, which runs
|
|
every tracked tool's `--selftest` and both read-refusal axes -- so the
|
|
`probes` column above is also the sweep's cover of that tool.
|