unitbob 0.7.14 → 0.7.16

package/dist/runner/worldProbe.js

@@ -1,13 +1,35 @@
 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, NEXT_WORLD_BOOT_TIMEOUT_MS } 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 = {
-    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: PROVISION_TIMEOUT_MS }),
-}) {
+const defaultDeps = {
+    runCmd: (command, args, options) => runInProject(options.cwd, command, args, { env: options.env, timeoutMs: options.timeoutMs ?? PROVISION_TIMEOUT_MS }),
+};
+// What both probes leave to the run itself, said with every `ok`. The probe
+// loads the connector's World and its own two or three steps; the project's
+// `step_definitions/` — and any `Before` hook a coordinator writes there — are
+// first loaded by the suite. So a green probe means the door opens, not that
+// every hook behind it is sound.
+const LEFT_TO_THE_RUN = "It ran the connector's own steps only; your step_definitions/ and the hooks in them are first loaded by the suite itself.";
+// 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).
@@ -33,7 +55,7 @@ export async function probeBehavioralWorld(projectRoot, deps = {
             },
         });
         if (result.code === 0)
-            return { status: 'ok' };
+            return { status: 'ok', message: LEFT_TO_THE_RUN };
         const detail = [result.stdout, result.stderr].map((text) => text.trim()).filter(Boolean).join('\n') || `exit ${result.code}`;
         return { status: 'fixable', message: `The connector-owned Ruby/Cucumber World probe failed: ${detail}` };
     }
@@ -44,6 +66,91 @@ 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),
+            },
+            // The run gives `BeforeAll` this long to start Next (ADR 0001: the probe
+            // may be looser than the run, never stricter), plus one request through
+            // the door once it is open.
+            timeoutMs: NEXT_WORLD_BOOT_TIMEOUT_MS + PROVISION_TIMEOUT_MS,
+        });
+        if (result.code === 0)
+            return { status: 'ok', message: LEFT_TO_THE_RUN };
+        // 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,137 @@
+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)$/;
+export function nextAppRoutes(projectRoot) {
+    const appDir = nextAppDir(projectRoot);
+    const routing = { rows: [], unread: [] };
+    if (!appDir)
+        return routing;
+    walk(join(projectRoot, appDir), appDir.split(/[\\/]/).join('/'), [], routing);
+    routing.rows.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return routing;
+}
+function walk(dir, relative, segments, routing) {
+    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], routing);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const file = `${relative}/${entry.name}`;
+        if (PAGE_FILE.test(entry.name)) {
+            routing.rows.push({ verb: 'GET', path, file, method: 'default' });
+        }
+        else if (ROUTE_FILE.test(entry.name)) {
+            const text = readFileSync(join(dir, entry.name), 'utf8');
+            const verbs = exportedHttpMethods(text);
+            for (const verb of verbs)
+                routing.rows.push({ verb, path, file, method: verb });
+            // Whatever it declares itself, a file that re-exports has addresses this
+            // reading cannot see; the model finds them in the graph.
+            if (REEXPORTS_ALL.test(text))
+                routing.unread.push(file);
+        }
+    }
+}
+// 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 a file goes to
+// `NextRouting.unread` instead, and the recipe tells the model to find its
+// addresses in the graph and name that file as their `source_file`; that is
+// the one address the inventory check accepts beyond the inventory.
+const REEXPORTS_ALL = /^\s*export\s+\*/m;
+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,42 @@ 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, unread } = 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 } : {}),
+        // The files this reading could not see into (ADR 0001): named here so
+        // the sentence below and `inventoryProblems` both know the gap.
+        ...(unread.length > 0 ? { unread } : {}),
+        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 +92,11 @@ 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,
+        ...(document.unread ? { unread: document.unread.length } : {}),
     };
 }
 // One question, up to two environments. Everything that can be decided from the
