# AssumLS
Language server + CLI checker for
enforcing documented assumptions across a codebase.
## Quick Start
**Define** assumptions in `ASSUM.md`:
```markdown
# network_available
Services assume stable network connectivity (this text displays on hover).
```
**Reference** in any code under the same directory:
```rust
// @ASSUME:network_available
async fn fetch_data() { ... }
```
**Check** for violations:
```sh
assumls check .
```
## How It Works
- **Definitions**: `# assumption_name` in any `ASSUM.md`
- **References**: `@ASSUME:assumption_name` in any language (in comments)
- **Scoping**: Files use nearest parent `ASSUM.md`
- **Validation**: Flags undefined refs, unused defs, duplicates
- Require `fd` and `rg` on PATH
## LSP Features
- Hover: Display body of assumption definition
- Completion: Suggest valid assumptions
- Go-to-def / Find refs: Navigate assumptions
- Rename: Update everywhere
- Diagnostics: Real-time error checking
<details><summary>Setup for Neovim.</summary>
```lua
local function register_assumls()
vim.lsp.config("assumls", {
cmd = { "assumls", "lsp" },
})
vim.lsp.enable("assumls", true)
end
```
</details>
## CLI
```sh
assumls check <path> # Exit 0 if clean, 1 if errors
assumls lsp # Start LSP server
```
## Installation
```sh
cargo install assumls
# Or, if you have cargo-binstall:
cargo binstall assumls
```
Or, grab one from [Releases](https://github.com/SichangHe/assumls/releases).
## Development
> [!NOTE]\
> This project is currently largely generated by coding agents and
> the author has yet to manually inspect all code.
- Install Rust
- Install `pre-commit` and run `pre-commit install`
## Examples
See `src/` (this project itself) and test directories under `test_data/`.
## License
MIT or Apache-2.0, per `Cargo.toml`.