Scalar objectives
A scalar objective tracks a number per sector, such as lines of legacy code or any per
thousand lines. The number may not get worse, and the objective is met at target.
objectives: legacy-lines: measure: { lines: true } direction: down target: 0 any-density: measure: ratio: of: { report: { command: node ./campaign/any-sites.mjs, format: regex, pattern: "..." } } per: { lines: true } scale: 1000 direction: down tolerance: 0.5 probes: fires: [{ path: src/a.ts, source: "let x: any;", report: [{ line: 1 }] }]Fields
Section titled “Fields”A scalar has measure instead of match or sector, and no holdout.
| Field | Meaning |
|---|---|
measure |
Where the number comes from. See below. |
direction |
Which way is better: down or up. Required. |
tolerance |
How far from the recorded value still counts as unchanged, for a number that wobbles. Default 0. |
target |
The value at which it is met. Required if a phase names the objective. Without one, it only ratchets. |
Measures
Section titled “Measures”Each measure is counted per file and summed over the sector.
measure |
Per file |
|---|---|
lines: true |
Non-blank lines, comments included. Reformatting is not progress. |
files: true |
1, so the value is the sector’s file count. |
report: <term> |
The diagnostics a report term puts on it. |
fn: module#export |
The number a CampaignMeasure function returns. |
ratio: { of, per, scale } |
Two of the above. The sector’s value is scale × Σof / Σper, or 0 when Σper is 0. |
command: <shell> |
Not summed: runs once from the repository root; its output is read whole, or through a pattern with a value group. Only for a campaign with no perimeter. |
A function or command returning anything but a finite number ≥ 0 fails check.
How it is held
Section titled “How it is held”The ledger records each sector’s value. If the value
moves past tolerance, check fails:
- Worse: accept it with
objectives concede --sector <sector> --reason …(--holdoutsis refused). - Better: run
objectives clearto record it, so the gain can’t be given back.
A phase may name only a scalar with a target; the sector leaves the phase when the value
reaches it. A scalar no phase names only ratchets. The editor rule never reports scalars.
Probes
Section titled “Probes”A report or fn source requires probes.fires. Each fires file must measure above zero
(or exactly its value); each ignores file must measure zero. lines and files need no
probes; command takes none.