@@ -122,8 +159,11 @@ 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` +
+            `${result.unread ? `; ${result.unread} route ${plural(result.unread, 'file re-exports its handlers and is', 'files re-export their handlers and are')} ` +
+                'listed under `unread` — their addresses are not in the inventory' : ''}. 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 +173,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 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 +204,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 +345,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
@@ -348,22 +414,29 @@ function findNode(nodes, file, action) {
 export function inventoryProblems(inventory, surfaces) {
     const declared = routeEntriesIn(inventory);
     if (declared === null) {
-        return ['the route inventory is not readable, so what the router declared cannot be confirmed'];
+        return ['the route inventory is not readable, so what the application declared cannot be confirmed'];
     }
     const written = routeEntriesIn(surfaces);
     if (written === null)
         return ['surfaces.json has no readable `surfaces` array'];
     const problems = [];
     const missing = [...declared.keys()].filter((id) => !written.has(id));
-    const invented = [...written.keys()].filter((id) => !declared.has(id));
+    // ADR 0001: the check is no stricter than the inventory's own claim. A file
+    // the inventory lists under `unread` is one it could not see into, so an
+    // address served by that file is the model's to add — and only that one.
+    const unread = unreadFilesIn(inventory);
+    const invented = [...written.keys()].filter((id) => !declared.has(id) && !unread.has(written.get(id)?.source_file));
     if (missing.length > 0) {
-        problems.push(`surfaces.json is missing ${missing.length} address the router declared: ${list(missing)}. ` +
+        problems.push(`surfaces.json is missing ${missing.length} address the inventory declared: ${list(missing)}. ` +
             'Copy every entry of the route inventory across unchanged.');
     }
     if (invented.length > 0) {
-        problems.push(`surfaces.json carries ${invented.length} route the router never declared: ${list(invented)}. ` +
-            'The router is the authority on what exists; an address it does not know is either a typo ' +
-            'in a copied id or invented.');
+        problems.push(`surfaces.json carries ${invented.length} route the inventory does not declare: ${list(invented)}. ` +
+            'The inventory is what the application declared about itself — its router\'s answer, or its route ' +
+            'files; an address it does not know is either a typo in a copied id or invented.' +
+            (unread.size > 0
+                ? ' The one exception is an address served by a route file listed under `unread`, with that file as its `source_file`.'
+                : ''));
     }
     // Two sentences rather than one, because the two kinds of rewrite are not the
     // same mistake and the person reading has to fix the right thing: one sends a
@@ -377,7 +450,7 @@ export function inventoryProblems(inventory, surfaces) {
     const relabelled = alteredFields(declared, written, LABEL_FIELDS);
     if (relabelled.length > 0) {
         problems.push(`surfaces.json reworded ${relabelled.length} handler_label: ${list(relabelled)}. ` +
-            'That name is what the router itself printed; the human names for the map are the ' +
+            'That name is what the inventory itself printed; the human names for the map are the ' +
             'capability titles in the next step, not this field.');
     }
     return problems;
@@ -407,6 +480,12 @@ function alteredFields(declared, written, fields) {
     }
     return altered;
 }
+// The `unread` list of a Next.js inventory, as a set; empty on a router's
+// inventory, which has no such list because a router declares all it serves.
+function unreadFilesIn(inventory) {
+    const unread = inventory?.unread;
+    return new Set(Array.isArray(unread) ? unread.filter((file) => typeof file === 'string') : []);
+}
 function routeEntriesIn(document) {
     const surfaces = document?.surfaces;
     if (!Array.isArray(surfaces))

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 {
@@ -59,7 +59,7 @@ function refuseAlteredAddresses(inventoryPath, surfaces) {
     const problems = inventoryProblems(inventory, surfaces);
     if (problems.length === 0)
         return;
-    throw new Error(`The routes in surfaces.json do not match the ones this project's router declared, so nothing ` +
+    throw new Error(`The routes in surfaces.json do not match the ones this project declared (its router's answer, or its route files), so nothing ` +
         `was uploaded and the previous map stays current:\n- ${problems.join('\n- ')}`);
 }
 // Spec 32-7, Task 1.11. The addresses are now a command's answer rather than the