unitbob 0.3.0 → 0.3.2

package/dist/files/guardrails.js

@@ -29,10 +29,22 @@ export function assertGuardrailPath(path) {
 // own RSpec setup when one exists; boots the Rails test environment directly
 // when none does. Both branches refuse a non-test environment — before boot
 // via ENV (nothing touched yet), after boot via Rails.env (config overrides).
+//
+// `rspec/core` is required first because this file has two callers and only one
+// of them is the `rspec` binary. The run loads it through that binary, which has
+// already required rspec-core by the time it reads a spec file; the boot check
+// of spec 32-6 loads it through a bare `ruby -e`, which has not. A Rails-
+// generated `spec/rails_helper.rb` calls `RSpec.configure` (inside `spec_helper`)
+// before it requires `rspec/rails`, so under the bare interpreter it died on
+// `uninitialized constant RSpec` — a healthy application declared broken, and its
+// owner told to edit a tracked file the recipes forbid touching. That made the
+// check stricter than the run it predicts, which is the one rule 32-6 is built
+// on. Under the binary this line is a no-op. Found on the a2time run 2026-08-04.
 export const UNITBOB_HELPER_RB = `# frozen_string_literal: true
 # Written by the unitbob connector on every materialization — do not edit.
 ENV['RAILS_ENV'] ||= 'test'
 abort 'unitbob_helper: refusing to run against a non-test environment' unless ENV['RAILS_ENV'] == 'test'
+require 'rspec/core'
 root = File.expand_path('../..', __dir__)
 if File.exist?(File.join(root, 'spec', 'rails_helper.rb'))
   # The project has its own RSpec setup — respect it (factories, cleaners…).

package/dist/runner/provision.js

@@ -31,6 +31,25 @@ async function provisionRuby(projectRoot, behavioralDir, deps) {
     if (!existsSync(sidecarGemfile) || readFileSync(sidecarGemfile, 'utf8') !== sidecarContent) {
         writeFileSync(sidecarGemfile, sidecarContent);
     }
+    // Start the sidecar from the project's own resolution, so bundler adds
+    // cucumber and leaves everything else on the versions the project already
+    // runs. Without a starting lock it resolves the whole graph from scratch: on
+    // a2time that moved 285 gems, handed the sidecar carrierwave 2.2.0 where the
+    // project pins 2.2.6, and Rails then would not load at all (`cannot load such
+    // file -- mimemagic/overlay`). The behavioral branch could not start, and the
+    // boot check of 32-6 had said `ok` — truthfully, because it only ever asks the
+    // structural runner. Found on the a2time run 2026-08-04.
+    //
+    // Copied on every provision rather than only when missing. A lock seeded once
+    // goes stale the moment the project upgrades a gem — the sidecar Gemfile
+    // inherits the project's *Gemfile* through `eval_gemfile`, never its lock, so
+    // nothing would pull the new version through and the drift this exists to
+    // prevent comes back slowly instead of at once. `bundle install` already runs
+    // on every provision, so re-adding cucumber to a fresh copy costs nothing new.
+    const projectLock = join(projectRoot, 'Gemfile.lock');
+    if (existsSync(projectLock)) {
+        writeFileSync(join(behavioralDir, 'Gemfile.lock'), readFileSync(projectLock, 'utf8'));
+    }
     const gemfileRel = '.unitbob/behavioral/Gemfile';
     const env = { BUNDLE_GEMFILE: gemfileRel };
     // Try project local bin/bundle, then bundle

package/dist/surfaces/routeInventory.js

@@ -25,7 +25,7 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
         return silent(projectRoot, asked.reason, asked.detail);
-    const rows = parseExpandedRoutes(asked.result.stdout);
+    const rows = parseRouterAnswer(asked.result.stdout);
     // Zero rows is far likelier to mean "this output is not what we know how to
     // read" than "this application has no addresses". Claiming the second would
     // hand the map a confident, empty answer, so we claim neither.
@@ -43,7 +43,7 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
     const path = routeInventoryPath(projectRoot);
     try {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails routes', environment: asked.environment, surfaces }, null, 2)}\n`);
+        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails router', environment: asked.environment, surfaces }, null, 2)}\n`);
     }
     catch (err) {
         // A read-only checkout or a full disk is not a reason to take the whole map
@@ -63,21 +63,13 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
 // first answer is decided there; only "this environment refused to load" is
 // worth asking again, because that is the one failure an environment can own.
 async function askTheRouter(projectRoot, deps) {
-    const first = await runRailsRoutes(projectRoot, deps, 'test');
+    const first = await askRouterOnce(projectRoot, deps, 'test');
     if (first === null) {
         // The command is not on this machine. A second environment cannot conjure it.
         return { reason: 'app_did_not_load', detail: 'the command did not run on this machine' };
     }
     if (first.code === 0)
         return { result: first, environment: 'test' };
-    // Rails learned `--expanded` in 5.1. Older ones reject the flag before they
-    // load anything, and saying "your application did not load" there sends
-    // somebody to debug an application that is perfectly fine — the same reason
-    // the boot check grew `runner_too_old` rather than calling vitest missing.
-    // The flag is refused the same way in every environment, so there is nothing
-    // to retry.
-    if (rejectedTheFlag(first))
-        return { reason: 'router_too_old' };
     // No exit code at all means the process was stopped rather than finished —
     // our own timeout, or a signal from outside. An application too large to
     // enumerate its routes in the time we allow has told us nothing about whether
@@ -85,12 +77,12 @@ async function askTheRouter(projectRoot, deps) {
     // Retrying would spend the same budget twice for the same silence.
     if (first.code === null)
         return { reason: 'did_not_finish' };
-    const second = await runRailsRoutes(projectRoot, deps, 'default');
+    const second = await askRouterOnce(projectRoot, deps, 'default');
     if (second !== null && second.code === 0)
         return { result: second, environment: 'default' };
     if (second !== null && second.code === null)
         return { reason: 'did_not_finish' };
-    // `rails routes` loads the application, so running it *is* the check: an app
+    // Asking the router loads the application, so asking it *is* the check: an app
     // that will not boot cannot print its routes. We do not ask the boot check
     // from spec 32-6 first — that would boot the app twice to learn the same
     // thing — but we do answer in its currency, quoting the runner's own first
@@ -139,21 +131,18 @@ function becauseOf(result) {
     switch (result.reason) {
         case 'unsupported_stack':
             return 'this project has no router Unitbob can ask yet (Rails is the only one so far)';
-        case 'router_too_old':
-            return '`rails routes --expanded` needs Rails 5.1 or newer, and this Rails refused the flag ' +
-                '(nothing is wrong with the application)';
         case 'app_did_not_load':
-            return `\`rails routes\` did not get through — ${result.detail}`;
+            return `the router could not be asked — ${result.detail}`;
         case 'did_not_finish':
             // No exit code means stopped, and we do not know by whom: our own
             // ${minutes}-minute limit, or something outside this process. Naming only
             // the timeout would put a duration on a run that may have been killed in
             // ten seconds — a claim we cannot make.
-            return `\`rails routes\` was stopped before it finished — either it ran past the ` +
+            return `the router was not done answering — either it ran past the ` +
                 `${ROUTES_TIMEOUT_MS / 60_000}-minute limit or something else killed it (nothing here says the ` +
                 'application is unhealthy)';
         case 'no_routes':
-            return '`rails routes` printed nothing this version knows how to read';
+            return 'the router answered in a shape this connector could not read';
         case 'could_not_write':
             return `the inventory could not be written — ${result.detail}`;
     }
@@ -164,17 +153,47 @@ function plural(count, one, many) {
 function looksLikeRails(projectRoot) {
     return existsSync(join(projectRoot, 'config', 'routes.rb'));
 }
-// `--expanded` rather than the default table: one field per line, so nothing
-// depends on guessing column widths, and a long URI pattern cannot run into its
-// neighbour. `test` is asked first because that is the environment the guardrail
-// suite boots in, so the routes read there are the routes the suite would see;
+// The question, asked of the router object rather than of the `rails routes`
+// command line. `--expanded` was the earlier reading, and it cost this project
+// its whole inventory on the a2time run: the flag arrived in Rails 5.1, that
+// application runs 5.0, and 194 addresses went back to being typed out by hand —
+// the exact work this module exists to remove. `routes` also prints for people,
+// so its field names move between versions (`URI` in Rails 7, `URI Pattern`
+// before it) and the reader had to know both.
+//
+// `Rails.application.routes.routes` has been the same object since Rails 3 and
+// answers in a shape we choose. Nothing here is version-specific except the one
+// thing that genuinely changed: `verb` was a Regexp before Rails 5 and is a
+// String after, so both are reduced to the same letters.
+//
+// The answer is printed behind a sentinel because an application is free to
+// write to stdout while it boots — an initializer with a banner, a deprecation
+// notice — and none of that is ours to parse.
+const ROUTES_SENTINEL = 'UNITBOB_ROUTES ';
+// One address per line rather than one array holding all of them: a project with
+// five hundred routes should not be a single line, and a line cut in half loses
+// one address instead of every address. That cannot lose addresses quietly —
+// output is only ever cut short when the process was killed, and a run that did
+// not exit cleanly is refused before anyone reads what it printed.
+const ROUTES_SCRIPT = `require 'json'
+Rails.application.routes.routes.each do |r|
+  next if r.respond_to?(:internal) && r.internal
+  STDOUT.print("${ROUTES_SENTINEL}" + JSON.generate(
+    'verb' => r.verb.is_a?(String) ? r.verb : r.verb.to_s.gsub(%r{[$^/]}, ''),
+    'path' => r.path.spec.to_s,
+    'controller' => r.defaults[:controller],
+    'action' => r.defaults[:action]
+  ) + "\\n")
+end`;
+// `test` is asked first because that is the environment the guardrail suite
+// boots in, so the routes read there are the routes the suite would see;
 // `default` means we leave RAILS_ENV alone and take whatever the project's own
 // setup chooses.
-async function runRailsRoutes(projectRoot, deps, environment) {
+async function askRouterOnce(projectRoot, deps, environment) {
     const local = join(projectRoot, 'bin', 'rails');
     const [command, args] = existsSync(local)
-        ? [local, ['routes', '--expanded']]
-        : ['bundle', ['exec', 'rails', 'routes', '--expanded']];
+        ? [local, ['runner', ROUTES_SCRIPT]]
+        : ['bundle', ['exec', 'rails', 'runner', ROUTES_SCRIPT]];
     try {
         return await deps.runCmd(command, args, {
             cwd: projectRoot,
@@ -187,33 +206,23 @@ async function runRailsRoutes(projectRoot, deps, environment) {
         return null; // the command is not on this machine
     }
 }
-// Ruby's own OptionParser wording, and Thor's — whichever layer of the `rails`
-// command line sees the flag first. Both name the flag they refused, and the
-// name has to be part of the match: "invalid option" is ordinary Ruby wording
-// that also turns up inside a failing initializer, and reading that as an old
-// Rails would tell somebody their application is fine while it is broken —
-// exactly the wrong-errand this reason exists to prevent, pointing the other way.
-function rejectedTheFlag(result) {
-    return /(?:invalid option|unknown switches?|unrecognized option)[^\n]*expanded/i.test(`${result.stdout}\n${result.stderr}`);
-}
-// The `--expanded` record:
-//
-//   --[ Route 1 ]------------------------------
-//   Prefix            | settings
-//   Verb              | GET
-//   URI               | /settings(.:format)
-//   Controller#Action | settings#index
-//
-// The path field is `URI` on Rails 7 and `URI Pattern` on older versions — both
-// are read, because which one we get is decided by the user's Gemfile. Fields we
-// do not use (Prefix, Source Location) are ignored rather than rejected, so a
-// newer Rails printing more of them still reads.
-export function parseExpandedRoutes(stdout) {
+// The router's answer: the sentinel lines, in among whatever the application
+// printed while booting. Lines are picked out by their prefix rather than by
+// position, so a banner or a deprecation notice costs nothing.
+export function parseRouterAnswer(stdout) {
     const rows = [];
     const seen = new Set();
-    let record = {};
-    const flush = () => {
-        for (const row of rowsFrom(record)) {
+    for (const line of stdout.split('\n')) {
+        if (!line.startsWith(ROUTES_SENTINEL))
+            continue;
+        let declared;
+        try {
+            declared = JSON.parse(line.slice(ROUTES_SENTINEL.length));
+        }
+        catch {
+            continue; // not the shape we know how to read
+        }
+        for (const row of rowsFrom((declared ?? {}))) {
             const key = `${row.verb} ${row.path}`;
             // The same address can be drawn under several prefixes. It is one address.
             if (seen.has(key))
@@ -221,37 +230,26 @@ export function parseExpandedRoutes(stdout) {
             seen.add(key);
             rows.push(row);
         }
-        record = {};
-    };
-    for (const line of stdout.split('\n')) {
-        if (/^--\[ Route /.test(line)) {
-            flush();
-            continue;
-        }
-        const separator = line.indexOf('|');
-        if (separator === -1)
-            continue;
-        record[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
     }
-    flush();
     return rows;
 }
 function rowsFrom(record) {
-    const pattern = record.URI ?? record['URI Pattern'];
-    const verb = record.Verb ?? '';
+    const pattern = typeof record.path === 'string' ? record.path : '';
+    const verb = typeof record.verb === 'string' ? record.verb : '';
     // No verb means a mounted Rack application (`mount Sidekiq::Web at: '/sidekiq'`),
     // not an address of this application. Its own routes live in its own router.
     if (!pattern || !verb)
         return [];
-    const handler = /^([A-Za-z0-9_/]+)#([A-Za-z0-9_]+)$/.exec(record['Controller#Action'] ?? '');
+    const controller = typeof record.controller === 'string' ? record.controller : undefined;
+    const action = typeof record.action === 'string' ? record.action : undefined;
     const path = pattern.replace(/\(\.:format\)$/, '');
-    // `match via: [:get, :post]` prints one record with both verbs. They are two
-    // addresses, and the map should say so.
+    // `match via: [:get, :post]` is one route object carrying both verbs. They are
+    // two addresses, and the map should say so.
     return verb.split('|').map((one) => ({
         verb: one.trim(),
         path,
-        controller: handler?.[1],
-        action: handler?.[2],
+        controller,
+        action,
     }));
 }
 function graphNodes(projectRoot) {

package/dist/verbs/validateBuild.js

@@ -106,7 +106,93 @@ function checkOneCase(row, id, expected, suiteText, add) {
     // as a mismatch rather than as the green it claims.
     if (suiteText && !suiteText.includes(expected.case_marker)) {
         add(`${id} is answered "covered", but its marker ${expected.case_marker} appears nowhere in the suite files.`);
+        return;
+    }
+    checkSurfaceCoverage(row, id, expected, suiteText, add);
+}
+// Which scenario reached which address. The a2time run of 2026-08-04 published
+// 97 coverage rows against 99 Scenarios: one Scenario had no row, another had a
+// row naming no address. Both mean the same thing — a Scenario that ran and
+// whose result reaches nothing on the map — and both were found by the
+// independent reviewer, hours later, doing a different job. This check was the
+// cheap place to find them and it was not looking.
+//
+// Only asked when the answer is already speaking this language: an answer with
+// no `surface_coverage` anywhere is an older map's shape, and refusing it here
+// would refuse what the server accepts. Within a branch that does declare it,
+// the rules below are the server's own, in the server's own order.
+function checkSurfaceCoverage(row, id, expected, suiteText, add) {
+    if (expected.surfaces.length === 0)
+        return;
+    const coverage = row.surface_coverage;
+    if (coverage === undefined)
+        return; // not this map's shape — the server decides
+    if (!Array.isArray(coverage)) {
+        add(`${id} is answered "covered", so its surface_coverage must be an array of {scenario, surfaces}.`);
+        return;
+    }
+    const named = new Set();
+    const reached = new Set();
+    for (const [index, item] of coverage.entries()) {
+        const entry = (item ?? {});
+        const scenario = String(entry.scenario ?? '').trim();
+        const surfaces = entry.surfaces;
+        if (!scenario || !Array.isArray(surfaces)) {
+            add(`${id} surface_coverage[${index}] must name a scenario and its surfaces.`);
+            continue;
+        }
+        if (surfaces.length === 0) {
+            add(`${id} surface_coverage names no surface for "${scenario}" — that scenario's result reaches nothing on the map.`);
+        }
+        if (suiteText && !suiteText.includes(scenario)) {
+            add(`${id} surface_coverage names "${scenario}", which appears nowhere in the suite files.`);
+        }
+        named.add(scenario);
+        surfaces.filter((s) => typeof s === 'string').forEach((s) => reached.add(s));
+    }
+    const missed = expected.surfaces.filter((surface) => !reached.has(surface));
+    if (missed.length > 0) {
+        add(`${id} surface_coverage accounts for no scenario at ${missed.join(', ')}.`);
+    }
+    const foreign = [...reached].filter((surface) => !expected.surfaces.includes(surface));
+    if (foreign.length > 0) {
+        add(`${id} surface_coverage names ${foreign.join(', ')}, which this branch's assignment does not carry.`);
+    }
+    // The other direction, and the one that found nothing on a2time because
+    // nobody asked it: a Scenario that carries the marker but appears in no row.
+    //
+    // Read off the file rather than parsed: a tag line carrying this marker, then
+    // the next line that has a colon in it, whose name is whatever follows the
+    // first colon. That holds for any Gherkin dialect, because only the keyword is
+    // translated and the colon is not. When the shape is not recognised the answer
+    // is silence — the server does parse this properly, and a guess here that says
+    // "you forgot a Scenario" about a Scenario that does not exist would cost the
+    // branch its publication.
+    const unlisted = scenarioNamesTagged(suiteText, expected.case_marker).filter((name) => !named.has(name));
+    if (unlisted.length > 0) {
+        add(`${id} surface_coverage does not account for ${unlisted.map((n) => `"${n}"`).join(', ')}.`);
+    }
+}
+// Scenario names carrying one marker, by shape rather than by grammar. See the
+// caller for why this stays deliberately timid.
+function scenarioNamesTagged(suiteText, marker) {
+    if (!suiteText)
+        return [];
+    const lines = suiteText.split('\n');
+    const names = [];
+    for (const [index, line] of lines.entries()) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('@') || !trimmed.split(/\s+/).includes(`@${marker}`))
+            continue;
+        const next = lines.slice(index + 1).find((candidate) => candidate.trim().length > 0) ?? '';
+        const colon = next.indexOf(':');
+        if (colon === -1)
+            continue;
+        const name = next.slice(colon + 1).trim();
+        if (name)
+            names.push(name);
     }
+    return names;
 }
 // Which field names the id. Read off the *assignment*, where the answer is
 // exact: the id is already known (it is `contract_key` minus its prefix), so the
@@ -169,7 +255,14 @@ function assignedCases(assignment) {
         const key = row.contract_key;
         const marker = row.case_marker;
         if (typeof key === 'string' && key.startsWith(CONTRACT_PREFIX) && typeof marker === 'string') {
-            found.push({ id: key.slice(CONTRACT_PREFIX.length), contract_key: key, case_marker: marker });
+            found.push({
+                id: key.slice(CONTRACT_PREFIX.length),
+                contract_key: key,
+                case_marker: marker,
+                // Only the behavioral assignment carries addresses. Its absence is what
+                // tells the coverage check below there is nothing of that kind here.
+                surfaces: Array.isArray(row.surfaces) ? row.surfaces.filter((s) => typeof s === 'string') : [],
+            });
         }
         Object.values(row).forEach(walk);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unitbob",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Unitbob connector — thin local hands for the Unitbob Rails brain. Owns no domain logic: it runs tools, relays bytes over the wire, and prints what the server returns.",
   "type": "module",
   "bin": {
@@ -15,7 +15,9 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json && chmod +x dist/bin.js",
     "prepublishOnly": "npm run build",
-    "test": "node --test test/*.test.ts"
+    "test": "node --test test/*.test.ts",
+    "check:release": "node scripts/check-release.mjs",
+    "hooks:install": "git config core.hooksPath hooks"
   },
   "publishConfig": {
     "access": "public"