oxidecomputer / oxidecomputer/prettier-plugin-asciidoc

A heading read directly under a description-list term has no printable spelling

Open
#186 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

mechanism:block-reading obligation:idempotence tier-2
Dominant language
TypeScript
Stars
0
Forks
1
PR merge metrics
No merged PRs in 30d

Description

A heading node that stands immediately after a description list whose last term carries no text of its own cannot be written back: whatever the printer emits, the oracle attaches it to that term as the item's description.

The position genuinely has no spelling, measured with no branch code at all - at main 1dd7e880, term:: / blank / = x is read as a dlist whose description is the TEXT = x by the oracle AND by our own reader (<dl><dt>term</dt><dd><p>= x</p></dd></dl>), and the same for == x and for the un-blanked term:: / = x. So there is no byte sequence that says "textless term, then a heading", and the printer cannot invent a separator (this repo does not invent bytes it was not given).

Reached now because the setext reading produces that structure where nothing did before. A fenced-code opener over a setext underline is read by the oracle as a dlist term plus one or two setext titles, and we now read the same; formatting it emits the term, a blank, and the headings in their ATX spelling, whose re-read makes the first heading the term's description and drops it.

The six sweep documents and what each is read as, so the level is not guessed from one of them:

term::  ```x  ----  foo  ----     ->  dlist + h1 + h1     (level 1)
term::  ```x  ---                 ->  dlist + h1          (level 1)
term::  ```x  ++++  foo  ++++     ->  dlist + h5 + h5     (level 4)
term::  ```x  +++                 ->  dlist + h5          (level 4)
term::  ```x  ====  inner  ====   ->  dlist + h0 + h0     (level 0)
term::  ```x  ===                 ->  dlist + h0          (level 0)

Not a new RENDER loss at these coordinates: all six are render-divergent at main too, differently - main reads the fence as a [source,x] listing block and emits a [source,x] block the oracle does not read as the source either. What is new is that the formatted output no longer re-reads as what we read, which is what the reparse gate measures.

Witnesses: bun run reparse-ledger, family heading-under-a-term, six rows, all p1, at line/pair/delimiter-fencedCode-near-1/delimiter-{listing,example,pass}{,-near-0}/adjacent/dlist-desc-line. The first of them:

term::                 term::
```x            ->
----                   == ```x
foo
----                   == foo

A fix has to decide what a heading under a textless term should become - the reader could refuse the structure, or the dlist print could end the list in a way the oracle honours - and both are outside the reading vocabulary that produced it.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with bun run reparse-ledger and the heading-under-a-term family, including its six fenced-code sweep rows. Trace the reader and dlist printer behavior described in issue 186, then decide whether the structure should be rejected or the list terminated differently; done means formatted output re-reads as the same structure without losing the headings.

Written by the indexing model from the issue text.

Assessment

Tech stack
bun, typescript
Domain
tooling
Issue type
Bug
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.