[takashi-matsuyama]

The fourth of the changes that move basou board (experimental) to a new shape of its declaration and its records. Like the first three, it lands on the integration branch board/shape-v3, not on main; all of them go to main and out in one release.

What changes

• A measure that adds up others and integers, and takes some away (total, from board_version: 3).

  measures:
    - { id: left, kind: total, plus: [100], minus: [hand_count], unit: slots }
    - { id: pages_all, kind: total, plus: [site_a.pages, site_b.pages], unit: pages }

  • plus lists at least one term, minus may be left out (an empty one is refused, as an empty exclude is). A term is an integer written in the declaration, from -9007199254740991 to 9007199254740991 (one outside is told that range), or the id of a measure whose value is one.
  • The value is computed exactly (as BigInt) and may be below 0. When a measure it takes was not measured, the total is null, and its reason names each such measure once, in the order written ('gone', 'web.none' are not measured); one out of the range a number holds exactly is null too, said after what it lacks.
  • A total takes no total, itself included ('t' is a total, which no total takes), and no measure whose value is not a number (regex_capture, file_name, file_paths). So totals are never chained, and are measured after every other measure; the measurement keeps the order declared. A ratio may take a total.

• A measure drawn in more than one lane (lane as a list, from board_version: 3). lane is one lane id, as before, or a non-empty list of them, each a lane of the board and none twice. A measure's lane is read as a list whatever the board's version, so a record (version 3) holds it as a list in its measurement and in the declaration it keeps; a measure with no lane has none. The board page draws the measure in each of its lanes' sections, and basou board measure lists them (docs.md 2 files [site, core]).

• A measure's id and an observation's key may be words joined by . (from board_version: 3), each word written as an id is (site.pages); a ratio's and a total's references take the same form. : and / are still refused, since the guide names working files after a key, and lane and ratio ids are as before. not_found now names a measure with formatPath, so measures["site.pages"] is not read as a measure pages inside site; an id without . keeps its place (measures.gone).

• Records of version 1 and 2 are read as before. Their one lane id is read by the board page as the lane of that id, and by the difference from the previous record as a list of that one, so the first record of version 3 does not show every measure's lane as moved. A reordered list of lanes is a change.

• A board of version 1 or 2 that uses any of these is told that version 3 reads it (measures[2].kind: 'total' is read from board_version 3 on; this file is board_version 2, and likewise for a list of lanes, an id or a reference with ., and an observation key with .). What it names is still held against the rest of the board, as version 3 would hold it.

• basou board guide says what a total's value is, that it may be below 0 and when it is null; the steps before a board is declared and basou board init's comment on measures say that a measure may be drawn in a list of lanes, and name total. The CHANGELOG says all of it under Unreleased.

Tests

• Declaration: a total of integers and measures, with and without minus; no plus, an empty plus or minus, a term that is not an integer or an id, an integer a number does not hold exactly, and a key a total does not take; a term naming no measure (one with . included), a total (itself included) or a measure that is not a number; a ratio of a total. A lane as an id or a list, read as a list in every version; an empty list, a lane listed twice or not on the board (and one not on the board listed twice), what is not a lane id. Ids and keys with . accepted, a duplicate one refused, and . broken at an end, twice in a row, before a word that does not start with a lowercase letter, after the second word, with : or /; . kept out of lane and ratio ids. Which version a board of version 1 or 2 is told reads each, and the cross-check lines beside it.
• Measure: a total over measures of two repos and integers, below 0 and 0; the order of the measurement; null naming each measure it lacks once, in order, before its range; exact up to the integers a number holds exactly (max + 2 - 3) and null past them, at both ends; not_found of an id with .; lanes kept as a list, of one or more, and none when there are none; a version 1 board's lane as a list in the measurement and the snapshot; a ratio over a total and an id with ..
• Diff: one lane id of an older record is no change against a list of that one, and a list with another lane, a lane added and a lane removed are.
• Board page: a measure of two lanes drawn in each, a version 3 record with a total and an id with ., and an older record's one lane id drawn in that lane only, not in a lane whose id it holds (co and core).
• board measure prints a total below 0, each lane of a measure and an id with ., says what a total lacks, and --json gives the lanes as a list; the guide's line and init's comment.
• Mutation checks in a copy: each of 43 mutations of the new code fails a test (the id grammar, the lanes' schema and cross-check, the total's terms and cross-check, the version notices, the order of measuring, the exact sum and its range, the reasons, the place in not_found, the diff's and the page's reading of an older lane, the text output). Six of them came from a review of the first commit and are held by the second.
• pnpm -r build, pnpm typecheck, pnpm -r test:coverage, pnpm test:scripts, pnpm lint, pnpm lint:lang and pnpm lint:paths pass locally.