Oko
Oko/Docs

Command reference

oko defects sweep

Runs a defect's class probe across every product, so its repair covers every instance of its class and not the one that was seen: term (b) of the class coverage `oko defects repaired` requires.

Invocation#

Command
oko defects sweep <id> --by SESSION [--json]

Inputs and options#

  • The defect declares its class probe first: `oko defects completion <id> --class --probe-program PROGRAM --probe-arg … --probe-scope … --probe-format lines|json`, the command that lists every instance of the class at a revision. --by is the session running the sweep.
  • The repositories are the ones Stado's product catalog names for every product (`stado product catalog --json`, each surface's repository by its name after the organization). Oko works without Stado: when the catalog does not answer, the sweep reads every checkout under the workspace instead and says why on stderr: `oko defects sweep: Stado's product catalog did not answer (<cause>); reading every checkout under the workspace instead`.

Output and state effect#

  • Runs the probe at the published main (`origin/main`) of each repository, in an export of that commit as every completion probe runs, and keeps on the defect `sweep {probe, by, at, scope, runs [{product, repository, reading}]}`, each reading `{result: read, revision, instances}`, `{result: refused, revision, cause}` or `{result: no-checkout, checkout}`; a later sweep replaces it. Prints `swept <id> at <time>: <n> repositories from <scope>, <n> instance(s) found (<n> recorded as defects of its class, <n> not), shown absent in <n>, not read in <n>`, a `found` line per instance with the defect that records it or `recorded by no defect`, a `not read` line per repository with its cause, and each `missing (b) sweep: …` step left; --json prints the coverage `oko defects show` reads ({id, product, title, standing, shape, siblings, swept, prevention, active, missing}).
  • An instance is recorded as a defect when a defect of the class (one not withdrawn, of the same shape) names it in its title, surface, evidence or a note; this is read whenever the coverage is read, so a defect recorded after the sweep counts without running it again. A repository read with no instance shows the shape absent there. A repository with no checkout on this machine is named but is no step, since no session here can read it; one whose probe refused is a step.
  • The native API runs the same as the defects `sweep` action ({id, by}) and answers the coverage; Oko Desktop's Shapes section runs it for a class.

Refusals and safe exits#

  • `defect <id> declares no class probe to sweep with; declare the probe that lists every instance of its class: oko defects completion <id> --class --probe-program <program> [--probe-arg <argument>]… --probe-scope <the products it reads> --probe-format lines|json [--probe-pointer <pointer>]`, before anything runs.
  • `defect <id> changed its class probe while the sweep ran; run oko defects sweep again against the current declaration`, and nothing is written.
  • `oko defects sweep requires <id>` and `--by <text>` (exit 2); `a sweep needs the session that runs the sweep` for a blank --by; an unknown or ambiguous id refuses as `oko defects show` does; a workspace that cannot be listed names it.

CLI reference#