249 lines
5.2 KiB
Markdown
249 lines
5.2 KiB
Markdown
## PR-11 — Dependency Fetching v0: local cache layout + git/path fetch
|
|
|
|
**Why:** Graph resolution needs a concrete directory for each dependency.
|
|
|
|
### Scope
|
|
|
|
* Implement `prometeu_compiler::deps::fetch`:
|
|
|
|
* `fetch_path(dep, base_dir) -> ProjectDir`
|
|
* `fetch_git(dep, cache_dir) -> ProjectDir`
|
|
* Define a cache layout:
|
|
|
|
* `~/.prometeu/cache/git/<hash>/...` (or configurable)
|
|
* the dependency is *materialized* as a directory containing `prometeu.json`
|
|
* For git deps (v0):
|
|
|
|
* accept `git` URL + optional `version`
|
|
* support `version: "latest"` as default
|
|
* implementation can pin to HEAD for now (but must expose in diagnostics)
|
|
|
|
### Deliverables
|
|
|
|
* Config option: `PROMETEU_CACHE_DIR` override
|
|
* Errors:
|
|
|
|
* clone failed
|
|
* missing manifest in fetched project
|
|
|
|
### Tests
|
|
|
|
* path fetch resolves relative paths
|
|
* cache path generation deterministic
|
|
|
|
### Acceptance
|
|
|
|
* Resolver can rely on fetcher to produce directories.
|
|
|
|
---
|
|
|
|
## PR-12 — Module Discovery v0: find PBS sources per project
|
|
|
|
**Why:** Once deps are resolved, the compiler must discover compilation units.
|
|
|
|
### Scope
|
|
|
|
* Define a convention (v0):
|
|
|
|
* `src/**/*.pbs` are source files
|
|
* `src/main.pbs` for `kind=app` (entry)
|
|
* Implement `prometeu_compiler::sources::discover(project_dir)`:
|
|
|
|
* returns ordered list of source files
|
|
* Enforce:
|
|
|
|
* `kind=app` must have `src/main.pbs`
|
|
* `kind=lib` must not require `main`
|
|
|
|
### Deliverables
|
|
|
|
* `ProjectSources { main: Option<Path>, files: Vec<Path> }`
|
|
|
|
### Tests
|
|
|
|
* app requires main
|
|
* lib without main accepted
|
|
|
|
### Acceptance
|
|
|
|
* Compiler can list sources for every node in the graph.
|
|
|
|
---
|
|
|
|
## PR-13 — Build Plan v0: deterministic compilation order
|
|
|
|
**Why:** We need a stable pipeline: compile deps first, then root.
|
|
|
|
### Scope
|
|
|
|
* Implement `prometeu_compiler::build::plan`:
|
|
|
|
* Input: `ResolvedGraph`
|
|
* Output: topologically sorted build steps
|
|
* Each step contains:
|
|
|
|
* project identity
|
|
* project dir
|
|
* sources list
|
|
* dependency edge map (alias -> resolved project)
|
|
|
|
### Deliverables
|
|
|
|
* `BuildPlan { steps: Vec<BuildStep> }`
|
|
|
|
### Tests
|
|
|
|
* topo ordering stable across runs
|
|
|
|
### Acceptance
|
|
|
|
* BuildPlan is deterministic and includes all info needed to compile.
|
|
|
|
---
|
|
|
|
## PR-14 — Compiler Output Format v0: emit per-project object module (intermediate)
|
|
|
|
**Why:** Linking needs an intermediate representation (IR/object) per project.
|
|
|
|
### Scope
|
|
|
|
* Define `CompiledModule` (compiler output) containing:
|
|
|
|
* `module_name` (project name)
|
|
* `exports` (functions/symbols)
|
|
* `imports` (symbol refs by (dep-alias, symbol))
|
|
* `const_pool` fragment
|
|
* `code` fragment
|
|
* `function_metas` fragment
|
|
* This is **not** the final VM blob.
|
|
|
|
### Deliverables
|
|
|
|
* `compile_project(step) -> Result<CompiledModule, CompileError>`
|
|
|
|
### Tests
|
|
|
|
* compile root-only project to `CompiledModule`
|
|
|
|
### Acceptance
|
|
|
|
* Compiler can produce a linkable unit per project.
|
|
|
|
---
|
|
|
|
## PR-15 — Link Orchestration v0 inside `prometeu_compiler`
|
|
|
|
**Why:** The compiler must produce the final closed-world blob.
|
|
|
|
### Scope
|
|
|
|
* Move “link pipeline” responsibility to `prometeu_compiler`:
|
|
|
|
* Input: `Vec<CompiledModule>` in build order
|
|
* Output: `ProgramImage` (single bytecode blob)
|
|
* Define linker responsibilities (v0):
|
|
|
|
* resolve imports to exports across modules
|
|
* assign final `FunctionTable` indices
|
|
* patch CALL targets to `func_id`
|
|
* merge const pools deterministically
|
|
* emit the final PBS v0 module image
|
|
|
|
### Deliverables
|
|
|
|
* `link(modules) -> Result<ProgramImage, LinkError>`
|
|
* `LinkError`:
|
|
|
|
* unresolved import
|
|
* duplicate export
|
|
* incompatible symbol signatures (if available)
|
|
|
|
### Tests
|
|
|
|
* `archive-pbs/test01` becomes an integration test:
|
|
|
|
* root depends on a lib
|
|
* root calls into lib
|
|
* output blob runs in VM
|
|
|
|
### Acceptance
|
|
|
|
* Compiler emits a single executable blob; VM only loads it.
|
|
|
|
---
|
|
|
|
## PR-16 — VM Boundary Cleanup: remove linker behavior from runtime
|
|
|
|
**Why:** Runtime should be dumb: no dependency resolution, no linking.
|
|
|
|
### Scope
|
|
|
|
* Audit `prometeu_core` + `prometeu_bytecode`:
|
|
|
|
* VM loads PBS v0 module
|
|
* VM verifies (optional) and executes
|
|
* Remove/disable any linker-like logic in runtime:
|
|
|
|
* no search for func idx by address beyond function table
|
|
* no module graph assumptions
|
|
|
|
### Deliverables
|
|
|
|
* VM init uses:
|
|
|
|
* `BytecodeLoader::load()` => `(code, const_pool, functions)`
|
|
* verifier as a gate
|
|
|
|
### Tests
|
|
|
|
* runtime loads compiler-produced blob
|
|
|
|
### Acceptance
|
|
|
|
* Linking is fully compiler-owned.
|
|
|
|
---
|
|
|
|
## PR-17 — Diagnostics UX: show dependency graph + resolution trace
|
|
|
|
**Why:** When deps fail, we need actionable feedback.
|
|
|
|
### Scope
|
|
|
|
* Add CLI output (or compiler API output) showing:
|
|
|
|
* resolved graph
|
|
* alias mapping
|
|
* where a conflict occurred
|
|
* Add `--explain-deps` mode (or equivalent)
|
|
|
|
### Deliverables
|
|
|
|
* human-readable resolution trace
|
|
|
|
### Tests
|
|
|
|
* snapshot tests for error messages (best-effort)
|
|
|
|
### Acceptance
|
|
|
|
* Users can debug dependency issues without guessing.
|
|
|
|
---
|
|
|
|
## Suggested execution order
|
|
|
|
1. PR-09 → PR-10 → PR-11
|
|
2. PR-12 → PR-13
|
|
3. PR-14 → PR-15
|
|
4. PR-16 → PR-17
|
|
|
|
---
|
|
|
|
## Notes for Junie
|
|
|
|
* Keep all “v0” decisions simple and deterministic.
|
|
* Favor explicit errors over silent fallback.
|
|
* Treat `archive-pbs/test01` as the north-star integration scenario.
|
|
* No background tasks: every PR must include tests proving the behavior.
|