fix(scripts): report an unmet prerequisite instead of dying with a module stack (#11824)

A fresh per-task worktree has no `node_modules` until `pnpm install` runs. The
gates in `scripts/` that import `typescript`, `yaml`, `semver`, `eslint` or
`github-slugger` used to answer that with a node-internals `ERR_MODULE_NOT_FOUND`
stack trace, which reads exactly like a real finding: same exit 1, no statement
that nothing was measured. Twenty-nine root gates did this, measured on one tree.

The failure is thrown while node LINKS the module graph, which completes before
any module body runs, so a preflight imported at the top of a gate never
executes. The failing imports are therefore deferred behind a thunk the gate
hands to a shared helper, which is the one shape that puts a catchable boundary
around them.

`scripts/import-prerequisite.mjs` classifies four failures that arrive wearing
the same error code and keeps them apart, because they have different remedies:
a package with no directory (`pnpm install`), a `@objectstack/*` package present
but never built (build it — including via node's self-reference resolution, which
a node_modules-only walk misses and would misreport as uninstalled), a partial
install, and a package that resolved and then threw — the last rethrown untouched
so its stack survives.

Wording follows `check-i18n-coverage.mjs`'s `reportPrerequisiteNotMet`: what is
unmet, why, the command that clears it, and that nothing was measured. Following
`cli-build-prerequisite.mjs`, the frame is shared and the claim about what went
unmeasured stays with the gate.

No gate's measurement changes; only how an unmet precondition is reported. Every
affected gate still produces its normal verdict on a built tree.


Claude-Session: https://claude.ai/code/session_015ahemw8RcTgqtxrj15PEZx

Co-authored-by: Claude <noreply@anthropic.com>

Author: os-steve

packages/lint/scripts/check-doc-formula-expressions.mjs

@@ -151,18 +151,19 @@ import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import { join, relative, resolve, sep, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import ts from 'typescript';
-import {
+import { requireDefaultExport, requireDependency } from '../../../scripts/import-prerequisite.mjs';
+const ts = await requireDefaultExport('typescript', () => import('typescript'), import.meta.url);
+const {
   validateExpression,
   isSupportedRlsExpression,
   sqlPredicateToCel,
   isPushdownableCel,
-} from '@objectstack/formula';
+} = await requireDependency('@objectstack/formula', () => import('@objectstack/formula'), import.meta.url);
 // The field-level `*When` root verdict AND its message, imported from the one
 // place that owns them (#11407). Same discipline as `validateExpression` above:
 // this gate is the SECOND consumer of that rule, and a second consumer that
 // re-derives the rule owns a dialect of it instead. See surface 3 below.
-import { fieldRuleRootIssue, FIELD_RULE_BOUND_ROOTS } from '@objectstack/lint';
+const { fieldRuleRootIssue, FIELD_RULE_BOUND_ROOTS } = await requireDependency('@objectstack/lint', () => import('@objectstack/lint'), import.meta.url);
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(HERE, '../../..');

packages/lint/scripts/check-doc-security-posture.mjs

@@ -123,8 +123,9 @@ import { join, relative, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 
-import ts from 'typescript';
-import { validateSecurityPosture, SECURITY_CBP_NO_RELATION } from '@objectstack/lint';
+import { requireDefaultExport, requireDependency } from '../../../scripts/import-prerequisite.mjs';
+const ts = await requireDefaultExport('typescript', () => import('typescript'), import.meta.url);
+const { validateSecurityPosture, SECURITY_CBP_NO_RELATION } = await requireDependency('@objectstack/lint', () => import('@objectstack/lint'), import.meta.url);
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = resolve(HERE, '../../..');

scripts/check-aggregator-roster.mjs

@@ -80,6 +80,7 @@
  * naming what could not be read (#4690). The self-test pins each refusal.
  */
 
+import { requireDependency } from './import-prerequisite.mjs';
 import { readFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -324,7 +325,7 @@ export function judge({ workflows }) {
 
 /** Read and parse both workflows into the shape `judge` consumes. */
 export async function readWorkflows(root) {
-  const { parse } = await import('yaml');
+  const { parse } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
   const workflows = new Map();
   for (const file of WORKFLOW_FILES) {
     const path = join(root, '.github', 'workflows', file);
@@ -381,7 +382,7 @@ async function selfTest() {
   };
 
   const root = scriptRepoRoot();
-  const { parse } = await import('yaml');
+  const { parse } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
   const sources = Object.fromEntries(
     WORKFLOW_FILES.map((file) => [file, readFileSync(join(root, '.github', 'workflows', file), 'utf8')]),
   );

scripts/check-ci-filter-parity.mjs

@@ -120,7 +120,8 @@ import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import process from 'node:process';
 
-import { parse } from 'yaml';
+import { requireDependency } from './import-prerequisite.mjs';
+const { parse } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
 
 import { CROSS_PACKAGE_TEST_INPUTS } from './check-cross-package-test-inputs.mjs';
 import { isEntrypoint } from './invoked-as.mjs';

scripts/check-cli-test-child-env.mjs

@@ -160,7 +160,8 @@ import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import ts from 'typescript';
+import { requireDefaultExport } from './import-prerequisite.mjs';
+const ts = await requireDefaultExport('typescript', () => import('typescript'), import.meta.url);
 
 import { isEntrypoint } from './invoked-as.mjs';
 import { parseSourceFile } from './ts-parse.mjs';

scripts/check-closing-keyword-parity.mjs

@@ -98,7 +98,8 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { parseDocument } from 'yaml';
+import { requireDependency } from './import-prerequisite.mjs';
+const { parseDocument } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
 import { isEntrypoint } from './invoked-as.mjs';
 
 const SELF = 'scripts/check-closing-keyword-parity.mjs';

scripts/check-cross-repo-closer-outcome.mjs

@@ -120,7 +120,8 @@ import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { isMap, isSeq, parseDocument } from 'yaml';
+import { requireDependency } from './import-prerequisite.mjs';
+const { isMap, isSeq, parseDocument } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
 import { isEntrypoint } from './invoked-as.mjs';
 
 const WORKFLOW = '.github/workflows/cross-repo-issue-closer.yml';

scripts/check-doc-anchors.mjs

@@ -119,7 +119,8 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, join, relative, resolve } from 'node:path';
-import Slugger from 'github-slugger';
+import { requireDefaultExport } from './import-prerequisite.mjs';
+const Slugger = await requireDefaultExport('github-slugger', () => import('github-slugger'), import.meta.url);
 
 import { stripCodeSpans, stripFencedBlocks } from './check-adr-links.mjs';
 import { isEntrypoint } from './invoked-as.mjs';

scripts/check-doc-frontmatter.mjs

@@ -147,7 +147,8 @@ import { createRequire } from 'node:module';
 import { join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
-import { parse, parseDocument } from 'yaml';
+import { requireDependency } from './import-prerequisite.mjs';
+const { parse, parseDocument } = await requireDependency('yaml', () => import('yaml'), import.meta.url);
 
 import { isEntrypoint } from './invoked-as.mjs';
 

scripts/check-driver-memory-census.mjs

@@ -107,7 +107,8 @@ import { readFileSync, readdirSync, existsSync } from 'node:fs';
 import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync } from 'node:child_process';
-import ts from 'typescript';
+import { requireDefaultExport } from './import-prerequisite.mjs';
+const ts = await requireDefaultExport('typescript', () => import('typescript'), import.meta.url);
 import { parseSourceFile } from './ts-parse.mjs';
 import { isEntrypoint } from './invoked-as.mjs';