plum

# Design: cross-file import resolution

## Problem

Every `libs/std/*.plum` file declares `module std`, but there's no actual

module-resolution mechanism — `ast::Import { path }` is parsed and then

completely discarded; `plum-cli`'s `compile` command only ever reads and

compiles the single file it's given. `libs/std/list.plum` references

`Option`/`Node`; `Node` is declared in the same file, but `Option` lives in

`libs/std/option.plum` — so `list.plum` cannot type-check or compile standalone

today. This is the second (and, after this lands, last) half of README's

"Known gaps" bullet about `libs/std`'s `List`/`Map` not fully compiling.

Wiring up `List`'s remaining `todo` methods (`add`/`set`/`removeAt`/`remove`/

`clear`/`reverse`) is explicitly **out of scope** for this spec — it's the next,

separate cycle. This spec only makes cross-file `import` actually resolve, so

`list.plum` (with its currently-implemented methods; still-`todo` ones keep

trapping at runtime exactly as they do today) compiles standalone for the

first time.

## Scope

In scope:

- `import <path>` resolves `<path>` (a `/`-separated string, e.g. `std/option`)

  to a file on disk and merges that file's declarations into the compiling

  program.

- Transitive imports (A imports B, B imports C: A sees C's declarations too).

- Diamond imports (A imports both B and C, both import D: D's declarations

  appear exactly once, not duplicated).

- Import cycles (A imports B, B imports A) resolve without an infinite loop or

  a spurious error — this is normal, permitted structure, not a mistake.

- A clear, specific error for: an import path that doesn't resolve to any file;

  two merged files declaring the same top-level name.

- Adding the one missing `import std/option` line to `libs/std/list.plum` (the

  concrete fix this whole spec exists to enable) and proving, via a real

  on-disk test, that `list.plum` now type-checks and compiles standalone.

Out of scope:

- `List`'s own `todo` methods (separate, later cycle).

- A package manager, versioning, or any registry — resolution is purely

  path-based against one configurable root directory.

- Selective/aliased imports (`import std/option { Some, None }`, `import ... as

  x`) — the grammar only supports a bare path today: `import <path>` always

  pulls in everything that path's file declares.

- Re-validating or fixing the OTHER `libs/std/*.plum` files' existing `import`

  lines that reference nonexistent targets (e.g. `http.plum`'s `import

  std/path` and `import std/http/content_type`, neither of which corresponds

  to a real file in this repo). Those files are a rough, partial port from

  another language's stdlib pseudo-syntax (per their own `NOTE:` comments) and

  aren't this spec's concern — this spec makes `import` itself work

  correctly; it doesn't audit every existing library file's import list.

- `Module`/`module <name>` gets no new semantics — it stays exactly as

  decorative/unused as it is today. Resolution is driven entirely by

  `Import.path`, never by matching one file's `module` name against another's.

## Path resolution

`import std/option` resolves against a single configurable root directory

(the "lib path"): `<lib-path>/std/option.plum`. `plum-cli`'s `compile`

subcommand gains a `--lib-path <dir>` flag, defaulting to `./libs` (relative to

the current working directory) — matching today's actual `libs/std/*.plum`

layout with no extra configuration needed to build the standard library from

the repo root.

## Architecture

Add a loader ahead of the existing, **unchanged** `plum_checker::check_source`

/ `plum_wasm_codegen::compile_source` — those two functions still only ever

see a single, already-fully-merged `ast::Source` and need no awareness that

multiple files were involved. The loader lives in `plum-core` (alongside

`AstParser`, which it uses directly) as a new small module:

```rust

pub fn load_and_merge(entry: &Path, lib_path: &Path) -> Result<ast::Source, String>

```

Algorithm: parse `entry` into a `Source`. Walk its `imports` (and, recursively,

every newly-loaded file's own `imports`) with a `visited: HashSet<PathBuf>` of

*canonicalized* file paths already parsed. For each import path not yet

visited: resolve it to `<lib_path>/<path>.plum`, error clearly if that file

doesn't exist, otherwise parse it, mark it visited, append its `items` to the

running merged list (recording each item's name -> source file for collision

detection), and recurse into *its* imports before returning to the caller's

remaining imports. An already-visited import is silently skipped (this is what

makes diamond imports and cycles both "just work" — a cycle's second visit to

an already-in-progress file is indistinguishable, at this level, from a diamond

import's second visit to an already-finished one; both hit the `visited` check

and stop).

Name-collision detection: as items are appended, check each item's name (a

function/method key, class name, enum name, or const name — one extraction

function per `Item` variant, mirroring how `plum-checker`'s own

`build_global_tables` already walks `source.items`) against a running

`HashMap<String, PathBuf>` of name -> the file that first declared it; a name

seen again from a *different* file is an error naming both files. (Two

`name<Receiver>(...)` methods with the same method name but different

receivers are NOT a collision — key on `(receiver, name)` for methods exactly

the way `plum-checker`'s `MethodEnv` already does, so unrelated methods that

happen to share a name across files, e.g. two different classes each defining

`length`, don't falsely collide.)

The result: one `ast::Source` whose `items` is the union of every reachable

file's items (each appearing exactly once), which `plum-cli` hands to the

existing `check_source`/`compile_source` unchanged.

## `plum-cli` integration

`cmd_compile` always routes through `load_and_merge` (even a zero-import file

trivially returns just itself) — the special-cased single-file parse it does

today is removed, not kept as a fallback. `Compile` gains a `--lib-path <dir>`

argument (default `"libs"`), passed straight through to `load_and_merge`.

## Testing

- `plum-core` loader unit tests (using `tempfile`-style on-disk fixtures — real

  files in a temp directory, not in-memory strings, since the loader's whole

  job is filesystem resolution):

  - a file importing another file sees the imported file's declarations

  - transitive import (A -> B -> C) surfaces C's declarations to A

  - diamond import (A -> B, A -> C, B -> D, C -> D) includes D's declarations

    exactly once

  - an import cycle (A -> B -> A) resolves without hanging or erroring

  - an import path that resolves to no file is a clear, specific error

  - two merged files declaring the same top-level name is a clear, specific

    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` — a

  correct, useful fix on its own regardless of the point below.

- A new end-to-end `plum-cli` integration test (matching the existing

  `plum-cli/tests/compile_tests.rs` convention: invoke the actual built

  `plum` binary via `std::process::Command`, using

  `concat!(env!("CARGO_MANIFEST_DIR"), "/...")`-relative fixture paths) that

  proves the *loader mechanism* end-to-end: two small, purpose-built fixture

  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

  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.

  This spec only makes the *import mechanism* correct and proven; it doesn't

  make every existing `libs/std` file type-check.

## README

Once this lands, the "Known gaps" bullet's cross-file-import clause is

removed entirely, leaving only the `List`-methods-still-`todo` clause (now

correctly describing it as blocked on nothing but not-yet-done work, since

both of its former prerequisites — variadic parameters and cross-file

imports — are complete).