Add source plugin frontend API

Author: fffonion

README.md

@@ -1,6 +1,6 @@
 # RustScript
 
-RustScript is the language, VM, Lua/JavaScript frontends, standard library, examples, bytecode/AOT tooling, wasm runtime support, and debugger-facing runtime contract for the RustScript family.
+RustScript is the language, VM/compiler core, standard library, examples, bytecode/AOT tooling, wasm runtime support, and debugger-facing runtime contract for the RustScript family. Compatibility language frontends now live in source-plugin crates.
 
 ## Related projects
 
@@ -9,6 +9,7 @@ RustScript is the language, VM, Lua/JavaScript frontends, standard library, exam
 - CLR VM: https://github.com/rustscript-lang/rustscript-clr-vm
 - Edge runtime and ABI: https://github.com/rustscript-lang/pd-edge
 - Controller: https://github.com/rustscript-lang/pd-controller
+- Compatibility frontends: https://github.com/rustscript-lang/rustscript-compat-frontends
 
 ## Crate usage
 
@@ -26,8 +27,7 @@ cargo test --workspace --jobs 4
 cargo build --workspace --release --jobs 4
 ```
 
-`pd-vm` is a stack-based virtual machine plus compiler toolchain used as a backend for multiple
-source syntaxes (`.rss`, `.js`, `.lua`).
+`pd-vm` is a stack-based virtual machine plus compiler toolchain. It includes the RustScript (`.rss`) frontend and exposes a source-plugin API for compatibility languages such as JavaScript and Lua.
 
 ## Contents
 
@@ -80,15 +80,10 @@ than optional hints.
 Run with the VM runner binary:
 
 ```powershell
-cargo run -p pd-vm --bin pd-vm-run -- --fuel 100000 examples/example.lua
+cargo run -p pd-vm --bin pd-vm-run -- --fuel 100000 examples/example.rss
 ```
 
-Other supported flavors:
-
-```powershell
-cargo run -p pd-vm --bin pd-vm-run -- examples/example.js
-cargo run -p pd-vm --bin pd-vm-run -- examples/example.rss
-```
+Compatibility frontends such as JavaScript and Lua are provided by source-plugin crates. Use `CompileSourceFileOptions::with_source_plugin(...)` when compiling those files from an embedding crate.
 
 ### REPL
 
@@ -104,13 +99,13 @@ cargo run -p pd-vm --bin pd-vm-run -- --repl
 Run with interactive `pdb` debugger on stdio:
 
 ```powershell
-cargo run -p pd-vm --bin pd-vm-run -- --debug examples/example.lua
+cargo run -p pd-vm --bin pd-vm-run -- --debug examples/example.rss
 ```
 
 Run debugger over TCP:
 
 ```powershell
-cargo run -p pd-vm --bin pd-vm-run -- --debug --tcp 127.0.0.1:9002 examples/example.lua
+cargo run -p pd-vm --bin pd-vm-run -- --debug --tcp 127.0.0.1:9002 examples/example.rss
 ```
 
 Useful commands: `break`, `break line`, `step`, `next`, `out`, `stack`, `locals`, `where`, `continue`, `fuel`, `epoch`.
@@ -120,7 +115,7 @@ Useful commands: `break`, `break line`, `step`, `next`, `out`, `stack`, `locals`
 Record execution:
 
 ```powershell
-cargo run -p pd-vm --bin pd-vm-run -- --record out/example.pdr examples/example.lua
+cargo run -p pd-vm --bin pd-vm-run -- --record out/example.pdr examples/example.rss
 ```
 
 Replay execution:
@@ -473,7 +468,7 @@ The end-to-end stack is split into layers. Not every entrypoint uses every layer
 
 1. Module/source loading (`compile_source_file()` path)
 1. Unit linking (`linker::merge_units`)
-1. Frontend lowering (`rustscript`, `javascript`, `lua`)
+1. Frontend lowering (built-in `rustscript`, plus any registered source plugins)
 1. Frontend-independent IR
 1. Type-consistency validation on legalized IR (for example rejecting known `if`/`else` branch mismatches)
 1. Lifetime/liveness lowering plus type metadata collection
@@ -504,8 +499,7 @@ monomorphic runtime fast paths, not to provide a full source-language static typ
 
 #### Compiler APIs
 
-Use `compile_source()` for RustScript, or `compile_source_file()` for extension-based flavor
-selection (`.rss`, `.js`, `.lua`).
+Use `compile_source()` for RustScript, or `compile_source_file()` for built-in `.rss` path loading. For compatibility languages, build options with `CompileSourceFileOptions::with_source_plugin(...)` and call `compile_source_file_with_options(...)`.
 
 ```text
 fn print(x);
