fix(test): type the driver double and narrow the dispatch result so the hidden test layer type-checks (#13408)

Author: os-steve

packages/objectql/src/engine-primary-datasource.test.ts

@@ -16,9 +16,20 @@
 // the refusal happens and is not silently a name.
 
 import { describe, it, expect } from 'vitest';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 import { ObjectQL } from './engine.js';
 
-const driver = (name: string) => ({
+/**
+ * A registrable driver double.
+ *
+ * Annotated `IDataDriver` deliberately, rather than left as an inferred object
+ * literal: `registerDriver` takes the real contract, so an un-annotated double
+ * is checked only at the call site and silently drifts as the interface grows.
+ * The annotation makes THIS declaration the thing that fails when a member is
+ * added — which is how the first version of this fixture was found short of
+ * `upsert` and `dropTable`.
+ */
+const driver = (name: string): IDataDriver => ({
   name,
   version: '1.0.0',
   supports: {},
@@ -27,18 +38,20 @@ const driver = (name: string) => ({
   checkHealth: async () => true,
   find: async () => [],
   findOne: async () => null,
-  create: async (_o: string, data: any) => ({ id: '1', ...data }),
-  update: async (_o: string, id: string, data: any) => ({ id, ...data }),
+  create: async (_o, data) => ({ id: '1', ...data }),
+  update: async (_o, id, data) => ({ id, ...data }),
+  upsert: async (_o, data) => ({ id: '1', ...data }),
   delete: async () => true,
   count: async () => 0,
   bulkCreate: async () => [],
   bulkUpdate: async () => [],
   bulkDelete: async () => {},
-  execute: async () => ({}),
+  execute: async () => null,
   beginTransaction: async () => ({}),
   commit: async () => {},
   rollback: async () => {},
   syncSchema: async () => {},
+  dropTable: async () => {},
 });
 
 function newEngine(): ObjectQL {

packages/runtime/src/http-dispatcher.ready.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect, vi } from 'vitest';
-import { HttpDispatcher } from './http-dispatcher.js';
+import { HttpDispatcher, type HttpDispatcherResult } from './http-dispatcher.js';
 
 function kernel(state: string, dataService?: unknown): any {
   return {
@@ -10,6 +10,34 @@ function kernel(state: string, dataService?: unknown): any {
 }
 const ctx: any = {};
 
+/**
+ * `HttpDispatcherResult.response` is OPTIONAL, so every read of it is a
+ * `possibly undefined` in a type-checked program — and this package's test
+ * layer IS type-checked, by `check:type-check-debt --re-measure` against a
+ * shrink-only ledger, even though `pnpm test` never sees it. That asymmetry is
+ * exactly how 19 fresh errors got in here behind a green `pnpm --filter
+ * @objectstack/runtime typecheck`: the package's own tsconfig excludes every
+ * `.test.ts` file, so the program that reported zero had never read this one.
+ *
+ * Narrow once, and narrow LOUDLY — the shape is lifted from the #8287 suite in
+ * `http-dispatcher.keys.test.ts`, deliberately rather than invented again.
+ * `expect(res.response).toBeDefined()` would satisfy a reader and narrow
+ * nothing (vitest's matchers are not assertion signatures), and a `!` would
+ * silence the compiler while leaving the failure to surface as `undefined is
+ * not an object` three lines later. A probe that answered no response at all is
+ * a different defect from one that answered the wrong status; this keeps them
+ * distinguishable.
+ *
+ * Applied to the WHOLE file, not just the #13408 suite: the reads are identical
+ * in kind, the repair is one call each, and leaving the older ones would bank a
+ * green while knowingly holding fixable errors in a file already open.
+ */
+function responseOf(res: HttpDispatcherResult): NonNullable<HttpDispatcherResult['response']> {
+  const { response } = res;
+  if (!response) throw new Error('GET /ready answered no response at all');
+  return response;
+}
+
 /** An engine whose `checkDriversHealth` reports the given verdicts. */
 function engine(results: Array<{ driverName: string; healthy: boolean }>) {
   return { checkDriversHealth: vi.fn(async () => results) };
@@ -38,14 +66,14 @@ describe('HttpDispatcher — GET /ready readiness probe', () => {
   it('returns 200 when the kernel is running', async () => {
     const res = await new HttpDispatcher(kernel('running')).dispatch('GET', '/ready', undefined, undefined, ctx);
     expect(res.handled).toBe(true);
-    expect(res.response.status).toBe(200);
-    expect(res.response.body.data.state).toBe('running');
+    expect(responseOf(res).status).toBe(200);
+    expect(responseOf(res).body.data.state).toBe('running');
   });
 
   it('returns 503 while booting or shutting down', async () => {
     for (const state of ['idle', 'initializing', 'stopping', 'stopped']) {
       const res = await new HttpDispatcher(kernel(state)).dispatch('GET', '/ready', undefined, undefined, ctx);
-      expect(res.response.status).toBe(503);
+      expect(responseOf(res).status).toBe(503);
     }
   });
 
@@ -57,7 +85,7 @@ describe('HttpDispatcher — GET /ready readiness probe', () => {
         kernel('running', engine([{ driverName: 'sql', healthy: true }])),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
+      expect(responseOf(res).status).toBe(200);
     });
 
     it('returns 503 naming the driver when one is down, even though the kernel runs', async () => {
@@ -68,9 +96,9 @@ describe('HttpDispatcher — GET /ready readiness probe', () => {
         ])),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
-      expect(res.response.body.error.message).toBe('Data driver unavailable');
-      expect(res.response.body.error.details).toEqual({ state: 'running', drivers: ['sql'] });
+      expect(responseOf(res).status).toBe(503);
+      expect(responseOf(res).body.error.message).toBe('Data driver unavailable');
+      expect(responseOf(res).body.error.details).toEqual({ state: 'running', drivers: ['sql'] });
     });
 
     it('does not re-probe within the memo TTL — k8s polls every few seconds', async () => {
@@ -91,14 +119,14 @@ describe('HttpDispatcher — GET /ready readiness probe', () => {
         }),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
+      expect(responseOf(res).status).toBe(200);
     });
 
     it('stays ready on an engine predating checkDriversHealth', async () => {
       const res = await new HttpDispatcher(kernel('running', { find: async () => [] }))
         .dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
+      expect(responseOf(res).status).toBe(200);
     });
   });
 });
@@ -122,21 +150,21 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         kernel('running', engineWithPrimary([{ driverName: 'pg', healthy: false }], primary('pg'))),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
-      expect(res.response.body.error.message).toBe('Data driver unavailable');
+      expect(responseOf(res).status).toBe(503);
+      expect(responseOf(res).body.error.message).toBe('Data driver unavailable');
       // Byte-identical to the shape #3756 shipped — an operator's alerting on
       // this body must not be able to tell that the handler changed.
-      expect(res.response.body.error.details).toEqual({ state: 'running', drivers: ['pg'] });
+      expect(responseOf(res).body.error.details).toEqual({ state: 'running', drivers: ['pg'] });
     });
 
     it('the all-healthy 200 body carries NO degraded key', async () => {
       const res = await new HttpDispatcher(
         kernel('running', engineWithPrimary([{ driverName: 'pg', healthy: true }], primary('pg'))),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
-      expect(res.response.body.data).toEqual({ status: 'ready', state: 'running' });
-      expect(res.response.body.data).not.toHaveProperty('degraded');
+      expect(responseOf(res).status).toBe(200);
+      expect(responseOf(res).body.data).toEqual({ status: 'ready', state: 'running' });
+      expect(responseOf(res).body.data).not.toHaveProperty('degraded');
     });
 
     it('does not even ASK which datasource is primary while everything is healthy', () => {
@@ -164,11 +192,11 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         )),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
-      expect(res.response.body.data.status).toBe('ready');
+      expect(responseOf(res).status).toBe(200);
+      expect(responseOf(res).body.data.status).toBe('ready');
       // ⛔ The rejected fourth option — filtering the bad driver out so it
       // becomes invisible — would show an EMPTY degraded list here.
-      expect(res.response.body.data.degraded).toEqual({
+      expect(responseOf(res).body.data.degraded).toEqual({
         drivers: ['tenant_mongo'],
         primaryDatasource: 'pg',
       });
@@ -182,8 +210,8 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         )),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
-      expect(res.response.body.error.details.drivers).toEqual(['pg']);
+      expect(responseOf(res).status).toBe(503);
+      expect(responseOf(res).body.error.details.drivers).toEqual(['pg']);
     });
 
     it('drains when BOTH are down — the primary is in the unhealthy set', async () => {
@@ -194,8 +222,8 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         )),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
-      expect(res.response.body.error.details.drivers).toEqual(['pg', 'tenant_mongo']);
+      expect(responseOf(res).status).toBe(503);
+      expect(responseOf(res).body.error.details.drivers).toEqual(['pg', 'tenant_mongo']);
     });
   });
 
