unitbob 0.7.13 → 0.7.15

package/dist/runner/worldProbe.js

@@ -1,13 +1,29 @@
 import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
+import { BEHAVIORAL_DIR, BEHAVIORAL_WORLD_JS_PATH, BEHAVIORAL_WORLD_PATH } from "../files/behavioral.js";
 import { BEHAVIORAL_GEMFILE } from "./bdd.js";
+import { firstErrorLine } from "./bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "./place.js";
 import { PROVISION_TIMEOUT_MS } from "./provision.js";
+import { looksLikeNext } from "../surfaces/nextRoutes.js";
 const PROBE_ROOT = '.unitbob/suite-build/world-probe';
-export async function probeBehavioralWorld(projectRoot, deps = {
+const defaultDeps = {
     runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: PROVISION_TIMEOUT_MS }),
-}) {
+};
+// Which Worlds are probed by running them: the ones that open a door into the
+// application — Ruby's, which integrates with Rails, and Next's, which starts
+// the application (spec 56-1). A harness that only guards the network
+// integrates with nothing on the project, and its one claim is executed in the
+// connector's own suite instead. False means: nothing on this project to
+// probe, and that is not a failure.
+export function worldIsProbed(projectRoot, runner) {
+    return runner === 'cucumber' || (runner === 'cucumber-js' && looksLikeNext(projectRoot));
+}
+// The probe for a runner `worldIsProbed` said yes to.
+export function probeWorld(projectRoot, runner, deps = defaultDeps) {
+    return runner === 'cucumber' ? probeBehavioralWorld(projectRoot, deps) : probeNextWorld(projectRoot, deps);
+}
+export async function probeBehavioralWorld(projectRoot, deps = defaultDeps) {
     // Written on the host, named to the run relative to the project root — the
     // same shape `bdd.ts` has always had, and the reason nothing here needs a path
     // rewritten when the run happens somewhere else (spec 36, §4.2).
@@ -44,6 +60,87 @@ export async function probeBehavioralWorld(projectRoot, deps = {
         rmSync(probeRoot, { recursive: true, force: true });
     }
 }
+// Spec 56-1, §2. A door is probed by walking through it: one scenario, one
+// request to `/`, and any HTTP status is an answer — the page may redirect,
+// may 404, may 500; what the probe asks is whether the application came up
+// and answered through Next. Red means the door did not open, and the first
+// error line of what the run printed is the message — the way `next` itself
+// says it: the module is not installed, the database guard refused, or a
+// developer's `next dev` is holding Next 16's lock.
+export async function probeNextWorld(projectRoot, deps = defaultDeps) {
+    const feature = `${NEXT_PROBE_ROOT}/world.feature`;
+    const steps = `${NEXT_PROBE_ROOT}/world_steps.js`;
+    const probeRoot = join(projectRoot, NEXT_PROBE_ROOT);
+    mkdirSync(probeRoot, { recursive: true });
+    writeFileSync(join(projectRoot, feature), NEXT_PROBE_FEATURE);
+    writeFileSync(join(projectRoot, steps), NEXT_PROBE_STEPS);
+    try {
+        const result = await deps.runCmd(`${BEHAVIORAL_DIR}/node_modules/.bin/cucumber-js`, [
+            feature,
+            '--require', BEHAVIORAL_WORLD_JS_PATH,
+            '--require', steps,
+            '--format', 'progress',
+            // Always: this probe starts a dev Next, and a dev Next never lets the
+            // process end on its own (see `cucumberJsExitArgs`).
+            '--exit',
+        ], {
+            cwd: projectRoot,
+            env: {
+                NODE_ENV: 'test',
+                CUCUMBER_PUBLISH_QUIET: 'true',
+                UNITBOB_REPO_ROOT: projectRootAsSeenByThePlace(projectRoot),
+            },
+        });
+        if (result.code === 0)
+            return { status: 'ok' };
+        // cucumber-js opens every run on a Node it has not been tested with by
+        // saying so; that line is not the error and must not be quoted as one.
+        const lines = [result.stdout, result.stderr]
+            .flatMap((text) => text.split('\n'))
+            .filter((line) => line.trim() && !CUCUMBER_NODE_NOTICE.test(line));
+        // The World's own refusal — the database guard — is printed under the
+        // connector's prefix and is the whole answer when it is there; cucumber-js
+        // would otherwise be quoted saying "a BeforeAll hook errored", with the
+        // reason folded under it.
+        const ours = lines.find((line) => line.trimStart().startsWith('[unitbob]'));
+        const detail = ours?.trim() ?? (lines.length > 0 ? firstErrorLine(lines.join('\n')) : `exit ${result.code}`);
+        return { status: 'fixable', message: `The connector-owned Next.js World probe failed: ${detail}` };
+    }
+    catch (error) {
+        return { status: 'fixable', message: `The connector-owned Next.js World probe could not run: ${String(error)}` };
+    }
+    finally {
+        rmSync(probeRoot, { recursive: true, force: true });
+    }
+}
+// Under the behavioral root, not beside the Ruby probe's files: a step file
+// `require`s `@cucumber/cucumber`, and Node finds it by walking up from the
+// file to the sidecar's `node_modules` — which is here and nowhere else. The
+// same walk makes the file CommonJS: the sidecar's `package.json` is the
+// nearest one, so a project that declares `"type": "module"` (umami does)
+// does not turn the probe's `.js` into an ES module. Removed after the run;
+// a leftover from a killed run is not in the runner environment, so the next
+// materialization clears it.
+const NEXT_PROBE_ROOT = `${BEHAVIORAL_DIR}/world-probe`;
+const CUCUMBER_NODE_NOTICE = /^This Node\.js version \(v[\d.]+\) has not been tested with this version of Cucumber/;
+const NEXT_PROBE_FEATURE = `Feature: Unitbob World profile
+  Scenario: the application answers through the door
+    When the World probe asks the application for "/"
+    Then the application answers with an HTTP status
+`;
+const NEXT_PROBE_STEPS = `const assert = require('node:assert');
+const { Then, When } = require('@cucumber/cucumber');
+
+// \`{string}\` rather than a literal \`"/"\`: in a Cucumber Expression \`/\` is
+// the alternation character, and the literal never matched.
+When('the World probe asks the application for {string}', async function (path) {
+  this.unitbobProbeResponse = await this.unitbobFetch(path);
+});
+
+Then('the application answers with an HTTP status', function () {
+  assert.ok(Number.isInteger(this.unitbobProbeResponse.status), 'no status came back');
+});
+`;
 const PROBE_FEATURE = `Feature: Unitbob World profile
   Scenario: request, assertion counter, mocks, and state mutation
     Given the first World probe scenario mutates supported state

package/dist/surfaces/nextRoutes.js

@@ -0,0 +1,133 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+// `next` among the dependencies *and* an app directory. Both, so that the
+// inventory and the World cannot disagree on "is this Next?": a project that
+// installs `next` for one tool and routes with Express is not the app router,
+// and an `app/` folder in a project without `next` is somebody else's `app/`.
+export function looksLikeNext(projectRoot) {
+    return dependsOnNext(projectRoot) && nextAppDir(projectRoot) !== undefined;
+}
+function dependsOnNext(projectRoot) {
+    const packageJson = join(projectRoot, 'package.json');
+    if (!existsSync(packageJson))
+        return false;
+    try {
+        const parsed = JSON.parse(readFileSync(packageJson, 'utf8'));
+        return 'next' in (parsed.dependencies ?? {}) || 'next' in (parsed.devDependencies ?? {});
+    }
+    catch {
+        return false; // an unreadable package.json names no dependency
+    }
+}
+// `app/` first, as Next itself chooses when both exist. Relative to the project
+// root, with the platform's separator, so it joins onto the root like any path.
+export function nextAppDir(projectRoot) {
+    return [join('app'), join('src', 'app')].find((dir) => existsSync(join(projectRoot, dir)));
+}
+// The gate every address goes through before its handler — `proxy.ts` from
+// Next 16, `middleware.ts` before it. Named in the inventory so the recipe
+// can say it exists; never listed as an address, because it has none.
+const GATE_FILES = ['proxy.ts', 'proxy.js', 'middleware.ts', 'middleware.js'];
+export function nextGate(projectRoot) {
+    for (const dir of ['', 'src']) {
+        for (const name of GATE_FILES) {
+            if (existsSync(join(projectRoot, dir, name)))
+                return dir ? `${dir}/${name}` : name;
+        }
+    }
+    return undefined;
+}
+const PAGE_FILE = /^page\.(tsx|jsx|js|ts)$/;
+const ROUTE_FILE = /^route\.(tsx|jsx|js|ts)$/;
+// Every address under the app directory, sorted by path so the inventory reads
+// like a route table rather than like a directory listing. Files are named
+// relative to the project root with forward slashes, which is how the graph
+// names them too.
+export function nextAppRoutes(projectRoot) {
+    const appDir = nextAppDir(projectRoot);
+    if (!appDir)
+        return [];
+    const rows = [];
+    walk(join(projectRoot, appDir), appDir.split(/[\\/]/).join('/'), [], rows);
+    return rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+function walk(dir, relative, segments, rows) {
+    const path = urlOfSegments(segments);
+    // A subtree with no URL has no addresses anywhere below it.
+    if (path === null)
+        return;
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => (a.name < b.name ? -1 : 1))) {
+        if (entry.isDirectory()) {
+            walk(join(dir, entry.name), `${relative}/${entry.name}`, [...segments, entry.name], rows);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const file = `${relative}/${entry.name}`;
+        if (PAGE_FILE.test(entry.name)) {
+            rows.push({ verb: 'GET', path, file, method: 'default' });
+        }
+        else if (ROUTE_FILE.test(entry.name)) {
+            for (const verb of exportedHttpMethods(readFileSync(join(dir, entry.name), 'utf8'))) {
+                rows.push({ verb, path, file, method: verb });
+            }
+        }
+    }
+}
+// The URL a folder path names, or null when Next gives it none.
+//
+// `(group)` organises files and is absent from the URL. `@slot` is a parallel
+// route rendered inside its parent's page; `(.)`, `(..)`, `(...)` and
+// `(..)(..)` intercept another route — neither has a URL of its own, and
+// nothing below them does either. `[id]`, `[...slug]` and `[[...slug]]` are
+// kept in Next's own spelling: the map already writes
+// `GET /api/admin/projects/[id]/clients`, and Rails' inventory keeps `:id`
+// the same way — the address as the framework declares it, not a pattern we
+// rewrite.
+export function urlOfSegments(segments) {
+    const kept = [];
+    for (const segment of segments) {
+        if (segment.startsWith('@') || /^\(\.{1,3}\)/.test(segment))
+            return null;
+        if (/^\(.*\)$/.test(segment))
+            continue;
+        kept.push(segment);
+    }
+    return `/${kept.join('/')}`;
+}
+// The seven methods a route file may export, in the order the inventory lists
+// them for one path.
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+const METHOD = HTTP_METHODS.join('|');
+// The five ways a route file declares a method, each read from the text:
+//   export async function GET() / export function GET()
+//   export const GET = …
+//   export { GET, POST }              and   export { GET, POST } from './x'
+//   export { handler as GET } …       — the name after `as` is the export
+//   export const { GET, POST } = handlers   (the Auth.js shape)
+//
+// Not read: `export * from './handlers'` — the file names no method, and
+// following the import would be a second module resolver. Such an address is
+// simply not in the inventory; the recipe says the model may still find it in
+// the graph, as it finds everything on a stack with no inventory at all.
+const DECLARED = [
+    new RegExp(`^\\s*export\\s+(?:async\\s+)?function\\s+(${METHOD})\\b`, 'gm'),
+    new RegExp(`^\\s*export\\s+(?:const|let|var)\\s+(${METHOD})\\s*[=:]`, 'gm'),
+];
+const EXPORT_LIST = /^\s*export\s+(?:(?:const|let|var)\s+)?\{([^}]*)\}/gm;
+export function exportedHttpMethods(text) {
+    const found = new Set();
+    for (const pattern of DECLARED) {
+        for (const match of text.matchAll(pattern))
+            found.add(match[1]);
+    }
+    for (const match of text.matchAll(EXPORT_LIST)) {
+        for (const item of match[1].split(',')) {
+            // `a as B` exports B; `A` exports A. Only the exported name is an address.
+            const exported = item.trim().split(/\s+as\s+/).pop()?.trim() ?? '';
+            if (HTTP_METHODS.includes(exported))
+                found.add(exported);
+        }
+    }
+    return HTTP_METHODS.filter((method) => found.has(method));
+}

package/dist/surfaces/routeInventory.js

@@ -5,6 +5,7 @@ import { firstErrorLine } from "../runner/bootcheck.js";
 import { projectRootAsSeenByThePlace, runInProject } from "../runner/place.js";
 import { detectStructuralRunner } from "../runner/precheck.js";
 import { graphNodes, methodNameOf, pathsMatch } from "./graph.js";
+import { looksLikeNext, nextAppRoutes, nextGate } from "./nextRoutes.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;
@@ -19,12 +20,21 @@ const defaultDeps = {
 export function routeInventoryPath(projectRoot) {
     return join(projectRoot, '.unitbob', 'map-build', 'route_inventory.json');
 }
-// Ask this project's router, and write what it says. Rails today; the design
-// records why Django, FastAPI and Flask come next and why Express cannot follow
-// at all (its addresses are registered by arbitrary code at run time).
+// Ask this project's router, and write what it says. Rails and Next.js (app
+// router) today; the design records why Django, FastAPI and Flask come next and
+// why Express cannot follow at all (its addresses are registered by arbitrary
+// code at run time).
 export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
-    if (!canAskTheRouter(projectRoot))
-        return silent(projectRoot, 'unsupported_stack');
+    switch (routeSourceOf(projectRoot)) {
+        case 'router':
+            return askRailsRouter(projectRoot, deps);
+        case 'files':
+            return readNextFiles(projectRoot);
+        default:
+            return silent(projectRoot, 'unsupported_stack');
+    }
+}
+async function askRailsRouter(projectRoot, deps) {
     const asked = await askTheRouter(projectRoot, deps);
     if ('reason' in asked)
         return silent(projectRoot, asked.reason, asked.detail);
@@ -36,17 +46,34 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
         return silent(projectRoot, 'no_routes');
     const nodes = graphNodes(projectRoot);
     const surfaces = rows.map((row) => toSurface(projectRoot, row, nodes));
-    // The inventory, and only the inventory. `surfaces.json` is not written here,
-    // however tempting: the recipe turns this file into that one with a single
-    // command — no output spent retyping addresses, and the file still does not
-    // exist until the model has begun. That absence is a check we would otherwise
-    // throw away, because `put-map-build` refuses a build whose `surfaces.json` is
-    // missing, and a pre-written file full of routes looks finished enough for the
-    // job, table and external surfaces never to be looked for.
+    return writeInventory(projectRoot, { declared_by: 'rails router', environment: asked.environment, surfaces }, 'router');
+}
+// Spec 56-1. No environment to choose and nothing to boot: the files are the
+// declaration. `gate` names the `proxy.ts`/`middleware.ts` every address goes
+// through — not an address itself, and the recipe says so.
+function readNextFiles(projectRoot) {
+    const rows = nextAppRoutes(projectRoot);
+    // An `app/` with no `page.*` or `route.*` declares nothing. As on Rails, we do
+    // not claim "no addresses" for a reading that may simply have missed them.
+    if (rows.length === 0)
+        return silent(projectRoot, 'no_routes');
+    const nodes = graphNodes(projectRoot);
+    const surfaces = rows.map((row) => toNextSurface(row, nodes));
+    const gate = nextGate(projectRoot);
+    return writeInventory(projectRoot, { declared_by: 'next app router', environment: 'default', ...(gate ? { gate } : {}), surfaces }, 'files');
+}
+// The inventory, and only the inventory. `surfaces.json` is not written here,
+// however tempting: the recipe turns this file into that one with a single
+// command — no output spent retyping addresses, and the file still does not
+// exist until the model has begun. That absence is a check we would otherwise
+// throw away, because `put-map-build` refuses a build whose `surfaces.json` is
+// missing, and a pre-written file full of routes looks finished enough for the
+// job, table and external surfaces never to be looked for.
+function writeInventory(projectRoot, document, source) {
     const path = routeInventoryPath(projectRoot);
     try {
         mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, `${JSON.stringify({ declared_by: 'rails router', environment: asked.environment, surfaces }, null, 2)}\n`);
+        writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`);
     }
     catch (err) {
         // A read-only checkout or a full disk is not a reason to take the whole map
@@ -57,9 +84,10 @@ export async function extractRouteInventory(projectRoot, deps = defaultDeps) {
     return {
         status: 'written',
         path,
-        routes: surfaces.length,
-        linked: surfaces.filter((surface) => surface.handler_symbol).length,
-        environment: asked.environment,
+        routes: document.surfaces.length,
+        linked: document.surfaces.filter((surface) => surface.handler_symbol).length,
+        environment: document.environment,
+        source,
     };
 }
 // One question, up to two environments. Everything that can be decided from the
@@ -122,8 +150,9 @@ function silent(projectRoot, reason, detail) {
 export function describeRouteInventory(result) {
     if (result.status === 'written') {
         return (`Route inventory written to ${result.path}: ${result.routes} ${plural(result.routes, 'address', 'addresses')} ` +
-            `from the router${result.environment === 'default' ? ' (read in the default environment — the test one ' +
-                'would not load)' : ''}, ${result.linked} tied to a graph node. The extract_surfaces recipe turns ` +
+            `from the ${result.source === 'files' ? 'file system' : 'router'}` +
+            `${result.source === 'router' && result.environment === 'default' ? ' (read in the default environment — ' +
+                'the test one would not load)' : ''}, ${result.linked} tied to a graph node. The extract_surfaces recipe turns ` +
             'this file into surfaces.json with one command, then adds the job, table and external surfaces to it.');
     }
     return `No route inventory: ${becauseOf(result)}. The extract_surfaces recipe reads the source instead.`;
@@ -133,7 +162,7 @@ export function describeRouteInventory(result) {
 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)';
+            return 'this project has no router Unitbob can ask yet (Rails and the Next.js app router so far)';
         case 'app_did_not_load':
             return `the router could not be asked — ${result.detail}`;
         case 'did_not_finish':
@@ -164,8 +193,19 @@ function plural(count, one, many) {
 // carry a `config/routes.rb` was asked to boot Rails. There are still several
 // stack detectors in this package; this removes the one that had a single caller
 // and no excuse.
-function canAskTheRouter(projectRoot) {
-    return (detectStructuralRunner(projectRoot) === 'rspec' && existsSync(join(projectRoot, 'config', 'routes.rb')));
+//
+// Next.js is the second source (spec 56-1), and it is a different kind: there
+// is no router object to ask, the files are the declaration. `looksLikeNext` is
+// the one answer to "is this Next?" in this package — the World that opens the
+// door into the application (`files/behavioral.ts`) asks the same function, so
+// the two cannot disagree.
+function routeSourceOf(projectRoot) {
+    if (detectStructuralRunner(projectRoot) === 'rspec' && existsSync(join(projectRoot, 'config', 'routes.rb'))) {
+        return 'router';
+    }
+    if (looksLikeNext(projectRoot))
+        return 'files';
+    return null;
 }
 // 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
@@ -294,6 +334,21 @@ function toSurface(projectRoot, row, nodes) {
     surface.handler_label = `${row.controller}#${row.action}`;
     return surface;
 }
+// The Next.js counterpart of `toSurface`. The file is the declaration, so it is
+// always the `source_file`; the label is `<file>#<method>` — `#default` for a
+// page — which is what the file itself says, the way `settings#index` is what
+// the router said. The link is looked up by the same two facts as on Rails:
+// this file, this method name. A page whose default export the graph did not
+// record keeps its address with no link — that is the `AdminDashboard` page of
+// the appartment run, and it is normal.
+function toNextSurface(row, nodes) {
+    const surface = { kind: 'route', id: `${row.verb} ${row.path}`, source_file: row.file };
+    const node = findNode(nodes, row.file, row.method);
+    if (node)
+        surface.handler_symbol = node.id;
+    surface.handler_label = `${row.file}#${row.method}`;
+    return surface;
+}
 // The link is *searched for*, never spelled. graphify names its node ids by an
 // internal rule, it is a third-party package (`pip install graphifyy`), and that
 // rule may change in any release. Rebuilding the rule here would make us

package/dist/verbs/putMapBuild.js

@@ -47,7 +47,7 @@ function refuseAlteredAddresses(inventoryPath, surfaces) {
         return; // no router was asked; there is nothing to hold the answer to
     if (!existsSync(inventoryPath)) {
         throw new Error(`${inventoryPath} is named by the build request but is not there. Run \`unitbob map-prepare\` ` +
-            'again so the addresses come from the router, then rebuild the surface map.');
+            'again so the addresses come from the router (or, on Next.js, the file routing), then rebuild the surface map.');
     }
     let inventory = null;
     try {

package/dist/verbs/suitePrepare.js

@@ -12,7 +12,7 @@ import { alignRunnerEnvironmentWithPlace } from "../runner/placeEnvironment.js";
 import { ensureRunner, ensureStructuralRunner } from "../runner/provision.js";
 import { ToolchainUnavailableError } from "../runner/toolchain.js";
 import { canPrepareBeforeImports, setupFileOf, STRUCTURAL_SETUP_FILE } from "../runner/vitest.js";
-import { probeBehavioralWorld } from "../runner/worldProbe.js";
+import { probeWorld, worldIsProbed } from "../runner/worldProbe.js";
 import { Wire } from "../wire.js";
 // The complete envelope for one branch, or null when this machine cannot
 // produce one: the server offered no combination this stack matches, or the
@@ -72,7 +72,7 @@ export async function suitePrepare(config, args = [], deps) {
         bootCheck: (projectRoot, runner, sourceFiles) => bootCheck(projectRoot, runner, sourceFiles),
         ensureRunner: deps?.ensureRunner ?? ensureRunner,
         ensureStructuralRunner: deps?.ensureStructuralRunner ?? ensureStructuralRunner,
-        worldProbe: deps?.worldProbe ?? probeBehavioralWorld,
+        worldProbe: deps?.worldProbe ?? probeWorld,
         runnerEnvelope: runnerEnvelopeFor,
         stdout: process.stdout,
         ...deps,
@@ -185,14 +185,16 @@ export async function suitePrepare(config, args = [], deps) {
                 continue;
             }
             // Every BDD runner with a connector-owned harness gets it here, before its
-            // branch is offered to the host (spec 35-1). Only Ruby is probed by
-            // running it: the Ruby World integrates deeply with Rails, and the probe
-            // needs an application to integrate with. The JS and Python harnesses do
-            // one thing — refuse connections that leave the machine — and their
-            // guards are executed for real in the connector's own suite.
+            // branch is offered to the host (spec 35-1). A World that opens a door
+            // into the application is probed by running it — Ruby's, which
+            // integrates deeply with Rails, and Next's, which starts the application
+            // (spec 56-1) — because the probe needs the application to answer. A
+            // harness that only refuses connections leaving the machine (JS
+            // elsewhere, Python) has nothing on the project to probe; its guard is
+            // executed for real in the connector's own suite.
             materializeBehavioralWorld(config.projectRoot, runner);
-            if (runner === 'cucumber') {
-                const probe = await actual.worldProbe(config.projectRoot);
+            if (worldIsProbed(config.projectRoot, runner)) {
+                const probe = await actual.worldProbe(config.projectRoot, runner);
                 if (probe.status === 'fixable') {
                     fixableNotices.push(`  Behavioral World profile is not ready (fixable): ${probe.message ?? 'probe failed'}`);
                     continue;
@@ -293,7 +295,15 @@ export async function suitePrepare(config, args = [], deps) {
     const bootAdvisories = [];
     const structuralIndex = branches.findIndex((branch) => branch.suite_kind === 'structural');
     if (structuralIndex !== -1) {
-        const boot = await actual.bootCheck(config.projectRoot, structuralRunner, structuralSourceFiles(config.projectRoot, { branches }));
+        const sources = structuralSourceFiles(config.projectRoot, { branches }, structuralRunner);
+        // Spec 55-1, §1. Said before the probe's answer and before "Next:", in the
+        // vibecoder's terms: these files are in the map and not in this suite.
+        if (sources.leftOut.length > 0) {
+            const count = sources.leftOut.length;
+            actual.stdout.write(`${count} ${count === 1 ? 'file' : 'files'} the map names ${count === 1 ? 'is' : 'are'} not ${structuralRunner} ` +
+                `and ${count === 1 ? 'was' : 'were'} left out of the code-structure suite: ${sources.leftOut.join(', ')}\n`);
+        }
+        const boot = await actual.bootCheck(config.projectRoot, structuralRunner, sources.files);
         if (boot.status === 'broken') {
             if (!canPrepareBeforeImports(structuralRunner) || setupFileOf(config.projectRoot)) {
                 branches.splice(structuralIndex, 1);
@@ -325,7 +335,7 @@ export async function suitePrepare(config, args = [], deps) {
     //
     // Not written into `request.json`: the coordinator reads that file whole and
     // pays for it on every turn of the longest-lived context in the run.
-    const sourcePackets = buildPackets(config.projectRoot, request);
+    const sourcePackets = buildPackets(config.projectRoot, request, structuralRunner);
     // A new request is a new build, and a new build has no previous run to be
     // stuck against (spec 34-6, criterion 3). Re-running this verb is a documented
     // step of the loop, so a failure set remembered from the build before it would
@@ -432,9 +442,9 @@ function displacedList(moved) {
 // failed build: the workers search the source themselves, exactly as they did
 // before this spec. The same rule the route inventory follows for the same
 // reason — a read-only checkout or a full disk must not take a build down.
-function buildPackets(projectRoot, request) {
+function buildPackets(projectRoot, request, runner) {
     try {
-        return writeSuitePackets(projectRoot, request);
+        return writeSuitePackets(projectRoot, request, runner);
     }
     catch (err) {
         return err.message;
@@ -535,18 +545,24 @@ function bootAdvisory(boot, runner) {
 // is not something a setup file can prepare its way around, and sending someone
 // to write one would waste the round it costs.
 function bootReport(boot, runner, prepared) {
-    const next = boot.cause !== 'defect_in_code'
-        ? 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
-            'it never writes to your project. Something outside that file is still missing here. Run the ' +
-            'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
-            'then run `unitbob suite-prepare` again.'
-        : prepared
-            ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
-            : `This is what these files do with nothing in front of them, and the run will have ` +
-                `${STRUCTURAL_SETUP_FILE} in front of them. Put into that file whatever has to happen before the ` +
-                'first import — the environment variables the modules read, a loader registration, and only as a ' +
-                'last resort an entry through the project\'s root module — then run `unitbob suite-prepare` again ' +
-                'and this same question will be asked through it.';
+    // Spec 55-1, §1. The third cause is ours: vite stopped on a file our own list
+    // handed it. Not a repair and not an install — the sentence repo 139 got
+    // twice, over a `.py` the map had named.
+    const next = boot.cause === 'harness'
+        ? 'This is a hole in the list of files Unitbob resolved for the map, not in your code — ' +
+            `${boot.file}. Report it; nothing to repair here.`
+        : boot.cause !== 'defect_in_code'
+            ? 'Unitbob installs the runner, and your declared dependencies with it, into `.unitbob/runners/` — ' +
+                'it never writes to your project. Something outside that file is still missing here. Run the ' +
+                'install your project needs (`bundle install`, `npm install`, `pip install -r requirements.txt`), ' +
+                'then run `unitbob suite-prepare` again.'
+            : prepared
+                ? 'Repair it and run `unitbob suite-prepare` again to build this branch.'
+                : `This is what these files do with nothing in front of them, and the run will have ` +
+                    `${STRUCTURAL_SETUP_FILE} in front of them. Put into that file whatever has to happen before the ` +
+                    'first import — the environment variables the modules read, a loader registration, and only as a ' +
+                    'last resort an entry through the project\'s root module — then run `unitbob suite-prepare` again ' +
+                    'and this same question will be asked through it.';
     // `boot.message` is the runner's own words, indented but never paraphrased:
     // this is the line the vibecoder can paste into a search.
     return `  ${boot.message}\n\n${boot.detail}\n\n  ${next}${caveatFor(runner, '  ')}\n`;