refactor(test): trim check:agent-analytics to the five that earn a gate

161 lines -> 100, 13 assertions -> 5. Dropped everything that tested a pure function
correct by inspection: which regex matches Applebot, that sessions bucket per half
hour, that `edition` is copied into the payload, that client_id is stable. Those were
ceremony, and ceremony has a maintenance cost — this suite has already produced two
defects of its own.

What survives is only what fails silently or takes a site down. This file is the only
thing in the repo that loads functions/ at all (check-links and check-sitemap read
built output), and that middleware runs in front of every request to both production
sites:

  * the middleware returns next()'s response unchanged
  * imqueue.net still 301s onto imqueue.org
  * an analytics failure still serves the page
  * the crawler's user-agent never reaches the payload — GA4 bot-filters it, so
    forwarding it collects nothing, forever, while every request answers 2xx
  * nothing is sent unless BOTH env vars are set (now also covering secret-without-id)

Still touches no network: verified under a global fetch spy.

Author: Mikhus

scripts/check-agent-analytics.js

@@ -1,122 +1,34 @@
 #!/usr/bin/env node
-// check-agent-analytics.js — guards lib/agent-analytics.js and the middleware that
-// carries it.
+// check-agent-analytics.js — the five things about lib/agent-analytics.js and
+// functions/_middleware.js that are worth a gate.
 //
-// Everything here is offline pure logic, which is why it can live in `npm test`
-// alongside check:redirects. It exists because every invariant in that module fails
-// SILENTLY when broken:
+// This file is the ONLY place in the repo that loads functions/. check-links and
+// check-sitemap read built output; nothing else ever executes the middleware that
+// runs in front of every request to both production sites.
 //
-//   * forward the crawler's user-agent and GA4's bot filter discards the entire
-//     dataset — no error, just an empty property
-//   * start emitting events for ordinary browser page views and the agent property
-//     quietly becomes a worse duplicate of the main one
-//   * throw anywhere in the middleware and it is not analytics that breaks, it is
-//     imqueue.org and imqueue.com
+// Deliberately small. An earlier version asserted thirteen things, including which
+// regex matches Applebot and that sessions bucket per half hour — pure functions
+// that are correct by inspection, and ceremony to maintain. What survives is only
+// what fails SILENTLY or takes a site down:
 //
-// None of those show up in a build log, so they are asserted here instead.
+//   1-3. the middleware always returns a response, whatever analytics does
+//   4.   the crawler's user-agent never reaches Google (it would bot-filter the lot)
+//   5.   nothing is sent unless the deployment is configured to send it
+//
+// Nothing here touches the network — verified by running it under a global fetch
+// spy. Delivery is deliberately NOT tested here; it needs a credential and a
+// network, which is what `npm run probe:agent-analytics` is for.
 const assert = require('node:assert');
 
