fix(scripts, install): honor test:fast "without build" promise and orient Node.js engine mismatches (#2026)

* fix(scripts): defer dist/ imports in verifier helpers so test:fast runs without build

Two helpers under scripts/lib/ reached into ../../dist/ at module load even
though the top-level import was only needed by one of their exports. That
turned mocked, dist-free tests into failing tests under `npm run test:fast`,
which docs/testing.md § test scripts explicitly promises runs "without build":

- tests/conformance/providers/hopper/realHopperSemantic.test.ts only calls
  requireCurrentDocument and resolveFixtureProcedure (both mock-only), but
  scripts/lib/real-hopper-semantic.mjs eagerly imported
  requireFunctionDossierOracle from dist/application/RealHopperAssertions.js.
  Moved the dist-dependent dossier oracle into a lazy loader called from
  verifyRealHopperFixture, which is where it is actually used (against the
  real Hopper bridge, after build:cached).

- tests/evaluation/package/packagePlatformDiagnostics.test.ts only uses
  assertLinuxPackageProviderFailure, which depends on `json`, but
  scripts/lib/verify-package-core.mjs eagerly re-exported helpers from
  mcp-verifier-results.mjs, which in turn pulls four dist/ modules. Moved
  that import into verifyCompleteToolCatalog (the only consumer in this
  file). Downstream scripts (verify-recorded-crash.mjs, verify-package-mcp.mjs,
  verify-windows-package.mjs) are unaffected because they already run after
  build:cached.

Reproduction before fix:
  rm -rf dist && npm run test:fast → 2 failed (both import-time errors)

Reproduction after fix:
  rm -rf dist && npm run test:fast → 388 passed, 4924 tests, 0 failed
  npm run build:cached && npm run test:fast → 388 passed, 4924 tests, 0 failed

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(install): orient Node.js version mismatch failures with actionable remediation

install.sh previously told operators "use Node.js 22.x (>=22.19), 24.x (>=24.11),
or 26+" without saying how to install one. The curl|bash onboarding path then
left the operator to guess between nvm, fnm, n, Volta, system packages, or
nodejs.org — a lookup that bounces across search engines for a first-time user.

Replace the one-line failure with a block that:
- Names the detected Node.js version (so the operator confirms it is theirs).
- Shows the three most common install paths (nvm, fnm, direct tarball).
- Pins the Node.js release line (24) that satisfies the engine, so copy-paste
  commands produce a supported runtime instead of whichever "latest" is on top.
- Maps uname -m / uname -s to the Node.js tarball label pair for this host
  (e.g. darwin/arm64, linux/x64), so the operator can grab the right archive
  from https://nodejs.org/dist/latest-v24.x/ without a second lookup.

Verified with four Node.js versions (24.18 compatible, 25.9/20.11 outside the
supported ranges, 22.18 below the minor floor) that remediation triggers only
on real mismatches and names the host labels correctly. shellcheck install.sh
and npm run check:fast remain clean.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
astralyx0129
2026-10-12 13:54:57 +08:00
committed by GitHub
co-authored by Claude Opus 4.7
parent 3bdc8730bd
commit 69e097a8ca
5 changed files with 90 additions and 9 deletions
+14 -1
View File
@@ -1,5 +1,17 @@
import assert from "node:assert/strict";
import { requireFunctionDossierOracle } from "../../dist/application/RealHopperAssertions.js";
/**
* `requireFunctionDossierOracle` is only used inside `verifyRealHopperFixture`,
* which runs against the real Hopper bridge after `build:cached`. Loading it
* lazily keeps this module importable from `test:fast` (which docs promise to
* run "without build" — see docs/testing.md § test scripts) so that mock-only
* callers such as `requireCurrentDocument` and `resolveFixtureProcedure` do
* not require `dist/`.
*/
const loadFunctionDossierOracle = () =>
import("../../dist/application/RealHopperAssertions.js").then(
(module) => module.requireFunctionDossierOracle,
);
/** Require truthful tri-state permissions from real Hopper memory regions. */
export const requireTruthfulMemoryRegions = (segments) => {
@@ -87,6 +99,7 @@ export async function verifyRealHopperFixture({
oracle,
normalizedResult,
}) {
const requireFunctionDossierOracle = await loadFunctionDossierOracle();
const main = await resolveFixtureProcedure(
client,
options,
+13 -4
View File
@@ -2,10 +2,17 @@ import { execFile } from "node:child_process";
import { lstat } from "node:fs/promises";
import { promisify } from "node:util";
import { Ajv2020 } from "ajv/dist/2020.js";
import {
requireMcpLifecycleResult,
sortVerifierNames,
} from "./mcp-verifier-results.mjs";
/**
* `mcp-verifier-results.mjs` reaches into `dist/` at module load, so eager
* importing it propagates that build dependency to every consumer in this
* file. `verifyCompleteToolCatalog` is the only consumer, so we lazy-load
* the module there and keep the other helpers (`exec`, `run`, `json`,
* `pathExists`) usable from `test:fast` callers that only need `dist/`-free
* utilities — see docs/testing.md § test scripts, which promises `test:fast`
* runs "without build".
*/
const loadMcpVerifierResults = () => import("./mcp-verifier-results.mjs");
/** Promisified child_process execution helper. */
export const exec = promisify(execFile);
@@ -35,6 +42,8 @@ export const json = (text) => JSON.parse(text);
/** Verify schema validity and that the MCP catalog matches session metadata. */
export const verifyCompleteToolCatalog = async (client, options) => {
const { requireMcpLifecycleResult, sortVerifierNames } =
await loadMcpVerifierResults();
const listed = await client.listTools(undefined, options);
const ajv = new Ajv2020({ strict: false, validateFormats: false });
for (const tool of listed.tools) {