3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-18 06:05:43 +01:00

Record the comprehension check: scoring run at fa8600f, overall 5.88; floor item 178 filed

This commit is contained in:
2026-11-14 10:51:11 +01:00
committed by Lillem4n
parent 1fd07949dd
commit b088d4f075
2 changed files with 58 additions and 1 deletions
+44
View File
@@ -1749,3 +1749,47 @@ Ruling: same
|---|---|---|---|---|---|
| Mid A | same | same | same | same | same |
| Inherited architect | same | same | same | same | same |
## 2026-11-14T09:49:34Z, PR #162 at fa8600f
| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall |
|---|---|---|---|---|---|
| Junior A | 7 | 5 | 6 | 5 | 5.5 |
| Mid A | 7 | 5.5 | 6 | 5.5 | 6 |
| Maintainability senior | 7 | 5.5 | 6 | 5.5 | 6 |
| Inherited architect | 6 | 5.5 | 6 | 5.5 | 6 |
| Mean | 6.75 | 5.38 | 6.00 | 5.38 | 5.88 |
Junior A, hardest first:
- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: a forward and a backward sweep over three verdicts and four standings, whose case derivation lives only in the decision log
- Self-sufficiency: `src/markdown/emit/line-escaping.ts:99` `readBack`: up to three escape passes running the reader inside the writer, with no statement of why three suffice
- Locality: `src/markdown/emit/inline-line.ts:120` `settledLine`: a generic fallback loop whose state changes out of sight through the `LineFallbacks.carried` Set
- Locality: `src/markdown/inline-content.ts:255` `directiveMarkPieces` / `closeBracket`: a mutable `Scan` shared across eight or more piece kinds
- Shape: `src/markdown/emit/block-text.ts:109` `prefixedLine`: open, started and innermostQuote bookkeeping for lazy container prefixes
Mid A, hardest first:
- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding`: the only case analysis kept outside the code, in a locally coined vocabulary
- Locality: `src/markdown/emit/inline-line.ts:120` `settledLine`: fallbacks mutate the `carried` Set and `openingLinkAsDirective` in place, and the 32-pass cap's termination is only named
- Locality: `src/markdown/inline-content.ts:424` `closeBracket` / `applyClosing`: one mutable `Scan` shared by nine piece kinds in a 695-line file
- Locality: `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: a reference-keyed memo with take, ask and depth rebasing, and headroom kept across three types
- Shape: `src/markdown/portable/adf-to-portable-markdown.ts:126` `portableSequence`: whether a block is replaced turns on a reference comparison
- Locality: `src/markdown/parse/markdown-to-adf.ts:126` `directiveNode`: the parser refuses a directive through a hand-kept map that must agree with the emitter
Maintainability senior, hardest first:
- Self-sufficiency, Overall: `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: two coined vocabularies and two sweeps, with the correctness argument in the decision log
- Locality: `src/markdown/emit/line-escaping.ts:99` `readBack`: a fixpoint over escapes steered by a full re-parse, with per-character `Uint8Array` codes
- Shape: `src/markdown/emit/inline-line.ts:120` `settledLine`: a three-type-parameter loop for two consumers, the `carried` Set mutated by helpers away from it
- Navigation, Locality: `src/markdown/inline-content.ts:592` `pairingMarks`: scanner state written from several functions, in a file sharing its name with the 17-line `src/markdown/parse/inline-content.ts`
- Locality: `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: drop-on-read entries with rebased headroom, whose staleness rules need proving before touching `walkBlocks`
- Self-sufficiency: `src/markdown/emit/adf-to-markdown.ts:57` `writeMarkdown`: the writer's emit, re-parse, compare and fall back design is stated nowhere at its entry
Inherited architect, would restructure first:
- Navigation, Overall: `src/markdown/parse/inline-content.ts:10` `readInlineContent`: a 17-line shim sharing its name with the real reader at the markdown root, which no note explains, a wrong turn on the 3am path
- Locality: `src/markdown/emit/line-escaping.ts:99` `readBack`: the writer's correctness depends on reading back through the reader
- Shape: `src/adf/document.ts:38` `readAdfDocument`: the file holds the reader, the writer prechecks, the schema refusals and text merging
- Shape: `src/markdown/emit/adf-to-markdown.ts:57` `writeMarkdown`: the shared writer lives in a file whose name means the lossless one
- Self-sufficiency: `src/markdown/emit/unspellable-runs.ts:49` `pairVerdicts`: hands its reason to a decision title, as the 32-pass cap at `src/markdown/emit/inline-line.ts:61` does
+14 -1
View File
@@ -6,7 +6,7 @@
`Bar = 0.1`
`Next ID = 178`
`Next ID = 179`
## Items
@@ -34,6 +34,7 @@
| 56 | 0.5.0 | | | **Give each piece of `blocks.ts`'s block-walk state and `inline-content.ts`'s `Scan` one owner that returns what it changes.** | 3 | 1 | 2 | 4 | 5 | code health by 5 | 13.1 |
| 118 | 0.5.0 | | | **Spell a portable link's title through `oneLine`.** | 1 | 1 | 1 | 1 | 1 | code health by 1 | 10.5 |
| 82 | 0.5.0 | | | **Give the directive tests and fixtures random UUID v7 ids in place of `a-1`, `a`, `x` and `h`.** | 2 | 1 | 1 | 2 | 3 | code health by 1 | 6.5 |
| 178 | 0.5.0 | | owner | **Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.** | 3 | 1 | 2 | 4 | 7 | code health by 8 | 6.2 |
| 58 | 0.5.0 | | | **Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.** | 4 | 2 | 2 | 6 | 6 | code health by 3 | 4.4 |
| 9 | 0.5.0 | | | **Ship an online sandbox: a web page with two textboxes converting between ADF and markdown on the library's browser build.** | 3 | 2 | 1 | 4 | 6 | 3 by 6 | 2.1 |
| 34 | 0.5.0 | | | **Read emphasis flanking by the whole character beside an astral symbol.** | 2 | 1 | 2 | 3 | 3 | 4 by 1 | 1.5 |
@@ -250,6 +251,18 @@ Found by the principles audit of item 99, 2026-10-14.
Technical principle: tests use random UUID v7 ids; `portable-markdown-to-adf.test.ts` already does.
Found by the technical-principles audit of item 78, 2026-10-05.
### 178. Reach the comprehension floor: move the reasoning behind the emitter's fallback and escape loops into the code that runs them, so each reads on its own.
The scoring run at fa8600f (PR #162) averaged 5.88 overall, under the 7.0 floor; Locality and Self-sufficiency scored lowest, at 5.38 each. Make these places, the ones every seat named, easier to read:
- `src/markdown/emit/unspellable-runs.ts:223` `pairStanding` / `pairVerdicts`: the case analysis behind the two sweeps lives only in `docs/decisions.md`. State it in the types or the code, with one vocabulary.
- `src/markdown/emit/inline-line.ts:120` `settledLine`: fallbacks change the `carried` Set and `openingLinkAsDirective` out of sight. Make each pass's state an explicit value, with the 32-pass bound visible where it holds.
- `src/markdown/emit/line-escaping.ts:99` `readBack`: say in the code why three escape passes suffice.
- `src/markdown/inline-content.ts:255` and `:424` (`directiveMarkPieces`, `closeBracket`, `applyClosing`): one mutable `Scan` shared by nine piece kinds in a 695-line file. Split it by piece kind.
- `src/markdown/emit/adf-to-markdown.ts:138` `spellingMemo`: keep its take, ask and depth rebasing in one type.
Keep every output byte-identical: the round-trip properties and the CommonMark suite must pass unchanged.
### 58. Port `ci.sh`, `publish.sh`, `docker-runner.sh` and `mutation-tests/run.sh` to standalone Python scripts.
Technical principle "Prefer a standalone Python script over a shell script": `AGENTS.md` §3 teaches