plum

# Plum CLI & Formatter Design

**Date:** 2026-07-19  
**Status:** Approved

## Overview

Add a `plum` CLI binary and a `format` command that formats `.plum` source files in place using Topiary (topiary-core v0.7.3) as the formatting engine. The project is restructured as a Cargo workspace.

---

## Workspace Structure

```
plum/
├── Cargo.toml                          ← workspace root
├── plum-core/
│   ├── Cargo.toml
│   └── src/
│       ├── lib.rs                      ← public API surface
│       ├── ast.rs                      ← moved from current src/ast.rs
│       ├── parser.rs                   ← moved from current src/parser.rs
│       └── formatter.rs                ← new: Topiary wrapper
├── plum-cli/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs                     ← clap CLI, file I/O only
└── tooling/
    └── tree-sitter-plum/
        └── queries/plum/
            └── format.scm              ← new: Topiary formatting rules
```

The current `plum` crate (`src/ast.rs`, `src/parser.rs`, `src/main.rs`) is split: library code moves to `plum-core`, the entry point becomes `plum-cli`.

---

## plum-core

### Public API

```rust
// src/lib.rs
pub mod ast;
pub mod parser;
pub mod formatter;

pub use formatter::{format_source, FormatterError};
pub use parser::AstParser;
```

### formatter.rs

```rust
pub fn format_source(source: &str) -> Result<String, FormatterError>
pub fn format_source_with_opts(source: &str, skip_idempotence: bool) -> Result<String, FormatterError>
```

- Constructs a Topiary `Language` from:
  - `tree_sitter_plum::LANGUAGE` (converted via `.into()` to `topiary_tree_sitter_facade::Language`)
  - `format.scm` embedded at compile time via `include_str!`
- Calls `topiary_core::formatter_str`
- Returns the formatted source as a `String`

### Dependencies (plum-core/Cargo.toml)

```toml
[dependencies]
tree-sitter = "0.24.5"
tree-sitter-plum = "0.1.0"
topiary-core = "0.7.3"
topiary-tree-sitter-facade = "0.7.3"
```

---

## plum-cli

### Commands

```
plum format <file>             Format file in place (silent on success)
plum format --check <file>     Exit 1 if file would change; print message to stderr
plum format --stdin            Read from stdin, write to stdout
```

### Behaviour

- `format <file>`: reads file, calls `plum_core::format_source`, writes result back only if content changed (avoids touching mtime unnecessarily)
- `format --check <file>`: same read + format, but instead of writing, compares and exits 1 with a message if different
- `format --stdin`: reads all of stdin, formats, writes to stdout — useful for editor integrations
- All errors print to stderr; stdout is reserved for formatted source (`--stdin` mode only)

### Dependencies (plum-cli/Cargo.toml)

```toml
[dependencies]
plum-core = { path = "../plum-core" }
clap = { version = "4", features = ["derive"] }
anyhow = "1"
```

---

## format.scm — Topiary Formatting Rules

Located at `tooling/tree-sitter-plum/queries/plum/format.scm`, embedded in `formatter.rs` via `include_str!`.

### Rules

| Construct | Rule |
|---|---|
| Binary operators (`+`, `-`, `*`, `/`, `%`, `\|`, `&`, `^`, `<<`, `>>`, `..`) | space before and after |
| Comparison operators (`<`, `<=`, `==`, `!=`, `>=`, `>`, `<>`) | space before and after |
| Boolean operators (`&&`, `\|\|`) | space before and after |
| `->` (return type arrow) | space before and after |
| `=` (in fn/const/assign) | space before and after |
| `=>` (in match case / pair argument) | space before and after |
| `,` separator | no space before, one space after |
| `:` in params and fields | no space before, one space after |
| `\|` in enum variants | hardline before |
| Statements in a `body` block | hardline between each |
| Top-level items (`fn`, `type`, `enum`, `trait`, `const`) | blank line between each |
| Comments | preserved as-is; blank line allowed before |
| `(` `)` in argument lists | scoped softline (single-line if fits, multi-line if not) |

### Idempotence

`skip_idempotence` defaults to `false` — Topiary runs formatting twice and errors if the result differs. This catches poorly-written query rules during development. The CLI exposes no flag for this; it is a library-level option.

---

## Error Handling

- Parse errors in the source: `tolerate_parsing_errors: false` — the formatter refuses to format files with syntax errors, printing the tree-sitter error to stderr.
- File not found / permission errors: `anyhow` propagates these with context.
- Formatter errors (bad query, non-idempotent output): printed to stderr, exit code 1.

---

## Out of Scope

- `plum check` / `plum build` / other compiler subcommands
- LSP integration
- Watch mode
- Formatting multiple files via glob patterns