docs: regenerate drifted stdlib source blocks from sys/hoon.hoon - #281
Open
sigilante wants to merge 1 commit into
Open
docs: regenerate drifted stdlib source blocks from sys/hoon.hoon#281sigilante wants to merge 1 commit into
sigilante wants to merge 1 commit into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sixteenth and final PR from the audit against
urbit/urbit@08026c84b2. 35#### Sourceblocks incontent/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 —
+rigin #272 and+hewin the #272 follow-up, both caught only by diffing against source.Every
## +arm/### +arm:doorheading was paired with its#### Sourceblock and diffed against the arm of the same qualified name inhoon.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:
Door headers.
+by,+in,+ja,+to,+rsand friends quote only the first few lines of a core — through|@or|_— because the full arm is hundreds of lines. Regenerating+bywould have inlined 262 lines into the reference. Detected by testing whether the doc block is a prefix of the source.Blocks that omit the leading
++ nameline. 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,+inand+polooked like drift.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 inhoon.hoonand 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
+bool0/1→%.y/%.nloobean literals, plus an explicit^- type+ape:ag(cold 0 ...)→(cold `@`0 ...)+mot:agdub, the UIP-135 leading-zero date segment+welp+zing+corl+curr+cury+bend+comp+here+knee+int/+uni/+uno=+ … |@ ++ $ … --wrappers for direct wet gatesVerified after the run
#### Sourceblocks are followed by prose rather than a fence; checked againstupstream/masterand confirmed pre-existing, not damage from this change.+trimfix and this PR's+ape:agfix coexist in the merged tree.🤖 Generated with Claude Code