-const BROWSER = 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36';
-const GPTBOT = 'Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko); compatible; GPTBot/1.2; +https://openai.com/gptbot';
-
-const u = (p, host = 'imqueue.org') => new URL(`https://${host}${p}`);
+const GPTBOT = 'Mozilla/5.0 (compatible; GPTBot/1.2; +https://openai.com/gptbot)';
 
 let checks = 0;
 const ok = (msg) => { checks++; console.log(`  ok    ${msg}`); };
 
 async function main() {
-  const { buildEvent, classifyCrawler, classifySurface, trackRequest } =
-    await import('../lib/agent-analytics.js');
-
-  // --- rule 2: only what gtag misses ---------------------------------------
-  assert.strictEqual(
-    buildEvent({ url: u('/tutorial/'), userAgent: BROWSER, status: 200, edition: 'org' }),
-    null,
-    'a browser reading an HTML page is gtag\'s job and must produce no event',
-  );
-  ok('browser + HTML page → no event (gtag already measures it)');
-
-  const mirror = buildEvent({ url: u('/tutorial/index.md'), userAgent: BROWSER, status: 200, edition: 'org' });
-  assert.ok(mirror, 'the agent surface counts even from an unrecognised client');
-  assert.strictEqual(mirror.events[0].params.surface, 'markdown-mirror');
-  assert.strictEqual(mirror.events[0].params.crawler, 'unclassified');
-  ok('any client + .md mirror → event, surface=markdown-mirror');
-
-  const botHtml = buildEvent({ url: u('/'), userAgent: GPTBOT, status: 200, edition: 'org' });
-  assert.ok(botHtml, 'a crawler on an HTML page is invisible to gtag and must be counted');
-  assert.strictEqual(botHtml.events[0].params.surface, 'html');
-  assert.strictEqual(botHtml.events[0].params.crawler, 'GPTBot');
-  assert.strictEqual(botHtml.events[0].params.operator, 'OpenAI');
-  ok('crawler + HTML page → event, surface=html (gtag never fires for it)');
-
-  // --- rule 3: the crawler UA must never reach Google ----------------------
-  for (const body of [mirror, botHtml]) {
-    assert.ok(
-      !JSON.stringify(body).includes('Mozilla'),
-      'the crawler user-agent must not appear anywhere in the payload — GA4 would '
-      + 'bot-filter the hit and the whole dataset would silently vanish',
-    );
-  }
-  ok('no user-agent string anywhere in the payload (GA4 bot filter would drop it)');
-
-  // --- rule 4: identity is a crawler family, never a visitor ---------------
-  const a = buildEvent({ url: u('/llms.txt'), userAgent: GPTBOT, status: 200, edition: 'org' });
-  const b = buildEvent({ url: u('/api/index.md'), userAgent: GPTBOT, status: 404, edition: 'org' });
-  assert.strictEqual(a.client_id, b.client_id, 'same crawler → same client_id');
-  const claude = buildEvent({ url: u('/llms.txt'), userAgent: 'ClaudeBot/1.0', status: 200, edition: 'org' });
-  assert.notStrictEqual(a.client_id, claude.client_id, 'different crawler → different client_id');
-  assert.ok(!/\d+\.\d+\.\d+\.\d+/.test(JSON.stringify(a)), 'no IP-shaped value in the payload');
-  ok('client_id is stable per crawler family and carries nothing identifying');
-
-  // --- the fields the reports are built on ---------------------------------
-  assert.strictEqual(b.events[0].params.status, '404', 'status is carried, as a string');
-  assert.strictEqual(b.events[0].params.page_location, 'https://imqueue.org/api/index.md');
-  assert.strictEqual(b.events[0].params.page_title, '/api/index.md');
-  assert.strictEqual(b.events[0].name, 'page_view',
-    'page_view is what populates GA4\'s built-in Pages reports without custom dimensions');
-  assert.strictEqual(b.events[0].params.engagement_time_msec, 1);
-  assert.ok(b.events[0].params.session_id, 'a session_id is required or engagement reads as zero');
-  ok('page_view + page_location + status + session_id present');
-
-  const com = buildEvent({ url: u('/index.md', 'imqueue.com'), userAgent: GPTBOT, status: 200, edition: 'com' });
-  assert.strictEqual(com.events[0].params.edition, 'com');
-  ok('edition is carried, so one property can hold both sites');
-
-  // Sessions bucket by half-hour: a crawl burst is a session, and a crawler that
-  // comes back tomorrow is not one long visit.
-  const t0 = 1_800_000_000_000;
-  const s1 = buildEvent({ url: u('/llms.txt'), userAgent: GPTBOT, status: 200, edition: 'org', now: t0 });
-  const s2 = buildEvent({ url: u('/llms.txt'), userAgent: GPTBOT, status: 200, edition: 'org', now: t0 + 60_000 });
-  const s3 = buildEvent({ url: u('/llms.txt'), userAgent: GPTBOT, status: 200, edition: 'org', now: t0 + 1_900_000 });
-  assert.strictEqual(s1.events[0].params.session_id, s2.events[0].params.session_id);
-  assert.notStrictEqual(s1.events[0].params.session_id, s3.events[0].params.session_id);
-  ok('session_id buckets per half hour (a crawl burst is one session)');
-
-  // --- classifiers ---------------------------------------------------------
-  assert.strictEqual(classifyCrawler(BROWSER), null);
-  assert.strictEqual(classifyCrawler('').crawler, 'no-user-agent');
-  assert.strictEqual(classifyCrawler('node').operator, 'Generic client');
-  assert.strictEqual(classifySurface('/blog/topics/rpc/'), null);
-  assert.strictEqual(classifySurface('/api/search-index.json'), 'symbol-index');
-  assert.strictEqual(classifySurface('/sitemap-api.xml'), 'sitemap');
-  ok('classifiers agree on browsers, empty UAs, HTTP clients and each surface');
-
-  // --- rule 5: inert without credentials -----------------------------------
-  const req = { headers: { get: () => GPTBOT } };
-  assert.strictEqual(
-    trackRequest({ request: req, env: {}, url: u('/llms.txt'), status: 200, edition: 'org' }),
-    null,
-    'with no env vars this must do nothing — a fork or preview deploy sends nothing',
-  );
-  assert.strictEqual(
-    trackRequest({ request: req, env: { GA4_MP_MEASUREMENT_ID: 'G-X' }, url: u('/llms.txt'), status: 200, edition: 'org' }),
-    null,
-    'half-configured is still inert',
-  );
-  ok('inert unless BOTH GA4_MP_MEASUREMENT_ID and GA4_MP_API_SECRET are set');
-
-  // --- the middleware contract: always returns, never throws ---------------
+  const { buildEvent, trackRequest } = await import('../lib/agent-analytics.js');
   const { onRequest } = await import('../functions/_middleware.js');
+
   const page = new Response('hi', { status: 200 });
   const ctx = (url, extra = {}) => ({
     request: new Request(url, { headers: { 'user-agent': GPTBOT } }),
@@ -126,23 +38,21 @@ async function main() {
     ...extra,
   });
 
-  assert.strictEqual(await onRequest(ctx('https://imqueue.org/llms.txt')), page,
-    'the response from next() must be passed through untouched');
+  // --- the middleware contract ---------------------------------------------
+  assert.strictEqual(
+    await onRequest(ctx('https://imqueue.org/llms.txt')), page,
+    'the response from next() must be passed through untouched',
+  );
   ok('middleware returns next()\'s response unchanged');
 
   const moved = await onRequest(ctx('https://imqueue.net/tutorial/'));
   assert.strictEqual(moved.status, 301);
   assert.strictEqual(moved.headers.get('location'), 'https://imqueue.org/tutorial/');
   ok('imqueue.net still 301s onto imqueue.org');
 
-  // Constraint 1 in functions/_middleware.js: this file runs in front of every
-  // request to BOTH sites, so a throw there is an outage, not a lost metric.
-  //
-  // Provoked with a request the middleware cannot even parse — `new URL()` throws
-  // inside the analytics block — rather than by configuring credentials and stubbing
-  // fetch to reach the same catch. Same invariant, no fake secrets, and nothing in
-  // this suite goes anywhere near the send path: `npm test` runs at pre-commit and on
-  // every pull request, and a gate has no business making network calls, valid or not.
+  // A throw in this file is an outage, not a lost metric. Provoked with a request the
+  // middleware cannot parse — new URL() throws inside the analytics block — so the
+  // catch is reached with no credentials, no fetch stub and no send path.
   const unparseable = await onRequest({
     request: { url: '://not-a-url', headers: { get: () => null } },
     env: { GA4_MP_MEASUREMENT_ID: 'G-X', GA4_MP_API_SECRET: 's' },
@@ -152,6 +62,35 @@ async function main() {
   assert.strictEqual(unparseable, page, 'a broken analytics path must still serve the page');
   ok('analytics failure degrades to "no measurement", never to "no page"');
 
+  // --- the two silent failures ---------------------------------------------
+  // GA4 discards traffic it identifies as an IAB bot, and the Measurement Protocol
+  // only knows the user-agent if you send it. Forward it and the property collects
+  // nothing, forever, while every request still answers 2xx.
+  const event = buildEvent({
+    url: new URL('https://imqueue.org/tutorial/index.md'),
+    userAgent: GPTBOT,
+    status: 200,
+    edition: 'org',
+  });
+  assert.ok(event, 'a crawler fetching a mirror must produce an event');
+  assert.ok(
+    !JSON.stringify(event).includes('Mozilla'),
+    'the crawler user-agent must not appear anywhere in the payload',
+  );
+  ok('no user-agent string in the payload (GA4 would bot-filter the whole dataset)');
+
+  // A fork, a preview deploy or a half-finished setup must send nothing anywhere.
+  const req = { headers: { get: () => GPTBOT } };
+  const url = new URL('https://imqueue.org/llms.txt');
+  for (const env of [{}, { GA4_MP_MEASUREMENT_ID: 'G-X' }, { GA4_MP_API_SECRET: 's' }]) {
+    assert.strictEqual(
+      trackRequest({ request: req, env, url, status: 200, edition: 'org' }),
+      null,
+      `must be inert with env ${JSON.stringify(env)}`,
+    );
+  }
+  ok('inert unless BOTH GA4_MP_MEASUREMENT_ID and GA4_MP_API_SECRET are set');
+
   console.log(`\nAll ${checks} agent-analytics checks passed.`);
 }