Allium Tools

Pre-release notice: This software is currently in a pre-release state. Treat it as unstable, expect breaking changes, and validate it carefully before production use.

Allium Tools is the multi-editor platform for the Allium specification language. It provides rich editor integration, a standalone Language Server (LSP), and a suite of CLI tools for validation, formatting, and analysis.

What is Allium?

Allium is a domain-specific language for specifying system behavior, rules, and data models. It focuses on clarity, traceability, and automated validation.

Key Concepts

• Blocks: Top-level declarations like rule, entity, enum, config, given, surface, and actor.
• Clauses: Express requirements and effects using when:, requires:, and ensures:.
• Traceability: Built-in support for linking specifications to implementation and tests.

Brief Syntax Example

module ordering

enum OrderStatus {
    pending | confirmed | dispatched
}

entity Order {
    status: OrderStatus
    total: Decimal
}

rule PlaceOrder {
    when: OrderSubmitted(basket)
    requires: basket.items.count > 0
    ensures: Order.created(status: pending, total: basket.total)
}

rule DispatchOrder {
    when: order: Order.status becomes confirmed
    requires: order.total > 0
    ensures: order.status = dispatched
}

Editor Support Matrix

Feature	VS Code	Neovim	Emacs	CLI
Diagnostics (Linting)	✅	✅	✅	✅
Hover Documentation	✅	✅	✅	-
Go to Definition	✅	✅	✅	-
Find References	✅	✅	✅	✅
Rename Refactoring	✅	✅	✅	-
Safe Fixes (Autofix)	✅	✅	✅	✅
Formatting	✅	✅	✅	✅
Code Lens	✅	-	-	-
Document Links	✅	✅	✅	-
Semantic Highlighting	✅	✅	✅	-
Folding	✅	✅	✅	-
Completions	✅	✅	✅	-
Diagram Preview	✅	-	-	✅
Rule Simulation	✅	-	-	-
Test Scaffold	✅	-	-	-

Quick Install

VS Code

1. Download the latest allium-vscode-<version>.vsix from GitHub Releases.
2. Install via Command Palette: Extensions: Install from VSIX....
3. See the VS Code Setup Guide for details.

Neovim

1. Install allium-lsp via your favorite plugin manager or from release artifacts.
2. Configure nvim-lspconfig to point to the allium-lsp binary.
3. See the Neovim Setup Guide for details.

Emacs

1. Install allium-mode and configure it to use allium-lsp with eglot or lsp-mode.
2. See the Emacs Setup Guide for details.

CLI

The allium CLI validates and parses Allium specification files.

• allium check — validate specifications and report diagnostics.
• allium parse — parse a file and output the syntax tree.

Install

Homebrew

brew tap juxt/allium && brew install allium

Cargo

cargo install allium-cli

From source

cargo build --release -p allium-cli

Pre-built binaries for Linux and macOS are available on the GitHub Releases page.

Documentation

• Architecture Overview
• Editor Setup Guides
• Contributing Guide
• Project Plan & Roadmap

Development

See AGENTS.md for development rules and the Project Roadmap for build instructions and priorities.

Git Hooks

This repository uses pre-commit hooks for local quality gates.

Install hooks:

npm install

Run the full test matrix locally:

npm run test:all

test:all runs fastest-to-slowest: test, test:nvim, test:emacs, test:nvim:integration, test:emacs:integration.

The pre-push hook runs npm run test:all before allowing a push.

Licence

MIT