@@ -215,8 +243,8 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
       const res = await new HttpDispatcher(kernel('running', engine(secondaryDown)))
         .dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
-      expect(res.response.body.error.details).toEqual({
+      expect(responseOf(res).status).toBe(503);
+      expect(responseOf(res).body.error.details).toEqual({
         state: 'running',
         drivers: ['tenant_mongo'],
       });
@@ -228,7 +256,7 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         resolvePrimaryDatasource: () => { throw new Error('registry exploded'); },
       })).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
+      expect(responseOf(res).status).toBe(503);
     });
 
     it.each([
@@ -241,7 +269,7 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         kernel('running', engineWithPrimary(secondaryDown, verdict)),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
+      expect(responseOf(res).status).toBe(503);
     });
 
     it.each([
@@ -255,7 +283,7 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         kernel('running', engineWithPrimary(secondaryDown, verdict)),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(503);
+      expect(responseOf(res).status).toBe(503);
     });
 
     it('NON-VACUITY: the same fixture returns 200 the moment the criterion resolves', async () => {
@@ -265,7 +293,7 @@ describe('HttpDispatcher — GET /ready primary-vs-secondary drain (#13408)', ()
         kernel('running', engineWithPrimary(secondaryDown, primary('pg'))),
       ).dispatch('GET', '/ready', undefined, undefined, ctx);
 
-      expect(res.response.status).toBe(200);
+      expect(responseOf(res).status).toBe(200);
     });
   });
 
