Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -461,9 +461,15 @@ JRuby**):
`pid`/`ppid`/`uid`/`gid`/`euid`/`egid`. There is **no `Process.fork`**
(`Process.respond_to?(:fork)` is `false`) — Go's runtime cannot be forked
safely; `spawn` is the supported way to start a child. **`Kernel#fork` is a
different story**: `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.
different story**: `fork { ... }` *does* exist and runs the block **in the same
process**, so **code that forks to isolate or to drop privileges gets neither
here** — measured 2026-11-15 against MRI 4.0.7, `x = 1; fork { x = 99 }` leaves
the parent's `x` at **99** where MRI leaves it at **1**, and the `Integer` it
returns is indistinguishable from a real pid. It exists because
`Puppet::Util::Execution.execute` is built on it
([#774](https://github.com/go-embedded-ruby/ruby/issues/774) weighs the three
ways out; the parity plan is
[#941](https://github.com/go-embedded-ruby/ruby/issues/941)).
- **Pattern matching (`case`/`in`):** value, variable-binding, class/constant,
array (incl. splat and nested), hash (`deconstruct_keys`, `**rest`/`**nil`),
find (`[*pre, x, *post]`), pin (`^x`) and alternative (`a | b`) patterns;
Expand Down
105 changes: 105 additions & 0 deletions readme_xref_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
// Copyright (c) the go-embedded-ruby/ruby authors
//
// SPDX-License-Identifier: BSD-3-Clause

package ruby_test

import (
"regexp"
"strings"
"testing"
)

// TestReadmeCrossReferencesResolve.
//
// The README sent readers to a section that was never written. Under
// Kernel#fork it 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 returned that citation and nothing else. The
// sentence names the stake exactly right — a program that forks to drop
// privileges drops none here — and then points at somewhere that does not
// exist, which is the one place a reader would have gone to find out.
//
// MEASURED, because a guard aimed at prose is worthless if it fires on prose
// that is fine (cf. go-desktop/catalog#26, where the obvious version of a number
// guard gave four must-never-fire hits against two real findings). The
// population was 8 references before this change and is 7 after, and every one
// is a genuine pointer at another part of the document — no emphasis caught by
// accident:
//
// *Set* *Supported today* (x3) *Running Puppet* *Runtime conformance*
// *Status* — and, until this change, *Known divergences*
//
// Seven resolved; *Known divergences* was the one that did not, and the fix
// alongside this test says the thing inline instead of pointing anywhere.
//
// ⛔ I first counted that population BY HAND with a grep and got 4. The regexp
// finds 8: the hand pattern only matched capitalised titles in one phrasing and
// silently missed three repeats of *Supported today* and *Status*. A population
// counted by eye is the thing this test exists to replace, so what it prints is
// the count — and it prints the dangling tally too, rather than a verdict that
// could disagree with the failures above it.
//
// ⛔ The README is flattened first: "see *Set* under\n*Supported today*" wraps
// across two source lines, so a line-based check sees neither half.
func TestReadmeCrossReferencesResolve(t *testing.T) {
readme := readFile(t, "README.md")
flat := strings.Join(strings.Fields(readme), " ")

// An italic phrase introduced by "see" or "under" is a reference to another
// part of this document. Emphasis is written the same way, which is why the
// pattern requires the italic to follow one of those two words IMMEDIATELY:
// `fork { ... } *does* exist` is emphasis and must not be matched.
ref := regexp.MustCompile(`(?i)\b(?:see|under)\s+\*([^*]{2,60})\*`)
found := ref.FindAllStringSubmatch(flat, -1)

// ⛔ A reworded README that matches nothing would make this test pass by
// having stopped looking. The population is the first thing asserted.
if len(found) == 0 {
t.Fatalf("README.md: no %q-style cross-reference matched at all; "+
"the wording changed shape, so teach the regexp rather than "+
"deleting the check", "see *Section*")
}

// A reference resolves to a heading that names it, or to a bold run-in item
// such as "**Set:**" — both are how this README labels a place.
lines := strings.Split(readme, "\n")
resolves := func(title string) bool {
lower := strings.ToLower(title)
for _, ln := range lines {
if strings.HasPrefix(strings.TrimSpace(ln), "#") &&
strings.Contains(strings.ToLower(ln), lower) {
return true
}
}
return strings.Contains(strings.ToLower(flat), "**"+lower)
}

// Reporting the denominator, not just the verdict: a reader of a green run
// should be able to see WHICH references were checked, so a population that
// quietly shrinks is visible.
for _, m := range found {
t.Logf(" reference: *%s*", strings.TrimSpace(m[1]))
}
dangling := 0
for _, m := range found {
title := strings.TrimSpace(m[1])
if !resolves(title) {
dangling++
t.Errorf("README.md refers to *%s*, and no heading or bold item in "+
"README.md names it.\nEither write that section or say the thing "+
"inline — a reference is a promise, and this one carried the "+
"consequence a reader needed.", title)
}
}
// ⛔ The verdict in this line has to agree with the run. A first draft said
// "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.
t.Logf("%d cross-reference(s) checked, %d dangling", len(found), dangling)
}
Loading