staysfixed 0.12.0 → 0.14.0

package/src/v2/adapters/source.js

@@ -532,10 +532,27 @@ export function readFile(relFile, text) {
   // Command-line flags. These are a mention, not a proof — a string that looks like a flag
   // may be one this program accepts or one it passes on to something else. It gets its own
   // wording so nobody mistakes the two.
-  for (const token of tokens) {
-    if (token.t === 'string' && /^--[a-z0-9][a-z0-9-]*$/i.test(token.v)) {
-      doors.push(door('command', token.v, 'a flag this file mentions', relFile, token.line, inTest, true, 'literal'));
-    }
+  //
+  // A CSS CUSTOM PROPERTY IS NOT A FLAG. `style={{ '--px': '1rem' }}` is a component setting
+  // its own spacing, and it was read here as a command-line flag this program accepts.
+  // Measured 2026-08-31 on a real site: eleven of them became doors, padding the denominator
+  // of the coverage ledger with eleven things no journey can ever walk, so a site whose real
+  // coverage was good read as worse than it was and the real never-opened doors sat in a list
+  // of invented ones.
+  //
+  // An object key is what tells them apart, and it is decided by BOTH neighbours, not one. A
+  // key is a string with a colon after it AND an opening brace or a comma in front of it.
+  // Checking only the colon would also throw away `cond ? '--verbose' : '--quiet'`, where the
+  // first branch has a colon after it too — and dropping a real flag is the wrong mistake to
+  // make here: an invented door makes the ledger read worse than the truth, a missing one
+  // makes it read better, and only one of those two can end in somebody believing a clean
+  // result they should not have.
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (token.t !== 'string' || !/^--[a-z0-9][a-z0-9-]*$/i.test(token.v)) continue;
+    const isAKey = tokens[i + 1]?.v === ':' && (tokens[i - 1]?.v === '{' || tokens[i - 1]?.v === ',');
+    if (isAKey) continue;
+    doors.push(door('command', token.v, 'a flag this file mentions', relFile, token.line, inTest, true, 'literal'));
   }
 
   // A server written straight on node:http registers nothing. There is no `app.get` for the
@@ -1285,6 +1302,19 @@ async function collectFiles(root, folders, maxFileBytes) {
 // Routes that live in the filesystem rather than in a call
 // ---------------------------------------------------------------------------
 
+/**
+ * What each Next.js metadata file is actually served at. The file is named for what it is;
+ * the address it answers on is a different word, and asking for the file's own name gets a
+ * 404 — which would then be reported as a route the build has lost.
+ */
+const SERVED_AS = /** @type {Record<string, string>} */ ({
+  sitemap: 'sitemap.xml',
+  robots: 'robots.txt',
+  manifest: 'manifest.webmanifest',
+  'opengraph-image': 'opengraph-image',
+  icon: 'icon',
+});
+
 /**
  * Every route that is not written as a call in JavaScript.
  *
@@ -1292,6 +1322,14 @@ async function collectFiles(root, folders, maxFileBytes) {
  * Both layouts are handled: an app folder, where a `route` file's exported method names are
  * the verbs, and a pages/api folder, where the file itself is the route.
  *
+ * SO DO THE OTHERS, AND UNTIL 2026-08-31 ONLY NEXT.JS WAS READ. Measured that day on a
+ * three-page SvelteKit site with an endpoint and a form in it: "0 routes". Not "we could not
+ * read them" — zero, printed as a fact, in a report that then called the site covered in
+ * full. SvelteKit writes an endpoint as `+server.ts` and a form handler as an `actions`
+ * export in `+page.server.ts`; Nuxt puts its under `server/api`; Astro puts its beside the
+ * pages in `src/pages`. Every one of those is a door somebody can knock on, and a door this
+ * tool cannot see is a door it cannot notice disappearing.
+ *
  * Python's routes are read here too, and this is the reason they are read HERE rather than
  * somewhere of their own: five places in this tool ask for routes, and four of them would
  * have had to be found and changed. A Flask app that had routes in one of them and none in
@@ -1341,7 +1379,40 @@ export async function readFileRoutes(root) {
 
   for (const appDir of ['app', 'src/app']) {
     await walk(path.join(root, appDir), async (rel, full) => {
-      if (!/(^|\/)route\.[cm]?[jt]sx?$/.test(rel.split(path.sep).join('/'))) return;
+      // METADATA FILES ARE ROUTES, and they were invisible. A Next.js site serves
+      // `/sitemap.xml` and `/robots.txt` from `app/sitemap.ts` and `app/robots.ts`, and this
+      // reader knew about neither, so neither was a door and no journey ever asked for either.
+      // Measured 2026-08-31 on a real site: two entries were deleted out of the sitemap and the
+      // run reported nothing whatever. A sitemap is how a search engine finds a product, so a
+      // sitemap that silently stops listing half of it is exactly the kind of break that is
+      // never noticed until the traffic has already gone.
+      //
+      // The file's name decides the address it is served at, and the folder it sits in decides
+      // what comes in front of that — the same rule as `route.ts`, so route groups in brackets
+      // and private folders starting with an underscore drop out the same way. `twitter-image`
+      // and `apple-icon` work identically and are left out only because nothing has measured
+      // them; adding one is adding a line to this list.
+      const asPosix = rel.split(path.sep).join('/');
+      const metadata = /(^|\/)(sitemap|robots|manifest|opengraph-image|icon)\.[cm]?[jt]sx?$/.exec(asPosix);
+      if (metadata) {
+        const under = '/' + path.dirname(rel)
+          .split(path.sep)
+          .filter((one) => one !== '.' && !(one.startsWith('(') && one.endsWith(')')) && !one.startsWith('_'))
+          .join('/');
+        const prefix = under === '/' ? '' : under.replace(/\/$/, '');
+        doors.push({
+          kind: 'route',
+          name: `${prefix}/${SERVED_AS[metadata[2]]}`,
+          detail: 'GET',
+          file: path.relative(root, full),
+          line: 1,
+          inTest: false,
+          named: true,
+          via: 'a Next.js metadata file',
+        });
+        return;
+      }
+      if (!/(^|\/)route\.[cm]?[jt]sx?$/.test(asPosix)) return;
       // A folder in brackets is a grouping, not part of the address; one starting with an
       // underscore is private and is not routed at all.
       const url = '/' + path.dirname(rel)
@@ -1366,7 +1437,12 @@ export async function readFileRoutes(root) {
     });
   }
 
-  for (const pagesDir of ['pages/api', 'src/pages/api']) {
+  // Astro keeps its endpoints in `src/pages` too, and an Astro project with an `api` folder in
+  // there would otherwise have every endpoint counted twice — once as a Next.js api route with
+  // the verb unknown, once as an Astro endpoint with the verb read. Two doors where there is
+  // one is the same lie as none where there is one, told the other way round.
+  const astro = await looksLikeAstro(root);
+  for (const pagesDir of astro ? ['pages/api'] : ['pages/api', 'src/pages/api']) {
     await walk(path.join(root, pagesDir), async (rel, full) => {
       if (!/\.[cm]?[jt]sx?$/.test(rel)) return;
       const stem = rel.replace(/\.[cm]?[jt]sx?$/, '').split(path.sep).join('/');
@@ -1378,6 +1454,114 @@ export async function readFileRoutes(root) {
     });
   }
 
+  // ── SvelteKit ─────────────────────────────────────────────────────────────
+  // `+server.ts` answers requests on the address of the folder it sits in, and the functions
+  // it exports are the verbs — exactly the same idea as a Next.js `route.ts`, spelled
+  // differently. `+page.server.ts` is not an endpoint, but an `actions` export in one IS: it
+  // is where every form on that page posts to, which makes it one of the busiest doors in a
+  // SvelteKit app and the one most worth noticing the disappearance of.
+  for (const routesDir of ['src/routes', 'routes']) {
+    let anyHere = false;
+    await walk(path.join(root, routesDir), async (rel, full) => {
+      const posix = rel.split(path.sep).join('/');
+      const name = posix.split('/').pop() ?? '';
+      const endpoint = /^\+server\.[cm]?[jt]s$/.test(name);
+      const pageServer = /^\+page(@[^.]*)?\.server\.[cm]?[jt]s$/.test(name);
+      if (!endpoint && !pageServer) return;
+      const url = '/' + posix.split('/').slice(0, -1)
+        .filter((s) => s !== '.' && !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'))
+        .join('/');
+      /** @type {string[]} */
+      let verbs = [];
+      try {
+        const reading = readFile(path.relative(root, full), await fsp.readFile(full, 'utf8'));
+        const named = reading.doors
+          .filter((d) => d.kind === 'export' && typeof d.name === 'string')
+          .map((d) => String(d.name));
+        if (endpoint) {
+          verbs = named.filter((n) => /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|fallback)$/.test(n));
+          // An endpoint file that exports nothing readable is still an endpoint. Reporting no
+          // door at all because the verbs would not parse is the failure this whole file
+          // exists to prevent.
+          if (verbs.length === 0) verbs = ['ANY'];
+        } else if (named.includes('actions')) {
+          verbs = ['POST'];
+        }
+      } catch {
+        if (endpoint) verbs = ['ANY'];
+      }
+      if (verbs.length === 0) return;
+      anyHere = true;
+      for (const verb of verbs) {
+        doors.push({
+          kind: 'route', name: url === '/' ? '/' : url.replace(/\/$/, ''), detail: verb,
+          file: path.relative(root, full), line: 1, inTest: false, named: true,
+          via: 'the folder it lives in',
+        });
+      }
+    });
+    // A project has one routes folder, not two. Stopping after the one that had something in
+    // it keeps a stray top-level `routes/` from being read as a second copy of the site.
+    if (anyHere) break;
+  }
+
+  // ── Nuxt ──────────────────────────────────────────────────────────────────
+  // Nuxt names the verb in the filename — `login.post.ts` is a POST — and serves `server/api`
+  // under `/api` while `server/routes` is served at the top level.
+  //
+  // Only read when the project says it is Nuxt, and that gate is not caution for its own sake.
+  // `server/api/orders.js` is an ordinary place to keep an Express handler, and that file
+  // already has its real route read out of the `router.get(...)` call inside it. Walking the
+  // folder as well would invent a second address beside the true one — two doors reported
+  // where one exists, which makes the door count a thing nobody can trust.
+  const nuxt = await looksLikeNuxt(root);
+  for (const [serverDir, prefix] of /** @type {[string, string][]} */ (nuxt ? [
+    ['server/api', '/api'], ['server/routes', ''], ['src/server/api', '/api'], ['src/server/routes', ''],
+  ] : [])) {
+    await walk(path.join(root, serverDir), async (rel, full) => {
+      if (!/\.[cm]?[jt]s$/.test(rel)) return;
+      const stem = rel.replace(/\.[cm]?[jt]s$/, '').split(path.sep).join('/');
+      const verbInName = stem.match(/\.(get|post|put|patch|delete|head|options)$/i);
+      const cleaned = (verbInName ? stem.slice(0, -verbInName[0].length) : stem).replace(/\/?index$/, '');
+      doors.push({
+        kind: 'route', name: `${prefix}/${cleaned}`.replace(/\/{2,}/g, '/').replace(/(.)\/$/, '$1') || '/',
+        detail: verbInName ? String(verbInName[1]).toUpperCase() : 'ANY',
+        file: path.relative(root, full), line: 1, inTest: false, named: true,
+        via: 'the folder it lives in',
+      });
+    });
+  }
+
+  // ── Astro ─────────────────────────────────────────────────────────────────
+  // Astro keeps its endpoints in the same folder as its pages, and tells them apart by
+  // extension alone: `.astro` is a page, and a plain `.ts` beside it is an endpoint whose
+  // exported function names are the verbs. Only read when the project says it is Astro,
+  // because that same folder belongs to the Next.js pages router in other projects and a
+  // page read as an endpoint would be counted twice.
+  if (astro) {
+    await walk(path.join(root, 'src/pages'), async (rel, full) => {
+      const posix = rel.split(path.sep).join('/');
+      if (!/\.[cm]?[jt]s$/.test(posix) || /\.d\.[cm]?ts$/.test(posix)) return;
+      const stem = posix.replace(/\.[cm]?[jt]s$/, '').replace(/\/?index$/, '');
+      /** @type {string[]} */
+      let verbs = ['ANY'];
+      try {
+        const reading = readFile(path.relative(root, full), await fsp.readFile(full, 'utf8'));
+        const named = reading.doors
+          .filter((d) => d.kind === 'export' && typeof d.name === 'string' && /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS|ALL)$/.test(String(d.name)))
+          .map((d) => String(d.name));
+        if (named.length > 0) verbs = named;
+      } catch { /* an unreadable endpoint is still an endpoint */ }
+      for (const verb of verbs) {
+        doors.push({
+          kind: 'route', name: `/${stem}`.replace(/(.)\/$/, '$1'), detail: verb,
+          file: path.relative(root, full), line: 1, inTest: false, named: true,
+          via: 'the folder it lives in',
+        });
+      }
+    });
+  }
+
   const python = await readPythonRoutes(root);
   doors.push(...python.doors);
   problems.push(...python.problems);
