Context
#22 (partial fix
for #19) ships @types/node@24.12.2 and sets engines.node: >=22.0.0,
but the CI test matrix stays on Node 22 only. Node 24 is blocked on an
upstream tree-sitter compile failure.
The blocker
tree-sitter@0.25.0 (current latest on npm) fails to build against
Node 24's V8 ABI. The reported errors live in the @types/node V8
headers — v8::Template::Set(...) signature, ReadExternalPointerField
template deduction, ConditionalStackAllocatedBase incomplete type, and
the node-addon-api / napi class shims. There are no prebuilt binaries
in the 0.25.0 tarball, so pnpm falls through to a source compile.
The fix is already merged upstream and tagged:
Both issues were open as of 2026-04-21. We have no visibility into an
estimated fix date.
What to do when tree-sitter@0.25.1 lands on npm
Diff is essentially a one-line revert of #22:
# .github/workflows/ci.yml — test job
strategy:
fail-fast: false
matrix:
os: [ubuntu-latest, macos-latest, windows-latest]
node: [22, 24]
runs-on: ${{ matrix.os }}
env:
MISE_NODE_VERSION: ${{ matrix.node }}
Then:
Escape hatches if upstream stays blocked
If tree-sitter/node-tree-sitter#276 doesn't resolve within ~8 weeks,
evaluate one of:
- Pin to the git tag:
"tree-sitter": "github:tree-sitter/node-tree-sitter#v0.25.1"
in any package.json that depends on it. Ugly — we'd be pulling a git
ref, not a signed npm artifact — and the OSS supply-chain story gets
murkier (osv-scanner and license-checker behave differently against
git refs vs. registry artifacts).
- Switch to
web-tree-sitter (the WASM build). No V8 ABI
dependency, works in both Node and browser contexts. But this is a
real refactor touching the scanner ingestion layer and would need its
own PR with careful testing.
- Stay on Node 22 and wait. Node 22 is maintenance LTS through
2027-04, so this is a viable hold position if upstream continues to
stall.
Option 1 is the minimal-diff escape hatch. Option 2 is the long-term
answer regardless, since WASM sidesteps every future Node-major V8 ABI
churn.
Acceptance
Context
#22 (partial fix
for #19) ships
@types/node@24.12.2and setsengines.node: >=22.0.0,but the CI test matrix stays on Node 22 only. Node 24 is blocked on an
upstream
tree-sittercompile failure.The blocker
tree-sitter@0.25.0(current latest on npm) fails to build againstNode 24's V8 ABI. The reported errors live in the
@types/nodeV8headers —
v8::Template::Set(...)signature,ReadExternalPointerFieldtemplate deduction,
ConditionalStackAllocatedBaseincomplete type, andthe
node-addon-api/ napi class shims. There are no prebuilt binariesin the 0.25.0 tarball, so pnpm falls through to a source compile.
The fix is already merged upstream and tagged:
— "tree-sitter C++20 requirements with node 24 and missing prebuilds"
(git tag
v0.25.1)— the 0.25.1 npm publish has been failing since June 2025 due to an
OIDC Trusted Publishing misconfiguration
Both issues were open as of 2026-04-21. We have no visibility into an
estimated fix date.
What to do when tree-sitter@0.25.1 lands on npm
Diff is essentially a one-line revert of #22:
Then:
mise.toml→node = "24"(local-dev default flips to active LTS).nvmrc/.node-version→24pnpm -r testgreen on all 6 matrix rows (3 OS × 2 Node versions)gh api -X PATCH /repos/theagenticguy/opencodehub/branches/main/protection/required_status_checksto add
test (ubuntu-latest, 22),test (ubuntu-latest, 24), etc.and drop the single-axis rows
Escape hatches if upstream stays blocked
If
tree-sitter/node-tree-sitter#276doesn't resolve within ~8 weeks,evaluate one of:
"tree-sitter": "github:tree-sitter/node-tree-sitter#v0.25.1"in any package.json that depends on it. Ugly — we'd be pulling a git
ref, not a signed npm artifact — and the OSS supply-chain story gets
murkier (osv-scanner and license-checker behave differently against
git refs vs. registry artifacts).
web-tree-sitter(the WASM build). No V8 ABIdependency, works in both Node and browser contexts. But this is a
real refactor touching the scanner ingestion layer and would need its
own PR with careful testing.
2027-04, so this is a viable hold position if upstream continues to
stall.
Option 1 is the minimal-diff escape hatch. Option 2 is the long-term
answer regardless, since WASM sidesteps every future Node-major V8 ABI
churn.
Acceptance
tree-sitter@0.25.1+available on npm (upstream unblock)node: [22, 24]× all three OSesmise.toml/.nvmrc/.node-versionflipped to Node 24pnpm -r testgreen on all 6 matrix rows