unitbob 0.6.2 → 0.7.0

package/dist/runner/failureDigest.js

@@ -12,10 +12,17 @@ const MARKER = /ubc_[0-9a-f]{12}(?![0-9a-f])/;
 // the first test produces no set at all, and comparing against nothing would
 // stop a branch over a harness problem the loop never even reached.
 export function failureSet(runner, report) {
+    const found = reportedFailures(runner, report);
+    return found && canonical(found.map(({ marker, file, message }) => ({ marker, file, message })));
+}
+// The same failures, with everything a reader needs and the comparison does not.
+// Reported in the order the runner reported them: this list is read by a person
+// deciding what to repair, and a run's own order is the one that matches the
+// console output next to it.
+export function reportedFailures(runner, report) {
     if (!report.trim())
         return null;
-    const found = extract(runner, report);
-    return found && canonical(found);
+    return extract(runner, report);
 }
 // One hash for one set. Same set, same hash, on any machine and in any order.
 export function digestOf(failures) {
@@ -99,7 +106,9 @@ function fromRspec(report) {
             return [];
         const name = `${text(example.description)} ${text(example.full_description)}`;
         const exception = example.exception;
-        return [failure(name, text(example.file_path), text(exception?.message))];
+        return [failure(name, text(example.file_path), text(exception?.message), {
+                name: text(example.full_description) || text(example.description),
+            })];
     });
 }
 function fromVitest(report) {
@@ -113,7 +122,9 @@ function fromVitest(report) {
                 return [];
             const messages = Array.isArray(assertion.failureMessages) ? assertion.failureMessages : [];
             const name = `${text(assertion.title)} ${text(assertion.fullName)}`;
-            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'))];
+            return [failure(name, text(file.name), messages.map((m) => text(m)).join('\n'), {
+                    name: text(assertion.fullName) || text(assertion.title),
+                })];
         });
     });
 }