@@ -1385,6 +1569,53 @@ export async function readFileRoutes(root) {
   return { doors, problems };
 }
 
+/**
+ * Is this a Nuxt project?
+ *
+ * Same reason as {@link looksLikeAstro}, for a different folder: `server/api` is Nuxt's
+ * routing and also an ordinary place to keep an Express handler, and only one of those two
+ * turns a filename into an address.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+async function looksLikeNuxt(root) {
+  for (const name of ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs']) {
+    if (fs.existsSync(path.join(root, name))) return true;
+  }
+  try {
+    const pkg = JSON.parse(await fsp.readFile(path.join(root, 'package.json'), 'utf8'));
+    const deps = { ...pkg?.dependencies, ...pkg?.devDependencies };
+    return 'nuxt' in deps || 'nuxt3' in deps || 'nuxt-edge' in deps;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is this an Astro project?
+ *
+ * It matters for one reason only: `src/pages/thing.ts` is a server endpoint in Astro and a
+ * whole page in the Next.js pages router, and the two folders are spelled identically. Read
+ * the wrong way, a page gets counted as a door it is not, or a door goes unseen. package.json
+ * settles it, and an `astro.config` file settles it for a project that has not installed
+ * anything yet.
+ *
+ * @param {string} root
+ * @returns {Promise<boolean>}
+ */
+async function looksLikeAstro(root) {
+  for (const name of ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts']) {
+    if (fs.existsSync(path.join(root, name))) return true;
+  }
+  try {
+    const pkg = JSON.parse(await fsp.readFile(path.join(root, 'package.json'), 'utf8'));
+    return 'astro' in { ...pkg?.dependencies, ...pkg?.devDependencies };
+  } catch {
+    return false;
+  }
+}
+
 /**
  * The commands a package installs and the entries it exports, straight out of its own
  * package.json. Exact, because npm reads the same field.
@@ -1625,7 +1856,23 @@ export const sourceAdapter = defineAdapter({
    * @param {import('./contract.js').PreparedBuild} build
    */
   async run(journey, build) {
-    const reading = await readContract({ root: build.root });
+    // THE FOLDERS THE JOURNEY NAMES, not the guessed ones.
+    //
+    // This walk read the project's source with no folders at all, so it fell back to the
+    // built-in guess — src, lib, app, bin, server, pages, api, electron, main, packages —
+    // while `journeys()` three functions above had already worked out the real list from the
+    // settings and written it into the step. Measured 2026-08-31 on a real Next.js site: the
+    // contract channel recorded 24 observations against 25 doors and never saw `format`,
+    // `slugify` or `emptyCart`, because they live in a folder the guess does not name.
+    //
+    // This is the worst shape a hole in this tool can take. The contract channel exists for
+    // exactly one job — noticing that an exported function has disappeared — and for every
+    // export outside the guessed folders it was not doing that job, silently, on every run,
+    // while the run reported a clean result. The step already carries the answer.
+    const reading = await readContract({
+      root: build.root,
+      folders: Array.isArray(journey.steps?.[0]?.folders) ? journey.steps[0].folders : undefined,
+    });
     const fileRoutes = await readFileRoutes(build.root);
     reading.doors.push(...fileRoutes.doors);
     // A folder the route walk could not open is a hole in the door list, and the door list is

package/src/v2/adapters/web.js

@@ -43,7 +43,7 @@ import path from 'node:path';
 
 import {
   countBucket, defineAdapter, howLongItTook, joinPath, notCovered, observation, sizeBucket,
-  timeBucket, trimForStorage, undoOurFootprint,
+  timeBucket, trimForStorage, undoOurFootprint, whatItSaid,
 } from './contract.js';
 import { copyForScratch, frozenEnvironment } from './process.js';
 import { freePort, looksDestructive, waitForServer } from './http.js';
@@ -298,7 +298,16 @@ export function journeysFrom(input) {
       surface: 'web',
       from: page.file,
       channels: ['meaning', 'effects', 'complaints', 'results', 'counters', 'pixels'],
-      steps: /** @type {any} */ ([{ act: 'open', goto: url, note: `open ${page.url}`, unfilled }]),
+      // `door`, `kind` and `doorDetail` are how the coverage ledger learns that this journey
+      // walked that page. Without them a page counted as opened only if an observation happened
+      // to land at the page's own address, and this adapter writes everything under
+      // `screen.<journey name>` — so every page of every site read as never walked, on runs
+      // that had just opened all of them. The HTTP adapter has named its doors this way since
+      // it was written; this is the same three fields, for the same reason. A page is reached
+      // by asking for its address, so the verb is GET.
+      steps: /** @type {any} */ ([
+        { act: 'open', goto: url, note: `open ${page.url}`, unfilled, door: page.url, kind: 'route', doorDetail: 'GET' },
+      ]),
     });
   }
 
