staysfixed 0.10.0 → 0.11.0

package/src/v2/coverage.js

@@ -48,7 +48,7 @@
 import { asAddress } from './adapters/electron.js';
 import { readContract, readFileRoutes, readPackageCommands } from './adapters/source.js';
 import { familyOf, irreversibility, isRunnable } from './journeys/from-routes.js';
-import { joinPath, splitPath } from './observation.js';
+import { CHANNELS, joinPath, splitPath } from './observation.js';
 import { listBuilds, listCaptures, loadCapture, referencePointer } from './store.js';
 
 /** @typedef {import('./types.js').Channel} Channel */
@@ -109,6 +109,10 @@ import { listBuilds, listCaptures, loadCapture, referencePointer } from './store
  *                                            Doors a step knocked on where the running build
  *                                            answered that they are not there. Knocking is not
  *                                            walking, and these have proved nothing.
+ * @property {string[]} [notTried]            Doors this journey's steps name, on a walk that
+ *                                            never happened — the adapter refused it and wrote
+ *                                            down only that. Nobody knocked, so nothing here
+ *                                            is walked.
  * @property {string[]} [doorAddresses]       Full door addresses, for steps that were specific
  *                                            enough to build one. A route step knows its verb,
  *                                            and GET /x and POST /x are two doors that share a
