fastjs 0.1.0__tar.gz

fastjs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fastjs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

fastjs-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include _quickjs_build.py
+recursive-include tests *.py

fastjs-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: fastjs
+Version: 0.1.0
+Summary: Python bindings for Bellard's QuickJS engine
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/QuickJS.txt
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# fastjs
+
+Python bindings for [Bellard's QuickJS](https://github.com/bellard/quickjs).
+Source builds download QuickJS revision
+`e585640ffa2cf88ce7c2d587583c6fe15928ec2f` (version 2026-06-04), verify its
+SHA-256 checksum, and compile it into the CPython extension. This requires a
+compiler supporting GNU C11 and Python development headers. Linux, macOS, and
+Windows x86_64 builds are configured; Windows uses MinGW-w64 UCRT64 GCC rather
+than MSVC. The release workflow tests wheels on each platform.
+
+```sh
+python -m pip install .
+```
+
+```python
+import fastjs
+
+assert fastjs.eval('1 + 2') == 3
+ctx = fastjs.Context(memory_limit=64 * 1024 * 1024, time_limit=0.5)
+ctx.set('name', 'Python')
+assert ctx.eval('`Hello, ${name}!`') == 'Hello, Python!'
+add = ctx.eval('(a, b) => a + b')
+assert add(20, 22) == 42
+
+obj = ctx.parse_json('{"items": [1, 2, 3]}')
+ctx.set('data', obj)
+assert ctx.eval('data.items.length') == 3
+assert obj.json() == '{"items":[1,2,3]}'
+```
+
+`Context.eval(source, filename='<eval>')` runs a global script. JavaScript
+exceptions become `fastjs.JSException`. Global lexical declarations (`let`,
+`const`) are available to subsequent scripts, but `get(name)` reads properties
+of the global object, such as those created by `var`.
+
+JavaScript null and undefined both become Python `None`; booleans, numbers,
+strings and BigInts become Python scalars. Other values become `Object` handles.
+Functions support positional calls with undefined as their `this` value.
+`Object.json()` returns a JSON string, or `None` when JSON.stringify returns
+undefined. Symbols remain opaque handles. Python arguments and globals support
+`None`, bool, float, str, safe integers and objects from the same context.
+Python integers outside ±(2**53 - 1) raise OverflowError; create BigInts through
+JavaScript expressions. Use `parse_json(json.dumps(value))` for Python lists and
+dicts. Python callbacks are not implemented yet.
+
+`execute_pending_job()` runs one queued promise job and returns whether one ran:
+
+```python
+ctx.eval('var answer; Promise.resolve(42).then(v => { answer = v; })')
+while ctx.execute_pending_job():
+    pass
+assert ctx.get('answer') == 42
+```
+
+Contexts and their objects must be used on the thread that created the context.
+Objects keep their context alive. The extension holds the GIL during execution.
+`time_limit` is seconds per operation (zero disables it); `memory_limit` is bytes
+(zero disables it); `stack_limit` defaults to 1 MiB and must be positive.
+The interrupt handler also checks Python signals. Limits help bound execution;
+this package is not a security boundary for hostile code. No filesystem,
+network, module loader, timers, console or QuickJS libc helpers are installed.
+Optional Intl/Temporal support is not built.
+
+Development:
+
+```sh
+uv venv --python 3.14
+uv pip install -e '.[test]'
+.venv/bin/python -m pytest
+```
+
+Downloaded archives are cached under `$XDG_CACHE_HOME/fastjs` (default:
+`~/.cache/fastjs`). Set `FASTJS_CACHE_DIR` to override that directory. The checksum
+is checked on every build, including cache hits. Source builds need network
+access on the first build; subsequent builds can reuse the cached archive
+offline. Generating package metadata and source distributions does not download
+QuickJS. Installing a prebuilt wheel needs neither QuickJS sources nor a compiler.
+
+QuickJS retains its upstream MIT license in `licenses/QuickJS.txt`, which is also
+included in distribution metadata.
+
+The `.github/workflows/test.yml` workflow builds and installs the extension and
+runs the tests on branch pushes and pull requests. It covers CPython 3.10–3.15
+on Linux (x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64). It does not publish packages.
+
+Releases are published to PyPI by `.github/workflows/release.yml` when a version
+tag is pushed. Set `project.version` in `pyproject.toml` to the release version,
+commit the changes, then push the commit and matching tag:
+
+```sh
+git tag 0.1.0
+git push origin HEAD
+git push origin 0.1.0
+```
+
+The tag must exactly match the package version (no `v` prefix). The workflow
+builds a source distribution and tests CPython 3.10–3.15 wheels on Linux
+(manylinux, x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64) before publishing. Windows ARM64, 32-bit, and free-threaded Python
+wheels are not built.
+PyPI trusted publishing must name the GitHub repository and `release.yml`, with
+no environment specified. Publishing uses OIDC and needs no PyPI API token.
+
+For a Windows source build, install MSYS2's `mingw-w64-ucrt-x86_64-gcc` package
+and add the MSYS2 `ucrt64\bin` directory to PATH. Use standard Windows CPython,
+then run `python -m pip wheel .`. The build selects setuptools' `mingw32`
+compiler automatically. Published wheels need neither MSYS2 nor GCC installed;
+the extension statically links compiler runtime support and winpthreads. The
+compiler itself is used only during builds.

fastjs-0.1.0/README.md

@@ -0,0 +1,110 @@
+# fastjs
+
+Python bindings for [Bellard's QuickJS](https://github.com/bellard/quickjs).
+Source builds download QuickJS revision
+`e585640ffa2cf88ce7c2d587583c6fe15928ec2f` (version 2026-06-04), verify its
+SHA-256 checksum, and compile it into the CPython extension. This requires a
+compiler supporting GNU C11 and Python development headers. Linux, macOS, and
+Windows x86_64 builds are configured; Windows uses MinGW-w64 UCRT64 GCC rather
+than MSVC. The release workflow tests wheels on each platform.
+
+```sh
+python -m pip install .
+```
+
+```python
+import fastjs
+
+assert fastjs.eval('1 + 2') == 3
+ctx = fastjs.Context(memory_limit=64 * 1024 * 1024, time_limit=0.5)
+ctx.set('name', 'Python')
+assert ctx.eval('`Hello, ${name}!`') == 'Hello, Python!'
+add = ctx.eval('(a, b) => a + b')
+assert add(20, 22) == 42
+
+obj = ctx.parse_json('{"items": [1, 2, 3]}')
+ctx.set('data', obj)
+assert ctx.eval('data.items.length') == 3
+assert obj.json() == '{"items":[1,2,3]}'
+```
+
+`Context.eval(source, filename='<eval>')` runs a global script. JavaScript
+exceptions become `fastjs.JSException`. Global lexical declarations (`let`,
+`const`) are available to subsequent scripts, but `get(name)` reads properties
+of the global object, such as those created by `var`.
+
+JavaScript null and undefined both become Python `None`; booleans, numbers,
+strings and BigInts become Python scalars. Other values become `Object` handles.
+Functions support positional calls with undefined as their `this` value.
+`Object.json()` returns a JSON string, or `None` when JSON.stringify returns
+undefined. Symbols remain opaque handles. Python arguments and globals support
+`None`, bool, float, str, safe integers and objects from the same context.
+Python integers outside ±(2**53 - 1) raise OverflowError; create BigInts through
+JavaScript expressions. Use `parse_json(json.dumps(value))` for Python lists and
+dicts. Python callbacks are not implemented yet.
+
+`execute_pending_job()` runs one queued promise job and returns whether one ran:
+
+```python
+ctx.eval('var answer; Promise.resolve(42).then(v => { answer = v; })')
+while ctx.execute_pending_job():
+    pass
+assert ctx.get('answer') == 42
+```
+
+Contexts and their objects must be used on the thread that created the context.
+Objects keep their context alive. The extension holds the GIL during execution.
+`time_limit` is seconds per operation (zero disables it); `memory_limit` is bytes
+(zero disables it); `stack_limit` defaults to 1 MiB and must be positive.
+The interrupt handler also checks Python signals. Limits help bound execution;
+this package is not a security boundary for hostile code. No filesystem,
+network, module loader, timers, console or QuickJS libc helpers are installed.
+Optional Intl/Temporal support is not built.
+
+Development:
+
+```sh
+uv venv --python 3.14
+uv pip install -e '.[test]'
+.venv/bin/python -m pytest
+```
+
+Downloaded archives are cached under `$XDG_CACHE_HOME/fastjs` (default:
+`~/.cache/fastjs`). Set `FASTJS_CACHE_DIR` to override that directory. The checksum
+is checked on every build, including cache hits. Source builds need network
+access on the first build; subsequent builds can reuse the cached archive
+offline. Generating package metadata and source distributions does not download
+QuickJS. Installing a prebuilt wheel needs neither QuickJS sources nor a compiler.
+
+QuickJS retains its upstream MIT license in `licenses/QuickJS.txt`, which is also
+included in distribution metadata.
+
+The `.github/workflows/test.yml` workflow builds and installs the extension and
+runs the tests on branch pushes and pull requests. It covers CPython 3.10–3.15
+on Linux (x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64). It does not publish packages.
+
+Releases are published to PyPI by `.github/workflows/release.yml` when a version
+tag is pushed. Set `project.version` in `pyproject.toml` to the release version,
+commit the changes, then push the commit and matching tag:
+
+```sh
+git tag 0.1.0
+git push origin HEAD
+git push origin 0.1.0
+```
+
+The tag must exactly match the package version (no `v` prefix). The workflow
+builds a source distribution and tests CPython 3.10–3.15 wheels on Linux
+(manylinux, x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64) before publishing. Windows ARM64, 32-bit, and free-threaded Python
+wheels are not built.
+PyPI trusted publishing must name the GitHub repository and `release.yml`, with
+no environment specified. Publishing uses OIDC and needs no PyPI API token.
+
+For a Windows source build, install MSYS2's `mingw-w64-ucrt-x86_64-gcc` package
+and add the MSYS2 `ucrt64\bin` directory to PATH. Use standard Windows CPython,
+then run `python -m pip wheel .`. The build selects setuptools' `mingw32`
+compiler automatically. Published wheels need neither MSYS2 nor GCC installed;
+the extension statically links compiler runtime support and winpthreads. The
+compiler itself is used only during builds.

fastjs-0.1.0/_quickjs_build.py

@@ -0,0 +1,88 @@
+"""Fetch the exact QuickJS input used by source builds (stdlib only)."""
+import hashlib
+import io
+import os
+from pathlib import Path
+import tarfile
+import tempfile
+from urllib.error import URLError
+from urllib.request import urlopen
+
+REVISION = "e585640ffa2cf88ce7c2d587583c6fe15928ec2f"
+VERSION = "2026-06-04"
+SHA256 = "56d9d9d7e206ea77a1a0badc560536e455d50639db6c0cc6e6ca8a8c5a12d47f"
+URL = f"https://codeload.github.com/bellard/quickjs/tar.gz/{REVISION}"
+ARCHIVE_NAME = f"quickjs-{REVISION}.tar.gz"
+SOURCES = ("quickjs", "dtoa", "libregexp", "libunicode", "cutils")
+FILES = (
+    "quickjs.c", "quickjs.h", "quickjs-atom.h", "quickjs-opcode.h",
+    "dtoa.c", "dtoa.h", "libregexp.c", "libregexp.h", "libregexp-opcode.h",
+    "libunicode.c", "libunicode.h", "libunicode-table.h", "cutils.c", "cutils.h",
+    "list.h", "LICENSE", "VERSION",
+)
+
+
+def cache_dir():
+    override = os.environ.get("FASTJS_CACHE_DIR")
+    if override:
+        return Path(override).expanduser()
+    return Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "fastjs"
+
+
+def verify(data):
+    if hashlib.sha256(data).hexdigest() != SHA256:
+        raise RuntimeError(
+            f"QuickJS SHA-256 mismatch for revision {REVISION}; "
+            f"expected {SHA256}. Remove any corrupt cached {ARCHIVE_NAME} and retry."
+        )
+
+
+def fetch_archive():
+    """Verify every cache hit; publish new downloads atomically."""
+    archive = cache_dir() / ARCHIVE_NAME
+    if archive.is_file():
+        data = archive.read_bytes()
+        verify(data)
+        return data
+    try:
+        with urlopen(URL, timeout=60) as response:
+            data = response.read()
+    except (OSError, URLError) as exc:
+        raise RuntimeError(
+            f"Could not download QuickJS from {URL}. Source builds need network "
+            f"access or a verified archive cached at {archive}. "
+            "Set FASTJS_CACHE_DIR to select another cache directory."
+        ) from exc
+    verify(data)
+    archive.parent.mkdir(parents=True, exist_ok=True)
+    temp_path = None
+    try:
+        with tempfile.NamedTemporaryFile(dir=archive.parent, delete=False) as temp:
+            temp_path = Path(temp.name)
+            temp.write(data)
+        temp_path.replace(archive)
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+    return data
+
+
+def prepare_sources(destination):
+    """Extract only known regular files, never archive paths or links."""
+    data = fetch_archive()
+    destination = Path(destination)
+    destination.mkdir(parents=True, exist_ok=True)
+    prefix = f"quickjs-{REVISION}"
+    with tarfile.open(fileobj=io.BytesIO(data), mode="r:gz") as archive:
+        for name in FILES:
+            member = archive.getmember(f"{prefix}/{name}")
+            if not member.isfile():
+                raise RuntimeError(f"QuickJS archive member is not a regular file: {name}")
+            with archive.extractfile(member) as source:
+                content = source.read()
+            target = destination / name
+            if not target.is_file() or target.read_bytes() != content:
+                target.write_bytes(content)
+    if (destination / "VERSION").read_text().strip() != VERSION:
+        raise RuntimeError("QuickJS archive version does not match the build configuration")
+    return destination

fastjs-0.1.0/licenses/QuickJS.txt

@@ -0,0 +1,22 @@
+QuickJS Javascript Engine
+
+Copyright (c) 2017-2021 Fabrice Bellard
+Copyright (c) 2017-2021 Charlie Gordon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

fastjs-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastjs"
+version = "0.1.0"
+description = "Python bindings for Bellard's QuickJS engine"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE", "licenses/QuickJS.txt"]
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+fastjs = ["*.pyi", "py.typed"]
+
+[tool.cibuildwheel]
+build = "cp{310,311,312,313,314,315}-{manylinux,macosx}_* cp{310,311,312,313,314,315}-win_amd64"
+test-requires = ["pytest>=7"]
+test-command = "python -m pytest {package}/tests -q"

fastjs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastjs-0.1.0/setup.py

@@ -0,0 +1,47 @@
+import sys
+import runpy
+from pathlib import Path
+
+from setuptools import Extension, setup
+from setuptools.command.build_ext import build_ext
+
+# PEP 517 does not guarantee that the source root is on sys.path.
+_quickjs = runpy.run_path(str(Path(__file__).with_name("_quickjs_build.py")))
+
+WINDOWS = sys.platform == "win32"
+
+
+class QuickJSBuildExt(build_ext):
+    def finalize_options(self):
+        # QuickJS needs GNU C extensions and winpthreads on Windows.
+        if WINDOWS and self.compiler is None:
+            self.compiler = "mingw32"
+        super().finalize_options()
+
+    def build_extensions(self):
+        if WINDOWS and self.compiler.compiler_type != "mingw32":
+            raise RuntimeError("Windows builds require MinGW-w64 (UCRT64) GCC on PATH")
+        root = _quickjs["prepare_sources"](Path(self.build_temp) / "quickjs")
+        for extension in self.extensions:
+            if extension.name == "fastjs._native":
+                extension.sources = ["src/fastjs/_native.c"] + [
+                    str(root / f"{name}.c") for name in _quickjs["SOURCES"]
+                ]
+                extension.include_dirs = [str(root)]
+        super().build_extensions()
+
+
+setup(
+    cmdclass={"build_ext": QuickJSBuildExt},
+    ext_modules=[Extension(
+        "fastjs._native",
+        sources=["src/fastjs/_native.c"],
+        define_macros=[("_GNU_SOURCE", None), ("CONFIG_VERSION", '"{}"'.format(_quickjs["VERSION"]))]
+        + ([("__USE_MINGW_ANSI_STDIO", "1")] if WINDOWS else []),
+        libraries=["m"],
+        extra_compile_args=["-std=gnu11", "-fwrapv", "-Wno-unused-parameter"],
+        # Keep wheels independent of MinGW DLLs on the user's PATH.
+        extra_link_args=["-static-libgcc", "-Wl,-Bstatic", "-lwinpthread", "-Wl,-Bdynamic"]
+        if WINDOWS else [],
+    )],
+)

fastjs-0.1.0/src/fastjs/__init__.py

@@ -0,0 +1,9 @@
+"""Embed Bellard's QuickJS JavaScript engine in Python."""
+from ._native import Context, JSException, Object
+
+__all__ = ["Context", "JSException", "Object", "eval"]
+
+
+def eval(source: str):
+    """Evaluate JavaScript in a fresh context."""
+    return Context().eval(source)

fastjs-0.1.0/src/fastjs/__init__.pyi

@@ -0,0 +1,14 @@
+from typing import Any
+
+class JSException(Exception): ...
+class Object:
+    def __call__(self, *args: None | bool | int | float | str | Object) -> Any: ...
+    def json(self) -> str | None: ...
+class Context:
+    def __new__(cls, memory_limit: int = 0, stack_limit: int = 1048576, time_limit: float = 0) -> Context: ...
+    def eval(self, source: str, filename: str = '<eval>') -> Any: ...
+    def get(self, name: str) -> Any: ...
+    def set(self, name: str, value: None | bool | int | float | str | Object) -> None: ...
+    def parse_json(self, source: str) -> Any: ...
+    def execute_pending_job(self) -> bool: ...
+def eval(source: str) -> Any: ...

fastjs-0.1.0/src/fastjs/_native.c

@@ -0,0 +1,225 @@
+#define PY_SSIZE_T_CLEAN
+#include <Python.h>
+#include <math.h>
+#include <time.h>
+#ifdef _WIN32
+#include <windows.h>
+#endif
+#include "quickjs.h"
+
+typedef struct {
+    PyObject_HEAD
+    JSRuntime *rt;
+    JSContext *ctx;
+    double timeout, deadline;
+    unsigned long thread;
+} Context;
+typedef struct { PyObject_HEAD Context *owner; JSValue value; } Object;
+static PyTypeObject ContextType, ObjectType;
+static PyObject *JSException;
+
+static double now(void) {
+#ifdef _WIN32
+    LARGE_INTEGER counter, frequency;
+    QueryPerformanceFrequency(&frequency);
+    QueryPerformanceCounter(&counter);
+    return (double)counter.QuadPart / (double)frequency.QuadPart;
+#else
+    struct timespec t;
+    clock_gettime(CLOCK_MONOTONIC, &t);
+    return t.tv_sec + t.tv_nsec / 1e9;
+#endif
+}
+static int interrupt(JSRuntime *rt, void *opaque) {
+    Context *c = opaque;
+    return (c->deadline > 0 && now() >= c->deadline) || PyErr_CheckSignals() < 0;
+}
+static int enter(Context *c) {
+    if (c->thread != PyThread_get_thread_ident()) {
+        PyErr_SetString(PyExc_RuntimeError, "Context must be used on its creating thread");
+        return -1;
+    }
+    c->deadline = c->timeout > 0 ? now() + c->timeout : 0;
+    JS_UpdateStackTop(c->rt);
+    return 0;
+}
+static PyObject *error(Context *c) {
+    JSValue exc = JS_GetException(c->ctx);
+    const char *s = JS_ToCString(c->ctx, exc);
+    if (!PyErr_Occurred()) PyErr_SetString(JSException, s ? s : "JavaScript exception");
+    if (s) JS_FreeCString(c->ctx, s);
+    JS_FreeValue(c->ctx, exc);
+    return NULL;
+}
+static PyObject *convert(Context *c, JSValue v) {
+    PyObject *result = NULL;
+    if (JS_IsException(v)) return error(c);
+    if (JS_IsNull(v) || JS_IsUndefined(v)) { result = Py_NewRef(Py_None); }
+    else if (JS_IsBool(v)) result = PyBool_FromLong(JS_ToBool(c->ctx, v));
+    else if (JS_IsNumber(v)) {
+        if (JS_VALUE_GET_TAG(v) == JS_TAG_INT) result = PyLong_FromLong(JS_VALUE_GET_INT(v));
+        else { double d; JS_ToFloat64(c->ctx, &d, v); result = PyFloat_FromDouble(d); }
+    } else if (JS_IsString(v) || JS_IsBigInt(c->ctx, v)) {
+        size_t len;
+        const char *s = JS_ToCStringLen(c->ctx, &len, v);
+        if (!s) { JS_FreeValue(c->ctx, v); return error(c); }
+        if (JS_IsBigInt(c->ctx, v)) result = PyLong_FromString((char *)s, NULL, 10);
+        else result = PyUnicode_DecodeUTF8(s, len, "surrogatepass");
+        JS_FreeCString(c->ctx, s);
+    } else {
+        Object *o = PyObject_New(Object, &ObjectType);
+        if (o) { o->owner = (Context *)Py_NewRef((PyObject *)c); o->value = v; return (PyObject *)o; }
+    }
+    JS_FreeValue(c->ctx, v);
+    return result;
+}
+static JSValue from_python(Context *c, PyObject *p) {
+    if (p == Py_None) return JS_NULL;
+    if (PyBool_Check(p)) return JS_NewBool(c->ctx, p == Py_True);
+    if (PyObject_TypeCheck(p, &ObjectType)) {
+        Object *o = (Object *)p;
+        if (o->owner != c) { PyErr_SetString(PyExc_ValueError, "Objects cannot cross contexts"); return JS_EXCEPTION; }
+        return JS_DupValue(c->ctx, o->value);
+    }
+    if (PyLong_Check(p)) {
+        int overflow;
+        long long n = PyLong_AsLongLongAndOverflow(p, &overflow);
+        if (!overflow && n >= -9007199254740991LL && n <= 9007199254740991LL)
+            return JS_NewInt64(c->ctx, n);
+        PyErr_SetString(PyExc_OverflowError, "Use a JavaScript BigInt expression for integers outside the safe range");
+        return JS_EXCEPTION;
+    }
+    if (PyFloat_Check(p)) return JS_NewFloat64(c->ctx, PyFloat_AS_DOUBLE(p));
+    if (PyUnicode_Check(p)) {
+        Py_ssize_t len;
+        const char *s = PyUnicode_AsUTF8AndSize(p, &len);
+        return s ? JS_NewStringLen(c->ctx, s, len) : JS_EXCEPTION;
+    }
+    PyErr_SetString(PyExc_TypeError, "Expected None, bool, int, float, str, or fastjs.Object");
+    return JS_EXCEPTION;
+}
+static PyObject *context_new(PyTypeObject *type, PyObject *args, PyObject *kw) {
+    static char *names[] = {"memory_limit", "stack_limit", "time_limit", NULL};
+    Py_ssize_t memory = 0, stack = 1024 * 1024;
+    double timeout = 0;
+    if (!PyArg_ParseTupleAndKeywords(args, kw, "|nnd", names, &memory, &stack, &timeout)) return NULL;
+    if (memory < 0 || stack <= 0 || timeout < 0 || !isfinite(timeout)) {
+        PyErr_SetString(PyExc_ValueError, "Limits must be nonnegative and finite; stack_limit must be positive"); return NULL;
+    }
+    Context *c = (Context *)type->tp_alloc(type, 0);
+    if (!c) return NULL;
+    c->thread = PyThread_get_thread_ident(); c->timeout = timeout;
+    c->rt = JS_NewRuntime();
+    if (!c->rt) { Py_DECREF(c); return PyErr_NoMemory(); }
+    if (memory) JS_SetMemoryLimit(c->rt, memory);
+    JS_SetMaxStackSize(c->rt, stack);
+    c->ctx = JS_NewContext(c->rt);
+    if (!c->ctx) { Py_DECREF(c); return PyErr_NoMemory(); }
+    JS_SetInterruptHandler(c->rt, interrupt, c);
+    return (PyObject *)c;
+}
+static void context_dealloc(Context *c) {
+    if (c->ctx) JS_FreeContext(c->ctx);
+    if (c->rt) JS_FreeRuntime(c->rt);
+    Py_TYPE(c)->tp_free((PyObject *)c);
+}
+static PyObject *context_eval(Context *c, PyObject *args, PyObject *kw) {
+    const char *source, *filename = "<eval>"; Py_ssize_t len;
+    static char *names[] = {"source", "filename", NULL};
+    if (!PyArg_ParseTupleAndKeywords(args, kw, "s#|s", names, &source, &len, &filename) || enter(c)) return NULL;
+    return convert(c, JS_Eval(c->ctx, source, len, filename, JS_EVAL_TYPE_GLOBAL));
+}
+static PyObject *context_parse(Context *c, PyObject *arg) {
+    Py_ssize_t len; const char *s = PyUnicode_AsUTF8AndSize(arg, &len);
+    if (!s || enter(c)) return NULL;
+    return convert(c, JS_ParseJSON(c->ctx, s, len, "<json>"));
+}
+static PyObject *context_get(Context *c, PyObject *arg) {
+    const char *name = PyUnicode_AsUTF8(arg);
+    if (!name || enter(c)) return NULL;
+    if (PyUnicode_FindChar(arg, 0, 0, PyUnicode_GET_LENGTH(arg), 1) >= 0) {
+        PyErr_SetString(PyExc_ValueError, "Global names cannot contain NUL"); return NULL;
+    }
+    JSValue global = JS_GetGlobalObject(c->ctx);
+    JSValue v = JS_GetPropertyStr(c->ctx, global, name);
+    JS_FreeValue(c->ctx, global);
+    return convert(c, v);
+}
+static PyObject *context_set(Context *c, PyObject *args) {
+    const char *name; PyObject *p;
+    if (!PyArg_ParseTuple(args, "sO", &name, &p) || enter(c)) return NULL;
+    JSValue v = from_python(c, p);
+    if (JS_IsException(v)) return PyErr_Occurred() ? NULL : error(c);
+    JSValue global = JS_GetGlobalObject(c->ctx);
+    int status = JS_SetPropertyStr(c->ctx, global, name, v);
+    JS_FreeValue(c->ctx, global);
+    if (status < 0) return error(c);
+    Py_RETURN_NONE;
+}
+static PyObject *context_job(Context *c, PyObject *unused) {
+    if (enter(c)) return NULL;
+    JSContext *ctx;
+    int status = JS_ExecutePendingJob(c->rt, &ctx);
+    if (status < 0) return error(c);
+    return PyBool_FromLong(status);
+}
+static void object_dealloc(Object *o) {
+    JS_FreeValue(o->owner->ctx, o->value);
+    Py_DECREF(o->owner); PyObject_Del(o);
+}
+static PyObject *object_json(Object *o, PyObject *unused) {
+    if (enter(o->owner)) return NULL;
+    return convert(o->owner, JS_JSONStringify(o->owner->ctx, o->value, JS_UNDEFINED, JS_UNDEFINED));
+}
+static PyObject *object_call(Object *o, PyObject *args, PyObject *kw) {
+    Context *c = o->owner;
+    if (kw && PyDict_Size(kw)) { PyErr_SetString(PyExc_TypeError, "JavaScript calls accept positional arguments only"); return NULL; }
+    if (enter(c)) return NULL;
+    if (!JS_IsFunction(c->ctx, o->value)) { PyErr_SetString(PyExc_TypeError, "JavaScript object is not callable"); return NULL; }
+    Py_ssize_t n = PyTuple_GET_SIZE(args);
+    JSValue *argv = PyMem_Calloc(n ? n : 1, sizeof(JSValue));
+    if (!argv) return PyErr_NoMemory();
+    Py_ssize_t i;
+    for (i = 0; i < n; i++) {
+        argv[i] = from_python(c, PyTuple_GET_ITEM(args, i));
+        if (JS_IsException(argv[i])) break;
+    }
+    PyObject *result = NULL;
+    if (i == n) result = convert(c, JS_Call(c->ctx, o->value, JS_UNDEFINED, (int)n, argv));
+    else if (!PyErr_Occurred()) error(c);
+    for (Py_ssize_t j = 0; j < i; j++) JS_FreeValue(c->ctx, argv[j]);
+    PyMem_Free(argv);
+    return result;
+}
+static PyMethodDef context_methods[] = {
+    {"eval", (PyCFunction)(void(*)(void))context_eval, METH_VARARGS | METH_KEYWORDS, "Evaluate a JavaScript script."},
+    {"parse_json", (PyCFunction)context_parse, METH_O, "Parse JSON into this context."},
+    {"get", (PyCFunction)context_get, METH_O, "Read a global property."},
+    {"set", (PyCFunction)context_set, METH_VARARGS, "Set a global property."},
+    {"execute_pending_job", (PyCFunction)context_job, METH_NOARGS, "Execute one queued promise job."},
+    {NULL}
+};
+static PyMethodDef object_methods[] = {
+    {"json", (PyCFunction)object_json, METH_NOARGS, "Serialize to JSON (or None for undefined)."}, {NULL}
+};
+static PyTypeObject ContextType = {
+    PyVarObject_HEAD_INIT(NULL, 0)
+    .tp_name = "fastjs.Context", .tp_basicsize = sizeof(Context), .tp_flags = Py_TPFLAGS_DEFAULT,
+    .tp_new = context_new, .tp_dealloc = (destructor)context_dealloc, .tp_methods = context_methods,
+};
+static PyTypeObject ObjectType = {
+    PyVarObject_HEAD_INIT(NULL, 0)
+    .tp_name = "fastjs.Object", .tp_basicsize = sizeof(Object), .tp_flags = Py_TPFLAGS_DEFAULT,
+    .tp_dealloc = (destructor)object_dealloc, .tp_methods = object_methods, .tp_call = (ternaryfunc)object_call,
+};
+static PyModuleDef module = {PyModuleDef_HEAD_INIT, .m_name = "_native", .m_size = -1};
+PyMODINIT_FUNC PyInit__native(void) {
+    if (PyType_Ready(&ContextType) < 0 || PyType_Ready(&ObjectType) < 0) return NULL;
+    PyObject *m = PyModule_Create(&module);
+    if (!m) return NULL;
+    JSException = PyErr_NewException("fastjs.JSException", NULL, NULL);
+    if (!JSException || PyModule_AddObjectRef(m, "JSException", JSException) < 0 ||
+        PyModule_AddObjectRef(m, "Context", (PyObject *)&ContextType) < 0 ||
+        PyModule_AddObjectRef(m, "Object", (PyObject *)&ObjectType) < 0) { Py_DECREF(m); return NULL; }
+    return m;
+}

fastjs-0.1.0/src/fastjs.egg-info/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: fastjs
+Version: 0.1.0
+Summary: Python bindings for Bellard's QuickJS engine
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: licenses/QuickJS.txt
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# fastjs
+
+Python bindings for [Bellard's QuickJS](https://github.com/bellard/quickjs).
+Source builds download QuickJS revision
+`e585640ffa2cf88ce7c2d587583c6fe15928ec2f` (version 2026-06-04), verify its
+SHA-256 checksum, and compile it into the CPython extension. This requires a
+compiler supporting GNU C11 and Python development headers. Linux, macOS, and
+Windows x86_64 builds are configured; Windows uses MinGW-w64 UCRT64 GCC rather
+than MSVC. The release workflow tests wheels on each platform.
+
+```sh
+python -m pip install .
+```
+
+```python
+import fastjs
+
+assert fastjs.eval('1 + 2') == 3
+ctx = fastjs.Context(memory_limit=64 * 1024 * 1024, time_limit=0.5)
+ctx.set('name', 'Python')
+assert ctx.eval('`Hello, ${name}!`') == 'Hello, Python!'
+add = ctx.eval('(a, b) => a + b')
+assert add(20, 22) == 42
+
+obj = ctx.parse_json('{"items": [1, 2, 3]}')
+ctx.set('data', obj)
+assert ctx.eval('data.items.length') == 3
+assert obj.json() == '{"items":[1,2,3]}'
+```
+
+`Context.eval(source, filename='<eval>')` runs a global script. JavaScript
+exceptions become `fastjs.JSException`. Global lexical declarations (`let`,
+`const`) are available to subsequent scripts, but `get(name)` reads properties
+of the global object, such as those created by `var`.
+
+JavaScript null and undefined both become Python `None`; booleans, numbers,
+strings and BigInts become Python scalars. Other values become `Object` handles.
+Functions support positional calls with undefined as their `this` value.
+`Object.json()` returns a JSON string, or `None` when JSON.stringify returns
+undefined. Symbols remain opaque handles. Python arguments and globals support
+`None`, bool, float, str, safe integers and objects from the same context.
+Python integers outside ±(2**53 - 1) raise OverflowError; create BigInts through
+JavaScript expressions. Use `parse_json(json.dumps(value))` for Python lists and
+dicts. Python callbacks are not implemented yet.
+
+`execute_pending_job()` runs one queued promise job and returns whether one ran:
+
+```python
+ctx.eval('var answer; Promise.resolve(42).then(v => { answer = v; })')
+while ctx.execute_pending_job():
+    pass
+assert ctx.get('answer') == 42
+```
+
+Contexts and their objects must be used on the thread that created the context.
+Objects keep their context alive. The extension holds the GIL during execution.
+`time_limit` is seconds per operation (zero disables it); `memory_limit` is bytes
+(zero disables it); `stack_limit` defaults to 1 MiB and must be positive.
+The interrupt handler also checks Python signals. Limits help bound execution;
+this package is not a security boundary for hostile code. No filesystem,
+network, module loader, timers, console or QuickJS libc helpers are installed.
+Optional Intl/Temporal support is not built.
+
+Development:
+
+```sh
+uv venv --python 3.14
+uv pip install -e '.[test]'
+.venv/bin/python -m pytest
+```
+
+Downloaded archives are cached under `$XDG_CACHE_HOME/fastjs` (default:
+`~/.cache/fastjs`). Set `FASTJS_CACHE_DIR` to override that directory. The checksum
+is checked on every build, including cache hits. Source builds need network
+access on the first build; subsequent builds can reuse the cached archive
+offline. Generating package metadata and source distributions does not download
+QuickJS. Installing a prebuilt wheel needs neither QuickJS sources nor a compiler.
+
+QuickJS retains its upstream MIT license in `licenses/QuickJS.txt`, which is also
+included in distribution metadata.
+
+The `.github/workflows/test.yml` workflow builds and installs the extension and
+runs the tests on branch pushes and pull requests. It covers CPython 3.10–3.15
+on Linux (x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64). It does not publish packages.
+
+Releases are published to PyPI by `.github/workflows/release.yml` when a version
+tag is pushed. Set `project.version` in `pyproject.toml` to the release version,
+commit the changes, then push the commit and matching tag:
+
+```sh
+git tag 0.1.0
+git push origin HEAD
+git push origin 0.1.0
+```
+
+The tag must exactly match the package version (no `v` prefix). The workflow
+builds a source distribution and tests CPython 3.10–3.15 wheels on Linux
+(manylinux, x86_64 and aarch64), macOS (Intel and Apple Silicon), and Windows
+(x86_64) before publishing. Windows ARM64, 32-bit, and free-threaded Python
+wheels are not built.
+PyPI trusted publishing must name the GitHub repository and `release.yml`, with
+no environment specified. Publishing uses OIDC and needs no PyPI API token.
+
+For a Windows source build, install MSYS2's `mingw-w64-ucrt-x86_64-gcc` package
+and add the MSYS2 `ucrt64\bin` directory to PATH. Use standard Windows CPython,
+then run `python -m pip wheel .`. The build selects setuptools' `mingw32`
+compiler automatically. Published wheels need neither MSYS2 nor GCC installed;
+the extension statically links compiler runtime support and winpthreads. The
+compiler itself is used only during builds.

fastjs-0.1.0/src/fastjs.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+MANIFEST.in
+README.md
+_quickjs_build.py
+pyproject.toml
+setup.py
+licenses/QuickJS.txt
+src/fastjs/__init__.py
+src/fastjs/__init__.pyi
+src/fastjs/_native.c
+src/fastjs/py.typed
+src/fastjs.egg-info/PKG-INFO
+src/fastjs.egg-info/SOURCES.txt
+src/fastjs.egg-info/dependency_links.txt
+src/fastjs.egg-info/requires.txt
+src/fastjs.egg-info/top_level.txt
+tests/test_fastjs.py
+tests/test_quickjs_build.py

fastjs-0.1.0/src/fastjs.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

fastjs-0.1.0/src/fastjs.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

fastjs-0.1.0/src/fastjs.egg-info/top_level.txt

@@ -0,0 +1 @@
+fastjs

fastjs-0.1.0/tests/test_fastjs.py

@@ -0,0 +1,149 @@
+import gc
+import json
+import threading
+
+import pytest
+
+import fastjs
+
+
+@pytest.mark.parametrize(('source', 'expected'), [
+    ('1 + 2', 3), ('1.5', 1.5), ('true', True), ('null', None),
+    ('undefined', None), ('"héllo\\u0000世界"', 'héllo\0世界'),
+    ('123456789012345678901234567890n', 123456789012345678901234567890),
+])
+def test_scalars(source, expected):
+    assert fastjs.eval(source) == expected
+
+
+def test_context_and_calls():
+    ctx = fastjs.Context()
+    ctx.set('name', 'world')
+    assert ctx.eval('`hello ${name}`') == 'hello world'
+    fn = ctx.eval('(a, b) => a + b')
+    assert fn(20, 22) == 42
+    ctx.eval('var counter = 0')
+    ctx.eval('counter++')
+    assert ctx.get('counter') == 1
+    with pytest.raises(TypeError):
+        fn(a=1)
+
+
+def test_objects_and_lifetime():
+    ctx = fastjs.Context()
+    obj = ctx.parse_json('{"items": [1, 2, 3]}')
+    ctx.set('data', obj)
+    assert ctx.eval('data.items[1]') == 2
+    assert json.loads(obj.json()) == {'items': [1, 2, 3]}
+    fn = ctx.eval('(obj) => obj.items.length')
+    del ctx
+    gc.collect()
+    assert fn(obj) == 3
+    assert fastjs.eval('() => 42')() == 42
+
+
+def test_errors_and_recovery():
+    ctx = fastjs.Context()
+    for script in ('throw new Error("boom")', 'const =', 'JSON.parse("!")'):
+        with pytest.raises(fastjs.JSException):
+            ctx.eval(script)
+    with pytest.raises(fastjs.JSException):
+        ctx.parse_json('{')
+    assert ctx.eval('42') == 42
+    with pytest.raises(fastjs.JSException, match='circular'):
+        ctx.eval('var x = {}; x.x = x; x').json()
+
+
+def test_invalid_arguments():
+    ctx = fastjs.Context()
+    for value in ([], {}, object()):
+        with pytest.raises(TypeError):
+            ctx.set('x', value)
+    with pytest.raises(OverflowError):
+        ctx.set('x', 2**60)
+    with pytest.raises(ValueError):
+        ctx.set('x', fastjs.Context().eval('({})'))
+    with pytest.raises(TypeError):
+        ctx.eval('({})')()
+    with pytest.raises(ValueError):
+        ctx.set('a\0b', 1)
+
+
+def test_promise_jobs():
+    ctx = fastjs.Context()
+    ctx.eval('var answer; Promise.resolve(42).then(v => {answer = v})')
+    assert ctx.execute_pending_job() is True
+    assert ctx.execute_pending_job() is False
+    assert ctx.get('answer') == 42
+
+
+def test_time_limit_and_recovery():
+    ctx = fastjs.Context(time_limit=0.01)
+    with pytest.raises(fastjs.JSException, match='interrupted'):
+        ctx.eval('while (true) {}')
+    assert ctx.eval('42') == 42
+    with pytest.raises(fastjs.JSException, match='interrupted'):
+        ctx.eval('() => {while (true) {}}')()
+
+
+@pytest.mark.parametrize('kwargs', [
+    {'memory_limit': -1}, {'stack_limit': 0}, {'time_limit': -1},
+    {'time_limit': float('nan')}, {'time_limit': float('inf')},
+])
+def test_invalid_limits(kwargs):
+    with pytest.raises(ValueError):
+        fastjs.Context(**kwargs)
+
+
+def test_memory_limit():
+    ctx = fastjs.Context(memory_limit=2 * 1024 * 1024)
+    with pytest.raises(fastjs.JSException):
+        ctx.eval('var a = []; for (var i = 0; i < 1000000; i++) a.push({i})')
+
+
+def test_thread_affinity():
+    ctx = fastjs.Context()
+    errors = []
+    def run():
+        try:
+            ctx.eval('1')
+        except RuntimeError as exc:
+            errors.append(str(exc))
+    thread = threading.Thread(target=run)
+    thread.start()
+    thread.join()
+    assert errors and 'creating thread' in errors[0]
+
+
+def test_global_properties_and_safe_integers():
+    ctx = fastjs.Context()
+    ctx.set('世界', 2**53 - 1)
+    assert ctx.get('世界') == 2**53 - 1
+    ctx.set('negative', -(2**53 - 1))
+    assert ctx.get('negative') == -(2**53 - 1)
+    ctx.eval('Object.defineProperty(globalThis, "fixed", {value: 1})')
+    with pytest.raises(fastjs.JSException):
+        ctx.set('fixed', 2)
+    with pytest.raises(ValueError):
+        ctx.get('a\0b')
+
+
+def test_call_conversion_failure_recovers():
+    ctx = fastjs.Context()
+    fn = ctx.eval('(...args) => args.length')
+    with pytest.raises(TypeError):
+        fn('allocated first', {})
+    with pytest.raises(ValueError):
+        fn(fastjs.Context().eval('({})'))
+    assert fn(1, 'two', None) == 3
+
+
+def test_shared_memory_atomics():
+    ctx = fastjs.Context()
+    result = ctx.eval('''
+        var shared = new Int32Array(new SharedArrayBuffer(4));
+        Atomics.store(shared, 0, 7);
+        var previous = Atomics.add(shared, 0, 2);
+        [previous, Atomics.load(shared, 0), Atomics.notify(shared, 0)];
+    ''')
+    assert json.loads(result.json()) == [7, 9, 0]

fastjs-0.1.0/tests/test_quickjs_build.py

@@ -0,0 +1,91 @@
+"""Build input integrity and offline cache behavior, without network access."""
+import hashlib
+import importlib.util
+import io
+from pathlib import Path
+import tarfile
+from urllib.error import URLError
+
+import pytest
+
+
+@pytest.fixture
+def build(monkeypatch, tmp_path):
+    spec = importlib.util.spec_from_file_location(
+        "_quickjs_build", Path(__file__).resolve().parents[1] / "_quickjs_build.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    monkeypatch.setenv("FASTJS_CACHE_DIR", str(tmp_path / "cache"))
+    return module
+
+
+def forbid_network(*args, **kwargs):
+    raise AssertionError("Unexpected download")
+
+
+def test_verified_download_and_offline_cache(build, monkeypatch):
+    content = b"verified archive"
+    monkeypatch.setattr(build, "SHA256", hashlib.sha256(content).hexdigest())
+    monkeypatch.setattr(build, "urlopen", lambda *a, **kw: io.BytesIO(content))
+    assert build.fetch_archive() == content
+    monkeypatch.setattr(build, "urlopen", forbid_network)
+    assert build.fetch_archive() == content
+    assert list(build.cache_dir().iterdir()) == [build.cache_dir() / build.ARCHIVE_NAME]
+
+
+def test_corrupt_cache_is_rejected(build, monkeypatch):
+    build.cache_dir().mkdir()
+    (build.cache_dir() / build.ARCHIVE_NAME).write_bytes(b"corrupt")
+    monkeypatch.setattr(build, "urlopen", forbid_network)
+    with pytest.raises(RuntimeError, match="SHA-256 mismatch"):
+        build.fetch_archive()
+
+
+def test_corrupt_download_is_not_cached(build, monkeypatch):
+    monkeypatch.setattr(build, "urlopen", lambda *a, **kw: io.BytesIO(b"corrupt"))
+    with pytest.raises(RuntimeError, match="SHA-256 mismatch"):
+        build.fetch_archive()
+    assert not (build.cache_dir() / build.ARCHIVE_NAME).exists()
+
+
+def test_download_failure_explains_cache(build, monkeypatch):
+    def unavailable(*args, **kwargs):
+        raise URLError("offline")
+    monkeypatch.setattr(build, "urlopen", unavailable)
+    with pytest.raises(RuntimeError, match="FASTJS_CACHE_DIR"):
+        build.fetch_archive()
+
+
+def archive_bytes(build, *, symlink=False):
+    output = io.BytesIO()
+    with tarfile.open(fileobj=output, mode="w:gz") as archive:
+        for name in (*build.FILES, "../escape"):
+            entry = tarfile.TarInfo(f"quickjs-{build.REVISION}/{name}")
+            data = (build.VERSION if name == "VERSION" else name).encode()
+            if symlink and name == "quickjs.c":
+                entry.type = tarfile.SYMTYPE
+                entry.linkname = "../../outside.c"
+                archive.addfile(entry)
+            else:
+                entry.size = len(data)
+                archive.addfile(entry, io.BytesIO(data))
+    return output.getvalue()
+
+
+def test_extracts_only_required_files(build, monkeypatch, tmp_path):
+    monkeypatch.setattr(build, "fetch_archive", lambda: archive_bytes(build))
+    destination = tmp_path / "sources"
+    assert build.prepare_sources(destination) == destination
+    assert {p.name for p in destination.iterdir()} == set(build.FILES)
+    assert not (tmp_path / "escape").exists()
+    # Reusing identical sources preserves timestamps for incremental builds.
+    before = (destination / "quickjs.c").stat().st_mtime_ns
+    build.prepare_sources(destination)
+    assert (destination / "quickjs.c").stat().st_mtime_ns == before
+
+
+def test_archive_links_are_rejected(build, monkeypatch, tmp_path):
+    monkeypatch.setattr(build, "fetch_archive", lambda: archive_bytes(build, symlink=True))
+    with pytest.raises(RuntimeError, match="not a regular file"):
+        build.prepare_sources(tmp_path / "sources")