@olomonhelpdesk2/helpdesk 0.1.4 → 0.1.5

package/helpdesk-capture.mjs

@@ -1,102 +1,4 @@
 #!/usr/bin/env node
-// core/capture/contract.ts
-var CAPTURE_CONTRACT = {
-  /** Same for every shot, so type is the same size across the whole set. */
-  viewport: { width: 1600, height: 1e3 },
-  /** Stills render at 2x → 3200x2000. */
-  stillScale: 2,
-  /** Clips at 1x; video is resampled downstream anyway. */
-  clipScale: 1,
-  /** Below this a frame is a failed shot rather than a small one. */
-  minStillWidth: 2300,
-  /**
-   * Clip length.
-   *
-   * A CAP rather than a target, and inherited from a marketing site's autoplay
-   * loop — which is not this product's constraint. A help-center clip showing a
-   * multi-step task may well want twenty seconds, so the window is the contract
-   * and the number is configurable.
-   */
-  clipSeconds: { min: 6, target: 9, max: 10 },
-  maxClipBytes: 2 * 1024 * 1024,
-  /** Everything renders as though it were this instant. */
-  pinnedClock: "2026-01-15T09:00:00.000Z",
-  /**
-   * And in this locale and this zone, set on the browser rather than inherited
-   * from whoever runs it, so a date on a screen reads the same from any machine.
-   *
-   * American English, because the products this documents are read in it: a
-   * frame showing "15/01/2026" beside an article written for an American
-   * reader is a screenshot of a product nobody uses.
-   */
-  locale: "en-US",
-  timezone: "UTC",
-  /**
-   * Injected before every shot. Necessary, not sufficient — see above.
-   */
-  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}"
-};
-var VISUAL_STABILITY = {
-  /** Gap between comparison frames. Short enough to be cheap, long enough to differ. */
-  intervalMs: 120,
-  /** Consecutive identical frames required. */
-  identicalFrames: 2,
-  /** Give up rather than hang; a page that never settles is a finding. */
-  timeoutMs: 1e4
-};
-function pngSize(bytes) {
-  const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
-  if (bytes.length < 24) return void 0;
-  if (SIGNATURE.some((byte, index) => bytes[index] !== byte)) return void 0;
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
-  return { width: view.getUint32(16), height: view.getUint32(20) };
-}
-var RECORDING_MISS_STATUS = 599;
-function isPublishable(result) {
-  return result === "ok" || result === "empty-state";
-}
-function actionFor(outcome) {
-  switch (outcome.result) {
-    case "ok":
-    case "empty-state":
-    case "canonical-redirect":
-      return void 0;
-    case "not-found": {
-      const noun = subjectOf(outcome.missingEndpoint ?? outcome.route);
-      return `Create one ${noun} in your test environment, then run this again.`;
-    }
-    case "thin":
-      return `Nothing rendered on ${outcome.route}. If it needs data, add some; if it is not a real screen, we will leave it out.`;
-    case "bounced":
-      return `${outcome.route} redirected${outcome.landed ? ` to ${outcome.landed}` : " somewhere else"}. If it needs a permission your test account lacks, use one that has it.`;
-    case "crashed":
-      return `${outcome.route} hit an error${outcome.error ? `: ${outcome.error}` : ""}. This is a bug in the app rather than in the setup.`;
-    case "unrecorded":
-      return `${outcome.route} asked for ${outcome.missingEndpoint ?? "data"}, which is not in the recording. Visit this screen while recording, then run this again.`;
-  }
-}
-function subjectOf(path3) {
-  const segments = path3.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
-  while (segments.length > 1 && looksLikeAnId(segments[segments.length - 1])) segments.pop();
-  const last = segments[segments.length - 1] ?? "record";
-  return last.replace(/[-_]/g, " ").replace(/s$/, "");
-}
-function looksLikeAnId(segment) {
-  return /^\d+$/.test(segment) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(segment) || // `inv_123`, `cus_9f2a`: a prefix, a separator, and something with a digit
-  // in it. Deliberately narrow — `sign-up` must survive this.
-  /^[a-z]{2,}[_-][a-z0-9]*\d[a-z0-9]*$/i.test(segment) || /^[0-9a-z]{16,}$/i.test(segment);
-}
-function captureReport(outcomes) {
-  const ready = outcomes.filter((outcome) => isPublishable(outcome.result));
-  const actionable = outcomes.map((outcome) => ({ outcome, action: actionFor(outcome) })).filter((entry) => Boolean(entry.action));
-  const lines = [
-    `${ready.length} screens ready \xB7 ${actionable.length} need attention`,
-    "",
-    ...actionable.map(({ outcome, action }) => `  ${outcome.route.padEnd(30)} ${action}`)
-  ];
-  return { ready: ready.length, needData: actionable.length, lines };
-}
-
 // core/capture/examples.ts
 var CI_EXAMPLES_OUT_ENV = "HELPDESK_EXAMPLES_OUT";
 var EXAMPLES_SCHEMA = "helpdesk.examples/1";