@@ -392,6 +396,14 @@ function asDoor(door) {
  * file: reading a door out of the source is how we know it exists, never evidence that
  * anybody opened it.
  *
+ * A refusal is dropped for the same reason. When an adapter cannot look at something it
+ * writes that down at the address it would have looked at, marked `refused` — a payment it
+ * would not make, a server that never started, a route with a parameter nobody supplied.
+ * Left in, the note saying "we did not look here" became the evidence that we did.
+ *
+ * Both still count in `byChannel`: they were written down, and the tallies say how much was
+ * written down. It is only the "somebody opened this door" set they are kept out of.
+ *
  * @param {Observation[]} observations
  * @returns {{paths: string[], byChannel: Partial<Record<Channel, number>>}}
  */
@@ -403,6 +415,7 @@ export function addressesTouched(observations) {
   for (const o of observations) {
     byChannel[o.channel] = (byChannel[o.channel] ?? 0) + 1;
     if (o.channel === 'contract') continue;
+    if (o.meta?.refused === true) continue;
     const parts = String(o.path).split('.');
     for (let i = 1; i <= parts.length; i++) paths.add(parts.slice(0, i).join('.'));
   }
@@ -435,6 +448,26 @@ export function walkFromCapture(capture, journey) {
     buildId: capture.build?.id,
     paths: touched.paths,
   };
+  // NOTHING WAS TRIED IS NOT A WALK.
+  //
+  // Every adapter has branches where it runs nothing and says so: the server never came up,
+  // the route has a `:id` nobody supplied a value for, the command spends money and there is
+  // nothing watching to stop it. Each one writes a single observation marked `refused` and
+  // returns. No `api.<door>.status` comes back, because no request went out.
+  //
+  // The status rule below reads a missing status as "it answered something we are happy
+  // with", so every one of those doors counted as walked. Measured 2026-08-31 with the HTTP
+  // adapter's own output: one route, one journey, the server never started, and the ledger
+  // came back doorsWalked 1 of 1 — full coverage of a product that had not been run — in the
+  // same report whose only line read "was not tried: It never started."
+  //
+  // A capture whose entire non-contract record is refusals is a walk that did nothing. Its
+  // steps opened nothing, and the doors they name are listed rather than dropped.
+  const seen = capture.observations ?? [];
+  const refusals = seen.filter((o) => o?.meta?.refused === true);
+  const anythingHappened = seen.some((o) => o?.channel !== 'contract' && o?.meta?.refused !== true);
+  const nothingWasTried = refusals.length > 0 && !anythingHappened;
+
   if (journey?.steps) {
     // Two lists, because a doorKey is kind and name only. That is right for an IPC channel or
     // an exported name, where the name IS the door; it is wrong for a route, where GET /basket
@@ -464,6 +497,8 @@ export function walkFromCapture(capture, journey) {
     const shut = [];
     /** @type {{door: string, status: number}[]} */
     const bounced = [];
+    /** @type {string[]} */
+    const untried = [];
     /** @param {any} s @returns {boolean} */
     const reallyWalked = (s) => {
       // The door is the ROUTE (`/reports`); the observation is addressed by method and route
@@ -474,6 +509,10 @@ export function walkFromCapture(capture, journey) {
         typeof s.method === 'string' && s.method ? `${s.method} ${s.door}` : null,
         String(s.door),
       ].filter(Boolean);
+      if (nothingWasTried) {
+        untried.push(String(keys[0] ?? s.door));
+        return false;
+      }
       const key = keys.find((k) => answered.has(/** @type {string} */ (k)));
       const code = key === undefined ? undefined : answered.get(/** @type {string} */ (key));
       // A redirect is real behaviour and it IS walked — but what you saw is the bounce, not the
@@ -492,6 +531,7 @@ export function walkFromCapture(capture, journey) {
     const byName = named.filter((s) => typeof s.doorDetail !== 'string' || s.doorDetail === '').filter(reallyWalked);
     if (shut.length > 0) walk.knockedShut = shut;
     if (bounced.length > 0) walk.onlyRedirected = bounced;
+    if (untried.length > 0) walk.notTried = untried;
     if (byName.length > 0) walk.doors = byName.map((s) => doorKey({ kind: String(s.kind), name: String(s.door) }));
     if (exact.length > 0) {
       walk.doorAddresses = exact.map((s) =>
@@ -561,6 +601,138 @@ function trimmedAddress(door) {
   return joinPath(['ipc', asAddress(door.name)]);
 }
 
+// ---------------------------------------------------------------------------
+// One order, every time
+// ---------------------------------------------------------------------------
+
+/**
+ * TWO IDENTICAL RUNS HAVE TO SAY THE SAME THING.
+ *
+ * This tool's whole method is running the same thing twice and subtracting what disagrees.
+ * A report that disagrees with itself between two identical runs is not untidy — it is the
+ * measurement contradicting the method, and a reader who spots it has no reason to believe
+ * the rest.
+ *
+ * It was doing exactly that. A capture id ends in three random bytes, deliberately, so two
+ * captures written inside the same second do not overwrite each other — and the store hands
+ * captures back in id order, so those random bytes decide which walk is read first. Measured
+ * 2026-08-31 on one unchanged product, three runs: help, the-code, the-code, help; then
+ * the-code, help, the-code, help; then help, the-code, the-code, help.
+ *
+ * Everything the ledger built in that order came out shuffled with it — which of two
+ * journeys got named as the evidence for a door, which six of eight shut doors got listed by
+ * name in the caveat, the order of the gaps, the key order of the tallies. So the walks are
+ * put in an order of the ledger's own before anything reads them, and that order is a
+ * function of what is IN each walk, never of when it arrived.
+ *
+ * @param {Walk[]} walks
+ * @returns {Walk[]}
+ */
+function inWalkOrder(walks) {
+  return [...walks]
+    .map((walk) => ({ walk, key: walkOrderKey(walk) }))
+    .sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
+    .map(({ walk }) => walk);
+}
+
+/**
+ * The whole of one walk, squeezed into a single sortable string.
+ *
+ * Every field that can reach the report is in here, so two walks only ever tie when they
+ * would produce the same words either way round. The addresses are the exception: a walk on
+ * a big product carries tens of thousands of them, and holding all of that in a sort key
+ * costs more than the ordering is worth. How many there are, plus a fingerprint of them,
+ * tells two walks apart just as well and stays one short string.
+ *
+ * @param {Walk} walk
+ * @returns {string}
+ */
+function walkOrderKey(walk) {
+  return [
+    walk.journey ?? '',
+    walk.at ?? '',
+    walk.buildId ?? '',
+    walk.source ?? '',
+    String((walk.paths ?? []).length),
+    digestOf(walk.paths ?? []),
+    (walk.doors ?? []).join('\u0001'),
+    (walk.doorAddresses ?? []).join('\u0001'),
+    (walk.knockedShut ?? []).map((d) => `${d.door}=${d.status}`).join('\u0001'),
+    (walk.onlyRedirected ?? []).map((d) => `${d.door}=${d.status}`).join('\u0001'),
+    (walk.notTried ?? []).join('\u0001'),
+    (walk.touchedFiles ?? []).join('\u0001'),
+    (walk.touchedFunctions ?? []).join('\u0001'),
+    String(walk.functionsNotListed ?? 0),
+  ].join('\u0000');
+}
+
+/**
+ * A short fingerprint of a list of strings. FNV-1a, written out rather than imported,
+ * because this file has no business opening a crypto library to decide a sort order.
+ *
+ * @param {string[]} items
+ * @returns {string}
+ */
+function digestOf(items) {
+  let hash = 0x811c9dc5;
+  for (const item of items) {
+    for (let i = 0; i < item.length; i++) {
+      hash ^= item.charCodeAt(i);
+      hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    hash ^= 0x0a;
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+/**
+ * Sort a list of pairs by the first of the two. Used wherever a caveat names only the first
+ * few of something: which few get named has to be decided by their names.
+ *
+ * @param {[string, unknown]} a
+ * @param {[string, unknown]} b
+ * @returns {number}
+ */
+function byFirst(a, b) {
+  return a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0;
+}
+
+/**
+ * The channel tallies written out in one fixed order — the channel list's own, not the order
+ * the observations happened to arrive in. Same reason as {@link inWalkOrder}: this object is
+ * printed by `--json`, and JSON keeps the order keys were added in.
+ *
+ * @param {Partial<Record<Channel, number>>} byChannel
+ * @returns {Partial<Record<Channel, number>>}
+ */
+function inChannelOrder(byChannel) {
+  /** @type {Record<string, number>} */
+  const out = {};
+  const held = /** @type {Record<string, number>} */ (byChannel);
+  for (const channel of CHANNELS) if (held[channel] !== undefined) out[channel] = held[channel];
+  // A channel this build of the tool has never heard of is still evidence somebody wrote
+  // down, and dropping it would make the report smaller than the run was.
+  for (const channel of Object.keys(held).sort()) if (out[channel] === undefined) out[channel] = held[channel];
+  return out;
+}
+
+/**
+ * Sort gaps into an order of their own. Only for gaps whose order carries no meaning — the
+ * ones read back out of stored captures, which arrive in whatever order the disk listed
+ * them. The gaps `toCoverage` builds are in rank order and are left exactly as they are.
+ *
+ * @param {CoverageGap[]} list
+ * @returns {CoverageGap[]}
+ */
+function inGapOrder(list) {
+  return [...list].sort((a, b) => {
+    const left = `${a.what}\u0000${a.why}\u0000${a.unlockedBy ?? ''}`;
+    const right = `${b.what}\u0000${b.why}\u0000${b.unlockedBy ?? ''}`;
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+}
+
 // ---------------------------------------------------------------------------
 // The ledger
 // ---------------------------------------------------------------------------
@@ -589,7 +761,7 @@ function trimmedAddress(door) {
 export function buildLedger(input) {
   /** @type {DoorEntry[]} */
   const entries = [];
-  const walks = input.walks.map((walk) => ({ walk, paths: new Set(walk.paths) }));
+  const walks = inWalkOrder(input.walks).map((walk) => ({ walk, paths: new Set(walk.paths) }));
 
   /** @type {Record<string, KindTally>} */
   const byKind = {};
@@ -684,7 +856,9 @@ export function buildLedger(input) {
   const shutDoors = new Map();
   for (const { walk } of walks) for (const d of walk.knockedShut ?? []) shutDoors.set(d.door, d.status);
   if (shutDoors.size > 0) {
-    const listed = [...shutDoors.entries()].slice(0, 6).map(([door, code]) => `${door} answered ${code}`).join(', ');
+    // Sorted, so which six get named is decided by their names and not by which capture the
+    // disk happened to hand back first. See `inWalkOrder` for why that was ever in doubt.
+    const listed = [...shutDoors.entries()].sort(byFirst).slice(0, 6).map(([door, code]) => `${door} answered ${code}`).join(', ');
     caveats.push(
       `${shutDoors.size} ${shutDoors.size === 1 ? 'door the code declares was' : 'doors the code declares were'} knocked on and answered as not being there (${listed}${shutDoors.size > 6 ? ', and more' : ''}). Knocking is not walking: nothing has been proved about ${shutDoors.size === 1 ? 'it' : 'them'}, and the source and the build that ran disagree about whether ${shutDoors.size === 1 ? 'it exists' : 'they exist'}.`,
     );
@@ -695,7 +869,20 @@ export function buildLedger(input) {
   if (bouncedDoors.size > 0) {
     const all = bouncedDoors.size >= Math.max(1, opened);
     caveats.push(
-      `${bouncedDoors.size} ${bouncedDoors.size === 1 ? 'door' : 'doors'} answered with a redirect rather than with ${bouncedDoors.size === 1 ? 'a page' : 'pages'} — ${[...bouncedDoors.entries()].slice(0, 5).map(([door, code]) => `${door} answered ${code}`).join(', ')}${bouncedDoors.size > 5 ? ', and more' : ''}. What was seen is the bounce, not what is behind it.${all ? ' EVERY door that answered did this, which is what a sign-in wall looks like from out here: this run has not been inside the product at all.' : ''}`,
+      `${bouncedDoors.size} ${bouncedDoors.size === 1 ? 'door' : 'doors'} answered with a redirect rather than with ${bouncedDoors.size === 1 ? 'a page' : 'pages'} — ${[...bouncedDoors.entries()].sort(byFirst).slice(0, 5).map(([door, code]) => `${door} answered ${code}`).join(', ')}${bouncedDoors.size > 5 ? ', and more' : ''}. What was seen is the bounce, not what is behind it.${all ? ' EVERY door that answered did this, which is what a sign-in wall looks like from out here: this run has not been inside the product at all.' : ''}`,
+    );
+  }
+  // A door whose journey was refused before anything ran. Nobody knocked on it, so it is not
+  // shut and it is not bounced — it is untouched, and the only wrong answer is to leave it
+  // out. This says the number out loud so nobody has to notice a door that quietly stopped
+  // being counted as walked.
+  /** @type {Set<string>} */
+  const untriedDoors = new Set();
+  for (const { walk } of walks) for (const door of walk.notTried ?? []) untriedDoors.add(door);
+  if (untriedDoors.size > 0) {
+    const listed = [...untriedDoors].sort().slice(0, 6).join(', ');
+    caveats.push(
+      `${untriedDoors.size} ${untriedDoors.size === 1 ? 'door was' : 'doors were'} never tried at all (${listed}${untriedDoors.size > 6 ? ', and more' : ''}). The journey that would have opened ${untriedDoors.size === 1 ? 'it' : 'them'} was refused before anything ran — the thing it needed did not start, or a value it needed was never supplied — and the reason is on the record beside it. ${untriedDoors.size === 1 ? 'It is' : 'They are'} counted here as never opened, because nothing knocked.`,
     );
   }
   if (input.doors.length === 0) {
@@ -719,8 +906,11 @@ export function buildLedger(input) {
     entries,
     byKind,
     journeys: new Set(walks.map(({ walk }) => walk.journey)).size,
-    byJourneySource,
-    byChannel: input.byChannel ?? {},
+    // Both of these are printed by `--json`, and JSON keeps the order keys were added in.
+    // Added in the order the walks arrived, they came out shuffled between two identical
+    // runs — see `inWalkOrder`. Written out in an order of their own, they do not.
+    byJourneySource: Object.fromEntries(Object.entries(byJourneySource).sort(byFirst)),
+    byChannel: inChannelOrder(input.byChannel ?? {}),
     captures: input.captures ?? walks.length,
     builds: input.builds ?? 0,
     caveats,
@@ -883,7 +1073,11 @@ export async function ledger(store, product, opts = {}) {
     captures,
     builds: wanted.length,
     caveats,
-    gaps: dedupeGaps(holes),
+    // These holes were collected build by build and capture by capture, in the order the
+    // store listed them — which is the order the random end of a capture id put them in.
+    // Nothing about one unreadable record makes it more urgent than another, so they go in
+    // an order of their own and two identical runs list them the same way round.
+    gaps: inGapOrder(dedupeGaps(holes)),
   });
 }
 
@@ -975,7 +1169,13 @@ export function gaps(led, opts = {}) {
     });
   }
 
-  const ranked = jobs.sort((a, b) => (b.rank === a.rank ? b.doors - a.doors : b.rank - a.rank));
+  // Whole families tie here routinely — ten folders of four unopened exports each score the
+  // same and hold the same number of doors — and a tie used to be settled by whichever came
+  // out of the map first. The family's own name settles it instead, so the list this file
+  // hands back is the same list every time and the cut at the end falls in the same place.
+  const ranked = jobs.sort(
+    (a, b) => b.rank - a.rank || b.doors - a.doors || (a.group < b.group ? -1 : a.group > b.group ? 1 : 0),
+  );
   if (ranked.length <= worst) return ranked;
 
   // The cut is real and it used to be invisible. `toCoverage` asks for eight jobs; a product

package/src/v2/detect.js

@@ -140,6 +140,24 @@ const PLATFORM_FOLDERS = [
 /** How many files the artifact and test sweeps will look at before giving up and saying so. */
 const MOST_FILES = 20_000;
 
+/**
+ * The folders a project's own code normally lives in. The same list the source reader falls
+ * back to, kept here so this file can say WHICH folders it asked for instead of leaving the
+ * reader to guess — see {@link whereTheCodeIs} for why that mattered.
+ */
+const USUAL_SOURCE_FOLDERS = ['src', 'lib', 'app', 'bin', 'server', 'pages', 'api', 'electron', 'main', 'packages'];
+
+/**
+ * Root-level files that are how a project is BUILT rather than what it ships. A packaging
+ * config sitting beside `src/` is no reason to read the whole repository; a `server.js`
+ * sitting beside `src/` is every reason.
+ */
+const ROOT_TOOLING_FILES = new Set([
+  'gulpfile.js', 'gulpfile.mjs', 'gulpfile.cjs', 'gruntfile.js', 'karma.conf.js',
+  'protractor.conf.js', 'gatsby-config.js', 'gatsby-node.js', 'gatsby-browser.js',
+  'gatsby-ssr.js', 'webpack.mix.js',
+]);
+
 /**
  * Folders that are never a product of their own: either the contract channel already read
  * them as part of the root product, or they hold work about the project rather than the
@@ -278,7 +296,11 @@ export async function detectProject(options = {}) {
   // The source read, once, for two answers — how many doors there are, and what the routes
   // are called. Reading Terminal Deck's 1,416 files twice because two functions each wanted
   // their own copy cost a second and a half of the two this whole detection takes.
-  const reading = readCode ? await readTheSource(root) : { doors: notRead(), routes: [], channels: [], envNames: [] };
+  // The folders are named here rather than left to the reader's own default, because the
+  // default reads `src/` and its cousins and NOTHING at the top level — see
+  // {@link whereTheCodeIs} for the server that went unread because of it.
+  const firstFolders = whereTheCodeIs(listing);
+  const reading = readCode ? await readTheSource(root, firstFolders) : { doors: notRead(), routes: [], channels: [], envNames: [] };
   const doors = reading.doors;
   const routes = reading.routes;
   const channels = reading.channels;
@@ -323,7 +345,7 @@ export async function detectProject(options = {}) {
       root, where: place.root, listing: local, pkg: place.pkg,
       // Doors and pages were read from the root, so they only describe the root. A
       // sub-package gets credited with them only when it IS the root.
-      doors: place.root === '.' ? doors : notRead(),
+      doors: place.root === '.' ? theRootsOwnDoors(doors, routes, members) : notRead(),
       pages: place.root === '.' ? pages : [],
       containers: place.root === '.' ? containers : { dockerfile: null, compose: null },
       scripts: place.pkg?.scripts ?? {},
@@ -354,6 +376,12 @@ export async function detectProject(options = {}) {
     for (const folder of listing.dirs) {
       if (SKIP_DIRS.has(folder) || folder.startsWith('.') || claimed.has(folder)) continue;
       if (members.some((m) => m.root === folder)) continue;
+      // Nor is a folder whose whole contents are already accounted for one level down. A
+      // monorepo's `apps/` is a shelf: every product in it was found, named and is being
+      // checked, and this warning would say the opposite in the plainest words on the page —
+      // "nothing in it is being checked" — about the two products directly above it.
+      const alreadyFound = (/** @type {string} */ p) => p.startsWith(`${folder}/`);
+      if (merged.some((p) => alreadyFound(p.where)) || members.some((m) => alreadyFound(m.root))) continue;
       // The root product's own source is not an unclaimed folder. These are the folders the
       // contract channel already read, plus the ones that are never a product on their own.
       if (ALREADY_COVERED.has(folder)) continue;
@@ -387,7 +415,7 @@ export async function detectProject(options = {}) {
     languages: await languagesIn(root),
     tests,
     scripts: scriptsOf(pkg?.scripts ?? {}),
-    ...(await theSourceAgain({ root, readCode, merged, listing, first: { doors, routes, channels, envNames } })),
+    ...(await theSourceAgain({ root, readCode, merged, listing, firstFolders, first: { doors, routes, channels, envNames } })),
     bulk: await measureBulk(root),
     pages,
     containers,
@@ -953,6 +981,94 @@ async function findMembers(root, globs, listing) {
   return members;
 }
 
+/**
+ * The doors that are the ROOT'S, once the ones belonging to sub-packages are handed back.
+ *
+ * The source is read once, from the top, which is what keeps this fast — but the routes it
+ * comes back with are the whole repository's, and the root is then judged on them. In a
+ * workspaces monorepo that made the root itself "the server", off the strength of routes
+ * written in `packages/api`: a shelf holding two packages, reported as a third product that
+ * ships nothing. `packages/api` was already in the list, correctly, one line above it.
+ *
+ * Only a clean sweep counts. The moment ONE route was read outside every member, the root has
+ * routes of its own and keeps the full count — losing a real server is far worse than listing
+ * a doubtful one, so the doubt goes that way. The route list is capped at 200 names, so this
+ * is a sample rather than a census on a repository with more than that; a root with routes of
+ * its own would have to contribute none of the first 200 to be missed, and its framework
+ * dependency or its own `server.js` says it is a server anyway.
+ *
+ * @param {ProjectShape['doors']} doors
+ * @param {ProjectShape['routes']} routes
+ * @param {{name: string, root: string}[]} members
+ * @returns {ProjectShape['doors']}
+ */
+function theRootsOwnDoors(doors, routes, members) {
+  if (members.length === 0 || routes.length === 0 || doors.route === 0) return doors;
+  const slashed = (/** @type {string} */ p) => p.split(path.sep).join('/');
+  const theirs = members.map((m) => slashed(m.root));
+  const inAMember = (/** @type {string} */ file) =>
+    theirs.some((their) => slashed(file).startsWith(`${their}/`));
+  if (!routes.every((one) => inAMember(one.file))) return doors;
+  return { ...doors, route: 0 };
+}
+
+/**
+ * Does the project keep code of its own at the top level, outside every folder below it?
+ *
+ * A repository whose whole server is one `server.js` beside `package.json` is completely
+ * normal, and it is the shape this file used to go blind on the moment somebody added a
+ * `src/` folder for something else.
+ *
+ * Only files that are the PRODUCT count. A build config, a declaration file and a test all
+ * sit at the top level of nearly every repository, and treating any of them as "the project
+ * keeps code up here" would make this true everywhere and so worth nothing.
+ *
+ * @param {{files: string[], dirs: string[]}} listing
+ * @returns {boolean}
+ */
+function rootHoldsItsOwnCode(listing) {
+  return listing.files.some((name) => {
+    if (!/\.[cm]?[jt]sx?$/.test(name)) return false;
+    if (name.startsWith('.')) return false;
+    if (/\.d\.[cm]?ts$/.test(name)) return false;              // a declaration describes, it opens nothing
+    if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(name)) return false;
+    if (/\.(config|conf)\.[cm]?[jt]sx?$/.test(name)) return false;
+    return !ROOT_TOOLING_FILES.has(name.toLowerCase());
+  });
+}
+
+/**
+ * Which folders to hand the source reader.
+ *
+ * THE FAILURE THIS EXISTS TO STOP, and it is the worst kind this tool has. The reader is
+ * pointed at a list of folders, and it reads THOSE and nothing else. So a project with its
+ * server in `server.js` at the top level and a `src/` folder holding anything at all had its
+ * server never opened: four routes read as zero, and every later question about them answered
+ * "nothing that worked has changed". A deleted route and a route that started returning 500
+ * both came back clean, exit 0. Measured on a four-route express server: 4 routes with no
+ * `src/` folder, 0 routes the moment an unrelated `src/` folder existed beside it.
+ *
+ * The reader can only be aimed at folders, never at single files, and the top-level files sit
+ * outside every folder there is. So when the project keeps code up there, the answer is the
+ * whole project — which is exactly what the reader already does for a project that has no
+ * `src/` at all. The two cases now behave the same way instead of one of them going silent.
+ *
+ * The cost of that is a wider read: an `examples/` folder gets opened too, and a route written
+ * in an example is counted. That is the right direction to be wrong in. An extra route makes a
+ * check ask for an address that answers 404 both times, which changes nothing and alarms
+ * nobody; a MISSING route makes the tool say "nothing that worked has changed" about a product
+ * whose orders endpoint has gone. Aiming the reader at single files would fix both, and that
+ * lives in `collectFiles` in the source adapter rather than here.
+ *
+ * @param {{files: string[], dirs: string[]}} listing
+ * @returns {string[]}   Folders to read. Empty means the reader falls back to the whole
+ *                       project, which is its own long-standing behaviour.
+ */
+function whereTheCodeIs(listing) {
+  if (rootHoldsItsOwnCode(listing)) return ['.'];
+  return USUAL_SOURCE_FOLDERS.filter((name) => listing.dirs.includes(name));
+}
+
 /**
  * Every door in the source, counted AND named, using the same reader the contract channel
  * uses so the number here and the number in a check can never disagree.
@@ -1951,6 +2067,40 @@ async function foreignServerIn(dir, sources, language) {
   return { yes: false, file: null, framework: null, readsPort: false };
 }
 
+/**
+ * Does this file belong to a package sitting INSIDE the folder being looked at?
+ *
+ * THE FAILURE THIS EXISTS TO STOP. Both server readings below open files three folders deep,
+ * which is right for a product folder and wrong for a shelf. In a workspaces monorepo it made
+ * `packages/api/src/server.js` count as evidence about `packages/` itself, and a folder that
+ * ships nothing at all was announced as "the server in packages/" with 0.8 confidence — a
+ * product that does not exist, sitting in the list beside four that do. The same file had
+ * already been read correctly one folder down, where it actually lives.
+ *
+ * A `package.json` on the way down is the line. Everything below it is that package's, and
+ * that package is looked at in its own right.
+ *
+ * @param {string} dir           The folder being asked about.
+ * @param {string} rel           A file inside it, relative to it.
+ * @param {Map<string, boolean>} seen   Answers already worked out, so one walk costs one look.
+ * @returns {boolean}
+ */
+function insideAnotherPackage(dir, rel, seen) {
+  const parts = rel.split(path.sep);
+  parts.pop();                                   // the filename itself is never a folder
+  let sofar = '';
+  for (const part of parts) {
+    sofar = sofar ? path.join(sofar, part) : part;
+    let itsOwn = seen.get(sofar);
+    if (itsOwn === undefined) {
+      itsOwn = fs.existsSync(path.join(dir, sofar, 'package.json'));
+      seen.set(sofar, itsOwn);
+    }
+    if (itsOwn) return true;
+  }
+  return false;
+}
+
 /**
  * Does a folder hold a server somebody wrote by hand, on node's own http module?
  *
@@ -1969,8 +2119,13 @@ async function foreignServerIn(dir, sources, language) {
  */
 async function handWrittenServerIn(dir) {
   const { files } = await readSome(dir, { most: 80, depth: 3 });
+  /** @type {Map<string, boolean>} */
+  const packagesInside = new Map();
   for (const one of files) {
     const where = one.rel.split(path.sep).join('/');
+    // Somebody else's package, read on the way past. It is a product in its own right and is
+    // found as one; borrowing its server for the folder above invents a second product.
+    if (insideAnotherPackage(dir, one.rel, packagesInside)) continue;
     // A server standing in a fixtures folder is a prop for somebody's test, not the product.
     // This tool's own repository has one, and without this line it reported ITSELF as a
     // server — which is exactly the kind of confident wrong answer that gets a tool switched
@@ -2007,8 +2162,13 @@ async function handWrittenServerIn(dir) {
  */
 async function looksLikeAServer(dir) {
   const { files } = await readSome(dir, { most: 60, depth: 3 });
+  /** @type {Map<string, boolean>} */
+  const packagesInside = new Map();
   for (const one of files) {
     if (/\.(test|spec)\.[cm]?[jt]sx?$/.test(one.rel)) continue;
+    // The same line as above: a socket opened inside a package of its own says nothing about
+    // the folder that package happens to sit in. `apps/` is not a server because `apps/api` is.
+    if (insideAnotherPackage(dir, one.rel, packagesInside)) continue;
     const listens = /\.listen\s*\(|createServer\s*\(|Deno\.serve\s*\(|Bun\.serve\s*\(|serve\s*\(\s*\{[^}]*port/.test(one.text);
     if (!listens) continue;
     const readsPort = /process\.env\.PORT|Deno\.env\.get\(\s*['"]PORT|env\.PORT/.test(one.text);
@@ -2291,7 +2451,13 @@ function startCommandFor(input) {
   // build. It takes the port as a flag, so nothing has to be downloaded to serve the files.
   if (build && script('preview') && (has('vite') || has('astro') || has('@sveltejs/kit'))) {
     return {
-      command: `${build} && ${script('preview')} -- --port $PORT --strictPort`,
+      // `--host 127.0.0.1` is not decoration. Measured on 2026-08-31 on an app scaffolded a
+      // minute earlier with `npm create vite@latest -- --template react-ts`: Vite ignores both
+      // the PORT and the HOST it is handed in the environment and binds the NAME `localhost`,
+      // which macOS resolves to the IPv6 loopback — so the site came up on `[::1]` and nothing
+      // whatever was listening on `127.0.0.1`. Naming the address makes the command land where
+      // the settings say it will, instead of wherever name resolution happens to put it.
+      command: `${build} && ${script('preview')} -- --port $PORT --strictPort --host 127.0.0.1`,
       kind: 'build-and-serve',
       why: 'It is built, and then the build is served by the tool that made it. That is what ships — a dev server serves unbundled source with a live-reload connection in every page, which is a second thing moving under the comparison.',
     };
@@ -2505,10 +2671,15 @@ function inGigabytes(bytes) {
  * @returns {Promise<string[]>}
  */
 async function proposeSourceFolders(root, products, listing) {
+  // Code at the top level belongs to no folder, and the reader only takes folders. So the
+  // settings this writes have to say "the whole project" rather than name a folder that would
+  // leave the project's own `server.js` unopened for good — the same silence
+  // {@link whereTheCodeIs} exists to stop, except written down and kept.
+  if (rootHoldsItsOwnCode(listing)) return ['.'];
+
   /** @type {Set<string>} */
   const folders = new Set();
-  const usual = ['src', 'lib', 'app', 'bin', 'server', 'pages', 'api', 'electron', 'main', 'packages'];
-  for (const name of usual) if (listing.dirs.includes(name)) folders.add(name);
+  for (const name of USUAL_SOURCE_FOLDERS) if (listing.dirs.includes(name)) folders.add(name);
 
   for (const product of products) {
     if (product.where === '.' || product.where === '') continue;
@@ -2772,14 +2943,16 @@ function plainly(items) {
  * @param {boolean} input.readCode
  * @param {Product[]} input.merged
  * @param {{files: string[], dirs: string[]}} input.listing
+ * @param {string[]} input.firstFolders   The folders the first read was actually given. Worked
+ *   out again from the usual list, this said "src was read" about a run that had in fact been
+ *   pointed at the whole project, and the whole project then got read a second time for nothing.
  * @param {{doors: ProjectShape['doors'], routes: ProjectShape['routes'], channels: ProjectShape['channels'], envNames: ProjectShape['envNames']}} input.first
  * @returns {Promise<{doors: ProjectShape['doors'], routes: ProjectShape['routes'], channels: ProjectShape['channels'], envNames: ProjectShape['envNames'], sourceFolders: string[]}>}
  */
 async function theSourceAgain(input) {
-  const { root, readCode, merged, listing, first } = input;
+  const { root, readCode, merged, listing, firstFolders, first } = input;
   const sourceFolders = await proposeSourceFolders(root, merged, listing);
-  const usual = ['src', 'lib', 'app', 'bin', 'server', 'pages', 'api', 'electron', 'main', 'packages'];
-  const alreadyRead = new Set(usual.filter((name) => listing.dirs.includes(name)));
+  const alreadyRead = new Set(firstFolders);
   const missed = sourceFolders.filter((folder) => !alreadyRead.has(folder));
   if (!readCode || missed.length === 0) return { ...first, sourceFolders };