List the numbers no source states

A limit, an interval, a lifetime, a wait or a window somebody picked and wrote into a product's code decides how the product behaves, and nothing tells the reader why that value and not another: a request cut off after five seconds refuses a slow answer that would have come, and a report that keeps a log's last lines loses the cause written above them. stado quality numbers lists every such number in one committed revision of a checkout, so each can be given its source or replaced by the event it stands in for.

stado quality numbers [--root DIR] [--revision REVISION] [--json]

--root names the checkout (the working directory by default) and --revision the commit read (the checkout's HEAD by default). The committed tree is read, never the working tree, so another session's uncommitted edits neither add rows nor hide them. The command exits 0 whenever the revision was read, whether it found rows or none; a reading with no row is the whole answer to "does this revision decide with a number nobody stated", and it is the completion measure of that defect class.

What is read

Every regular file of the revision whose extension is rs or sh, outside any directory named tests (a test states the values it provokes a case with; there the number is the case, not a decision of the product). A symlink or a submodule is not read. A line whose code starts with // or # is a comment or an attribute and states no value, and a line's code ends where // starts a comment.

Two kinds of number are rows:

• A named constant (const or static, any visibility) of a number type (u8 to u128, usize, i8 to i128, isize, f32, f64, Duration, the NonZero integers) whose value writes a number literal outside its strings, unless a comment line directly above it, or the statement itself, cites an address (https:// or http://) where its value is stated. The constant is one row however many lines it spans, reported as its name.
• An inline shape, wherever it stands, in a Rust line or a script Stado embeds in a string: a clock (Duration::from_secs(N) and its millis, micros, nanos and float forms), a shell pause (sleep N), a shell deadline (--max-time N, --connect-timeout N, timeout N), an SSH deadline (ConnectTimeout=N, ServerAliveInterval=N, ServerAliveCountMax=N) and a display window (tail -n N, head -n N), each with N not zero, reported as the matched text.

These words are declared once, in stado-rs/src/cli/quality/numbers/shapes.json (schema version 1), each shape with why it is one; the reading knows no product.

numeric-provenance.json

A number whose source cannot be cited beside it (a schema version, an operator's stated value, a measurement) is given one in the revision's numeric-provenance.json at the checkout's root:

{
  "schema_version": 1,
  "numbers": [
    { "path": "src/limits.rs", "match": "DISK_FULL_PERCENT", "source": "the operator's stated disk-full threshold" }
  ]
}

path is the file as the revision holds it, match is the row's match (a constant's name, or a shape's matched text) and source says where the value comes from. Such a number is not a row. An entry whose number the revision no longer holds at that path is a row of its own, so the file never keeps a source for a number that is gone.

Output

Plain output is one line per row, the form a probe that reads lines takes:

<path>:<line>: <shape> <match>: <why>
numeric-provenance.json: <path> <match>: declared with a source, but <commit> holds no such number there

With --json, stdout carries one document: schema (stado.quality.numbers.v1), root, revision (the full commit), read (extensions, outside_directories, why_outside and the number of files read), instances (each with path, line, shape, match, text and why) and stale (each with path, match and source). A line on stderr counts both.

A commit that adds one is refused

Every stado quality check, the check of one revision (--revision) and the pre-push check (--pre-push), reads each checked commit and its first parent the same way before any gate or manifest is read, and refuses the commit when its reading has a row the parent's has not: a number no source states that the commit writes, moves into another file, or uncovers by dropping its numeric-provenance.json entry. Only the files the commit changes are read on both sides, every file when it changes numeric-provenance.json; a commit with no parent counts every row it holds. Rows the parent already had are not the commit's and do not refuse it.

stado quality check: <commit> adds <n> number(s) no source states:
  <path>:<line>: <shape> <match>: <why>
Give each its source (an address its doc comment cites, or an entry of numeric-provenance.json naming its path, match and source), or wait on the event it stands in for, then commit again; `stado quality numbers --revision <commit>` lists them.

When the shapes or the committed files cannot be read the check refuses too, saying the commit is not known to state each number's source, with git's own words.

Refusals

Each refusal ends the reading before any row is printed, so it says nothing about the revision's numbers:

Refusal	Exit	Why	What to do
reading <root> as a Git checkout	2	the directory holds no Git repository	pass --root naming a checkout, or run inside one
resolving <revision> in <root>	2	the checkout holds no commit of that name	name a commit it holds; fetch it first when it is only on the origin
reading the files of <commit> in <root>	69	git did not list or hand over a committed file (a missing object); the code marks it retryable, since a repaired repository answers	run git -C <root> fsck, repair what it names, read again
reading numeric-provenance.json of <commit>	1	the file is not the document above: not JSON, another schema_version, an unknown field, or an entry without its path, match or source	write it as documented, commit it, read again
reading the number shapes this Stado declares	1	this build's shapes.json does not parse or a pattern does not compile	install a Stado whose declaration reads

stado errors show stado.quality.numbers lists the same causes with the test that provokes each. The real journey tests/quality/numbers.rs (kompilator test --manifest-path stado-rs/Cargo.toml --test quality-numbers) reads a repository of its own with each kind of row, a cited constant, a declared one, a constant under tests/ and an uncommitted one, provokes every refusal, and has stado quality check --revision refuse a commit that adds a constant and pass that step for the next commit, which gives it a source.

In Stado Desktop

Releases → Available operations… carries List the numbers a revision decides with that no source states. It takes a repository on the selected Stado API host and an optional revision and runs the same command with --json; it changes nothing.