plum

# Nested Method Declarations — Design Spec

## Goal

Let methods be declared indented directly inside a `type`/`enum` body,
implicitly bound to that type as their receiver, instead of always requiring
a separate top-level declaration with an explicit `<Receiver>` annotation:

```
enum Step(n: Int) =
  | READ_MIN_OCCURANCES(0)
  | READ_MAX_OCCURANCES(1)
  | READ_CHAR_TO_COUNT(2)
  | COUNT_OCCURANCES(3)

  toNumber(self) =
    match self
      READ_MIN_OCCURANCES => 0
      READ_MAX_OCCURANCES => 1
      READ_CHAR_TO_COUNT => 2
      COUNT_OCCURANCES => 3
```

`toNumber(self) = ...` here is exactly equivalent to writing
`toNumber<Step>(self) = ...` at the top level today — nesting inside the
enum body is sugar for the receiver annotation, not a new binding mechanism.

## Non-goals

- **Purely additive, not a replacement.** Today's top-level
  `methodName<Receiver>(...) = ...` form keeps working unchanged, and can be
  freely mixed with nested declarations for the same type (some methods
  nested, some declared the old way) — this spec only adds a second surface
  syntax for the same underlying `ast::Fn { type_param: Some(receiver), ... }`
  shape; the checker and codegen need no awareness that this feature exists.
- **`trait` bodies are out of scope.** A trait's body holds method
  *signatures* (`trait_field`, no body) — nesting a full method
  *implementation* inside a trait would be a "default method" feature,
  a materially different and separate concept from what's being asked for
  here (which is about `enum`/`type`, per the motivating example). Not
  addressed by this spec.
- No change to how the receiver annotation `<Receiver>` behaves when used
  explicitly at the top level — untouched.

## Current state

- `class`/`enum` grammar rules (`tooling/tree-sitter-plum/grammar.js`) only
  allow `repeat(alias($.class_field, $.field))` /
  `optional(repeat(alias($.enum_field, $.field)))` inside their body — no
  path for a full `fn` declaration to appear nested inside either.
- `fn` (top-level today) already supports an optional receiver annotation:
  `field("type", optional(alias($.fn_type, $.type)))`, parsed by
  `plum-core/src/parser.rs`'s `parse_fn` into `ast::Fn.type_param: Option<String>`.
  A method declared today (`toNumber<Step>(self) -> Int = ...`) already
  produces exactly the AST shape this feature's nested form should also
  produce — the only thing missing is a grammar/parser path that arrives at
  that same shape without writing `<Step>` explicitly, by inferring it from
  nesting position instead.
- `parse_source` (`plum-core/src/parser.rs`) builds `Source.items: Vec<Item>`
  by matching each top-level child's `kind()` (`"class"`, `"trait"`,
  `"enum"`, `"fn"`, `"const"`) to one `Item` each — there is currently no
  concept of one top-level declaration producing MORE than one `Item`.

## Design

### Grammar

`class` and `enum` each gain an optional trailing `repeat($.fn)` after their
existing fields, reusing the `fn` rule completely unmodified (a nested
method is byte-for-byte the same grammar as a top-level method, just
appearing at a different position in the tree — including still allowing
(but not requiring) its own explicit `<Receiver>` annotation, which would be
redundant but not a parse error, same as any other harmless redundancy the
grammar doesn't specifically forbid elsewhere):

```js
class: ($) =>
  seq(
    "type",
    field("name", $.type_identifier),
    field("generics", optional($.generics)),
    field("implements", optional(seq("(", commaSep1($.type_identifier), ")"))),
    "=",
    $._indent,
    field("fields", optional(repeat(alias($.class_field, $.field)))),
    field("methods", optional(repeat($.fn))),
    $._dedent,
  ),

enum: ($) =>
  seq(
    "enum",
    field("name", $.type_identifier),
    field("params", optional(seq("(", commaSep1($.enum_param), ")"))),
    "=",
    $._indent,
    optional(repeat(alias($.enum_field, $.field))),
    field("methods", optional(repeat($.fn))),
    $._dedent,
  ),
```

Fields and methods are distinguished structurally without any new
lookahead/conflict: a `class_field`/`enum_field` always starts
`identifier ":" ...` (or `"|" identifier ...` for enum variants), while `fn`
always starts `identifier ("<" ... ">")? "(" ...` — the token immediately
after the leading identifier (`:` vs `<`/`(`) already disambiguates them, the
same way the grammar already disambiguates other same-position alternatives
elsewhere.

### Parser

Rather than changing `parse_class`/`parse_enum`'s existing return types
(`Class`/`Enum`, unchanged — no other caller/test should need to know this
feature exists), add one new helper:

```rust
/// Collects any `fn` named children nested directly inside a class/enum/etc.
/// body and parses each as an ordinary top-level `Fn`, with `type_param`
/// forced to `owner` regardless of whatever the nested `fn` itself parsed
/// (a nested method's receiver is implicit from its enclosing declaration,
/// not from its own optional `<Receiver>` annotation — which, if written
/// explicitly and redundantly, is simply overridden, not treated as a
/// conflict/error).
fn collect_nested_fns(&self, node: Node, owner: &str) -> Vec<Fn> {
    self.children_of_kind(node, "fn")
        .into_iter()
        .map(|n| {
            let mut f = self.parse_fn(n);
            f.type_param = Some(owner.to_string());
            f
        })
        .collect()
}
```

`parse_source` calls this alongside `parse_class`/`parse_enum` for each
`"class"`/`"enum"` top-level child, pushing the resulting `Fn`s as
additional `Item::Fn(...)` entries immediately after the owning
`Item::Class(...)`/`Item::Enum(...)` — i.e. one `class`/`enum` grammar node
can now expand to MULTIPLE `Item`s in `Source.items`, in declaration order
(class/enum first, then each of its nested methods in the order written).
This is the one structural change to `parse_source`'s loop; everything
downstream of `Source.items` (checker, codegen) already iterates
`Item::Fn` as a flat list and needs no changes — a nested method is
indistinguishable from a top-level one by the time it reaches `Item::Fn`.

### Checker / Codegen

No changes. By construction, a nested method desugars to exactly the
`ast::Fn { type_param: Some(receiver), ... }` shape a top-level
`<Receiver>`-annotated method already produces — every downstream consumer
(dispatch resolution, monomorphization, codegen) is already correct for
that shape and has no way to observe which surface syntax produced it.

### Testing strategy

- Tree-sitter corpus: an `enum`/`type` with fields followed by one or more
  nested `fn` declarations, confirming the new `fn`-inside-`enum`/`class`
  node shape parses; confirm a `class`/`enum` with NO nested methods
  (today's shape) is unaffected; confirm a `trait` is unaffected (no `fn`
  nesting added there).
- `plum-core` parser tests: parsing a nested method produces an `Item::Fn`
  with `type_param == Some("EnclosingTypeName")`, appearing in `Source.items`
  immediately after the owning `Item::Class`/`Item::Enum`, in the same
  relative order as multiple nested methods were written.
- `plum-checker`/`plum-wasm-codegen` tests: a nested method type-checks,
  dispatches, and runs identically to the same method written in today's
  top-level `<Receiver>` form (e.g. compile the `Step`/`toNumber` example
  from this spec's Goal section, or a smaller equivalent, and confirm it
  runs correctly end-to-end) — proving the desugaring is truly
  behavior-identical, not just parse-identical.