fix: JavaScript extensions scale to a large corpus

[gennaroprota]

A JavaScript extension could not read the corpus of a large project. Reading ctx.corpus.symbols was enough to cause the process to die with an access violation and no diagnostic. Two bugs were behind it, one in how the interpreter is set up and one in how an array reaches it, and a third change makes the limit the script ran into visible.

Changes

• Source:
  • jerry_port_context_alloc now returns the allocated size, not a pointer to the allocated block. jerry_init asks the port for a block to hold the context and the heap, and takes the size of that block from what the call returns. We returned a pointer, instead, so the engine read an address as a length, believed it had a much larger heap than it had, and wrote past the 512 KiB it really had.
  • Running out of JavaScript heap says so. The engine's default behavior on a fatal condition is to end the process with a bare failure code. Our jerry_port_fatal now says what happened and where the limit is, so the author of the script can see what they ran into.
  • A JavaScript extension can read a corpus of any size. An array was converted to JavaScript element by element, up front. Each element that is an object cost an interpreter object of its own, and the interpreter's heap is a fixed 512 KiB that a build cannot simply enlarge, since 16-bit compressed pointers cap it there, so a few thousand symbols filled it. An array now reaches JavaScript through a proxy, as an object already did, and an element is converted when a script reads it, so what a script holds has to fit rather than the whole corpus.
• Tests: A unit test reads an array far larger than the heap could hold as JavaScript objects, and checks its length and the sum of its elements.
• Breaking changes: The heap limit is now enforced. A script that went past it could appear to work while writing into memory that was not the interpreter's; it now stops with the out-of-memory message.

Testing

The new unit test in tests/unit/Engines/JavaScript.cpp covers the lazy conversion. On develop, it crashes with an access violation; with the first two commits and not the third, it ends with the out-of-memory message; with all three it passes. The existing unit tests that pin the snapshot semantics of a converted array, including that a script's writes do not reach the DOM, pass unchanged.

The out-of-memory message itself ends the process, so no test asserts it in-process; it was checked by running the test above without the third commit.

Our own schema generator, docs/mrdocs/extensions/schema.js, now runs within the enforced heap for the first time. Run as the schema-check test runs it, it still produces artifacts byte-identical to the committed ones.

Documentation

Not needed. The documentation never described the heap or the workaround, and the obvious loop over ctx.corpus.symbols that the example extensions use now works on a large corpus. The out-of-memory message states the limit where a script meets it.

Fixes #1294.

[github-actions]

✨ Highlights

• 🧪 New golden tests added

🧾 Changes by Scope

Scope	Lines Δ%	Lines Δ	Lines +	Lines -	Files Δ	Files +	Files ~	Files ↔	Files -
🛠️ Source	51%	1083	798	285	7	-	7	-	-
🧪 Unit Tests	18%	389	363	26	1	-	1	-	-
📦 Other	11%	234	234	-	8	6	2	-	-
🥇 Golden Tests	8%	173	173	-	4	4	-	-	-
📄 Docs	7%	141	137	4	5	1	4	-	-
🔧 Toolchain	4%	86	78	8	4	2	2	-	-
Total	100%	2106	1783	323	29	13	16	-	-

Legend: Files + (added), Files ~ (modified), Files ↔ (renamed), Files - (removed)

🔝 Top Files

• src/mrdocs/Engines/JavaScript/ValueBridge.ipp (Source): 553 lines Δ (+444 / -109)
• src/mrdocs/Engines/JavaScript.cpp (Source): 485 lines Δ (+325 / -160)
• tests/unit/Engines/JavaScript.cpp (Unit Tests): 389 lines Δ (+363 / -26)

Generated by 🚫 dangerJS against c7a0050

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.12%. Comparing base (1a0bbac) to head (c7a0050).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #1319   +/-   ##
========================================
  Coverage    83.12%   83.12%           
========================================
  Files           35       35           
  Lines         3662     3662           
  Branches       844      844           
========================================
  Hits          3044     3044           
  Misses         410      410           
  Partials       208      208           

Flag	Coverage Δ
bootstrap	83.12% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[cppalliance-bot]

An automated preview of the documentation is available at https://1319.mrdocs.prtest2.cppalliance.org/index.html

If more commits are pushed to the pull request, the docs will rebuild at the same URL.

2026-09-24 03:10:00 UTC

[alandefreitas]

The general direction is correct, but it failed CI and was missing components for a more stable fix. I've pushed extra commits to consider that.

[gennaroprota]

Thanks. A few comments:

Do the benchmarks really support the conclusions drawn in the docs?

• bench.lua uses os.clock (process CPU time), while bench.js uses Date.now (wall-clock time).
• The JavaScript loop tests i < s.length on every iteration, and each read of length goes through the proxy trap. Lua's ipairs does nothing comparable.
• "Build text" compares out += in JavaScript with table.concat in Lua. I guess the fair JavaScript version is push and then join.
• tests/benchmrks/CMakeLists.txt says the target prints a median table, but run.py computes a mean.

Is the MSan ignorelist too broad?

• We are silencing any MSan finding in JerryScript. But the one finding we currently have is in parser_check_anonymous_function_declaration. Wouldn't a single fun: entry for that be better?

Exit paths

• jerry_port_fatal correctly leaves through _Exit, but jerry_port_context_alloc exits with std::exit.

Commit-on-demand

• jerryCommitOnDemand runs on every access violation in the process and takes jerryBlocksMutex. If a crash ever happens inside the unordered_map operations that hold that mutex, the handler tries to lock it again on the same thread. That's UB for std::mutex and, in practice, a deadlock. So a crash would become a hang.
• The comment at JavaScript.cpp:196 says Windows has no demand-zero pages. I think committed Windows pages are demand-zero, too; the actual constraint is the commit charge, which the next sentence states correctly.

Stale comments

• ValueBridge.ipp:87 says "the handler was still freed above". Since commit 4, it's the target that holds the holder.
• Type.hpp:69 still lists "fatal errors" among the port functions taken from the default library, a few lines above the new bullet says jerry_port_fatal is ours.
• The "small heap" rationale survives in docs/mrdocs/extensions/schema.js:20, utils/codegen/generate-schema.sh:15 and src/mrdocs/Generators/script/ScriptGenerator.cpp:102.