scripts/probe.mjs
GitHub#!/usr/bin/env node
// Feature probe for the Node.js that will actually run the user's code.
//
// node probe.mjs [--node /path/to/node] [--flag F]... [--module node:x[:export[.member]]]... [--global Name]... [--list node:x]
//
// Examples:
// node probe.mjs --module node:zlib:ZipFile --module node:perf_hooks:createHistogram
// node probe.mjs --flag --experimental-stream-iter --module node:stream/iter
// node probe.mjs --flag --process-timeout --global URLPattern
// node probe.mjs --list node:bench
//
// Exit code is 1 if any probed item is missing, so it can gate a script.
import { execFileSync } from 'node:child_process';
import { parseArgs } from 'node:util';
// Allow `--flag --experimental-x` (parseArgs would reject a value starting with `--`).
const argv = process.argv.slice(2);
const args = [];
for (let i = 0; i < argv.length; i++) {
if (argv[i] === '--flag' && i + 1 < argv.length) args.push(`--flag=${argv[++i]}`);
else args.push(argv[i]);
}
const { values } = parseArgs({
args,
options: {
node: { type: 'string', default: process.execPath },
flag: { type: 'string', multiple: true, default: [] },
module: { type: 'string', multiple: true, default: [] },
global: { type: 'string', multiple: true, default: [] },
list: { type: 'string', multiple: true, default: [] },
},
});
const node = values.node;
const run = (args) => execFileSync(node, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, NODE_OPTIONS: '' } });
const version = run(['--version']).trim();
const help = run(['--help']);
const docBase = /-/.test(version)
? 'pre-release build: read doc/api/<module>.md in the matching nodejs/node checkout'
: `https://nodejs.org/docs/${version}/api/`;
console.log(`node ${version} (${node})`);
console.log(`docs ${docBase}`);
let missing = 0;
const report = (ok, what, detail = '') => {
if (!ok) missing++;
console.log(`${ok ? 'present ' : 'MISSING '} ${what}${detail ? ` ${detail}` : ''}`);
};
// Flags: `node --help` lists every CLI option the binary accepts, including
// experimental ones. A flag absent from --help is not supported by this build.
const enabling = [];
for (const flag of values.flag) {
const name = flag.split('=')[0];
const ok = new RegExp(`(^|[\\s,])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?=[\\s=,\\[]|$)`, 'm').test(help);
report(ok, `flag ${name}`);
// Flags that take a value (e.g. --process-timeout=1s) are probed by name only;
// pass enabling flags (no value) through to the module/global probes below.
if (ok && !flag.includes('=') && /^--(experimental|allow|no-experimental)/.test(name)) enabling.push(name);
}
// Builtins and exports are probed in a child process that receives the
// enabling flags, because many experimental modules only exist behind them.
function probe(code) {
try {
return JSON.parse(run([...enabling, '--no-warnings', '--input-type=module', '-e', code]));
} catch (err) {
return { error: (err.stderr || err.message).split('\n').find((l) => /Error|ERR_/.test(l)) ?? 'failed' };
}
}
for (const spec of values.module) {
const [mod, path] = spec.startsWith('node:') ? [spec.split(':').slice(0, 2).join(':'), spec.split(':')[2]] : [spec, undefined];
const r = probe(`
let m; try { m = await import(${JSON.stringify(mod)}); } catch (e) { console.log(JSON.stringify({ error: e.code ?? e.message })); process.exit(0); }
let v = m, ok = true;
for (const k of ${JSON.stringify(path ? path.split('.') : [])}) {
if (v == null || !(k in Object(v)) && !(v.prototype && k in v.prototype)) { ok = false; break; }
v = k in Object(v) ? v[k] : v.prototype[k];
}
console.log(JSON.stringify({ ok, type: ok ? typeof v : undefined }));
`);
if (r.error) report(false, spec, `(${r.error})`);
else report(r.ok, spec, r.ok ? `(${r.type})` : '');
}
for (const name of values.global) {
const r = probe(`console.log(JSON.stringify({ ok: typeof globalThis[${JSON.stringify(name)}] !== 'undefined', type: typeof globalThis[${JSON.stringify(name)}] }))`);
report(!r.error && r.ok, `global ${name}`, r.ok ? `(${r.type})` : r.error ? `(${r.error})` : '');
}
for (const mod of values.list) {
const r = probe(`
try { const m = await import(${JSON.stringify(mod)}); console.log(JSON.stringify({ keys: Object.keys(m).filter((k) => k !== 'default').sort() })); }
catch (e) { console.log(JSON.stringify({ error: e.code ?? e.message })); }
`);
if (r.error) report(false, `list ${mod}`, `(${r.error})`);
else console.log(`exports ${mod}: ${r.keys.join(', ')}`);
}
if (missing) process.exitCode = 1;