@@ -578,11 +587,20 @@ export const webAdapter = defineAdapter({
     });
     if (!up.up) {
       await stopServer(child);
+      // The app's own words go first, ahead of the wait's account of which loopback address it
+      // knocked on. Same measurement, same date as the HTTP adapter's copy of this: the reason
+      // a site will not boot is one line the runtime printed, the sentence built from this is
+      // trimmed to 160 characters where a person reads it, and anything after the first
+      // sentence was therefore never seen by anybody.
+      const printed = Buffer.concat(said).toString('utf8');
+      const headline = whatItSaid(printed, { mostLines: 1 });
       return {
         build,
         root: work,
         ready: false,
-        why: `${up.why} What it printed while trying: ${trimForStorage(Buffer.concat(said).toString('utf8'), 1500).text || '(nothing)'}`,
+        why: `${headline ? `It said: ${headline}. ` : ''}${up.why} What it printed while trying, in full: ${
+          trimForStorage(printed, 1500).text || '(nothing)'
+        }`,
         dispose: async () => {
           await stopServer(child);
           await fsp.rm(base, { recursive: true, force: true });
@@ -984,10 +1002,34 @@ async function lookAt(input) {
 export function describeTraffic(journey, calls, footprint) {
   /** @type {Observation[]} */
   const out = [];
+  /** Addresses that only exist because of a request WE cancelled. See below. */
+  const ourOwnFootprint = [];
   for (const call of calls) {
     const asked = `${call.method} ${call.pattern}`;
     const where = joinPath('net', journey.name, asked);
 
+    // A REQUEST OUR OWN TEARDOWN CANCELLED IS NOT PART OF THE PRODUCT'S ADDRESS LIST.
+    //
+    // Next.js starts a prefetch behind every internal link, on its own, with nobody asking.
+    // Closing the page cancels whatever is still in flight. Whether a given prefetch got far
+    // enough to become a call at all is therefore a race between it and our own teardown — so
+    // the ADDRESSES it produces exist on one pass of a build and not on the other. Measured
+    // 2026-08-31 across eight runs a side: with nothing timing out the total is 852 every time,
+    // and about 90 of those 852 — roughly one in nine — were reached by only one of the two
+    // passes. Two byte-identical passes disagreeing about which addresses exist is the
+    // measurement contradicting its own method.
+    //
+    // An earlier fix stopped these being reported as the product complaining, which killed the
+    // phantom findings; it could not stop them moving the count, because the address is still
+    // created on the pass that saw it. This is that fix taken one step further: the whole call
+    // contributes nothing, because none of it is a fact about the product — it is a fact about
+    // when we closed the browser. Nothing is dropped silently: how many there were, and which,
+    // is said in one observation at a fixed address at the end of this function.
+    if (call.unfinishedAtTeardown && !call.refused && !call.failed) {
+      ourOwnFootprint.push(asked);
+      continue;
+    }
+
     if (call.refused) {
       out.push(
         notCovered({
@@ -1045,22 +1087,6 @@ export function describeTraffic(journey, calls, footprint) {
           surface: 'web',
         }),
       );
-    } else if (call.unfinishedAtTeardown) {
-      // Missing coverage, not a complaint. The page was still asking for this when the walk
-      // ended, and the abort that followed is this tool closing the page — reporting it as
-      // the product failing made an unchanged tree look broken in four runs out of five.
-      // Recorded rather than dropped: something was being asked for and how it ended was
-      // never seen, which is a hole, and a hole is louder than a complaint, never quieter.
-      out.push(
-        notCovered({
-          channel: 'effects',
-          path: `${where}.how it finished`,
-          reason: 'refused',
-          says:
-            `The page was still asking for ${asked} when the walk ended, so how that finished was never seen. ` +
-            `The request was cancelled by this tool closing the page, which is not the product doing anything wrong.`,
-        }),
-      );
     }
     if (call.status !== undefined) {
       out.push(
@@ -1100,6 +1126,30 @@ export function describeTraffic(journey, calls, footprint) {
       );
     }
   }
+
+  // Said out loud, at ONE address that does not move, rather than at an address per request.
+  // The count and the list live in the sentence, which is never compared, so this can report a
+  // different number on two passes without ever reporting a difference. It is a hole, and it is
+  // named as one: something was being asked for and how it ended was never seen.
+  if (ourOwnFootprint.length > 0) {
+    const many = ourOwnFootprint.length !== 1;
+    out.push(
+      notCovered({
+        channel: 'effects',
+        path: joinPath('net', journey.name, 'requests still in flight when the walk ended'),
+        reason: 'refused',
+        says:
+          `${ourOwnFootprint.length} request${many ? 's were' : ' was'} still in flight when this walk ended, and ` +
+          `${many ? 'they were' : 'it was'} cancelled by this tool closing the page rather than by anything the ` +
+          `product did — a framework that prefetches behind every link starts these on its own. How ${many ? 'they' : 'it'} ` +
+          `would have finished was never seen: ${ourOwnFootprint.sort().slice(0, 8).join(', ')}` +
+          `${ourOwnFootprint.length > 8 ? `, and ${ourOwnFootprint.length - 8} more` : ''}. ` +
+          `Each one is kept out of the address list on purpose, because whether a cancelled request got far enough ` +
+          `to make an address is a race with our own teardown, and two passes of one build must not disagree about ` +
+          `which addresses exist.`,
+        }),
+    );
+  }
   return out;
 }