Skip to content

Commit 4b0256e

Browse files
tannevaledclaude
andauthored
README: a cross-reference to a section that was never written, and a gate for the class (#943)
Under Kernel#fork the README said: fork { ... } *does* exist and runs the block in the same process -- see the table under *Known divergences*, because code that forks to isolate or to drop privileges gets neither here. ⛔ There is no "Known divergences" table. `git grep -i divergenc` over every markdown file in the repository returns that citation and nothing else. The sentence names the stake exactly right -- a program that forks to drop privileges drops none here -- and then sends the reader to the one place that would have told them what to do about it, which does not exist. ## The fix says the thing instead of promising it The divergence is now inline, with the measurement: `x = 1; fork { x = 99 }` leaves the parent's x at 99 where MRI 4.0.7 leaves it at 1 (measured today through cmd/oracle), and the Integer returned is indistinguishable from a real pid. The reason it exists -- Puppet::Util::Execution.execute is built on it -- is stated, and the open questions point at #774 and the parity plan #941. ## The gate, measured before it was written A guard on prose is worthless if it fires on prose that is fine, so the population came first. TestReadmeCrossReferencesResolve finds every italic phrase introduced by "see" or "under" and requires a heading or a bold run-in item to name it: *Set* *Supported today* (x3) *Running Puppet* *Runtime conformance* *Status* -- and, until this change, *Known divergences* 8 before, 7 after, and NO false positives: emphasis such as `fork { ... } *does* exist` is not matched, because the italic has to follow "see" or "under" immediately. ⛔ Proved by mutation, not by passing: putting the dangling reference back makes it fail by assertion, naming *Known divergences*. Two things the writing of it taught, both recorded in the test: - I counted the population BY HAND first and got 4. The regexp finds 8 -- my grep pattern only matched capitalised titles in one phrasing and silently missed three repeats and *Status*. A population counted by eye is what this test replaces. - The first draft logged "all resolve" unconditionally, and printed it directly under a failure it had just reported. A summary that contradicts its own output is how a reader learns to stop reading summaries; it now prints the dangling tally. ⛔ It also flattens the README before matching, because "see *Set* under \n*Supported today*" wraps across two source lines and a line-based check sees neither half. Refs #774, #941 Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
1 parent 131942a commit 4b0256e

2 files changed

Lines changed: 114 additions & 3 deletions

File tree

‎README.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -461,9 +461,15 @@ JRuby**):
461461
`pid`/`ppid`/`uid`/`gid`/`euid`/`egid`. There is **no `Process.fork`**
462462
(`Process.respond_to?(:fork)` is `false`) — Go's runtime cannot be forked
463463
safely; `spawn` is the supported way to start a child. **`Kernel#fork` is a
464-
different story**: `fork { ... }` *does* exist and runs the block in the same
465-
process — see the table under *Known divergences*, because code that forks to
466-
isolate or to drop privileges gets neither here.
464+
different story**: `fork { ... }` *does* exist and runs the block **in the same
465+
process**, so **code that forks to isolate or to drop privileges gets neither
466+
here** — measured 2026-11-15 against MRI 4.0.7, `x = 1; fork { x = 99 }` leaves
467+
the parent's `x` at **99** where MRI leaves it at **1**, and the `Integer` it
468+
returns is indistinguishable from a real pid. It exists because
469+
`Puppet::Util::Execution.execute` is built on it
470+
([#774](https://github.com/go-embedded-ruby/ruby/issues/774) weighs the three
471+
ways out; the parity plan is
472+
[#941](https://github.com/go-embedded-ruby/ruby/issues/941)).
467473
- **Pattern matching (`case`/`in`):** value, variable-binding, class/constant,
468474
array (incl. splat and nested), hash (`deconstruct_keys`, `**rest`/`**nil`),
469475
find (`[*pre, x, *post]`), pin (`^x`) and alternative (`a | b`) patterns;

‎readme_xref_test.go‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
// Copyright (c) the go-embedded-ruby/ruby authors
2+
//
3+
// SPDX-License-Identifier: BSD-3-Clause
4+
5+
package ruby_test
6+
7+
import (
8+
"regexp"
9+
"strings"
10+
"testing"
11+
)
12+
13+
// TestReadmeCrossReferencesResolve.
14+
//
15+
// The README sent readers to a section that was never written. Under
16+
// Kernel#fork it said:
17+
//
18+
// fork { ... } *does* exist and runs the block in the same process — see the
19+
// table under *Known divergences*, because code that forks to isolate or to
20+
// drop privileges gets neither here.
21+
//
22+
// ⛔ There is no "Known divergences" table. `git grep -i divergenc` over every
23+
// markdown file in the repository returned that citation and nothing else. The
24+
// sentence names the stake exactly right — a program that forks to drop
25+
// privileges drops none here — and then points at somewhere that does not
26+
// exist, which is the one place a reader would have gone to find out.
27+
//
28+
// MEASURED, because a guard aimed at prose is worthless if it fires on prose
29+
// that is fine (cf. go-desktop/catalog#26, where the obvious version of a number
30+
// guard gave four must-never-fire hits against two real findings). The
31+
// population was 8 references before this change and is 7 after, and every one
32+
// is a genuine pointer at another part of the document — no emphasis caught by
33+
// accident:
34+
//
35+
// *Set* *Supported today* (x3) *Running Puppet* *Runtime conformance*
36+
// *Status* — and, until this change, *Known divergences*
37+
//
38+
// Seven resolved; *Known divergences* was the one that did not, and the fix
39+
// alongside this test says the thing inline instead of pointing anywhere.
40+
//
41+
// ⛔ I first counted that population BY HAND with a grep and got 4. The regexp
42+
// finds 8: the hand pattern only matched capitalised titles in one phrasing and
43+
// silently missed three repeats of *Supported today* and *Status*. A population
44+
// counted by eye is the thing this test exists to replace, so what it prints is
45+
// the count — and it prints the dangling tally too, rather than a verdict that
46+
// could disagree with the failures above it.
47+
//
48+
// ⛔ The README is flattened first: "see *Set* under\n*Supported today*" wraps
49+
// across two source lines, so a line-based check sees neither half.
50+
func TestReadmeCrossReferencesResolve(t *testing.T) {
51+
readme := readFile(t, "README.md")
52+
flat := strings.Join(strings.Fields(readme), " ")
53+
54+
// An italic phrase introduced by "see" or "under" is a reference to another
55+
// part of this document. Emphasis is written the same way, which is why the
56+
// pattern requires the italic to follow one of those two words IMMEDIATELY:
57+
// `fork { ... } *does* exist` is emphasis and must not be matched.
58+
ref := regexp.MustCompile(`(?i)\b(?:see|under)\s+\*([^*]{2,60})\*`)
59+
found := ref.FindAllStringSubmatch(flat, -1)
60+
61+
// ⛔ A reworded README that matches nothing would make this test pass by
62+
// having stopped looking. The population is the first thing asserted.
63+
if len(found) == 0 {
64+
t.Fatalf("README.md: no %q-style cross-reference matched at all; "+
65+
"the wording changed shape, so teach the regexp rather than "+
66+
"deleting the check", "see *Section*")
67+
}
68+
69+
// A reference resolves to a heading that names it, or to a bold run-in item
70+
// such as "**Set:**" — both are how this README labels a place.
71+
lines := strings.Split(readme, "\n")
72+
resolves := func(title string) bool {
73+
lower := strings.ToLower(title)
74+
for _, ln := range lines {
75+
if strings.HasPrefix(strings.TrimSpace(ln), "#") &&
76+
strings.Contains(strings.ToLower(ln), lower) {
77+
return true
78+
}
79+
}
80+
return strings.Contains(strings.ToLower(flat), "**"+lower)
81+
}
82+
83+
// Reporting the denominator, not just the verdict: a reader of a green run
84+
// should be able to see WHICH references were checked, so a population that
85+
// quietly shrinks is visible.
86+
for _, m := range found {
87+
t.Logf(" reference: *%s*", strings.TrimSpace(m[1]))
88+
}
89+
dangling := 0
90+
for _, m := range found {
91+
title := strings.TrimSpace(m[1])
92+
if !resolves(title) {
93+
dangling++
94+
t.Errorf("README.md refers to *%s*, and no heading or bold item in "+
95+
"README.md names it.\nEither write that section or say the thing "+
96+
"inline — a reference is a promise, and this one carried the "+
97+
"consequence a reader needed.", title)
98+
}
99+
}
100+
// ⛔ The verdict in this line has to agree with the run. A first draft said
101+
// "all resolve" unconditionally and printed it directly under a failure it
102+
// had just reported — a summary that contradicts its own output is how a
103+
// reader learns to stop reading summaries.
104+
t.Logf("%d cross-reference(s) checked, %d dangling", len(found), dangling)
105+
}

0 commit comments

Comments
 (0)