@@ -199,6 +101,108 @@ function describeMissingExample(route, needs) {
   return `the seed command named no record for ${named} on ${route}, so there is nothing real to open. Add one to the file it writes at ${CI_EXAMPLES_OUT_ENV}`;
 }
 
+// core/capture/contract.ts
+var CAPTURE_CONTRACT = {
+  /** Same for every shot, so type is the same size across the whole set. */
+  viewport: { width: 1600, height: 1e3 },
+  /** Stills render at 2x → 3200x2000. */
+  stillScale: 2,
+  /** Clips at 1x; video is resampled downstream anyway. */
+  clipScale: 1,
+  /** Below this a frame is a failed shot rather than a small one. */
+  minStillWidth: 2300,
+  /**
+   * Clip length.
+   *
+   * A CAP rather than a target, and inherited from a marketing site's autoplay
+   * loop — which is not this product's constraint. A help-center clip showing a
+   * multi-step task may well want twenty seconds, so the window is the contract
+   * and the number is configurable.
+   */
+  clipSeconds: { min: 6, target: 9, max: 10 },
+  maxClipBytes: 2 * 1024 * 1024,
+  /** Everything renders as though it were this instant. */
+  pinnedClock: "2026-01-15T09:00:00.000Z",
+  /**
+   * And in this locale and this zone, set on the browser rather than inherited
+   * from whoever runs it, so a date on a screen reads the same from any machine.
+   *
+   * American English, because the products this documents are read in it: a
+   * frame showing "15/01/2026" beside an article written for an American
+   * reader is a screenshot of a product nobody uses.
+   */
+  locale: "en-US",
+  timezone: "UTC",
+  /**
+   * Injected before every shot. Necessary, not sufficient — see above.
+   */
+  motionOff: "*,*::before,*::after{animation:none!important;transition:none!important;caret-color:transparent!important}"
+};
+var VISUAL_STABILITY = {
+  /** Gap between comparison frames. Short enough to be cheap, long enough to differ. */
+  intervalMs: 120,
+  /** Consecutive identical frames required. */
+  identicalFrames: 2,
+  /** Give up rather than hang; a page that never settles is a finding. */
+  timeoutMs: 1e4
+};
+function pngSize(bytes) {
+  const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+  if (bytes.length < 24) return void 0;
+  if (SIGNATURE.some((byte, index) => bytes[index] !== byte)) return void 0;
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return { width: view.getUint32(16), height: view.getUint32(20) };
+}
+var RECORDING_MISS_STATUS = 599;
+function isPublishable(result) {
+  return result === "ok" || result === "empty-state";
+}
+function actionFor(outcome) {
+  switch (outcome.result) {
+    case "ok":
+    case "empty-state":
+    case "canonical-redirect":
+      return void 0;
+    case "not-found": {
+      if ((!outcome.missingEndpoint || outcome.missingEndpoint === outcome.route) && !outcome.route.includes("[")) {
+        return `${outcome.route} answered Not Found here, and its address names no record to create. If it is behind a feature flag, turn the flag on where the run happens; if it is gone, it will drop out of the plan.`;
+      }
+      const asked = outcome.missingEndpoint ?? outcome.route;
+      const noun = subjectOf(fillsPattern(outcome.route, asked) ? outcome.route : asked);
+      return `Create one ${noun} in your test environment, then run this again.`;
+    }
+    case "thin":
+      return `Nothing rendered on ${outcome.route}. If it needs data, add some; if it is not a real screen, we will leave it out.`;
+    case "bounced":
+      return `${outcome.route} redirected${outcome.landed ? ` to ${outcome.landed}` : " somewhere else"}. If it needs a permission your test account lacks, use one that has it.`;
+    case "crashed":
+      return `${outcome.route} hit an error${outcome.error ? `: ${outcome.error}` : ""}. This is a bug in the app rather than in the setup.`;
+    case "unrecorded":
+      return `${outcome.route} asked for ${outcome.missingEndpoint ?? "data"}, which is not in the recording. Visit this screen while recording, then run this again.`;
+  }
+}
+function subjectOf(path3) {
+  const segments = path3.split("/").filter(Boolean).filter((segment) => !/^(api|v\d+)$/.test(segment));
+  while (segments.length > 1 && looksLikeAnId(segments[segments.length - 1])) segments.pop();
+  const last = segments[segments.length - 1] ?? "record";
+  return last.replace(/[-_]/g, " ").replace(/s$/, "");
+}
+function looksLikeAnId(segment) {
+  return /^\[{1,2}[^\]]+\]{1,2}$/.test(segment) || /^\d+$/.test(segment) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(segment) || // `inv_123`, `cus_9f2a`: a prefix, a separator, and something with a digit
+  // in it. Deliberately narrow — `sign-up` must survive this.
+  /^[a-z]{2,}[_-][a-z0-9]*\d[a-z0-9]*$/i.test(segment) || /^[0-9a-z]{16,}$/i.test(segment);
+}
+function captureReport(outcomes) {
+  const ready = outcomes.filter((outcome) => isPublishable(outcome.result));
+  const actionable = outcomes.map((outcome) => ({ outcome, action: actionFor(outcome) })).filter((entry) => Boolean(entry.action));
+  const lines = [
+    `${ready.length} screens ready \xB7 ${actionable.length} need attention`,
+    "",
+    ...actionable.map(({ outcome, action }) => `  ${outcome.route.padEnd(30)} ${action}`)
+  ];
+  return { ready: ready.length, needData: actionable.length, lines };
+}
+
 // core/cli-package.ts
 var HELPDESK_CLI_PACKAGE = "@olomonhelpdesk2/helpdesk";
 function helpdeskCommand(command, args = []) {
@@ -234,7 +238,7 @@ var EMPTY_STATE_PHRASES = [
   /\bno results\b/i,
   /\bthis (list|table) is empty\b/i
 ];
-function classifyRoute(observation) {
+function classifyRoute(observation, options = {}) {
   const text2 = observation.text.trim();
   const unrecorded = observation.failedRequests?.find((request) => request.status === RECORDING_MISS_STATUS);
   if (unrecorded) {
@@ -244,21 +248,26 @@ function classifyRoute(observation) {
   if (crash) return { route: observation.route, result: "crashed", error: crash };
   const missing = missingBecause(observation, text2);
   if (missing) return { route: observation.route, result: "not-found", missingEndpoint: missing };
+  let followed;
   if (observation.landedOn && !samePlace(observation.route, observation.landedOn)) {
     const canonical = canonicalisation(observation.route, observation.landedOn);
-    return {
-      route: observation.route,
-      result: canonical ? "canonical-redirect" : "bounced",
-      // Carried only when it is a finding. A parent handing off to its default
-      // child needs no row, so it needs no detail either.
-      ...canonical ? {} : { landed: observation.landedOn }
-    };
+    if (!canonical && options.follow?.(observation.landedOn)) {
+      followed = { landed: observation.landedOn };
+    } else {
+      return {
+        route: observation.route,
+        result: canonical ? "canonical-redirect" : "bounced",
+        // Carried only when it is a finding. A parent handing off to its default
+        // child needs no row, so it needs no detail either.
+        ...canonical ? {} : { landed: observation.landedOn }
+      };
+    }
   }
   if (EMPTY_STATE_PHRASES.some((phrase) => phrase.test(text2))) {
-    return { route: observation.route, result: "empty-state" };
+    return { route: observation.route, result: "empty-state", ...followed };
   }
-  if (text2.length < THIN_TEXT_CHARS) return { route: observation.route, result: "thin" };
-  return { route: observation.route, result: "ok" };
+  if (text2.length < THIN_TEXT_CHARS) return { route: observation.route, result: "thin", ...followed };
+  return { route: observation.route, result: "ok", ...followed };
 }
 function crashedBecause(observation, text2) {
   const uncaught = observation.errors?.[0];
@@ -416,6 +425,82 @@ function attestation(run) {
   ].filter(Boolean).join("\n");
 }
 
+// core/capture/run-verdict.ts
+function runVerdict(run) {
+  const delivered = run.captured + run.unchanged;
+  const missed = run.skipped + run.refused + run.failed;
+  const counts = `${run.captured} photographed, ${run.unchanged} unchanged, ${run.skipped} skipped, ${run.refused} refused, ${run.failed} failed`;
+  if (run.screens > 0 && delivered === 0) {
+    return {
+      exit: 1,
+      annotation: `::error title=No screenshots were delivered::None of the ${run.screens} screens was photographed (${counts}). The step log says why for each one.`,
+      sentence: `Nothing was delivered, so this run fails rather than passing with no screenshots: ${counts}.`
+    };
+  }
+  if (missed > 0) {
+    return {
+      exit: run.failed > 0 ? 1 : 0,
+      annotation: `::warning title=${missed} of ${run.screens} screens were not photographed::${counts}. The step log says why for each one.`
+    };
+  }
+  return { exit: 0 };
+}
+
+// core/capture/unclassified.ts
+var SEPARATOR = " > ";
+function commonRegion(selectors) {
+  const parts = selectors.map((selector) => selector.split(SEPARATOR));
+  const first = parts[0] ?? [];
+  let shared = 0;
+  while (shared < first.length && parts.every((steps) => steps[shared] === first[shared])) shared += 1;
+  return shared >= 3 ? first.slice(0, shared).join(SEPARATOR) : "";
+}
+function groupUnclassified(refused) {
+  const enough = Math.max(2, Math.ceil(new Set(refused.map((screen) => screen.route)).size / 2));
+  const where = /* @__PURE__ */ new Map();
+  for (const screen of refused) {
+    for (const value of screen.values) {
+      const seen = where.get(value.at) ?? { screens: /* @__PURE__ */ new Set(), lengths: /* @__PURE__ */ new Set() };
+      seen.screens.add(screen.route);
+      seen.lengths.add(value.length);
+      where.set(value.at, seen);
+    }
+  }
+  const shared = [...where.entries()].filter(([, seen]) => seen.screens.size >= enough).map(([at, seen]) => ({ at, screens: [...seen.screens].sort(), lengths: [...seen.lengths].sort((a, b) => a - b) })).sort((a, b) => b.screens.length - a.screens.length || a.at.localeCompare(b.at));
+  const isShared = new Set(shared.map((element) => element.at));
+  const screens = [];
+  const onlyShared = [];
+  for (const screen of refused) {
+    const rest = screen.values.filter((value) => !isShared.has(value.at));
+    if (rest.length) {
+      screens.push({ route: screen.route, count: rest.length, within: commonRegion(rest.map((value) => value.at)) });
+    } else if (screen.values.length) {
+      onlyShared.push(screen.route);
+    }
+  }
+  return { shared, screens, onlyShared: [...new Set(onlyShared)].sort() };
+}
+function describeLengths(lengths) {
+  const low = lengths[0] ?? 0;
+  const high = lengths[lengths.length - 1] ?? low;
+  return low === high ? `${low} character${low === 1 ? "" : "s"}` : `${low} to ${high} characters`;
+}
+function describeShared(element, summary) {
+  const unblocks = summary.onlyShared.filter((route) => element.screens.includes(route)).length;
+  return `One element sits outside every part of the page the clearance names, in the same place on ${element.screens.length} screens: ${element.at} (${describeLengths(element.lengths)}). Something in the same place on every screen is part of the app's own layout, such as a feedback or help button, so it is classified once. Say what it is on Setup` + (unblocks ? `, and the ${unblocks} screen${unblocks === 1 ? "" : "s"} held back only by it can be photographed.` : ".");
+}
+function describeRemainder(screen) {
+  return `${screen.route}: ${screen.count} value${screen.count === 1 ? "" : "s"} outside every part of the page the clearance names` + (screen.within ? `, all inside ${screen.within}.` : ", spread across the page.");
+}
+function unclassifiedLines(summary) {
+  if (!summary.shared.length && !summary.screens.length) return [];
+  return [
+    "Not photographed until somebody says what is there:",
+    ...summary.shared.map((element) => `  ${describeShared(element, summary)}`),
+    ...summary.screens.map((screen) => `  ${describeRemainder(screen)}`)
+  ];
+}
+
 // adapters/capture-cli.ts
 import { createRequire } from "node:module";
 import path from "node:path";
@@ -550,7 +635,7 @@ var PATTERNS = [
   {
     kind: "passport",
     regex: /\b[A-Z]{1,2}\d{6,9}\b/g,
-    because: "the shape of a passport or licence number",
+    because: "the shape of a passport or license number",
     replace: (match) => `${match.slice(0, 1)}${"0".repeat(match.length - 1)}`
   },
   {
@@ -616,6 +701,20 @@ function gateFrame(pageText, options = {}) {
   };
 }
 
+// core/capture/sign-in.ts
+var IDENTIFIER_HINT = /\b(username|email)\b/;
+var IDENTIFIER_NAME = /user|login|e-?mail/;
+function identifies(field) {
+  if (field.type === "email") return true;
+  if (IDENTIFIER_HINT.test(field.autocomplete)) return true;
+  return (field.type === "text" || field.type === "") && IDENTIFIER_NAME.test(field.name);
+}
+function looksLikeSignIn(fields) {
+  const secrets = fields.filter((field) => field.type === "password");
+  if (secrets.some((field) => field.autocomplete.split(/\s+/).includes("current-password"))) return true;
+  return secrets.some((secret) => fields.some((field) => field.form === secret.form && identifies(field)));
+}
+
 // core/capture/publication/pixels.ts
 import { deflateSync, inflateSync } from "node:zlib";
 var MediaRefused = class extends Error {
@@ -649,7 +748,7 @@ function decodePng(buffer) {
     offset += 12 + length;
   }
   if (bitDepth !== 8 || colourType !== 2 && colourType !== 6) {
-    throw new MediaRefused(`only 8-bit RGB and RGBA PNGs are supported here, not colour type ${colourType} at ${bitDepth} bits`);
+    throw new MediaRefused(`only 8-bit RGB and RGBA PNGs are supported here, not color type ${colourType} at ${bitDepth} bits`);
   }
   const channels = colourType === 6 ? 4 : 3;
   const raw = inflateSync(Buffer.concat(data));
@@ -1594,7 +1693,9 @@ async function captureOne(options, shot, build) {
       };
     }
     const seen = await page.observe?.() ?? {};
-    const observed = { ...classifyRoute({ ...seen, route: visit, text: pageText }), route: shot.route };
+    const origin = new URL(options.baseUrl).origin;
+    const follow = (landed) => seen.landedOrigin === origin && options.shots.some((other) => fillsPattern(other.route, landed.split(/[?#]/)[0] ?? landed));
+    const observed = { ...classifyRoute({ ...seen, route: visit, text: pageText }, { follow }), route: shot.route };
     if (!isPublishable(observed.result)) {
       return {
         outcome: {
@@ -1634,7 +1735,8 @@ async function captureOne(options, shot, build) {
             // Where and never what: a value nobody has classified is a value
             // nobody has established is safe to write down, and a reason that
             // quoted it would put it in this run's log.
-            reason: `${unaccounted.length} value(s) on this screen are outside every region the clearance names (${unaccounted.map((value) => `${value.at} (${value.length} character(s))`).join("; ")}), so it is restricted until somebody classifies them`
+            reason: `${unaccounted.length} value(s) on this screen are outside every region the clearance names (${unaccounted.map((value) => `${value.at} (${value.length} character(s))`).join("; ")}), so it is restricted until somebody classifies them`,
+            unaccounted: unaccounted.map((value) => ({ at: value.at, length: value.length }))
           },
           observed,
           ...evidence ? { seen: evidence } : {}
@@ -1750,7 +1852,7 @@ async function captureOne(options, shot, build) {
         result: observed.result,
         sha256,
         settled: frame.settled,
-        ...frame.settled ? {} : {
+        ...frame.settled ? observed.landed ? { reason: `followed its redirect to ${observed.landed}` } : {} : {
           reason: "photographed, but this screen never stopped moving \u2014 its hash will differ every run, so drift on it means nothing"
         }
       } : {
@@ -1913,11 +2015,21 @@ async function playwrightBrowser(options = {}) {
           return page.locator("body").ariaSnapshot().catch(() => "");
         },
         async isSignIn() {
-          return await page.locator('input[type="password"]').count() > 0;
+          const fields = await page.evaluate(() => {
+            const forms = Array.from(document.forms);
+            return Array.from(document.querySelectorAll("input")).map((input) => ({
+              type: (input.getAttribute("type") ?? "text").toLowerCase(),
+              autocomplete: (input.getAttribute("autocomplete") ?? "").toLowerCase(),
+              name: `${input.name} ${input.id}`.toLowerCase(),
+              form: input.form ? forms.indexOf(input.form) : -1
+            }));
+          }).catch(() => []);
+          return looksLikeSignIn(fields);
         },
         async observe() {
           return {
             landedOn: pathOf(page.url()),
+            landedOrigin: new URL(page.url()).origin,
             ...status === void 0 ? {} : { status },
             errors: [...errors],
             consoleErrors: [...consoleErrors],
@@ -3045,7 +3157,7 @@ function parseArgs(argv) {
     else if (flag === "--live-clock") args.liveClock = true;
     else if (flag === "--allow-production") args.allowProduction = true;
     else if (flag === "--rebaseline" || flag === "--force") {
-      return '--rebaseline needs a reason: `--rebaseline "new brand colours shipped"`. Replacing every stored frame moves every checksum at once, and a re-baseline nobody wrote down is indistinguishable from the product changing.';
+      return '--rebaseline needs a reason: `--rebaseline "new brand colors shipped"`. Replacing every stored frame moves every checksum at once, and a re-baseline nobody wrote down is indistinguishable from the product changing.';
     }
   }
   if (args.out) {
@@ -3249,7 +3361,9 @@ Approve one on the plan page, then run this again.`
             jobId: runId,
             item: outcome.route,
             status: outcome.status === "captured" || outcome.status === "unchanged" ? "ok" : outcome.status === "failed" ? "failed" : "skipped",
-            ...outcome.reason ? { note: outcome.reason } : {}
+            ...outcome.reason ? { note: outcome.reason } : {},
+            // So Setup can ask about them, once each. See `core/capture/unclassified.ts`.
+            ...outcome.unaccounted?.length ? { unaccounted: outcome.unaccounted } : {}
           });
         }
       },
@@ -3303,6 +3417,13 @@ Approve one on the plan page, then run this again.`
       `
 ${report.captured} photographed, ${report.unchanged} unchanged, ${report.skipped} skipped, ${report.refused} refused, ${report.failed} failed.`
     );
+    const unclassified = unclassifiedLines(
+      groupUnclassified(
+        report.outcomes.flatMap((outcome) => outcome.unaccounted?.length ? [{ route: outcome.route, values: outcome.unaccounted }] : [])
+      )
+    );
+    if (unclassified.length) console.log(`
+${unclassified.join("\n")}`);
     if (local) {
       const kept = new Map(frames.map((frame) => [frame.id, frame]));
       for (const shot of shots) {
@@ -3394,7 +3515,18 @@ ${gapReport(gapsFrom([...stage.replay.misses])).join("\n")}`);
         ...report.survey.length ? { survey: report.survey } : {}
       });
     }
-    return report.failed ? 1 : 0;
+    const verdict = runVerdict({
+      screens: shots.length,
+      captured: report.captured,
+      unchanged: report.unchanged,
+      skipped: report.skipped,
+      refused: report.refused,
+      failed: report.failed
+    });
+    if (verdict.sentence) console.log(`
+${verdict.sentence}`);
+    if (verdict.annotation && process.env["GITHUB_ACTIONS"] === "true") console.log(verdict.annotation);
+    return verdict.exit;
   } catch (error) {
     if (runId) {
       await tellHelpDesk(parsed.to, headers, {

package/helpdesk-seed.mjs

@@ -788,7 +788,7 @@ var PATTERNS = [
   {
     kind: "passport",
     regex: /\b[A-Z]{1,2}\d{6,9}\b/g,
-    because: "the shape of a passport or licence number",
+    because: "the shape of a passport or license number",
     replace: (match) => `${match.slice(0, 1)}${"0".repeat(match.length - 1)}`
   },
   {
@@ -1270,7 +1270,7 @@ ${carriedReport(sealed.carried, args.cassette).join("\n")}`);
     console.log(`
 ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}`);
     console.log(
-      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognised. Read them before you commit this."
+      "\nThese survived the field pass, which means they were in free text or under a key nothing\nrecognized. Read them before you commit this."
     );
     return 1;
   }
@@ -1278,7 +1278,7 @@ ${describeScrub({ scrubbed: "", findings: sealed.findings, needsReview: true })}
   return 0;
 }
 function carriedReport(carried, cassette) {
-  if (!carried.length) return ["Every key in the recording was recognised and rewritten."];
+  if (!carried.length) return ["Every key in the recording was recognized and rewritten."];
   const ranked = [...carried].sort((a, b) => score(b) - score(a) || b.count - a.count);
   const width = Math.max(...ranked.map((field) => field.key.length));
   const worth = ranked.filter((field) => score(field) > 0);
@@ -1380,7 +1380,7 @@ async function routes(args) {
   const cassette = parseCassette(await readFile(args.cassette, "utf8"));
   const found = exampleRoutes(cassette);
   if (!found.length) {
-    console.log("The recording holds no parameterised routes, so there are no example ids to offer.");
+    console.log("The recording holds no parameterized routes, so there are no example ids to offer.");
     return 0;
   }
   console.log("Routes the recording can answer, with an identifier it has already served:\n");

package/helpdesk.mjs

@@ -793,6 +793,7 @@ function readProduct(routes, options) {
   };
   const documentable = routes.filter((route) => !route.skipped);
   const total = Math.min(documentable.length, maxScreens);
+  const reading = { how: "source", commit: options.commit ?? null };
   let done = 0;
   let withFacts = 0;
   const out = routes.map((route) => {
@@ -803,12 +804,15 @@ function readProduct(routes, options) {
       const source = read(reached.path);
       if (source !== void 0) files.push({ path: reached.path, contents: source, depth: reached.depth });
     }
-    const facts = readScreenFacts(files);
     done += 1;
     options.onScreen?.(route, done, total);
-    if (!hasAnything(facts)) return route;
+    if (files.length === 0) return route;
+    const facts = readScreenFacts(files);
+    if (!hasAnything(facts)) {
+      return { ...route, facts: noScreenFacts(reading) };
+    }
     withFacts += 1;
-    return { ...route, facts };
+    return { ...route, facts: { ...facts, read: reading } };
   });
   return { routes: out, read: withFacts, filesOpened: opened.size };
 }
@@ -937,7 +941,7 @@ function markersPullRequestBody(result) {
   const lines = [
     "This adds one-line comments that link screens in this repository to the help articles that describe them.",
     "",
-    "**Nothing here changes behaviour.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
+    "**Nothing here changes behavior.** Each line is a comment. Once merged, a change to one of these files tells our help desk which article may now be out of date, so somebody can check it before a customer does.",
     "",
     `${result.proposals.length} marker${result.proposals.length === 1 ? "" : "s"} proposed.`
   ];
@@ -1000,7 +1004,10 @@ async function runMap(options) {
         }
       },
       aliases: aliasesFromTsconfig(tsconfig),
-      baseUrl: baseUrlFromTsconfig(tsconfig)
+      baseUrl: baseUrlFromTsconfig(tsconfig),
+      // Stamped onto every reading, so a map carries the commit its labels and
+      // controls were read at and a later one can tell fresh from stale.
+      commit: headCommit(options.cwd)
     });
     routes = read.routes;
     const reading = describeReading(routes);
@@ -1075,6 +1082,13 @@ function originOf(cwd) {
     return void 0;
   }
 }
+function headCommit(cwd) {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd, encoding: "utf8" }).trim() || null;
+  } catch {
+    return null;
+  }
+}
 
 // adapters/invoked-as-command.ts
 import { realpathSync } from "node:fs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olomonhelpdesk2/helpdesk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Reads a product's screens, plans its help articles, and photographs them.",
   "type": "module",
   "engines": {