@@ -294,8 +322,8 @@ describe('HttpDispatcher — GET /health liveness probe', () => {
     const res = await new HttpDispatcher(kernel('running', e))
       .dispatch('GET', '/health', undefined, undefined, ctx);
 
-    expect(res.response.status).toBe(200);
-    expect(res.response.body.data.status).toBe('ok');
+    expect(responseOf(res).status).toBe(200);
+    expect(responseOf(res).body.data.status).toBe('ok');
     expect(e.checkDriversHealth).not.toHaveBeenCalled();
   });
 });

scripts/check-type-check-coverage.mjs

@@ -901,18 +901,23 @@ const TEST_DEBT = {
       + 'ead731756, which is what the lowering at the top of this note closed.',
   },
   '@objectstack/runtime': {
-    errors: 217,
-    note: 'TS18048 x98 (possibly-undefined), TS2345 x26, TS18046 x20, TS2339 x16, TS2493 x15, TS2835 x11, '
-      + 'TS2554 x11. LOWERED 227 -> 217 at ead731756 (#12723) -- the entry that card was filed on, where '
-      + 'the slack turned out to be 10 rather than the 1 it reported: the 226 it quoted was itself a '
-      + 'reading taken days earlier, which is the card\'s own point about a number that drifts. The tally '
-      + 'above was taken at 227 and is NOT re-tallied here; that sweep measured per-entry TOTALS only. Src '
-      + 'graduated in #4311 (declares `typecheck`); this is purely the hidden test layer. Measured 220 -> '
+    errors: 206,
+    note: 'TS18048 x91 (possibly-undefined), TS18046 x27, TS2339 x17, TS2493 x15, TS2835 x13, TS2345 x10, '
+      + 'TS7006 x8, TS6133 x6, TS2554 x4, TS2353 x4, TS2571 x3, TS2550 x2 -- RE-TALLIED at 206 (#13408). '
+      + 'The previous note carried its composition from a 227-era sweep that measured per-entry TOTALS '
+      + 'only and said so; this one is a fresh per-code count of the same program the ratchet measures. '
+      + 'LOWERED 217 -> 206 (#13408), and the -11 is fully attributed to ONE file: '
+      + 'src/http-dispatcher.ready.test.ts held 30 TS18048 reads of the optional '
+      + '`HttpDispatcherResult.response` -- 19 added by that card\'s own new /ready suite and 11 that '
+      + 'pre-dated it -- and all 30 were replaced by a `responseOf()` narrowing helper, the shape already '
+      + 'used by the #8287 suite in src/http-dispatcher.keys.test.ts. That card found them the hard way: '
+      + 'the package `typecheck` excludes test files, so its green said nothing about the 19 it had just '
+      + 'added, and only this ratchet saw them. Nothing else in the package moved. Earlier lineage: 220 -> '
       + '218 (5ab08428, one of only two entries that ever shrank; TS6133 x25 collapsed to x7 while '
       + 'possibly-undefined grew, so that net -2 hid a much larger churn in both directions) -> 227 '
-      + '(e8db1a230). The latest +9 is fully attributed and is ONE file: every one of the nine is a '
-      + 'TS18048 in src/domains/meta-item-envelope.test.ts, added by #5563 / PR #5895 (the '
-      + '`GET /meta/:type/:name` envelope convergence). Nothing else in the package moved.',
+      + '(e8db1a230, +9 all TS18048 in src/domains/meta-item-envelope.test.ts from #5563 / PR #5895) -> '
+      + '217 (ead731756, #12723). Src graduated in #4311 (declares `typecheck`); this is purely the '
+      + 'hidden test layer.',
   },
   '@objectstack/cli': {
     errors: 144,