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