chore(tools): check:internals recognises the test kit's makeRequestContext - #1246

devcorner: rango-t155 · session rango-s284

Problem

Rule 1 of tools/check-internals.mjs (request-context-object-create) recognised a RequestContext only through getRequestContext, _getRequestContext, createRequestContext, an annotation, or a same-file helper. The internal test kit's makeRequestContext (src/__tests__/kit/request-context.ts, landed in S1) is imported from another file, so Object.create(makeRequestContext(...)) in a test was invisible to the ratchet. cache-scope.test.ts and build-version-table.test.ts carried a : RequestContext annotation with a "Typed so check-internals counts the Object.create below" comment to keep their counts honest; without it the check reported "baseline 1, now 0" although the Object.create was still there (finding rango-t131-c1, confirmed in rango-t131-c2).

No router behaviour changes: the only src/ edits drop two type annotations and one now-unused type import in tests.

Before / after (internal shape)

Before:

// Typed so check-internals counts the Object.create below.
const ctx: RequestContext = makeRequestContext({ url: EXAMPLE_URL, versions });
const derived = Object.create(ctx) as typeof ctx;

After:

const ctx = makeRequestContext({ url: EXAMPLE_URL, versions });
const derived = Object.create(ctx) as typeof ctx; // counted

Code changes

• tools/check-internals.mjs
  • KIT_REQUEST_CONTEXT_FACTORY / KIT_REQUEST_CONTEXT_MODULE: the kit factory is matched by import, not by name. callIsRequestContext falls through to importsKitFactoryAs(sf, local) when the callee identifier has no same-file declaration; it accepts import { makeRequestContext } or import { makeRequestContext as x } whose relative specifier resolves (extension stripped) to packages/rangojs-router/src/__tests__/kit/request-context. A same-named function from another module, a local declaration that shadows the import, and a method call obj.makeRequestContext() are not matched.
  • resolveRelative(importer, specifier) is extracted from importsBrowser (rule 4) and shared by both rules; rule 4's behaviour is unchanged.
  • Header comment: the kit factory is listed among the recognised sources; a namespace import of the kit is added to the known misses.
• tools/check-internals.test.mjs: two tests.
  • Positive: the kit factory through a named import, an aliased import, an extensionless specifier, a variable, and a deeper importer (cache/cf/__tests__).
  • Negative: a makeRequestContext imported from ./helpers.js, one from a look-alike ./kit/request-context.js that resolves elsewhere, a method call, a local binding that shadows the kit import, and a same-file function of that name returning a plain object (the shape of cache-key.test.ts).
• src/cache/__tests__/cache-scope.test.ts, src/server/__tests__/build-version-table.test.ts: the compensating annotations and their comments are dropped; build-version-table.test.ts loses its now-unused type RequestContext import.

Test plan

• node tools/check-internals.mjs: OK, 3389 files scanned; request-context-object-create 21, internal-vi-mock 327, rsc-param-literal 71, browser-import-into-server 1. Baseline unchanged; no count moved.
• Red before green on the repo: the base checker run against this tree reports cache-scope.test.ts baseline 1, now 0 and build-version-table.test.ts baseline 1, now 0 (FAILED, 2 below the baseline); this checker passes.
• Red before green on the unit tests: with the base checker the positive test fails (26/27); with a name-only variant (makeRequestContext added to REQUEST_CONTEXT_FACTORIES) both new tests fail (25/27); with this checker 27/27 pass.
• node --test tools/*.test.mjs: 53/53 pass.
• vitest run src/cache/__tests__/cache-scope.test.ts src/server/__tests__/build-version-table.test.ts: 2 files, 64 tests pass.
• pnpm run typecheck: 16/16 tasks pass.
• oxlint --deny-warnings: 0 warnings, 0 errors. oxfmt --check .: clean.
• test:unit:all not run: the only src/ change removes type annotations and a type import in the two test files above, which were run directly. No e2e: no runtime code changes.

Practices

• Lint: oxlint --deny-warnings and oxfmt --check . on the whole repo; nothing found.
• Dead code: the type RequestContext import in build-version-table.test.ts became unused and is removed; cache-scope.test.ts still uses it (a parameter at line 613), so it stays. The inline path resolution in importsBrowser is replaced by the shared resolveRelative, so no duplicate is left. Nothing else is left without callers.
• Tests: two new node:test cases pin the import-scoped match (positive and negative), each shown red against the base checker and a name-only variant; the two touched vitest files pass.
• Code review: the diff was reviewed by hand for correctness (shadowing, aliases, extensionless and nested specifiers, rule 4 parity after the extraction) and for reuse. Left: a namespace import (import * as kit) of the kit is not recognised; no test uses one, and it is recorded in the header's known misses.
• Docs: the rule's documentation is the header of tools/check-internals.mjs, updated here. AGENTS.md already names the test kit as the seam and pnpm check:internals as the check; nothing else needs changing.

Notes

• Matching stays syntax-only: the import is resolved by path, not by the TypeScript program, consistent with the rest of the check.