rapydscript-ng 0.7.24 → 0.8.0

package/test/traceback.pyj

@@ -0,0 +1,263 @@
+# globals: assrt, rs_generate_source_map
+import traceback
+
+generate_source_map = rs_generate_source_map
+
+# ---------------------------------------------------------------------------
+# _vlq_decode
+# ---------------------------------------------------------------------------
+
+# All-zero segment: AAAA → [0, 0, 0, 0]
+assrt.deepEqual(traceback._vlq_decode('AAAA'), [0, 0, 0, 0], 'AAAA → all zeros')
+
+# Positive deltas: I=8→4, A=0, A=0, G=6→3
+assrt.deepEqual(traceback._vlq_decode('IAAG'), [4, 0, 0, 3], 'IAAG → [4,0,0,3]')
+
+# Source line delta of 1: AACA → [0, 0, 1, 0]
+assrt.deepEqual(traceback._vlq_decode('AACA'), [0, 0, 1, 0], 'AACA → [0,0,1,0]')
+
+# Single negative value: D=3 (odd) → -1
+assrt.deepEqual(traceback._vlq_decode('D'), [-1], 'D → [-1]')
+
+# Negative source column delta: H=7 (odd) → -3
+assrt.deepEqual(traceback._vlq_decode('IAAH'), [4, 0, 0, -3], 'IAAH → [4,0,0,-3]')
+
+# Multi-byte VLQ: k has continuation bit, kD → 50
+assrt.deepEqual(traceback._vlq_decode('kD'), [50], 'kD → [50] multi-byte')
+
+# Multi-byte VLQ in a full four-field segment
+assrt.deepEqual(traceback._vlq_decode('kDAAkD'), [50, 0, 0, 50], 'kDAAkD → [50,0,0,50]')
+
+# Empty string → empty array
+assrt.deepEqual(traceback._vlq_decode(''), v'[]', 'empty string → empty result')
+
+# ---------------------------------------------------------------------------
+# _decode_source_map
+# ---------------------------------------------------------------------------
+
+# Empty mappings → one line group with no entries
+decoded = traceback._decode_source_map({'version': 3, 'sources': v'[]', 'mappings': '', 'sourceRoot': ''})
+assrt.strictEqual(decoded.length, 1, 'empty mappings → 1 line group')
+assrt.strictEqual(decoded[0].length, 0, 'that group has no entries')
+
+# Single segment at origin
+smap = JSON.parse(generate_source_map([[0, 0, 'a.pyj', 0, 0]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+assrt.ok(decoded.length >= 1, 'single segment: at least one line group')
+e = decoded[0][0]
+assrt.strictEqual(e.gen_col, 0, 'gen_col 0')
+assrt.strictEqual(e.src_file, 'a.pyj', 'src_file a.pyj')
+assrt.strictEqual(e.src_line, 0, 'src_line 0')
+assrt.strictEqual(e.src_col, 0, 'src_col 0')
+
+# Two segments on separate generated lines — deltas accumulate across lines
+smap = JSON.parse(generate_source_map([[0, 0, 'a.pyj', 0, 0], [1, 0, 'a.pyj', 1, 0]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+assrt.ok(decoded.length >= 2, 'two-line map: at least 2 line groups')
+assrt.strictEqual(decoded[1][0].src_line, 1, 'second line resolves to src_line 1')
+assrt.strictEqual(decoded[1][0].src_col, 0, 'second line resolves to src_col 0')
+
+# Two segments on same line — gen_col delta is relative within the line
+smap = JSON.parse(generate_source_map([[0, 0, 'a.pyj', 0, 0], [0, 4, 'a.pyj', 0, 3]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+assrt.strictEqual(decoded[0].length, 2, 'two segs on same line → 2 entries')
+assrt.strictEqual(decoded[0][0].gen_col, 0, 'first entry gen_col=0')
+assrt.strictEqual(decoded[0][1].gen_col, 4, 'second entry gen_col=4')
+assrt.strictEqual(decoded[0][1].src_col, 3, 'second entry src_col=3')
+
+# Two source files — source index resolves correctly
+smap = JSON.parse(generate_source_map([[0, 0, 'f1.pyj', 0, 0], [0, 10, 'f2.pyj', 0, 0]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+assrt.strictEqual(decoded[0][0].src_file, 'f1.pyj', 'first seg → f1.pyj')
+assrt.strictEqual(decoded[0][1].src_file, 'f2.pyj', 'second seg → f2.pyj')
+
+# sourceRoot is prepended to src_file
+smap = JSON.parse(generate_source_map([[0, 0, 'a.pyj', 0, 0]], 'out.js', 'src/'))
+decoded = traceback._decode_source_map(smap)
+assrt.strictEqual(decoded[0][0].src_file, 'src/a.pyj', 'sourceRoot prepended')
+
+# Gap in generated lines (line 1 empty) — line group count matches max line
+smap = JSON.parse(generate_source_map([[0, 0, 'a.pyj', 0, 0], [2, 0, 'a.pyj', 2, 0]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+assrt.ok(decoded.length >= 3, 'gap: at least 3 groups for lines 0..2')
+assrt.strictEqual(decoded[1].length, 0, 'gap: line 1 group is empty')
+assrt.strictEqual(decoded[2][0].src_line, 2, 'line 2 resolves to src_line 2')
+
+# ---------------------------------------------------------------------------
+# _find_mapping
+# ---------------------------------------------------------------------------
+
+# Build a decoded map with two entries on line 0 and one on line 1
+smap = JSON.parse(generate_source_map(
+    [[0, 0, 'a.pyj', 10, 0], [0, 5, 'a.pyj', 10, 4], [1, 0, 'a.pyj', 20, 0]], 'out.js', ''))
+decoded = traceback._decode_source_map(smap)
+
+# Exact gen_col match
+m = traceback._find_mapping(decoded, 0, 0)
+assrt.ok(m, 'exact match gen_col=0')
+assrt.strictEqual(m.src_line, 10, 'src_line 10 for gen_col=0')
+assrt.strictEqual(m.src_col, 0, 'src_col 0 for gen_col=0')
+
+# Between two entries — picks the one with largest gen_col not exceeding target
+m = traceback._find_mapping(decoded, 0, 7)
+assrt.ok(m, 'match between entries (gen_col=7)')
+assrt.strictEqual(m.gen_col, 5, 'picks gen_col=5 for target 7')
+assrt.strictEqual(m.src_col, 4, 'src_col 4 for that entry')
+
+# Target gen_col before all entries on the line → no match
+m = traceback._find_mapping(decoded, 0, -1)
+assrt.ok(not m, 'gen_col before first entry → None')
+
+# Line with a single entry
+m = traceback._find_mapping(decoded, 1, 0)
+assrt.ok(m, 'single entry on line 1 found')
+assrt.strictEqual(m.src_line, 20, 'src_line 20 on line 1')
+
+# gen_line beyond decoded range → None
+assrt.ok(not traceback._find_mapping(decoded, 99, 0), 'out-of-range gen_line → None')
+
+# Null/empty decoded → None
+assrt.ok(not traceback._find_mapping(None, 0, 0), 'null decoded → None')
+assrt.ok(not traceback._find_mapping(v'[]', 0, 0), 'empty decoded → None')
+
+# Line group with no entries → None
+smap2 = JSON.parse(generate_source_map([[2, 0, 'a.pyj', 5, 0]], 'out.js', ''))
+decoded2 = traceback._decode_source_map(smap2)
+assrt.ok(not traceback._find_mapping(decoded2, 0, 0), 'empty line group → None')
+assrt.ok(traceback._find_mapping(decoded2, 2, 0), 'populated line group → found')
+
+# ---------------------------------------------------------------------------
+# _parse_stack_frame
+# ---------------------------------------------------------------------------
+
+# Chrome/Node with function name in parentheses
+f = traceback._parse_stack_frame('    at foo (script.js:10:5)')
+assrt.ok(f, 'parsed Chrome frame with function name')
+assrt.strictEqual(f.file, 'script.js', 'file from Chrome frame')
+assrt.strictEqual(f.line, 9, 'line is 0-based (10 → 9)')
+assrt.strictEqual(f.col, 4, 'col is 0-based (5 → 4)')
+assrt.strictEqual(f.func, 'foo', 'func captured for named Chrome frame')
+
+# Chrome/Node with method name (dot notation)
+f = traceback._parse_stack_frame('    at Object.bar (app.js:3:1)')
+assrt.ok(f, 'parsed Chrome frame with method name')
+assrt.strictEqual(f.file, 'app.js', 'file from method Chrome frame')
+assrt.strictEqual(f.line, 2, 'line 0-based')
+assrt.strictEqual(f.col, 0, 'col 0-based')
+assrt.strictEqual(f.func, 'Object.bar', 'func captured for method Chrome frame')
+
+# Chrome/Node bare (no function name)
+f = traceback._parse_stack_frame('    at script.js:3:1')
+assrt.ok(f, 'parsed bare Chrome frame')
+assrt.strictEqual(f.file, 'script.js', 'file from bare frame')
+assrt.strictEqual(f.line, 2, 'line 0-based from bare frame')
+assrt.strictEqual(f.col, 0, 'col 0-based from bare frame')
+assrt.ok(not f.func, 'func is falsy for bare Chrome frame')
+
+# Firefox format with function name
+f = traceback._parse_stack_frame('bar@script.js:7:12')
+assrt.ok(f, 'parsed Firefox frame with function name')
+assrt.strictEqual(f.file, 'script.js', 'file from Firefox frame')
+assrt.strictEqual(f.line, 6, 'line 0-based from Firefox frame')
+assrt.strictEqual(f.col, 11, 'col 0-based from Firefox frame')
+assrt.strictEqual(f.func, 'bar', 'func captured for Firefox frame')
+
+# Firefox anonymous frame
+f = traceback._parse_stack_frame('@/path/to/file.js:1:1')
+assrt.ok(f, 'parsed anonymous Firefox frame')
+assrt.strictEqual(f.line, 0, 'line 0-based anonymous Firefox')
+assrt.strictEqual(f.col, 0, 'col 0-based anonymous Firefox')
+assrt.ok(not f.func, 'func is falsy for anonymous Firefox frame')
+
+# Lines that are not stack frames → None
+assrt.ok(not traceback._parse_stack_frame('TypeError: some error'), 'error message → None')
+assrt.ok(not traceback._parse_stack_frame(''), 'empty string → None')
+assrt.ok(not traceback._parse_stack_frame('Traceback (most recent call last):'), 'header line → None')
+
+# ---------------------------------------------------------------------------
+# set_source_map_data / _get_decoded_map
+# ---------------------------------------------------------------------------
+
+# Clearing the source map
+traceback.set_source_map_data(None)
+assrt.ok(not traceback._get_decoded_map(), '_get_decoded_map returns falsy when no map set')
+
+# Setting a source map makes _get_decoded_map return a decoded object
+smap = JSON.parse(generate_source_map([[0, 0, 'test.pyj', 0, 0]], 'out.js', ''))
+traceback.set_source_map_data(smap)
+d1 = traceback._get_decoded_map()
+assrt.ok(d1, '_get_decoded_map returns decoded map after set')
+
+# Second call returns the same cached object
+d2 = traceback._get_decoded_map()
+assrt.ok(d1 is d2, '_get_decoded_map returns cached object on second call')
+
+# Re-setting the map invalidates the cache and produces a new decoded object
+traceback.set_source_map_data(smap)
+d3 = traceback._get_decoded_map()
+assrt.ok(d1 is not d3, 're-setting map clears cache and re-decodes')
+
+# ---------------------------------------------------------------------------
+# _get_internal_traceback — end-to-end with mock error
+#
+# We use a hand-crafted error.stack that represents a V8 stack trace for
+# a fictional "demo.js" file, paired with a source map that maps those
+# generated positions back to "demo.pyj" source lines.  This lets us
+# test the full mapping pipeline without needing to eval compiled code.
+#
+# ---------------------------------------------------------------------------
+
+# Source map: two user-code frames mapped to known pyj source positions.
+#   demo.js:5:3  (gen_line=4, gen_col=2) → demo.pyj line 2 col 5 (src_line=1, src_col=4)
+#   demo.js:10:1 (gen_line=9, gen_col=0) → demo.pyj line 5 col 1 (src_line=4, src_col=0)
+segments = [
+    [4, 0, 'demo.pyj', 1, 0],
+    [4, 2, 'demo.pyj', 1, 4],
+    [9, 0, 'demo.pyj', 4, 0],
+]
+smap = JSON.parse(generate_source_map(segments, 'demo.js', ''))
+traceback.set_source_map_data(smap)
+
+mock_err = new Error('test error')
+mock_err.name = 'TestError'
+mock_err.stack = (
+    'TestError: test error\n'
+    '    at new TestError (baselib.js:1:1)\n'
+    '    at throw_me (demo.js:5:3)\n'
+    '    at demo.js:10:1'
+)
+
+e, js_lines, mapped_lines = traceback._get_internal_traceback(mock_err)
+
+# The error message is the first return value
+assrt.strictEqual(e, 'TestError: test error', 'error message returned as first element')
+
+# The JS frames array must include the user frame
+assrt.ok(js_lines.join('\n').indexOf('throw_me') >= 0, 'JS section: user frame present')
+
+# Mapped lines are returned as an array with entries for each mapped frame
+assrt.ok(mapped_lines.length > 0, 'mapped lines returned when source map is set')
+assrt.ok(mapped_lines.join('\n').indexOf('demo.pyj') >= 0, 'mapped frames reference demo.pyj')
+
+# Frame at demo.js:5:3 → gen_line=4, gen_col=2 → src_line=1 → displayed as line 2
+assrt.ok(mapped_lines.join('\n').indexOf('"demo.pyj", line 2') >= 0, 'first frame maps to line 2 in demo.pyj')
+
+# Frame at demo.js:10:1 → gen_line=9, gen_col=0 → src_line=4 → displayed as line 5
+assrt.ok(mapped_lines.join('\n').indexOf('"demo.pyj", line 5') >= 0, 'second frame maps to line 5 in demo.pyj')
+
+# Named frame includes "in <funcname>" in the mapped output
+assrt.ok(mapped_lines.join('\n').indexOf('in throw_me') >= 0, 'function name "throw_me" included in mapped frame')
+
+# Bare frame (no function name) does not produce a spurious "in" clause
+bare_mapped = v'[]'
+for ml in mapped_lines:
+    if ml.indexOf('line 5') >= 0:
+        bare_mapped.push(ml)
+assrt.ok(bare_mapped.length > 0, 'bare frame entry found')
+assrt.ok(bare_mapped[0].indexOf(', in ') < 0, 'bare frame has no "in" clause')
+
+# When source map is cleared, mapped_lines is empty
+traceback.set_source_map_data(None)
+e_no_map, js_lines_no_map, mapped_lines_no_map = traceback._get_internal_traceback(mock_err)
+assrt.strictEqual(mapped_lines_no_map.length, 0, 'no mapped lines without source map')
+assrt.strictEqual(e_no_map, 'TestError: test error', 'JS error message still returned without map')

package/test/treeshaking.pyj

@@ -0,0 +1,181 @@
+# vim:fileencoding=utf-8
+# globals: test_path, compiler_dir, assrt
+
+path = require('path')
+vm = require('vm')
+
+tree_shake = require('./treeshake.mjs').default
+baselib = fs.readFileSync(path.join(compiler_dir, 'baselib-plain-pretty.js'), 'utf-8')
+src_lib = path.join(compiler_dir, '..', 'src', 'lib')
+
+eq = assrt.equal
+ok = assrt.ok
+
+def new_output_stream(opts):
+    return v'new RapydScript.OutputStream(opts)'
+
+def make_output_stream(omit_baselib):
+    opts = {
+        'js_version': 6,
+        'beautify': False,
+        'private_scope': False,
+        'write_name': False,
+        'keep_docstrings': False,
+    }
+    if omit_baselib:
+        opts['omit_baselib'] = True
+    else:
+        opts['baselib_plain'] = baselib
+    return new_output_stream(opts)
+
+async def parse_code(code, extra_opts):
+    opts = {
+        'filename': '<test>',
+        'basedir': test_path,
+        'libdir': src_lib,
+    }
+    if extra_opts:
+        for k in extra_opts:
+            opts[k] = extra_opts[k]
+    return await RapydScript.parse(code, opts)
+
+def js_of(ast, omit_baselib):
+    output = make_output_stream(omit_baselib)
+    ast.print(output)
+    return output.get()
+
+async def compile_shaken(code, extra_opts):
+    ast = await parse_code(code, extra_opts)
+    tree_shake(ast)
+    return js_of(ast, True)
+
+async def run_shaken(code, extra_opts):
+    ast = await parse_code(code, extra_opts)
+    tree_shake(ast)
+    output = make_output_stream(False)
+    ast.print(output)
+    js = output.get()
+    sandbox = {'console': console}
+    vm.runInNewContext(js, sandbox, {'filename': '<treeshake-test>'})
+    return sandbox
+
+async def run_tests():
+    # ── dead top-level function removed ──────────────────────────────────────────
+    js = await compile_shaken('def live():\n    return 1\ndef dead():\n    return 2\nx = live()')
+    ok(js.indexOf('function dead') < 0, 'dead function must be removed')
+    ok(js.indexOf('function live') >= 0, 'live function must be kept')
+
+    # ── dead top-level class removed ─────────────────────────────────────────────
+    js = await compile_shaken('class Live:\n    def __init__(self):\n        self.x = 1\nclass Dead:\n    def __init__(self):\n        self.y = 2\nu = Live()')
+    ok(js.indexOf('function Dead') < 0, 'dead class must be removed')
+    ok(js.indexOf('function Live') >= 0, 'live class must be kept')
+
+    # ── transitively dead code removed ───────────────────────────────────────────
+    js = await compile_shaken('def helper():\n    return 42\ndef dead_caller():\n    return helper()\ndef live():\n    return 1\nx = live()')
+    ok(js.indexOf('function helper') < 0, 'transitively dead helper must be removed')
+    ok(js.indexOf('function dead_caller') < 0, 'dead caller must be removed')
+    ok(js.indexOf('function live') >= 0, 'live function must be kept')
+
+    # ── transitively live code preserved ─────────────────────────────────────────
+    js = await compile_shaken('def helper():\n    return 42\ndef live_caller():\n    return helper()\nx = live_caller()')
+    ok(js.indexOf('function helper') >= 0, 'transitively live helper must be kept')
+    ok(js.indexOf('function live_caller') >= 0, 'live caller must be kept')
+
+    # ── circular references: both live ───────────────────────────────────────────
+    js = await compile_shaken('def a():\n    return b()\ndef b():\n    return a()\na()')
+    ok(js.indexOf('function a') >= 0, 'circular-dep a must be kept')
+    ok(js.indexOf('function b') >= 0, 'circular-dep b must be kept')
+
+    # ── function used as value stays live ─────────────────────────────────────────
+    js = await compile_shaken('def foo():\n    return 1\ncallback = foo')
+    ok(js.indexOf('function foo') >= 0, 'function used as value must be kept')
+
+    # ── class used as base class stays live ──────────────────────────────────────
+    js = await compile_shaken('class Base:\n    def method(self):\n        return 1\nclass Derived(Base):\n    pass\nx = Derived()')
+    ok(js.indexOf('function Base') >= 0, 'base class must be kept')
+    ok(js.indexOf('function Derived') >= 0, 'derived class must be kept')
+
+    # ── decorator marks function as live ─────────────────────────────────────────
+    js = await compile_shaken('def my_dec(f):\n    return f\n@my_dec\ndef foo():\n    return 1\nfoo()')
+    ok(js.indexOf('function my_dec') >= 0, 'decorator must be kept when decorated function is live')
+
+    # ── completely unused module import removed ───────────────────────────────────
+    js = await compile_shaken('from _treeshake_mod import func_used\nx = 1')
+    ok(js.indexOf('_treeshake_mod') < 0, 'unused module must be removed from output')
+    ok(js.indexOf('ρσ_modules') < 0 or js.indexOf('_treeshake_mod') < 0, 'module IIFE must not be emitted')
+
+    # ── module used only in dead code is removed ─────────────────────────────────
+    js = await compile_shaken('from _treeshake_mod import func_used\ndef dead():\n    return func_used()\nx = 1')
+    ok(js.indexOf('_treeshake_mod') < 0, 'module only referenced from dead code must be removed')
+
+    # ── partially used module: only used function imported ───────────────────────
+    js = await compile_shaken('from _treeshake_mod import func_used, func_unused\nx = func_used()')
+    ok(js.indexOf('func_unused') < 0, 'unused import binding must be removed')
+    ok(js.indexOf('func_used') >= 0, 'used import binding must be kept')
+
+    # ── used module kept, unused function in it removed ──────────────────────────
+    js = await compile_shaken('from _treeshake_mod import func_used\nx = func_used()')
+    ok(js.indexOf('func_unused') < 0, 'unused function in used module must be removed')
+    ok(js.indexOf('module_var') >= 0, 'module variable (non-def) must always be kept')
+
+    # ── transitive liveness: helper_b calls helper_a ─────────────────────────────
+    js = await compile_shaken('from _treeshake_mod import helper_b\nx = helper_b()')
+    ok(js.indexOf('helper_a') >= 0, 'transitively needed helper_a must be kept')
+    ok(js.indexOf('helper_b') >= 0, 'directly imported helper_b must be kept')
+    ok(js.indexOf('func_unused') < 0, 'unrelated func_unused must be removed')
+
+    # ── stdlib module removed when unused ────────────────────────────────────────
+    js = await compile_shaken('from math import sin\ndef dead():\n    return sin(1.0)\nx = 1')
+    ok(js.indexOf('math') < 0 or js.indexOf('ρσ_modules.math') < 0,
+       'stdlib module only used from dead code must be removed')
+
+    # ── stdlib: only used function kept (when module not cached) ─────────────────
+    js = await compile_shaken('from math import sin\nx = sin(1.0)')
+    ok(js.indexOf('sin') >= 0, 'used stdlib function must be present')
+
+    # ── namespace import: module without side-effect calls removed when unused ────
+    # _treeshake_mod has only a simple scalar assignment at module level (no calls)
+    js = await compile_shaken('import _treeshake_mod\nx = 1')
+    ok(js.indexOf('_treeshake_mod') < 0, 'namespace import of module with no side-effect calls must be removed when unused')
+
+    # ── namespace import: module kept when namespace is used ─────────────────────
+    js = await compile_shaken('import _treeshake_mod\nx = _treeshake_mod.func_used()')
+    ok(js.indexOf('_treeshake_mod') >= 0, 'namespace import of used module must be kept')
+
+    # ── side-effect namespace import: module with module-level call must be kept ──
+    # Mirrors calibre's "import initialize" pattern where the module patches a global
+    js = await compile_shaken('import _treeshake_side_effect\nx = 1')
+    ok(js.indexOf('_treeshake_side_effect') >= 0, 'namespace import of module with side-effect calls must not be removed')
+
+    # ── side-effect namespace import: the side effect must actually run ───────────
+    ctx = await run_shaken('import _treeshake_side_effect\nresult = "x".__treeshake_test()')
+    eq(ctx['result'], 'side_effect_ran', 'side-effect namespace import must execute module-level calls')
+
+    # ── behavior: tree-shaken code runs correctly ─────────────────────────────────
+    ctx = await run_shaken('def live():\n    return 42\ndef dead():\n    return 99\nresult = live()')
+    eq(ctx['result'], 42, 'tree-shaken code must return correct result')
+    ok(not (ctx['dead'] if ctx['dead'] else False), 'dead function must not be defined after tree shaking')
+
+    # ── behavior: class instantiation survives tree shaking ──────────────────────
+    ctx = await run_shaken('class MyClass:\n    def __init__(self, v):\n        self.v = v\nobj = MyClass(7)')
+    eq(ctx['obj'].v, 7, 'instantiated object must have correct attribute')
+
+    # ── behavior: decorator works after tree shaking ─────────────────────────────
+    ctx = await run_shaken('def identity(f):\n    return f\n@identity\ndef compute():\n    return 55\nresult = compute()')
+    eq(ctx['result'], 55, 'decorated function must work correctly after tree shaking')
+
+    # ── variable at top level not removed by tree shaking ────────────────────────
+    ctx = await run_shaken('my_var = 123\ndef unused():\n    return 0')
+    eq(ctx['my_var'], 123, 'top-level variable must not be removed')
+
+    # ── @no_prune: function never called directly is preserved ────────────────────
+    js = await compile_shaken('@no_prune\ndef pinned():\n    return 1\ndef unpinned():\n    return 2\nx = 1')
+    ok(js.indexOf('function pinned') >= 0, '@no_prune function must not be pruned')
+    ok(js.indexOf('function unpinned') < 0, 'non-annotated unused function must still be pruned')
+
+    # ── @no_prune: class never referenced is preserved ───────────────────────────
+    js = await compile_shaken('@no_prune\nclass PinnedClass:\n    def __init__(self):\n        self.x = 1\nclass UnpinnedClass:\n    def __init__(self):\n        self.y = 2\nx = 1')
+    ok(js.indexOf('function PinnedClass') >= 0, '@no_prune class must not be pruned')
+    ok(js.indexOf('function UnpinnedClass') < 0, 'non-annotated unused class must still be pruned')
+
+__test_async_done__ = run_tests()

package/test/web_repl_export.pyj

@@ -0,0 +1,88 @@
+# globals: assrt, fs, require, test_path, compiler_dir, console
+
+async def run_tests():
+    os = require('os')
+    path = require('path')
+    vm = require('vm')
+
+    run_export = require('./web_repl_export.mjs').default
+    base_path = path.resolve(compiler_dir, '..')
+    lib_path = compiler_dir
+
+    tmpdir = fs.mkdtempSync(path.join(os.tmpdir(), 'rs-web-repl-test-'))
+    await run_export(base_path, lib_path, {'files': [tmpdir]})
+
+    rs_path = path.join(tmpdir, 'rapydscript.js')
+    assrt.ok(fs.existsSync(rs_path), 'web-repl-export must create rapydscript.js')
+
+    # Load rapydscript.js into a vm context; the IIFE does (function(external_namespace){...})(this)
+    # so this === ctx and ctx.RapydScript is set to the namespace object
+    rs_code = fs.readFileSync(rs_path, 'utf-8')
+    ctx = {'console': console}
+    vm.runInNewContext(rs_code, ctx)
+    RS = ctx.RapydScript
+
+    assrt.ok(RS, 'RapydScript namespace must be defined after loading rapydscript.js')
+    assrt.ok(RS.compile, 'compile must be defined on the namespace')
+    assrt.ok(RS.create_embedded_compiler, 'create_embedded_compiler must be defined on the namespace')
+    assrt.ok(RS.file_data, 'file_data must be present on the namespace')
+
+    # Verify basic compilation works
+    js = await RS.compile('x = 1 + 2\n', 'test.pyj', {})
+    assrt.ok(js and js.length > 0, 'compile must return non-empty JS for basic code')
+
+    # Set up a virtual file system that records stat and write calls so each hook
+    # can be verified independently.  Cache path for __vfs__/mymod.pyj is
+    # __vfs__/mymod.pyj-cached (cache_file_name with empty module_cache_dir).
+    vfs_source = 'def greet(name):\n    return "Hello, " + name\n'
+    vfs_written = {}
+    stat_calls = []
+    write_calls = []
+
+    def vfs_read(vfs_path, enc):
+        if vfs_path == '__vfs__/mymod.pyj':
+            return Promise.resolve(vfs_source)
+        err = new Error('ENOENT: ' + vfs_path)
+        err.code = 'ENOENT'
+        return Promise.reject(err)
+
+    def vfs_write(vfs_path, data):
+        write_calls.push(vfs_path)
+        vfs_written[vfs_path] = data
+        return Promise.resolve()
+
+    def vfs_stat(vfs_path):
+        stat_calls.push(vfs_path)
+        if vfs_path == '__vfs__/mymod.pyj':
+            # Return content so the compiler avoids a separate readfile call
+            return Promise.resolve({'mtimeMs': 1000, 'content': vfs_source})
+        err = new Error('ENOENT: ' + vfs_path)
+        err.code = 'ENOENT'
+        return Promise.reject(err)
+
+    RS.virtual_file_system = {
+        'read_file': vfs_read,
+        'write_file': vfs_write,
+        'stat_file': vfs_stat,
+    }
+
+    # create_embedded_compiler sets basedir=__vfs__ and libdir=__stdlib__, routing
+    # all user imports through VFS
+    embedded = await RS.create_embedded_compiler()
+    js2 = await embedded.compile('from mymod import greet\nresult = greet("World")\n')
+    assrt.ok(js2 and js2.length > 0, 'embedded compiler with VFS must return non-empty JS')
+    assrt.ok(js2.indexOf('greet') >= 0, 'compiled output must reference the function imported via VFS')
+
+    # stat_file must be called when the compiler resolves the VFS module path
+    assrt.ok(stat_calls.length > 0, 'stat_file must be called during compilation of VFS imports')
+    assrt.ok(stat_calls.indexOf('__vfs__/mymod.pyj') >= 0,
+             'stat_file must be called with the imported module path')
+
+    # write_file must be called when the compiler writes the parsed-AST cache
+    assrt.ok(write_calls.length > 0, 'write_file must be called to persist the compiled VFS module cache')
+    assrt.ok(write_calls.indexOf('__vfs__/mymod.pyj-cached') >= 0,
+             'write_file must be called with the cache path derived from the VFS module')
+
+    fs.rmSync(tmpdir, {'recursive': True})
+
+__test_async_done__ = run_tests()