Skip to content

docs: regenerate drifted stdlib source blocks from sys/hoon.hoon - #281

Open
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr13-stdlib-regen
Open

docs: regenerate drifted stdlib source blocks from sys/hoon.hoon#281
sigilante wants to merge 1 commit into
urbit:masterfrom
sigilante:docs/pr13-stdlib-regen

Conversation

@sigilante

Copy link
Copy Markdown
Contributor

Sixteenth and final PR from the audit against urbit/urbit@08026c84b2. 35 #### Source blocks in content/hoon/stdlib/ no longer matched the arms they quote.

Companion PRs: #266, #267, #269#280.

Method

Regenerated mechanically, not by hand. Two earlier PRs in this series showed that hand-reconstructing a source tail produces plausible, wrong Hoon — +rig in #272 and +hew in the #272 follow-up, both caught only by diffing against source.

Every ## +arm / ### +arm:door heading was paired with its #### Source block and diffed against the arm of the same qualified name in hoon.hoon, with comments stripped and indentation normalised. Where they differed, the doc block was replaced with the source verbatim.

Final state by the same script: 681 blocks match, 26 deliberate excerpts, 0 drift.

Three classes of false positive had to be excluded first

Any one of these would have done real damage on a naive run:

  1. Door headers. +by, +in, +ja, +to, +rs and friends quote only the first few lines of a core — through |@ or |_ — because the full arm is hundreds of lines. Regenerating +by would have inlined 262 lines into the reference. Detected by testing whether the doc block is a prefix of the source.

  2. Blocks that omit the leading ++ name line. Some entries start at ~/ %po. I compare against both the full arm and the arm minus its first line, and the replacement preserves whichever convention the block already used. Without this, +in and +po looked like drift.

  3. Arms already corrected in other open PRs of this series were excluded by name, so this branch doesn't conflict with them.

One block fixed by hand

+by's header is genuine drift, not an excerpt — it still shows =* node ?>(?=(^ a) n.a), an alias that appears nowhere in hoon.hoon and is used by none of the door's arms. I removed that single line rather than replacing the block, which would have inlined the whole core.

Representative corrections

Arm Change
+bool 0/1%.y/%.n loobean literals, plus an explicit ^- type
+ape:ag (cold 0 ...)(cold `@`0 ...)
+mot:ag gained dub, the UIP-135 leading-zero date segment
+welp +zing +corl +curr +cury +bend +comp +here +knee +int/+uni/+uno dropped =+ … |@ ++ $ … -- wrappers for direct wet gates

Verified after the run

  • Re-ran the differ: 0 drift remaining.
  • Code-fence balance checked in every stdlib file.
  • Cross-file anchors checked: 0 broken.
  • Six #### Source blocks are followed by prose rather than a fence; checked against upstream/master and confirmed pre-existing, not damage from this change.
  • Test-merged against the fifteen open companion PRs — all clean, including confirmation that docs: correct Hoon stdlib signatures that mislead readers into broken code #267's +trim fix and this PR's +ape:ag fix coexist in the merged tree.

🤖 Generated with Claude Code

Against urbit/docs.urbit.org@08026c84b2. 35 `#### Source` blocks in content/hoon/stdlib/ no
longer matched the arms they quote. Regenerated mechanically rather than by
hand, because two earlier PRs in this series showed that hand-reconstructing a
source tail produces plausible, wrong Hoon (+rig and +hew, both caught by
diffing).

METHOD

  Every `## +arm` / `### +arm:door` heading was paired with its `#### Source`
  block and diffed against the arm of the same qualified name extracted from
  hoon.hoon, with comments stripped and leading indentation normalised. Where
  they differed, the doc block was replaced with the source verbatim.

  Final state, by the same script: 681 blocks match, 26 are deliberate
  excerpts, 0 drift.

THREE CLASSES OF FALSE POSITIVE HAD TO BE EXCLUDED FIRST, or the run would have
done real damage:

  1. Door headers. `+by`, `+in`, `+ja`, `+to`, `+rs` and friends quote only the
     first few lines of a core -- through `|@` or `|_` -- because the full arm
     is hundreds of lines. A naive regeneration would have inlined all 262
     lines of `+by` into the reference. Detected by testing whether the doc
     block is a PREFIX of the source.

  2. Blocks that omit the leading `++  name` line. Some entries start at
     `~/  %po`. Compared against both the full arm and the arm minus its first
     line, and the replacement preserves whichever convention the block already
     used. Without this, `+in` and `+po` looked like drift.

  3. Arms already corrected in other open PRs of this series (trim, bif, apt,
     del, dif, shas, mink, mock, mack, inde, iny, peg, mure, mute, rend, molt,
     rt, stab, mes, hif, clz, ctz, ham, rig, hew, slub) were excluded by name,
     so this branch does not conflict with them.

ONE BLOCK WAS FIXED BY HAND: `+by`'s header is genuine drift, not an excerpt --
it still shows `=*  node  ?>(?=(^ a) n.a)`, an alias that appears NOWHERE in
hoon.hoon and is used by none of the door's arms. Removed that single line
rather than replacing the block, which would have inlined the whole core.

Representative corrections, all now verbatim:
  +bool   `0`/`1` -> `%.y`/`%.n` loobean literals, and an explicit ^- type
  +ape:ag `(cold 0 ...)` -> `(cold `@`0 ...)`
  +mot:ag gained `dub`, the UIP-135 leading-zero date segment
  +welp +zing +corl +curr +cury +bend +comp +here +knee +int/+uni/+uno
          dropped their `=+ ... |@ ++ $ ... --` wrappers for direct wet gates

VERIFIED AFTER THE RUN
  - re-ran the differ: 0 drift remaining
  - code-fence balance checked in every stdlib file
  - cross-file anchors checked: 0 broken
  - the 6 `#### Source` blocks followed by prose rather than a fence were
    checked against upstream/master and are PRE-EXISTING, not damage from this
    change

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant