358 lines
5.9 KiB
Markdown
358 lines
5.9 KiB
Markdown
# PBS Compiler — Junie PR Plan
|
|
|
|
> **Purpose:** this document defines a sequence of small, focused Pull Requests to be implemented by *Junie*, one at a time.
|
|
>
|
|
> **Audience:** compiler implementer (AI or human).
|
|
>
|
|
> **Scope:** PBS-first compiler architecture. TS and Lua frontends are assumed **removed**.
|
|
>
|
|
> **Hard rules:**
|
|
>
|
|
> * Each PR must compile and pass tests.
|
|
> * Each PR must include tests.
|
|
> * No speculative features.
|
|
> * Follow the `Prometeu Base Script (PBS) - Implementation Spec`.
|
|
|
|
---
|
|
|
|
## Global Architectural Direction (Non-negotiable)
|
|
|
|
* PBS is the **primary language**.
|
|
* Frontend is implemented **before** runtime integration.
|
|
* Architecture uses **two IR layers**:
|
|
|
|
* **Core IR** (PBS-semantic, typed, resolved)
|
|
* **VM IR** (stack-based, backend-friendly)
|
|
* VM IR remains simple and stable.
|
|
* Lowering is explicit and testable.
|
|
|
|
---
|
|
|
|
# PR-01 — ProjectConfig and Frontend Selection
|
|
|
|
### Goal
|
|
|
|
Introduce a project-level configuration that selects the frontend and entry file explicitly.
|
|
|
|
### Motivation
|
|
|
|
The compiler must not hardcode entry points or languages. PBS will be the first frontend, others may return later.
|
|
|
|
### Scope
|
|
|
|
* Add `ProjectConfig` (serde-deserializable) loaded from `prometeu.json`
|
|
* Fields (v0):
|
|
|
|
* `script_fe: "pbs"`
|
|
* `entry: "main.pbs"`
|
|
* Refactor compiler entry point to:
|
|
|
|
* load config
|
|
* select frontend by `script_fe`
|
|
* resolve entry path relative to project root
|
|
|
|
### Files Likely Touched
|
|
|
|
* `compiler/mod.rs`
|
|
* `compiler/driver.rs`
|
|
* `common/config.rs` (new)
|
|
|
|
### Tests (mandatory)
|
|
|
|
* unit test: load valid `prometeu.json`
|
|
* unit test: invalid frontend → diagnostic
|
|
* integration test: project root + entry resolution
|
|
|
|
### Notes to Junie
|
|
|
|
Do **not** add PBS parsing yet. This PR is infrastructure only.
|
|
|
|
---
|
|
|
|
# PR-02 — Core IR Skeleton (PBS-first)
|
|
|
|
### Goal
|
|
|
|
Introduce a **Core IR** layer independent from the VM IR.
|
|
|
|
### Motivation
|
|
|
|
PBS semantics must be represented before lowering to VM instructions.
|
|
|
|
### Scope
|
|
|
|
* Add new module: `ir_core`
|
|
* Define minimal structures:
|
|
|
|
* `Program`
|
|
* `Module`
|
|
* `Function`
|
|
* `Block`
|
|
* `Instr`
|
|
* `Terminator`
|
|
* IDs only (no string-based calls):
|
|
|
|
* `FunctionId`
|
|
* `ConstId`
|
|
* `TypeId`
|
|
|
|
### Constraints
|
|
|
|
* Core IR must NOT reference VM opcodes
|
|
* No lowering yet
|
|
|
|
### Tests
|
|
|
|
* construct Core IR manually in tests
|
|
* snapshot test (JSON) for deterministic shape
|
|
|
|
---
|
|
|
|
# PR-03 — Constant Pool and IDs
|
|
|
|
### Goal
|
|
|
|
Introduce a stable constant pool shared by Core IR and VM IR.
|
|
|
|
### Scope
|
|
|
|
* Add `ConstPool`:
|
|
|
|
* strings
|
|
* numbers
|
|
* Replace inline literals in VM IR with `ConstId`
|
|
* Update existing VM IR to accept `PushConst(ConstId)`
|
|
|
|
### Tests
|
|
|
|
* const pool deduplication
|
|
* deterministic ConstId assignment
|
|
* IR snapshot stability
|
|
|
|
---
|
|
|
|
# PR-04 — VM IR Cleanup (Stabilization)
|
|
|
|
### Goal
|
|
|
|
Stabilize VM IR as a **lowering target**, not a language IR.
|
|
|
|
### Scope
|
|
|
|
* Replace string-based calls with `FunctionId`
|
|
* Ensure locals are accessed via slots
|
|
* Remove or internalize `PushScope` / `PopScope`
|
|
|
|
### Tests
|
|
|
|
* golden VM IR tests
|
|
* lowering smoke test (Core IR → VM IR)
|
|
|
|
---
|
|
|
|
# PR-05 — Core IR → VM IR Lowering Pass
|
|
|
|
### Goal
|
|
|
|
Implement the lowering pass from Core IR to VM IR.
|
|
|
|
### Scope
|
|
|
|
* New module: `lowering/core_to_vm.rs`
|
|
* Lowering rules:
|
|
|
|
* Core blocks → labels
|
|
* Core calls → VM calls
|
|
* Host calls preserved
|
|
* No PBS frontend yet
|
|
|
|
### Tests
|
|
|
|
* lowering correctness
|
|
* instruction ordering
|
|
* label resolution
|
|
|
|
---
|
|
|
|
# PR-06 — PBS Frontend: Lexer
|
|
|
|
### Goal
|
|
|
|
Implement PBS lexer according to the spec.
|
|
|
|
### Scope
|
|
|
|
* Token kinds
|
|
* Keyword table
|
|
* Span tracking
|
|
|
|
### Tests
|
|
|
|
* tokenization tests
|
|
* keyword vs identifier tests
|
|
* bounded literals
|
|
|
|
---
|
|
|
|
# PR-07 — PBS Frontend: Parser (Raw AST)
|
|
|
|
### Goal
|
|
|
|
Parse PBS source into a raw AST.
|
|
|
|
### Scope
|
|
|
|
* Imports
|
|
* Top-level declarations
|
|
* Blocks
|
|
* Expressions (calls, literals, control flow)
|
|
|
|
### Tests
|
|
|
|
* valid programs
|
|
* syntax error recovery
|
|
|
|
---
|
|
|
|
# PR-08 — PBS Frontend: Symbol Collection and Resolver
|
|
|
|
### Goal
|
|
|
|
Resolve names, modules, and visibility.
|
|
|
|
### Scope
|
|
|
|
* Type namespace vs value namespace
|
|
* Visibility rules
|
|
* Import resolution
|
|
|
|
### Tests
|
|
|
|
* duplicate symbols
|
|
* invalid imports
|
|
* visibility errors
|
|
|
|
---
|
|
|
|
# PR-09 — PBS Frontend: Type Checking
|
|
|
|
### Goal
|
|
|
|
Validate PBS semantics.
|
|
|
|
### Scope
|
|
|
|
* Primitive types
|
|
* Structs
|
|
* `optional<T>` and `result<T, E>`
|
|
* Mutability rules
|
|
* Return path validation
|
|
|
|
### Tests
|
|
|
|
* type mismatch
|
|
* mutability violations
|
|
* implicit `none` behavior
|
|
|
|
---
|
|
|
|
# PR-10 — PBS Frontend: Semantic Lowering to Core IR
|
|
|
|
### Goal
|
|
|
|
Lower typed PBS AST into Core IR.
|
|
|
|
### Scope
|
|
|
|
* ID-based calls
|
|
* ConstPool usage
|
|
* Control flow lowering
|
|
* SAFE vs HIP effects represented explicitly
|
|
|
|
### Tests
|
|
|
|
* PBS → Core IR snapshots
|
|
* semantic correctness
|
|
|
|
---
|
|
|
|
# PR-11 — Host-bound Contracts and Syscall Mapping
|
|
|
|
### Goal
|
|
|
|
Connect PBS host-bound contracts to runtime syscalls (without executing them).
|
|
|
|
### Scope
|
|
|
|
* Contract registry
|
|
* Mapping: contract.method → syscall id
|
|
* Core IR host call nodes
|
|
|
|
### Tests
|
|
|
|
* invalid contract calls
|
|
* correct syscall mapping
|
|
|
|
---
|
|
|
|
# PR-12 — Diagnostics Canonicalization
|
|
|
|
### Goal
|
|
|
|
Standardize diagnostics output.
|
|
|
|
### Scope
|
|
|
|
* Error codes (`E_*`, `W_*`)
|
|
* Stable messages
|
|
* Span accuracy
|
|
|
|
### Tests
|
|
|
|
* golden diagnostics
|
|
|
|
---
|
|
|
|
# PR-13 — Backend Integration (VM IR → Bytecode)
|
|
|
|
### Goal
|
|
|
|
Reconnect the pipeline to the Prometeu runtime backend.
|
|
|
|
### Scope
|
|
|
|
* VM IR → bytecode emission
|
|
* No PBS semantics here
|
|
|
|
### Tests
|
|
|
|
* bytecode emission smoke test
|
|
|
|
---
|
|
|
|
# PR-14 — End-to-End PBS Compile Test
|
|
|
|
### Goal
|
|
|
|
Prove the full pipeline works.
|
|
|
|
### Scope
|
|
|
|
* Sample PBS project
|
|
* Compile → bytecode
|
|
* Diagnostics only (no execution)
|
|
|
|
### Tests
|
|
|
|
* golden bytecode snapshot
|
|
|
|
---
|
|
|
|
## Final Note to Junie
|
|
|
|
Do **not** skip PRs.
|
|
Do **not** merge multiple PRs together.
|
|
If the spec is unclear, create a failing test and document the ambiguity.
|
|
|
|
This plan is the authoritative roadmap for PBS frontend implementation.
|