@@ -130,16 +141,55 @@ function fromVitest(report) {
 function fromJunitXml(report) {
     if (!/<testsuites?\b/.test(report))
         return null;
-    const cases = report.match(/<testcase\b[^>]*(?:\/>|>[\s\S]*?<\/testcase>)/g) ?? [];
+    // Self-closing first, and as its own alternative rather than a branch inside
+    // one `[^>]*`. Written the other way the engine backtracks out of `\/>` into
+    // `>[\s\S]*?<\/testcase>` and swallows the next element whole, so a passing
+    // self-closed case immediately before a failing one hands back the passing
+    // one's name and file. Harmless while this was only hashed; wrong the moment
+    // spec 37-2 started printing it to somebody deciding what to repair.
+    const cases = report.match(/<testcase\b[^>]*\/>|<testcase\b[^>]*>[\s\S]*?<\/testcase>/g) ?? [];
     return cases.flatMap((testcase) => {
-        const problem = testcase.match(/<(?:failure|error)\b[^>]*(?:\/>|>[\s\S]*?<\/(?:failure|error)>)/);
+        const problem = testcase.match(/<(failure|error)\b[^>]*\/>|<(failure|error)\b[^>]*>([\s\S]*?)<\/(?:failure|error)>/);
         if (!problem)
             return [];
         const name = attribute(testcase, 'name');
         const file = attribute(testcase, 'file') || attribute(testcase, 'classname');
-        return [failure(name, file, attribute(problem[0], 'message'))];
+        const message = attribute(problem[0], 'message');
+        // pytest puts the one-line summary in `message=` and the assertion with its
+        // traceback in the element's body. The body is what a person needs; the
+        // attribute is what the digest compares, and changing its bytes would make
+        // every branch look like it had moved once.
+        const body = unescapeXml(problem[3] ?? '').trim();
+        return [failure(name, file, message, {
+                name,
+                detail: [unescapeXml(message), body].filter(Boolean).join('\n'),
+            })];
     });
 }
+// The five entities XML defines plus numeric references — pytest escapes its
+// newlines as `&#10;`, and a traceback rendered as one line of `&#10;` is not a
+// traceback. This is pytest's own writer on the other end, not arbitrary markup.
+// `&amp;` last, so `&amp;lt;` comes back as `&lt;` rather than as `<`.
+function unescapeXml(value) {
+    return value
+        .replace(/&#(\d+);/g, (whole, code) => codePoint(Number(code), whole))
+        .replace(/&#x([0-9a-f]+);/gi, (whole, code) => codePoint(parseInt(code, 16), whole))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+// A reference outside Unicode is left as it was written. Nothing here is worth
+// throwing over: this runs while somebody is reading why their suite is red.
+function codePoint(value, whole) {
+    try {
+        return String.fromCodePoint(value);
+    }
+    catch {
+        return whole;
+    }
+}
 // Cucumber Messages (NDJSON), both the Ruby and the JS emitter. One scenario is
 // spread over several envelopes: the pickle holds its name, tags and file, the
 // testCase maps its steps, and testStepFinished carries each step's result.
@@ -164,7 +214,13 @@ function fromCucumberMessages(report) {
             continue;
         const startedId = text(finished.testCaseStartedId);
         const list = results.get(startedId) ?? [];
-        list.push(finished.testStepResult ?? {});
+        list.push({
+            // The step's own id travels with its result, so the text of the step that
+            // failed can be recovered from the pickle it came from (spec 37-2,
+            // criterion 5). Nothing in the digest reads it.
+            testStepId: finished.testStepId,
+            ...(finished.testStepResult ?? {}),
+        });
         results.set(startedId, list);
     }
     return envelopes.flatMap((envelope) => {
@@ -180,12 +236,27 @@ function fromCucumberMessages(report) {
         const tags = Array.isArray(pickle.tags) ? pickle.tags : [];
         const tagText = rows(tags).map((tag) => text(tag.name)).join(' ');
         const message = failed.map((step) => text(step.message)).find((line) => line.trim()) ?? '';
-        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message)];
+        return [failure(`${tagText} ${text(pickle.name)}`, text(pickle.uri), message, {
+                name: text(pickle.name),
+                step: cucumberStepText(failed[0], testCase, pickle),
+            })];
     });
 }
-// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). It names
-// no file — the whole behavioral bundle is one run — so the scenario's marker
-// and message carry the identity alone.
+// Which step of that Scenario failed, in the words of the feature file. Three
+// hops, because Cucumber Messages keeps the result, the mapping and the text in
+// three different envelopes: result → testStep → pickleStep.
+function cucumberStepText(failed, testCase, pickle) {
+    const testSteps = Array.isArray(testCase.testSteps) ? rows(testCase.testSteps) : [];
+    const testStep = testSteps.find((step) => text(step.id) === text(failed.testStepId));
+    if (!testStep)
+        return '';
+    const pickleSteps = Array.isArray(pickle.steps) ? rows(pickle.steps) : [];
+    return text(pickleSteps.find((step) => text(step.id) === text(testStep.pickleStepId))?.text);
+}
+// The connector's own pytest-bdd report (`runner/pytestBddPlugin.ts`). Its
+// `file` is the `.feature` the Scenario came from, and it is empty on a report
+// written by a connector older than spec 37-2 — which is why it is read
+// defensively rather than assumed.
 function fromPytestBdd(report) {
     const data = parseObject(report);
     if (!Array.isArray(data?.scenarios))
@@ -194,17 +265,28 @@ function fromPytestBdd(report) {
         if (text(scenario.status) === 'passed')
             return [];
         const tags = Array.isArray(scenario.tags) ? scenario.tags.map((tag) => text(tag)).join(' ') : '';
-        return [failure(`${tags} ${text(scenario.name)}`, '', text(scenario.failure))];
+        // Our own plugin records one entry per step with its status, and marks the
+        // one it caught the exception in — so the step is read, never guessed.
+        const steps = Array.isArray(scenario.steps) ? rows(scenario.steps) : [];
+        const broke = steps.find((step) => text(step.status) === 'failed');
+        return [failure(`${tags} ${text(scenario.name)}`, text(scenario.file), text(scenario.failure), {
+                name: text(scenario.name),
+                step: broke ? `${text(broke.keyword)} ${text(broke.text)}`.trim() : '',
+            })];
     });
 }
-// Only the first line of a message. Later lines are backtraces and diffs, which
+// `message` is only the first line. Later lines are backtraces and diffs, which
 // carry object ids and absolute paths that differ between two runs of the same
-// unchanged failure — the very drift that would make this comparison useless.
-function failure(name, file, message) {
+// unchanged failure — the very drift that would make the comparison useless.
+// `detail` keeps all of it: nothing on that field is hashed.
+function failure(name, file, message, extra = {}) {
     return {
         marker: name.match(MARKER)?.[0] ?? '',
         file,
         message: message.split('\n')[0]?.trim() ?? '',
+        name: (extra.name ?? name).trim(),
+        step: extra.step ?? '',
+        detail: (extra.detail ?? message).trim(),
     };
 }
 function indexBy(envelopes, key) {

package/dist/runner/provision.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { executable } from "../proc.js";
 import { BEHAVIORAL_DIR } from "../files/behavioral.js";
 import { runInProject } from "./place.js";
-import { commandFileOnHost, defaultToolDeps, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
+import { commandFileOnHost, defaultToolDeps, hasGemfileWith, projectProvidesRunner, runnerAvailable, SIDECAR_DIR, sidecarPath, } from "./toolchain.js";
 // How long a local setup step may take before we stop waiting. Provisioning a
 // runner and loading a cold Rails test environment sit in the same ballpark —
 // tens of seconds on a large app — so `runner/bootcheck.ts` waits on this same
@@ -295,6 +295,92 @@ async function provisionVitest(projectRoot, deps) {
 // project's own bundler settings are never touched, and no other bundler
 // invocation carries this.
 const UNFROZEN_SIDECAR = { BUNDLE_FROZEN: 'false', BUNDLE_DEPLOYMENT: 'false' };
+// One gem line for the sidecar, asked for only if the project has not asked for
+// it already.
+//
+// `eval_gemfile` runs the project's own Gemfile inside *this* Dsl object — that
+// is the whole point of it, and it is also the trap. Every `gem` line we add
+// afterwards lands in the same dependency list the project just filled, so a gem
+// the project already names is declared twice, and bundler's rules for that are
+// strict: identical requirements warn, differing ones raise `GemfileError` while
+// the Gemfile is still being parsed.
+//
+// Measured on bundler 2.4.22 and 4.0.1 after A2.Time (Rails 5.0, Ruby 2.7.8)
+// could not generate a behavioral suite at all, 2026-08-20. It pins
+// `webmock "~> 3.23"`; we asked for `webmock (>= 0)`:
+//
+//   You cannot specify the same gem twice with different version requirements.
+//   You specified: webmock (~> 3.23) and webmock (>= 0). Bundler cannot continue.
+//
+// Parsing fails before resolution begins, so there is no lock and no versions to
+// negotiate — and `suite-prepare` rewrote the same conflicting file on every
+// retry, which left the vibecoder with nothing to patch either. The comment that
+// used to sit on the webmock line had this exactly backwards: it promised the
+// project's own version would win "because bundler starts from the project's own
+// resolution". True of resolution. Parsing never reached it.
+//
+// `dependencies` is Bundler::Dsl's own reader and the Gemfile is instance_eval'd
+// on the Dsl, so the list is in scope and already holds everything the project
+// declared. Checked in the dsl.rb of 2.1.4, 2.2.33, 2.3.27, 2.4.22 and 4.0.1 —
+// 2.1.4 because it is what Ruby 2.7.8 ships, and Ruby 2.7.8 is what the
+// application that found this bug runs.
+//
+// What we would have added is dropped rather than merged, version and all: a
+// project pinning `cucumber "~> 8.0"` gets a sidecar on cucumber 8 instead of a
+// hard failure. The suite then runs on the version that project already trusts,
+// which is the bargain the rest of this sidecar strikes anyway — it inherits the
+// project's Gemfile precisely so the two cannot drift apart.
+//
+// One thing this does give up, measured on 2.1.4 and 4.0.1 rather than assumed.
+// Where the requirements happened to match, bundler used to keep *both*
+// declarations — the project's and ours — so a gem the project had confined to
+// `group :test` also arrived ungrouped through us, and no `BUNDLE_WITHOUT` could
+// drop it. Skipping our line leaves only the project's, groups and all. That is
+// the honest arrangement, and it is not silent: the World probe of spec 35-1
+// asserts against a live `WebMock::NetConnectNotAllowedError`, so a webmock that
+// did not come along stops `suite-prepare` with a fixable probe failure instead
+// of letting a suite run with the block it advertises quietly missing.
+function gemLineUnlessTheProjectHasIt(name, requirement) {
+    const pin = requirement ? `, "${requirement}"` : '';
+    return `gem "${name}"${pin}, require: false unless dependencies.any? { |d| d.name == "${name}" }\n`;
+}
+const BUNDLER_OUTPUT_LINES = 20;
+const BUNDLER_OUTPUT_CHARS = 2000;
+// What bundler said, kept instead of thrown away. Reads as the sentence after
+// "Bundler failed to ...", whichever of its three shapes it takes.
+//
+// Both Ruby sidecars used to capture `result` and then return a fixed line, so a
+// provisioning failure reached the vibecoder as "Bundler failed to provision ..."
+// and nothing else. On A2.Time that hid the `GemfileError` above completely: the
+// run reported a blocked behavioral branch, the reason was already in this
+// process's memory, and it still took a round trip through the user — run bundler
+// by hand, paste the output — to find out what it was. An error we have been told
+// is not one to make somebody fetch again.
+//
+// The tail, because bundler puts the reason last on failures long enough to
+// scroll (a resolution conflict prints its whole search first), and a Gemfile
+// that will not parse is short enough that the tail is all of it. Not
+// `installerComplaint`, which is next door and does the opposite on purpose: it
+// picks the single line pip labelled an error out of hundreds of lines of
+// compiler noise. Bundler's verdict carries no such label — the one that matters
+// here opens with `[!]` and runs over three lines — so filtering by line would
+// drop exactly the sentence worth keeping.
+function whatBundlerSaid(result) {
+    const text = [result.stdout, result.stderr].map((part) => part.trim()).filter(Boolean).join('\n');
+    // A null code is a process this connector killed, not one that decided
+    // anything. No number is named with it: the two callers run under different
+    // budgets — `provisionRspec` asks for `DEPENDENCY_INSTALL_TIMEOUT_MS`,
+    // `provisionRuby` takes the `PROVISION_TIMEOUT_MS` default — and a message
+    // that states the wrong one is worse than a message that states none.
+    if (!text) {
+        return result.code === null
+            ? 'It said nothing: it was stopped before it could, having run past its timeout or lost the place it was running in.'
+            : `It said nothing, and exited ${result.code}.`;
+    }
+    const lines = text.split('\n');
+    const tail = lines.slice(-BUNDLER_OUTPUT_LINES).join('\n').slice(-BUNDLER_OUTPUT_CHARS);
+    return `It said:\n${tail.length < text.length ? `...\n${tail}` : tail}`;
+}
 // A sidecar Gemfile that inherits the project's own, plus rspec-rails. Bundler
 // resolves the two together, so the application's gems come with it — the same
 // arrangement the Cucumber sidecar has used since spec 32-1, and the reason the
@@ -303,6 +389,20 @@ async function provisionRspec(projectRoot, deps) {
     const sidecarGemfile = sidecarPath(projectRoot, 'Gemfile');
     writeIfChanged(sidecarGemfile, '# Sidecar Gemfile written by the unitbob connector — do not edit.\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
+        // Deliberately *not* guarded the way the Cucumber sidecar below is.
+        // `ensureStructuralRunner` only reaches here when the project does not
+        // supply rspec itself, so the duplicate that stopped A2.Time has almost no
+        // way in — and the guard would cost something real where it does. Measured
+        // 2026-08-20 on a gem project that carries rspec-rails as a gemspec
+        // development dependency: bundler replaces a `:development` dependency with
+        // ours rather than refusing it, so today the runner lands in `:default` and
+        // is always installed. Guarded, we would skip our line and leave it in
+        // `:development`, where a `BUNDLE_WITHOUT=development` would take the
+        // structural runner away from a project that had it working.
+        //
+        // That leaves one narrow hole: rspec-rails reached through an eval'd
+        // sub-Gemfile does raise the duplicate error here. It is now a legible one
+        // — see the message below, which no longer swallows what bundler said.
         'gem "rspec-rails", require: false\n');
     // Start from the project's own resolution for the reason spelled out on the
     // Cucumber sidecar below: without it bundler re-resolves the whole graph and
@@ -320,7 +420,7 @@ async function provisionRspec(projectRoot, deps) {
         return { status: 'provisioned' };
     return {
         status: 'fixable',
-        message: `Bundler failed to provision rspec-rails under ${SIDECAR_DIR}.`,
+        message: `Bundler failed to provision rspec-rails under ${SIDECAR_DIR}. ${whatBundlerSaid(result)}`,
         checklist: [
             'Ensure bundler is installed (`gem install bundler`), then run ' +
                 `\`BUNDLE_GEMFILE=${SIDECAR_DIR}/Gemfile bundle install\` from the project root.`,
@@ -348,17 +448,82 @@ function copyLockIfPresent(projectRoot, destination) {
     if (existsSync(projectLock))
         writeFileSync(destination, readFileSync(projectLock, 'utf8'));
 }
+// The pin the sidecar asks for, and the oldest Ruby that pin will install on.
+// Written next to each other because they are one fact: every cucumber in the
+// 9.x line declares `required_ruby_version >= 2.7` (checked against rubygems for
+// 9.0.0 through 9.2.1, 2026-08-24). Move the pin and this number moves with it.
+const CUCUMBER_PIN = '~> 9.0';
+const CUCUMBER_MIN_RUBY = { major: 2, minor: 7, text: '2.7' };
+// Spec 37-2, criterion 4. One known refusal, made legible — not a parser for
+// other people's error messages.
+//
+// a2time, 2026-08-17: the behavioral branch came back "Bundler failed to
+// provision Cucumber sidecar gem", and the cause was a fact this process could
+// have read in one command — the host's Ruby is 2.6.10, older than the cucumber
+// this connector pins. It cost a round trip through the vibecoder to run
+// `bundle install` by hand and read the same sentence back.
+//
+// Asked before the install rather than after: `bundle install` on a cold
+// application takes minutes, and the answer is the same either way.
+//
+// Only when our pin is the one that applies. A project that declares cucumber
+// itself keeps its own version — `gemLineUnlessTheProjectHasIt` drops our line
+// whole — and refusing that project over a floor it never had to meet would
+// stop a build that works.
+//
+// The Gemfile is read as text, while the line that drops the pin asks bundler's
+// own resolved `dependencies`. The two can disagree, and only one direction of
+// disagreement is expensive: a project whose cucumber arrives through `gemspec`
+// or an `eval_gemfile` would be refused over a floor it never had to meet. So
+// those two words count as "the project may name it", and the check stays quiet
+// — back to bundler's own message, which is where this started and no worse.
+const PROJECT_MAY_NAME_CUCUMBER = /^\s*gem\s+["']cucumber["']|^\s*gemspec\b|^\s*eval_gemfile\b/m;
+async function rubyTooOldForCucumber(projectRoot, deps) {
+    if (hasGemfileWith(projectRoot, PROJECT_MAY_NAME_CUCUMBER))
+        return null;
+    const result = await deps
+        .runCmd('ruby', ['-v'], { cwd: projectRoot })
+        .catch(() => ({ code: 1, stdout: '', stderr: '' }));
+    if (result.code !== 0)
+        return null;
+    // A version we cannot read stops nothing. This check exists to replace one
+    // confusing message with one clear one, and guessing here would replace a
+    // clear failure with a wrong refusal.
+    const found = `${result.stdout}\n${result.stderr}`.match(/\bruby (\d+)\.(\d+)\.(\d+)/i);
+    if (!found)
+        return null;
+    const [, major, minor] = found;
+    const older = Number(major) < CUCUMBER_MIN_RUBY.major
+        || (Number(major) === CUCUMBER_MIN_RUBY.major && Number(minor) < CUCUMBER_MIN_RUBY.minor);
+    return older ? `${major}.${minor}.${found[3]}` : null;
+}
 async function provisionRuby(projectRoot, behavioralDir, deps) {
+    const oldRuby = await rubyTooOldForCucumber(projectRoot, deps);
+    if (oldRuby) {
+        return {
+            status: 'fixable',
+            message: `Cucumber ${CUCUMBER_PIN} needs Ruby ${CUCUMBER_MIN_RUBY.text} or newer, and the Ruby answering here is ` +
+                `${oldRuby}. Bundler was not asked to install it.`,
+            checklist: [
+                `Run Unitbob where the application runs. The Ruby that answered is ${oldRuby}; if the app itself runs ` +
+                    'on a newer one inside a container, name that container under `exec` in `.unitbob.json` and this ' +
+                    'check runs there instead.',
+                `Or declare \`cucumber\` in the project's own Gemfile at a version that supports Ruby ${oldRuby} — ` +
+                    'the sidecar drops its own pin whenever the project names the gem.',
+            ],
+        };
+    }
     const sidecarGemfile = join(behavioralDir, 'Gemfile');
     const sidecarContent = '# Sidecar Gemfile generated by Unitbob (Spec 32-1)\n' +
         'eval_gemfile File.expand_path("../../../Gemfile", __FILE__)\n' +
-        'gem "cucumber", "~> 9.0", require: false\n' +
+        gemLineUnlessTheProjectHasIt('cucumber', CUCUMBER_PIN) +
         // The connector-owned World blocks outgoing HTTP (spec 35-1), and it can only
-        // do that if webmock resolves here. A project that already carries the gem
-        // keeps its own version, because bundler starts from the project's own
-        // resolution. A project that does not would otherwise get a World promising a
-        // block it silently never performs — the exact shape of failure 35-1 closes.
-        'gem "webmock", require: false\n';
+        // do that if webmock resolves here. A project that does not carry the gem
+        // would otherwise get a World promising a block it silently never performs —
+        // the exact shape of failure 35-1 closes. A project that does carry it keeps
+        // its own version, and now actually gets to: see the comment on the helper
+        // for what asking twice cost A2.Time.
+        gemLineUnlessTheProjectHasIt('webmock');
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }
@@ -399,7 +564,7 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     }
     return {
         status: 'fixable',
-        message: 'Bundler failed to provision Cucumber sidecar gem.',
+        message: `Bundler failed to provision Cucumber sidecar gem. ${whatBundlerSaid(result)}`,
         checklist: ['Ensure bundler is installed (`gem install bundler`) and run `bundle install` manually inside `.unitbob/behavioral/`.'],
     };
 }

package/dist/runner/pytest.js

@@ -17,7 +17,7 @@ export const PYTEST_INI = '[pytest]\naddopts =\n';
 // JUnit XML report goes to --junit-xml, not stdout. The command is
 // connector-owned: the suite artifact never carries a command string.
 //
-// Every file of the branch is named positionally (spec 43, §6.5) — a branch is
+// Every file of the branch is named positionally (spec one-place-per-rule, §6.5) — a branch is
 // one file per assignment now, and pytest takes as many paths as it is given.
 //
 // Which pytest is a single question answered in one place (`locateRunner`), so

package/dist/runner/pytestBddPlugin.js

@@ -27,6 +27,11 @@ _UNITBOB_OUT = os.path.abspath(_UNITBOB_OUT) if _UNITBOB_OUT else None
 def pytest_bdd_before_scenario(request, feature, scenario):
     _UNITBOB_CURRENT[id(scenario)] = {
         "name": scenario.name,
+        # Which .feature file this Scenario came from. Every hook here is handed
+        # the feature and none of them recorded it, so a red run named the
+        # Scenario and left the reader to find the file (spec 37-2, criterion 5).
+        # Project-relative where pytest-bdd offers it.
+        "file": getattr(feature, "rel_filename", None) or getattr(feature, "filename", None) or "",
         "tags": sorted(scenario.tags),
         "status": "passed",
         "failure": "",

package/dist/runner/rspec.js

@@ -18,7 +18,7 @@ export const RSPEC_RESULT_FILE = join(GUARDRAILS_DIR, 'rspec_result.json');
 // corrupt it.
 //
 // `suitePaths` is every file of the branch in the suite blob's own
-// project-relative form (spec 43, §6.5). Named one by one rather than as a
+// project-relative form (spec one-place-per-rule, §6.5). Named one by one rather than as a
 // directory: the artifact already says exactly which files it is, while a
 // directory would also collect whatever else happens to be sitting under the
 // root.

package/dist/runner/vitest.js

@@ -37,7 +37,7 @@ const PROJECT_CONFIGS = [
 // file of the branch in `include`, and the positional filters keep the run to
 // exactly those files.
 //
-// Named files rather than a directory glob, since spec 43, §6.5 made a branch
+// Named files rather than a directory glob, since spec one-place-per-rule, §6.5 made a branch
 // several files: the artifact already says which files it is, and a glob would
 // have to guess a naming convention nothing enforces. `include` is written even
 // when the project has no config of its own — Vitest's default include only

package/dist/surfaces/graph.js

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { graphPath } from "../files/mapBuild.js";
+export function graphNodes(projectRoot) {
+    const path = graphPath(projectRoot);
+    if (!existsSync(path))
+        return [];
+    try {
+        const graph = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(graph.nodes))
+            return [];
+        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
+    }
+    catch {
+        return []; // an unreadable graph costs us the links, not the addresses
+    }
+}
+export function pathsMatch(candidate, file) {
+    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
+    const wanted = file.replace(/\\/g, '/');
+    if (normalised === wanted)
+        return 'exact';
+    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
+}
+// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
+// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
+// them are read the same way — drop the call parentheses, then take the last
+// name — so the match survives the decoration without depending on which form
+// this release of graphify happens to use. The id itself is never rebuilt from
+// any of this; it is copied.
+export function methodNameOf(label) {
+    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
+    return parts[parts.length - 1] ?? '';
+}

package/dist/surfaces/routeInventory.js

@@ -1,10 +1,10 @@
-import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { executable } from "../proc.js";
 import { firstErrorLine } from "../runner/bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.js";
 import { detectStructuralRunner } from "../runner/precheck.js";
-import { graphPath } from "../files/mapBuild.js";
+import { graphNodes, methodNameOf, pathsMatch } from "./graph.js";
 // Reading a router means booting the application, which on a large Rails app is
 // tens of seconds. The same budget the other boot-shaped step uses.
 const ROUTES_TIMEOUT_MS = 120_000;
@@ -266,20 +266,6 @@ function rowsFrom(record) {
         action,
     }));
 }
-function graphNodes(projectRoot) {
-    const path = graphPath(projectRoot);
-    if (!existsSync(path))
-        return [];
-    try {
-        const graph = JSON.parse(readFileSync(path, 'utf8'));
-        if (!Array.isArray(graph.nodes))
-            return [];
-        return graph.nodes.filter((node) => !!node && typeof node.id === 'string');
-    }
-    catch {
-        return []; // an unreadable graph costs us the links, not the addresses
-    }
-}
 function toSurface(projectRoot, row, nodes) {
     const surface = { kind: 'route', id: `${row.verb} ${row.path}` };
     if (!row.controller || !row.action)
@@ -350,23 +336,6 @@ function findNode(nodes, file, action) {
     // still ships, without a link.
     return candidates.length === 1 ? candidates[0] : undefined;
 }
-function pathsMatch(candidate, file) {
-    const normalised = candidate.replace(/\\/g, '/').replace(/^\.\//, '');
-    const wanted = file.replace(/\\/g, '/');
-    if (normalised === wanted)
-        return 'exact';
-    return normalised.endsWith(`/${wanted}`) ? 'suffix' : 'no';
-}
-// Real graphify labels a Ruby method `.send_to_fsa()` and a JS one
-// `initButtons()`; a qualified `CheckoutController#create` also turns up. All of
-// them are read the same way — drop the call parentheses, then take the last
-// name — so the match survives the decoration without depending on which form
-// this release of graphify happens to use. The id itself is never rebuilt from
-// any of this; it is copied.
-function methodNameOf(label) {
-    const parts = label.replace(/\(.*\)\s*$/, '').split(/::|[#./]/).filter(Boolean);
-    return parts[parts.length - 1] ?? '';
-}
 // What `surfaces.json` must contain for every address the router declared, and
 // what it must not contain on top of them. Used before upload (`put-map-build`):
 // the inventory removed the model's chance to invent an address, and this

package/dist/verbs/putSuiteBuild.js

@@ -46,7 +46,7 @@ export async function putSuiteBuild(config, _args = [], deps) {
     // skipped by going straight to the upload — but reported the way every other
     // local failure here is reported: against the branch it belongs to.
     //
-    // Since spec 43 that check is exactly one question, and it is about a branch
+    // Since spec one-place-per-rule that check is exactly one question, and it is about a branch
     // the answer has *no* entry for: everything else it used to ask is now asked
     // of the server, by a dry run, before this command runs at all. So its
     // problems can never land on a branch this loop visits, and they are reported

package/dist/verbs/run.js

@@ -30,7 +30,7 @@ function resolve(config, deps) {
         getSuites: () => wire.getSuites(),
         postRunsBatch: (runs) => wire.postRunsBatch(runs),
         // The whole envelope, support files and all: a branch is a set of files
-        // since spec 43, §6, and picking `path` and `content` out of it here was
+        // since spec one-place-per-rule, §6, and picking `path` and `content` out of it here was
         // where the rest of them used to be lost.
         materializeStructural: (projectRoot, item) => materializeGuardrails(projectRoot, {
             suite_digest: item.suite_digest,
@@ -145,7 +145,7 @@ export function runStructuralByRunner(projectRoot, runner, suitePaths) {
     }
 }
 // Every file of the branch, in the order the envelope carries them. A structural
-// branch is one file per assignment since spec 43, §6, and running only the main
+// branch is one file per assignment since spec one-place-per-rule, §6, and running only the main
 // one would execute a fraction of what the map says is guarded.
 function artifactPaths(file) {
     return [file.path, ...(file.support_files ?? []).map((entry) => entry.path)];