@@ -526,23 +520,17 @@ let add = |value| value + base;
 add(5);
 ```
 
-Lua closure equivalent lowered by frontend:
-
-```lua
-local add = function(value) return value + base end
-```
+Compatibility frontends can lower equivalent closure forms through the source-plugin API.
 
 Built-in print aliases (no declaration needed):
 
 - RustScript: `print(value);`, `print("... {}", a);`, `println(value);`, `println("... {}", a);`
-- JavaScript subset: `console.log(value);` and `print(value);`
-- Lua subset: `print(value)`
+- Compatibility frontends may provide their own print aliases through plugin lowering.
 
 Host calls must be explicitly imported:
 
 - RustScript: `use runtime;`, `use http;`, `use rate_limit;`
-- JavaScript: `import * as runtime from "runtime";`, `import * as http from "http";`
-- Lua: `require("runtime")`, `require("http")`
+- Compatibility frontends own their import syntax through `SourcePlugin::parse_imports(...)` and `SourcePlugin::strip_imports(...)`.
 
 #### Assembler API
 
@@ -633,18 +621,11 @@ Module/source loading:
 
 - `crate::...` module paths are not supported in RustScript source loading; use relative module paths
 
-JavaScript frontend:
-
-- arrow closures with block bodies are not supported (expression-body arrows only)
-- `return <expr>;` is lowered to `<expr>;` (function results still follow final-expression semantics)
-
-Lua frontend:
+Source plugins:
 
-- Lua pattern API string methods (`:match`, `:gsub`, etc.) are not supported
-- function literal bodies are limited to `function(...) end`, `function(...) return end`, or `function(...) return <expr[, expr...]> end`
-- direct `function`/`local function` bodies are still minimal: empty/fallthrough, `return`, `return <expr[, expr...]>`, or a single return-only `if`/`elseif`/`else` chain
-- `pcall(...)` / `xpcall(...)` lower with success-only semantics and always prefix `true` before the callee return values
-- multi-return unpacking is currently limited to compiler-known Lua function/closure return shapes; extra return values are dropped, missing locals are filled with `null`, but plain assignment destructuring and arbitrary host-call unpacking are not supported
+- Compatibility-language parsing, lowering, and source import scanning belong in plugin crates.
+- `pd-vm` exposes `SourcePlugin`, `FrontendIr`, parser dialect helpers, and IR builder types for plugin authors.
+- `compile_source_file()` without options only handles built-in `.rss`; use `compile_source_file_with_options()` for plugin-backed extensions.
 
 ### JIT Internals
 

build.rs

@@ -378,7 +378,7 @@ fn render_builtin_catalog(
     )
     .unwrap();
     writeln!(&mut out, "#[repr(u16)]").unwrap();
-    writeln!(&mut out, "pub(crate) enum BuiltinFunction {{").unwrap();
+    writeln!(&mut out, "pub enum BuiltinFunction {{").unwrap();
     for (index, variant) in builtin_variant_order.iter().enumerate() {
         if index == 0 {
             writeln!(&mut out, "    {variant} = 0,").unwrap();
@@ -514,7 +514,7 @@ fn render_builtin_catalog(
 
     writeln!(
         &mut out,
-        "pub(crate) fn is_builtin_namespace(namespace: &str) -> bool {{"
+        "pub fn is_builtin_namespace(namespace: &str) -> bool {{"
     )
     .unwrap();
     writeln!(
@@ -527,7 +527,7 @@ fn render_builtin_catalog(
 
     writeln!(
         &mut out,
-        "pub(crate) fn resolve_builtin_namespace_call(namespace: &str, member: &str) -> Option<BuiltinFunction> {{"
+        "pub fn resolve_builtin_namespace_call(namespace: &str, member: &str) -> Option<BuiltinFunction> {{"
     )
     .unwrap();
     writeln!(
@@ -589,13 +589,13 @@ fn render_builtin_catalog(
     render_builtin_signature_method(&mut out, &builtin_variant_order);
     writeln!(
         &mut out,
-        "    pub(crate) fn from_namespaced_name(name: &str) -> Option<Self> {{"
+        "    pub fn from_namespaced_name(name: &str) -> Option<Self> {{"
     )
     .unwrap();
     writeln!(&mut out, "        resolve_namespaced_builtin(name)").unwrap();
     writeln!(&mut out, "    }}").unwrap();
     writeln!(&mut out).unwrap();
-    writeln!(&mut out, "    pub(crate) fn call_index(self) -> u16 {{").unwrap();
+    writeln!(&mut out, "    pub fn call_index(self) -> u16 {{").unwrap();
     writeln!(&mut out, "        match self {{").unwrap();
     writeln!(
         &mut out,
@@ -1078,7 +1078,7 @@ fn render_builtin_arity_method(
     builtin_variant_order: &[String],
     actual_builtin_by_variant: &HashMap<String, Vec<&CallableDecl>>,
 ) {
-    writeln!(out, "    pub(crate) fn arity(self) -> u8 {{").unwrap();
+    writeln!(out, "    pub fn arity(self) -> u8 {{").unwrap();
     writeln!(out, "        match self {{").unwrap();
     for variant in builtin_variant_order {
         let arity = actual_builtin_by_variant
@@ -1103,11 +1103,7 @@ fn render_builtin_accepts_arity_method(
     builtin_variant_order: &[String],
     actual_builtin_by_variant: &HashMap<String, Vec<&CallableDecl>>,
 ) {
-    writeln!(
-        out,
-        "    pub(crate) fn accepts_arity(self, arity: u8) -> bool {{"
-    )
-    .unwrap();
+    writeln!(out, "    pub fn accepts_arity(self, arity: u8) -> bool {{").unwrap();
     writeln!(out, "        match self {{").unwrap();
     for variant in builtin_variant_order {
         let mut conditions = actual_builtin_by_variant

docs/blog/v07-why-rustscript.md

@@ -6,9 +6,9 @@
 
 ## The Starting Point
 
-pd-vm already runs four source-language frontends on the same stack-based VM with the same bytecode. All four lower into a shared `FrontendIr` before compilation, and all four run on a runtime that uses no garbage collector and relies on deterministic ownership for memory management.
+pd-vm runs RustScript on a stack-based VM with bytecode that plugin frontends can also target. Built-in RustScript and plugin sources lower into a shared `FrontendIr` before compilation, then run on a runtime that uses no garbage collector and relies on deterministic ownership for memory management.
 
-Given those other frontends, a fair question is: why add another one? What does a Rust-shaped scripting syntax buy a VM that already works?
+Given the plugin path for compatibility languages, a fair question is: what does a Rust-shaped scripting syntax buy this VM?
 
 The short answer is that RustScript exists because its syntax carries **intent that the compiler can act on**. Move-vs-copy distinctions, borrow annotations, and mutability declarations are not runtime features. They are compiler inputs. And they happen to be in a syntax that AI models already know well.
 
@@ -34,14 +34,14 @@ let b = a;           // move: `a` is consumed, slot is cleared
 
 The compiler sees the local-to-local rebind of a non-copyable value, lowers it as a consuming load (`MoveVar` in the IR), and emits the null-clear sequence. Using `a` after this point is a compile-time error, not a runtime surprise.
 
-Compare the same logic in the JavaScript frontend:
+Compare the same logic in a copy-by-default compatibility frontend:
 
 ```javascript
 let a = [1, 2, 3];
 let b = a;           // copy: both `a` and `b` share the array
 ```
 
-Both programs compile to valid bytecode on the same VM. The difference is what the compiler knows at the point of the assignment. RustScript's syntax tells it "this is a transfer of ownership." The JS frontend's syntax tells it nothing, so it defaults to shared copy.
+Both programs compile to valid bytecode on the same VM. The difference is what the compiler knows at the point of the assignment. RustScript's syntax tells it "this is a transfer of ownership." A copy-by-default plugin syntax tells it nothing, so it defaults to shared copy.
 
 ### `.copy()` and Borrows
 
@@ -70,7 +70,7 @@ The core of RustScript's value is the availability analysis in `availability.rs`
 
 When `enable_local_move_semantics` is active (RustScript only), the pass enforces stricter rules:
 
-| Situation | RustScript behavior | JS / Lua behavior |
+| Situation | RustScript behavior | Compatibility plugin behavior |
 |---|---|---|
 | Local-to-local rebind of a collection | Move source, reject reuse | Copy (shared ownership) |
 | Local read after move | Compile error | N/A (no moves) |
@@ -113,7 +113,7 @@ The capture binding modes are:
 | **BorrowMut** | `&mut x` in capture position | Non-consuming; mutation tracked |
 | **Move** | `x` (default for non-copyable) | Outer local consumed |
 
-In the JS and Lua frontends, all captures degrade to `Copy` mode. The capture slot still gets a value, but the outer scope keeps its own copy unconditionally.
+Compatibility frontends can choose to degrade captures to `Copy` mode. The capture slot still gets a value, but the outer scope keeps its own copy unconditionally.
 
 ## Type Inference and the Ownership Surface
 
@@ -128,12 +128,12 @@ These are all DX-layer decisions. They catch mistakes before bytecode is generat
 
 ## The AI Angle: Syntax Proximity to Rust
 
-There is a practical benefit that was not part of the original design but became increasingly clear as the project grew: **AI code-generation models produce better RustScript than they produce JavaScript or Lua for this VM**.
+There is a practical benefit that was not part of the original design but became increasingly clear as the project grew: **AI code-generation models produce better RustScript than they produce compatibility languages for this VM**.
 
 The reason is corpus proximity. Large language models trained on significant amounts of Rust code have internalized Rust's ownership patterns, borrow semantics, and idiomatic structures. When asked to write RustScript for pd-vm — which lives in the same repository as the Rust runtime — the model:
 
 1. **Naturally uses ownership-aware patterns.** It writes `let b = a;` as a move and `let b = a.copy();` when it needs the source to survive. It does not try to share mutable state through aliasing.
-2. **Avoids GC-dependent patterns.** Rust-trained models do not reach for garbage-collected idioms like long-lived closures over mutable state or circular references. Those patterns would be valid in the JS frontend but counterproductive for a GC-free runtime.
+2. **Avoids GC-dependent patterns.** Rust-trained models do not reach for garbage-collected idioms like long-lived closures over mutable state or circular references. Those patterns can be natural in compatibility-language frontends but counterproductive for a GC-free runtime.
 3. **Matches the surrounding code style.** The pd-vm runtime is Rust. The compiler is Rust. The test harness is Rust. When the scripting language is also Rust-shaped, the model does not need to context-switch between two different programming idioms within the same codebase.
 4. **Produces more accurate type annotations.** Because the model knows Rust's type annotation syntax, it generates valid RustScript type hints that feed into the compiler's inference pipeline rather than leaving locals at `Unknown`.