From b47c9562eccc231c1436258ced8de61dac328474 Mon Sep 17 00:00:00 2001 From: Colby Mchenry Date: Fri, 8 May 2026 08:54:32 -0500 Subject: [PATCH] fix(cli): hard-exit on Node 25.x instead of soft warning + crash (#149) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Node 25.x V8 turboshaft WASM JIT Zone allocator bug (https://github.com/colbymchenry/codegraph/issues/81) reliably crashes CodeGraph mid-indexing with `Fatal process out of memory: Zone` when tree-sitter grammars get JIT-compiled. We already had: - `engines: "node": ">=18.0.0 <25.0.0"` in package.json - Lazy grammar loading (#61) - A startup `console.warn` when Node 25+ is detected But the recurring duplicates (#54, #81, #140, plus comments from multiple unique users) show those defenses aren't enough: - npm `engines` is a soft warning by default, so `npm install -g` doesn't block. - The startup `console.warn` is a single yellow line that scrolls off-screen before the OOM 30 seconds later, so users connect the crash to "CodeGraph is broken" rather than "I'm on the wrong Node version" and file a fresh issue. This patch turns the soft warning into a hard exit. On Node 25+ we print a bordered banner that names the V8 root cause, embeds the detected version, gives Node 22 LTS install commands (nvm + Homebrew), and links to #81 — then exit(1) BEFORE any tree-sitter import triggers WASM JIT. The previous behaviour is preserved behind `CODEGRAPH_ALLOW_UNSAFE_NODE=1` for anyone who patched V8 themselves or wants to test a future Node 25 fix. The banner builder is extracted to `src/bin/node-version-check.ts` so the test can import it without triggering CLI bootstrap. Five unit tests pin the version interpolation, root-cause explanation, recovery commands (nvm + brew), override env var, and #81 link — these are load-bearing and shouldn't get edited away silently. Suite: 509 → 514, all passing. Verified both paths manually by flipping the threshold to 22 in dist and running on Node 22.20.0: without the env var the CLI prints the banner and exits 1; with `CODEGRAPH_ALLOW_UNSAFE_NODE=1` it prints the banner and continues. Co-authored-by: Claude Opus 4.7 (1M context) --- __tests__/node-version-check.test.ts | 43 ++++++++++++++++++++++++++++ src/bin/codegraph.ts | 25 +++++++++------- src/bin/node-version-check.ts | 36 +++++++++++++++++++++++ 3 files changed, 93 insertions(+), 11 deletions(-) create mode 100644 __tests__/node-version-check.test.ts create mode 100644 src/bin/node-version-check.ts diff --git a/__tests__/node-version-check.test.ts b/__tests__/node-version-check.test.ts new file mode 100644 index 0000000..d7b725c --- /dev/null +++ b/__tests__/node-version-check.test.ts @@ -0,0 +1,43 @@ +/** + * Pin the Node-25 block banner content. The banner replaced a soft + * `console.warn` because the warning was scrolling off-screen before + * the OOM crash 30 seconds later, generating duplicate bug reports + * (#54, #81, #140). The recipe and override env var below are + * load-bearing — if any of them get edited away, this test catches it. + */ + +import { describe, it, expect } from 'vitest'; +import { buildNode25BlockBanner } from '../src/bin/node-version-check'; + +describe('buildNode25BlockBanner', () => { + it('embeds the reported Node version in the header', () => { + expect(buildNode25BlockBanner('25.9.0')).toContain( + 'Unsupported Node.js version: 25.9.0' + ); + }); + + it('names the V8 turboshaft WASM root cause and the OOM symptom', () => { + const banner = buildNode25BlockBanner('25.7.0'); + expect(banner).toContain('V8 WASM JIT'); + expect(banner).toContain('turboshaft'); + expect(banner).toContain('Fatal process out of memory: Zone'); + }); + + it('points users to Node 22 LTS via nvm and Homebrew', () => { + const banner = buildNode25BlockBanner('25.7.0'); + expect(banner).toContain('Node.js 22 LTS'); + expect(banner).toContain('nvm install 22'); + expect(banner).toContain('brew install node@22'); + }); + + it('documents the CODEGRAPH_ALLOW_UNSAFE_NODE override', () => { + const banner = buildNode25BlockBanner('25.7.0'); + expect(banner).toContain('CODEGRAPH_ALLOW_UNSAFE_NODE=1'); + }); + + it('links to issue #81 for the root-cause writeup', () => { + expect(buildNode25BlockBanner('25.7.0')).toContain( + 'github.com/colbymchenry/codegraph/issues/81' + ); + }); +}); diff --git a/src/bin/codegraph.ts b/src/bin/codegraph.ts index f29b846..8ee7a6f 100644 --- a/src/bin/codegraph.ts +++ b/src/bin/codegraph.ts @@ -24,6 +24,8 @@ import * as fs from 'fs'; import { getCodeGraphDir, isInitialized } from '../directory'; import { createShimmerProgress } from '../ui/shimmer-progress'; +import { buildNode25BlockBanner } from './node-version-check'; + // Lazy-load heavy modules (CodeGraph, runInstaller) to keep CLI startup fast. async function loadCodeGraph(): Promise { try { @@ -44,20 +46,21 @@ async function loadCodeGraph(): Promise { const importESM = new Function('specifier', 'return import(specifier)') as (specifier: string) => Promise; -// Warn about unsupported Node.js versions (Node 25+ has V8 turboshaft WASM bugs) +// Block CodeGraph on Node.js 25.x — V8's turboshaft WASM JIT has a Zone +// allocator bug that reliably crashes when compiling tree-sitter +// grammars (see #54, #81, #140). The previous behaviour was a soft +// console.warn that scrolls off-screen before the OOM crash 30 seconds +// later, leading to a steady stream of "what is this OOM" reports. +// Hard-exit before any WASM work; allow override via env var for users +// who patched V8 themselves or want to test a future fix. const nodeVersion = process.versions.node; const nodeMajor = parseInt(nodeVersion.split('.')[0] ?? '0', 10); if (nodeMajor >= 25) { - console.warn( - '\x1b[33m⚠\x1b[0m CodeGraph may crash on Node.js %s due to a V8 WASM compiler bug in Node 25+.', - nodeVersion - ); - console.warn( - ' Please use Node.js 22 LTS instead: https://nodejs.org/en/download' - ); - console.warn( - ' See: https://github.com/colbymchenry/codegraph/issues/81\n' - ); + process.stderr.write(buildNode25BlockBanner(nodeVersion) + '\n'); + if (!process.env.CODEGRAPH_ALLOW_UNSAFE_NODE) { + process.exit(1); + } + // Override active — banner shown for visibility, continuing. } // Check if running with no arguments - run installer diff --git a/src/bin/node-version-check.ts b/src/bin/node-version-check.ts new file mode 100644 index 0000000..6aed161 --- /dev/null +++ b/src/bin/node-version-check.ts @@ -0,0 +1,36 @@ +/** + * Node.js version compatibility check. + * + * Node 25.x has a V8 turboshaft WASM JIT Zone allocator bug that + * reliably crashes CodeGraph with `Fatal process out of memory: Zone` + * during tree-sitter grammar compilation. This module owns the + * user-facing banner shown before exit. Kept side-effect-free so it's + * safe to import from tests without triggering CLI bootstrap. + */ + +/** + * Build the bordered banner shown when CodeGraph detects an + * unsupported Node.js major version (currently 25+). Pinned via unit + * test so the recovery commands and override instructions can't be + * silently stripped by future edits. + */ +export function buildNode25BlockBanner(nodeVersion: string): string { + const sep = '─'.repeat(72); + return [ + sep, + `[CodeGraph] Unsupported Node.js version: ${nodeVersion}`, + sep, + 'Node.js 25.x has a V8 WASM JIT (turboshaft) Zone allocator bug that', + 'crashes with `Fatal process out of memory: Zone` when CodeGraph', + 'compiles tree-sitter grammars. CodeGraph WILL crash on this Node', + 'version mid-indexing. See https://github.com/colbymchenry/codegraph/issues/81', + '', + 'Fix: install Node.js 22 LTS:', + ' nvm install 22 && nvm use 22 # nvm', + ' brew install node@22 && brew link --overwrite --force node@22 # Homebrew', + '', + 'To override (NOT recommended — you will likely OOM):', + ' CODEGRAPH_ALLOW_UNSAFE_NODE=1 codegraph ...', + sep, + ].join('\n'); +}