2172082 | plum

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

2172082 — Peter John 2026-07-23T21:09:28+05:30

docs: correct cross-file-imports spec scope; add implementation plan

Files changed (2) hide show

docs/superpowers/plans/2026-07-23-cross-file-imports.md +618 -0
docs/superpowers/specs/2026-07-23-cross-file-imports-design.md +17 -11

docs/superpowers/plans/2026-07-23-cross-file-imports.md ADDED Viewed

@@ -0,0 +1,618 @@
+# Cross-File Import Resolution Implementation Plan
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+**Goal:** Make `import <path>` actually resolve to a file on disk and merge its declarations into the compiling program, so files split across `libs/std/*.plum` can reference each other.
+**Architecture:** Add a `load_and_merge(entry, lib_path)` loader in `plum-core` that recursively resolves and parses `import` targets (tracking visited files so diamond imports and cycles both resolve cleanly) and merges every reachable file's items into one `ast::Source`, erroring on duplicate top-level names. `plum-checker::check_source` and `plum_wasm_codegen::compile_source` are completely unchanged — they only ever see the one merged `Source`. `plum-cli`'s `compile` subcommand routes through the loader and gains a `--lib-path` flag.
+**Tech Stack:** Rust, tree-sitter (parsing, unchanged), std::fs/std::path for file resolution. No grammar changes — `import <path>` already parses into `ast::Import { path }`.
+## Global Constraints
+- Spec: `docs/superpowers/specs/2026-07-23-cross-file-imports-design.md`
+- `import std/option` resolves to `<lib-path>/std/option.plum`. `--lib-path` defaults to `./libs` (relative to CWD).
+- In scope: transitive imports, diamond imports (no duplication), import cycles (resolve without hanging or erroring), a clear error for an unresolvable import path, a clear error for two files declaring the same top-level name.
+- Out of scope: selective/aliased imports, a package manager/registry, fixing OTHER `libs/std/*.plum` files' pre-existing broken `import` lines (e.g. `http.plum`'s `import std/path`), any new semantics for `module <name>`.
+- **Known, deliberately accepted scope boundary**: the real `libs/std/list.plum` does NOT fully type-check standalone even after this plan — its `join` method calls `Buffer()`, which is declared nowhere in this repo, and `plum-checker` doesn't process `Item::Trait` at all (no trait-bounded dispatch). Both are separate, unscoped gaps. This plan proves the *loader mechanism* with small fixture files, not with the real, currently-broken `list.plum`.
+- Run `cargo build --workspace` and `cargo test --workspace` after every task that touches Rust code — all pre-existing tests must keep passing throughout.
+---
+### Task 1: `plum-core` — `load_and_merge` loader
+**Files:**
+- Create: `plum-core/src/loader.rs`
+- Modify: `plum-core/src/lib.rs` (export the new module)
+- Modify: `plum-core/Cargo.toml` (add a dev-dependency for on-disk test fixtures)
+- Test: `plum-core/tests/loader_test.rs`
+**Interfaces:**
+- Consumes: `crate::ast::{Source, Item, Import}` (existing), `crate::parser::AstParser` (existing), `tree_sitter`/`tree_sitter_plum` (existing dependencies of this crate).
+- Produces: `pub fn load_and_merge(entry: &std::path::Path, lib_path: &std::path::Path) -> Result<ast::Source, String>`. Task 2 (`plum-cli`) calls this directly; Task 3's test also calls it.
+- [ ] **Step 1: Add the `tempfile` dev-dependency**
+`plum-core/Cargo.toml` currently has no `[dev-dependencies]` section. Add one:
+```toml
+[dev-dependencies]
+tempfile = "3"
+```
+- [ ] **Step 2: Write the failing loader tests**
+Create `plum-core/tests/loader_test.rs`:
+```rust
+use plum_core::load_and_merge;
+use std::fs;
+use tempfile::TempDir;
+/// Writes `name` (without a directory prefix — always placed directly under
+/// the temp dir's `lib_path` subdirectory) with `contents`, creating parent
+/// directories as needed (so `"std/option"` works).
+fn write_lib_file(lib_path: &std::path::Path, name: &str, contents: &str) -> std::path::PathBuf {
+    let path = lib_path.join(format!("{}.plum", name));
+    fs::create_dir_all(path.parent().unwrap()).unwrap();
+    fs::write(&path, contents).unwrap();
+    path
+}
+#[test]
+fn import_sees_imported_declarations() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "helper", "module fixtures\n\nhelperFn() -> Int =\n  42\n");
+    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport helper\n\nmain() -> Int =\n  helperFn()\n");
+    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
+    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
+        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
+        _ => None,
+    }).collect();
+    assert!(names.contains(&"main"), "expected 'main' in merged items, got {:?}", names);
+    assert!(names.contains(&"helperFn"), "expected 'helperFn' in merged items, got {:?}", names);
+}
+#[test]
+fn transitive_import_surfaces_grandchild_declarations() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "c", "module fixtures\n\ncFn() -> Int =\n  3\n");
+    write_lib_file(&lib_path, "b", "module fixtures\n\nimport c\n\nbFn() -> Int =\n  cFn()\n");
+    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\n\nmain() -> Int =\n  bFn()\n");
+    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
+    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
+        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
+        _ => None,
+    }).collect();
+    assert!(names.contains(&"cFn"), "expected transitively-imported 'cFn', got {:?}", names);
+}
+#[test]
+fn diamond_import_includes_shared_dependency_once() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "d", "module fixtures\n\ndFn() -> Int =\n  4\n");
+    write_lib_file(&lib_path, "b", "module fixtures\n\nimport d\n\nbFn() -> Int =\n  dFn()\n");
+    write_lib_file(&lib_path, "c", "module fixtures\n\nimport d\n\ncFn() -> Int =\n  dFn()\n");
+    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\nimport c\n\nmain() -> Int =\n  bFn() + cFn()\n");
+    let merged = load_and_merge(&entry, &lib_path).expect("load_and_merge failed");
+    let d_count = merged.items.iter().filter(|i| matches!(i, plum_core::ast::Item::Fn(f) if f.name == "dFn")).count();
+    assert_eq!(d_count, 1, "expected 'dFn' exactly once in a diamond import, got {}", d_count);
+}
+#[test]
+fn import_cycle_resolves_without_hanging_or_erroring() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "b", "module fixtures\n\nimport a\n\nbFn() -> Int =\n  1\n");
+    let entry = write_lib_file(&lib_path, "a", "module fixtures\n\nimport b\n\nmain() -> Int =\n  bFn()\n");
+    let merged = load_and_merge(&entry, &lib_path).expect("import cycle should resolve, not error");
+    let names: Vec<&str> = merged.items.iter().filter_map(|i| match i {
+        plum_core::ast::Item::Fn(f) => Some(f.name.as_str()),
+        _ => None,
+    }).collect();
+    assert!(names.contains(&"main"));
+    assert!(names.contains(&"bFn"));
+}
+#[test]
+fn unresolvable_import_is_a_clear_error() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport does_not_exist\n\nmain() -> Int =\n  0\n");
+    let result = load_and_merge(&entry, &lib_path);
+    assert!(result.is_err());
+    let msg = result.unwrap_err();
+    assert!(msg.contains("does_not_exist"), "expected error to name the missing import, got: {}", msg);
+}
+#[test]
+fn duplicate_top_level_name_across_files_is_a_clear_error() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "helper", "module fixtures\n\nsharedFn() -> Int =\n  1\n");
+    let entry = write_lib_file(&lib_path, "main", "module fixtures\n\nimport helper\n\nsharedFn() -> Int =\n  2\n");
+    let result = load_and_merge(&entry, &lib_path);
+    assert!(result.is_err());
+    let msg = result.unwrap_err();
+    assert!(msg.contains("sharedFn"), "expected error to name the duplicate 'sharedFn', got: {}", msg);
+}
+#[test]
+fn same_method_name_on_different_receivers_across_files_is_not_a_collision() {
+    let dir = TempDir::new().unwrap();
+    let lib_path = dir.path().join("libs");
+    write_lib_file(&lib_path, "cat", "\
+module fixtures
+type Cat =
+  age: Int
+length<Cat>(self) -> Int =
+  self.age
+");
+    let entry = write_lib_file(&lib_path, "main", "\
+module fixtures
+import cat
+type Box =
+  items: Int
+length<Box>(self) -> Int =
+  self.items
+main() -> Int =
+  0
+");
+    let merged = load_and_merge(&entry, &lib_path).expect("same method name on different receivers should not collide");
+    let method_count = merged.items.iter().filter(|i| matches!(i, plum_core::ast::Item::Fn(f) if f.name == "length")).count();
+    assert_eq!(method_count, 2, "expected both 'length' methods to survive the merge, got {}", method_count);
+}
+```
+- [ ] **Step 3: Run the tests to verify they fail**
+Run: `cargo test -p plum-core --test loader_test 2>&1 | tail -60`
+Expected: FAIL to compile — `plum_core::load_and_merge` doesn't exist yet.
+- [ ] **Step 4: Implement `plum-core/src/loader.rs`**
+```rust
+use std::collections::{HashMap, HashSet};
+use std::path::{Path, PathBuf};
+use crate::ast::{Import, Item, Source};
+use crate::parser::AstParser;
+/// Resolves `entry`'s `import` statements (transitively, and tolerating
+/// diamond imports and cycles) against `lib_path`, and merges every reachable
+/// file's top-level items into a single `Source`. The result's `module` and
+/// `imports` fields are `entry`'s own (imported files' `module`/`imports`
+/// fields are not otherwise used once their `items` have been merged in) —
+/// only `items` accumulates across files.
+///
+/// `import "std/option"` resolves to `<lib_path>/std/option.plum`.
+pub fn load_and_merge(entry: &Path, lib_path: &Path) -> Result<Source, String> {
+    let entry_canon = std::fs::canonicalize(entry)
+        .map_err(|e| format!("cannot read entry file '{}': {}", entry.display(), e))?;
+    let entry_source = parse_file(&entry_canon)?;
+    let mut visited: HashSet<PathBuf> = HashSet::new();
+    let mut items: Vec<Item> = Vec::new();
+    let mut names: HashMap<String, PathBuf> = HashMap::new();
+    visited.insert(entry_canon.clone());
+    merge_items(&entry_canon, &entry_source, &mut items, &mut names)?;
+    for import in &entry_source.imports {
+        load_import(import, lib_path, &mut visited, &mut items, &mut names)?;
+    }
+    Ok(Source {
+        module: entry_source.module,
+        imports: entry_source.imports,
+        items,
+    })
+}
+fn load_import(
+    import: &Import,
+    lib_path: &Path,
+    visited: &mut HashSet<PathBuf>,
+    items: &mut Vec<Item>,
+    names: &mut HashMap<String, PathBuf>,
+) -> Result<(), String> {
+    let target = lib_path.join(format!("{}.plum", import.path));
+    let target_canon = std::fs::canonicalize(&target)
+        .map_err(|_| format!("import '{}': no such file '{}'", import.path, target.display()))?;
+    if !visited.insert(target_canon.clone()) {
+        // Already loaded — a diamond import or a cycle. Either way, its items
+        // are already in `items`; nothing more to do.
+        return Ok(());
+    }
+    let source = parse_file(&target_canon)?;
+    merge_items(&target_canon, &source, items, names)?;
+    for nested in &source.imports {
+        load_import(nested, lib_path, visited, items, names)?;
+    }
+    Ok(())
+}
+fn parse_file(path: &Path) -> Result<Source, String> {
+    let text = std::fs::read_to_string(path)
+        .map_err(|e| format!("cannot read '{}': {}", path.display(), e))?;
+    let mut parser = tree_sitter::Parser::new();
+    parser
+        .set_language(&tree_sitter_plum::LANGUAGE.into())
+        .map_err(|e| format!("language error: {}", e))?;
+    let tree = parser
+        .parse(&text, None)
+        .ok_or_else(|| format!("parse failed for '{}'", path.display()))?;
+    let ap = AstParser::new(&text);
+    Ok(ap.parse_source(tree.root_node()))
+}
+fn merge_items(
+    file: &Path,
+    source: &Source,
+    items: &mut Vec<Item>,
+    names: &mut HashMap<String, PathBuf>,
+) -> Result<(), String> {
+    for item in &source.items {
+        let key = item_name_key(item);
+        if let Some(existing_file) = names.get(&key) {
+            return Err(format!(
+                "duplicate declaration '{}': declared in both '{}' and '{}'",
+                key,
+                existing_file.display(),
+                file.display()
+            ));
+        }
+        names.insert(key, file.to_path_buf());
+        items.push(item.clone());
+    }
+    Ok(())
+}
+/// A collision key that mirrors `plum-checker`'s own separation of
+/// namespaces: methods are keyed by `(receiver, name)` (so `length<Cat>` and
+/// `length<Box>` never collide, exactly like `plum_checker::MethodEnv`),
+/// while classes/traits/enums/consts/free-functions are each their own
+/// flat, kind-qualified namespace.
+fn item_name_key(item: &Item) -> String {
+    match item {
+        Item::Class(c) => format!("class::{}", c.name),
+        Item::Trait(t) => format!("trait::{}", t.name),
+        Item::Enum(e) => format!("enum::{}", e.name),
+        Item::Const(c) => format!("const::{}", c.name),
+        Item::Fn(f) => match &f.type_param {
+            Some(recv) => format!("method::{}::{}", recv, f.name),
+            None => format!("fn::{}", f.name),
+        },
+    }
+}
+```
+- [ ] **Step 5: Export the new module**
+In `plum-core/src/lib.rs`, replace:
+```rust
+pub mod ast;
+pub mod parser;
+pub mod formatter;
+pub use formatter::{format_source, format_source_with_opts, FormatterError};
+pub use parser::AstParser;
+```
+with:
+```rust
+pub mod ast;
+pub mod parser;
+pub mod formatter;
+pub mod loader;
+pub use formatter::{format_source, format_source_with_opts, FormatterError};
+pub use parser::AstParser;
+pub use loader::load_and_merge;
+```
+- [ ] **Step 6: Run the tests to verify they pass**
+Run: `cargo test -p plum-core --test loader_test 2>&1 | tail -80`
+Expected: all 7 tests PASS.
+- [ ] **Step 7: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all pre-existing tests still PASS (this task only adds a new module and a new dev-dependency; nothing existing is touched).
+- [ ] **Step 8: Commit**
+```bash
+git add plum-core/src/loader.rs plum-core/src/lib.rs plum-core/Cargo.toml plum-core/tests/loader_test.rs Cargo.lock
+git commit -m "feat(plum-core): add load_and_merge cross-file import loader"
+```
+---
+### Task 2: `plum-cli` — `--lib-path` and loader integration
+**Files:**
+- Modify: `plum-cli/src/main.rs` (`Command::Compile` variant, `cmd_compile`)
+- Test: `plum-cli/tests/compile_tests.rs`
+- Test fixtures: `test/import_fixtures/helper.plum`, `test/import_fixtures/main.plum` (new)
+**Interfaces:**
+- Consumes: `plum_core::load_and_merge(entry: &Path, lib_path: &Path) -> Result<ast::Source, String>` (Task 1).
+- Produces: `plum compile <file> --lib-path <dir>` resolves imports. No new public Rust functions (this is the CLI's own binary entry point).
+- [ ] **Step 1: Write the failing CLI integration test and its fixtures**
+Create `test/import_fixtures/helper.plum`:
+```
+module fixtures
+helperValue() -> Int =
+  42
+```
+Create `test/import_fixtures/main.plum`:
+```
+module fixtures
+import helper
+main() -> Int =
+  helperValue()
+```
+Add to `plum-cli/tests/compile_tests.rs` (this file already has a `plum_bin()` helper — reuse it, don't redefine it):
+```rust
+#[test]
+fn compile_with_import_resolves_via_lib_path() {
+    let src_path = concat!(env!("CARGO_MANIFEST_DIR"), "/../test/import_fixtures/main.plum");
+    let lib_path = concat!(env!("CARGO_MANIFEST_DIR"), "/../test/import_fixtures");
+    let out_path = std::env::temp_dir().join(format!("plum_test_import_{}.wasm", std::process::id()));
+    let out_path_str = out_path.to_str().unwrap();
+    let status = Command::new(plum_bin())
+        .args(["compile", src_path, "--lib-path", lib_path, "-o", out_path_str])
+        .status()
+        .expect("failed to run plum compile");
+    assert!(status.success(), "plum compile exited with: {}", status);
+    let bytes = std::fs::read(out_path).expect("output wasm not found");
+    assert_eq!(&bytes[0..4], b"\0asm");
+}
+```
+- [ ] **Step 2: Run the test to verify it fails**
+Run: `cargo test -p plum-cli compile_with_import_resolves_via_lib_path 2>&1 | tail -40`
+Expected: FAIL — `--lib-path` isn't a recognized flag yet (clap error), or (if you haven't rebuilt) the import is silently dropped and `helperValue` is undefined, producing a type-check error.
+- [ ] **Step 3: Add `--lib-path` and route `cmd_compile` through the loader**
+In `plum-cli/src/main.rs`, the `Compile` variant currently reads:
+```rust
+    /// Compile a Plum source file to WASM
+    Compile {
+        /// Source file to compile
+        file: std::path::PathBuf,
+        /// Output path (default: input with .wasm extension)
+        #[arg(short, long)]
+        output: Option<std::path::PathBuf>,
+    },
+```
+Replace it with:
+```rust
+    /// Compile a Plum source file to WASM
+    Compile {
+        /// Source file to compile
+        file: std::path::PathBuf,
+        /// Output path (default: input with .wasm extension)
+        #[arg(short, long)]
+        output: Option<std::path::PathBuf>,
+        /// Root directory `import <path>` is resolved against (`import std/x` -> `<lib-path>/std/x.plum`)
+        #[arg(long, default_value = "libs")]
+        lib_path: std::path::PathBuf,
+    },
+```
+The dispatch in `run()` currently reads:
+```rust
+        Command::Compile { file, output } => cmd_compile(file, output),
+```
+Replace with:
+```rust
+        Command::Compile { file, output, lib_path } => cmd_compile(file, output, lib_path),
+```
+`cmd_compile` currently reads (~line 106-137):
+```rust
+fn cmd_compile(file: std::path::PathBuf, output: Option<std::path::PathBuf>) -> Result<()> {
+    let source = fs::read_to_string(&file)
+        .with_context(|| format!("failed to read {}", file.display()))?;
+    // Parse
+    let mut parser = tree_sitter::Parser::new();
+    parser
+        .set_language(&tree_sitter_plum::LANGUAGE.into())
+        .map_err(|e| anyhow::anyhow!("language error: {e}"))?;
+    let tree = parser
+        .parse(&source, None)
+        .ok_or_else(|| anyhow::anyhow!("parse failed"))?;
+    let ap = AstParser::new(&source);
+    let ast = ap.parse_source(tree.root_node());
+    // Type check
+    if let Err(errors) = plum_checker::check_source(&ast) {
+        for e in &errors {
+            eprintln!("type error: {}", e.message);
+        }
+        process::exit(1);
+    }
+    // Codegen
+    let wasm_bytes = plum_wasm_codegen::compile_source(&ast)
+        .map_err(|e| anyhow::anyhow!("codegen error: {e}"))?;
+    // Write output
+    let out_path = output.unwrap_or_else(|| file.with_extension("wasm"));
+    fs::write(&out_path, &wasm_bytes)
+        .with_context(|| format!("failed to write {}", out_path.display()))?;
+```
+Replace the parse block (everything from `let source = fs::read_to_string...` through `let ast = ap.parse_source(tree.root_node());`) with a single call to the loader, and add the new `lib_path` parameter:
+```rust
+fn cmd_compile(
+    file: std::path::PathBuf,
+    output: Option<std::path::PathBuf>,
+    lib_path: std::path::PathBuf,
+) -> Result<()> {
+    let ast = plum_core::load_and_merge(&file, &lib_path)
+        .map_err(|e| anyhow::anyhow!("{e}"))?;
+    // Type check
+    if let Err(errors) = plum_checker::check_source(&ast) {
+        for e in &errors {
+            eprintln!("type error: {}", e.message);
+        }
+        process::exit(1);
+    }
+    // Codegen
+    let wasm_bytes = plum_wasm_codegen::compile_source(&ast)
+        .map_err(|e| anyhow::anyhow!("codegen error: {e}"))?;
+    // Write output
+    let out_path = output.unwrap_or_else(|| file.with_extension("wasm"));
+    fs::write(&out_path, &wasm_bytes)
+        .with_context(|| format!("failed to write {}", out_path.display()))?;
+```
+(Leave the rest of the function — whatever follows the `fs::write` call — unchanged.)
+`AstParser`, `tree_sitter::Parser`, and `tree_sitter_plum::LANGUAGE` are used in `plum-cli/src/main.rs` ONLY inside the block you just replaced in `cmd_compile` — `cmd_format` does not use them. After this edit, remove the now-unused `use plum_core::AstParser;` import near the top of the file (~line 9). The `tree_sitter`/`tree_sitter_plum` crates were referenced only via their fully-qualified paths (`tree_sitter::Parser::new()`, `tree_sitter_plum::LANGUAGE`) with no `use` import for them, so there's no `use` line to remove for those — but confirm with `cargo build -p plum-cli 2>&1 | grep -i warning` that no unused-import warning remains after removing the `AstParser` import.
+- [ ] **Step 4: Run the test to verify it passes**
+Run: `cargo test -p plum-cli compile_with_import_resolves_via_lib_path 2>&1 | tail -40`
+Expected: PASS.
+- [ ] **Step 5: Run the full plum-cli test suite**
+Run: `cargo test -p plum-cli 2>&1 | tail -60`
+Expected: all tests PASS, including the pre-existing `compile_simple_add_produces_wasm` (which passes no `--lib-path`, exercising the new flag's default value — `simple_add.plum` has no imports, so the loader trivially returns just that one file, and the default `./libs` never needs to exist for a file with no imports since `load_and_merge` only ever touches `lib_path` when resolving an actual `import`).
+- [ ] **Step 6: Run the full workspace test suite**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS.
+- [ ] **Step 7: Commit**
+```bash
+git add plum-cli/src/main.rs plum-cli/tests/compile_tests.rs test/import_fixtures/
+git commit -m "feat(plum-cli): resolve import via --lib-path using the new loader"
+```
+---
+### Task 3: `libs/std/list.plum` — add the missing import
+**Files:**
+- Modify: `libs/std/list.plum`
+**Interfaces:**
+- Consumes: nothing new (this task doesn't touch Rust code).
+- Produces: nothing new (this is a one-line library fix; Task 2's loader is already fully tested and proven).
+- [ ] **Step 1: Add the import line**
+In `libs/std/list.plum`, the file currently opens:
+```
+module std
+# A node stores the data in a list and contains pointers to the previous and next sibling nodes
+type Node(a) =
+```
+Change it to:
+```
+module std
+import std/option
+# A node stores the data in a list and contains pointers to the previous and next sibling nodes
+type Node(a) =
+```
+- [ ] **Step 2: Confirm no test regresses**
+Run: `cargo test --workspace 2>&1 | tail -100`
+Expected: all tests PASS (no existing test currently compiles `libs/std/list.plum` at all — this is a one-line fix to a library file that isn't part of the Rust build, so nothing should change). This step exists to catch the unexpected case where something DOES already reference this file's exact text.
+- [ ] **Step 3: Commit**
+```bash
+git add libs/std/list.plum
+git commit -m "fix(libs/std): list.plum imports std/option instead of relying on unresolved cross-file references"
+```
+---
+### Task 4: README — close the gap
+**Files:**
+- Modify: `README.md` (the "Known gaps" section)
+**Interfaces:**
+- Consumes: nothing.
+- Produces: nothing (docs only).
+- [ ] **Step 1: Update the Known gaps bullet**
+Run: `grep -n "cross-file" README.md` to find the current bullet, which reads along the lines of:
+```
+- `libs/std`'s actual `List`/`Map` still don't fully compile — there's no cross-file import resolution yet, so a file that references a type/enum declared in a different `libs/std` file won't type-check standalone; separately, `List`'s methods beyond `get`/`length` (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) are still `todo` — variadic parameters (`values: ...a`) now work as a language feature, but wiring these methods up is separate, unstarted work
+```
+Replace it with:
+```
+- `libs/std`'s actual `List`/`Map` still don't fully compile — cross-file `import` resolution now works (`import <path>` resolves against `--lib-path`, defaulting to `./libs`), and variadic parameters work, but `List`'s methods beyond `get`/`length` (`add`, `set`, `removeAt`, `remove`, `clear`, `reverse`) are still `todo`; separately, `List`'s own `join` method (and `Map`) reference a `Buffer` type and trait-bounded dispatch (`Stringable`) that don't exist yet — `plum-checker` doesn't process trait declarations at all currently
+```
+- [ ] **Step 2: Commit**
+```bash
+git add README.md
+git commit -m "docs: cross-file import resolution is no longer a known gap"
+```

docs/superpowers/specs/2026-07-23-cross-file-imports-design.md CHANGED Viewed

@@ -125,17 +125,23 @@ argument (default `"libs"`), passed straight through to `load_and_merge`.
     error naming both files
   - two different classes/methods across files sharing a method name (but
     different receivers) is NOT an error
-- `libs/std/list.plum` gains the one new line: `import std/option`.
+- `libs/std/list.plum` gains the one new line: `import std/option` — a
+  correct, useful fix on its own regardless of the point below.
-- A new end-to-end test (in whichever crate is the natural home for a
+- A new end-to-end `plum-cli` integration test (matching the existing
-  real-filesystem integration test — `plum-cli` or a new top-level
+  `plum-cli/tests/compile_tests.rs` convention: invoke the actual built
+  `plum` binary via `std::process::Command`, using
-  `tests/` — using `concat!(env!("CARGO_MANIFEST_DIR"), "/../libs")` or
+  `concat!(env!("CARGO_MANIFEST_DIR"), "/...")`-relative fixture paths) that
-  equivalent to locate the real repo `libs/` directory) that loads and merges
-  `libs/std/list.plum` via `load_and_merge`, then runs the existing
-  `check_source` and `compile_source` against the merged result, asserting
+  proves the *loader mechanism* end-to-end: two small, purpose-built fixture
-  both succeed — proving `list.plum` compiles standalone for the first time.
+  files (one importing the other) compile successfully via `plum compile
+  <entry> --lib-path <dir>`.
+  **Not** in scope for this test: asserting that the real `libs/std/list.plum`
+  fully type-checks/compiles standalone. It doesn't, independent of this
-  (Its still-`todo` methods compile to a runtime trap exactly as they do
+  spec — `list.plum`'s `join` method calls `Buffer()`, and `Buffer` isn't
+  declared anywhere in this repo; more generally, `plum-checker` doesn't
+  process `Item::Trait` at all yet (no trait-bounded dispatch, e.g. `a.toStr()`
+  on a generic constrained to `Stringable`). Both are separate, unscoped gaps.
-  today; this test only proves the *file* now resolves and compiles, not that
+  This spec only makes the *import mechanism* correct and proven; it doesn't
-  every method works — that's the next cycle's job.)
+  make every existing `libs/std` file type-check.
 ## README