104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# AGENTS.md — lsp-typst
|
|
|
|
## Project Overview
|
|
|
|
`lsp-typst` is an Emacs Lisp package that provides **LSP support for Typst** (the typesetting language) via `lsp-mode`. It connects to the **tinymist** LSP server to provide completion, diagnostics, formatting, and other LSP features in buffers using `typst-ts-mode`.
|
|
|
|
- **Homepage:** https://labs.phundrak.com/phundrak/lsp-typst
|
|
- **License:** GPLv3+
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
# Enter the reproducible dev shell (Nix)
|
|
nix develop
|
|
|
|
# Run tests (currently a placeholder — see Testing Status below)
|
|
eask test
|
|
```
|
|
|
|
No build step is required — the package is pure Elisp.
|
|
|
|
## Dependencies
|
|
|
|
| Dependency | Min. Version | Purpose |
|
|
|-------------------|--------------|--------------------------------------|
|
|
| Emacs | 30.1 | Runtime |
|
|
| `lsp-mode` | 10 | LSP client infrastructure |
|
|
| `f` | 0.20 | File path manipulation |
|
|
| `typst-ts-mode` | 0.12 | Typst major mode (recommended) |
|
|
|
|
The package can also **auto-download** the `tinymist` binary from GitHub releases.
|
|
|
|
## Project Structure
|
|
|
|
| Path | Purpose |
|
|
|-------------------------------------|--------------------------------------|
|
|
| `lsp-typst.el` | Single-file package (all source) |
|
|
| `Eask` | Eask build/test configuration |
|
|
| `flake.nix` | Nix flake for reproducible dev shell |
|
|
| `flake.lock` | Locked Nix inputs (auto-generated) |
|
|
|
|
Everything lives in one Elisp file; keep it that way unless complexity warrants splitting.
|
|
|
|
## Key Conventions
|
|
|
|
- **Lexical binding** is enabled (`lexical-binding: t`).
|
|
- **Colon-double-space** is enforced (`colon-double-space: t`).
|
|
- **Naming:** All public symbols are prefixed `lsp-typst-*`.
|
|
- **Docstrings:** Present on all `defcustom` and `defgroup` forms. First line is a complete sentence.
|
|
- **Comment style:** Section headers use `;;;` with standard Emacs conventions (`;;; Code:`, `;;; Commentary:`, `;;; lsp-typst.el ends here`).
|
|
- **Single-file package:** Keep source in `lsp-typst.el` unless the package grows significantly.
|
|
- **Indentation:** Standard Emacs Lisp indentation.
|
|
|
|
## Public API (User-Facing Customization)
|
|
|
|
| Variable | Default | Description |
|
|
|-----------------------------------|------------------------------------------|-------------------------------------|
|
|
| `lsp-typst-server-command` | `"tinymist"` | LSP server binary path |
|
|
| `lsp-typst-server-command-args` | `'("lsp")` | CLI arguments for the server |
|
|
| `lsp-typst-download-url` | Auto-detected per platform | URL to download tinymist |
|
|
| `lsp-typst-store-path` | Inside `lsp-server-install-dir` | Where the downloaded binary is kept |
|
|
|
|
There are no interactive commands defined — all configuration is via `defcustom`.
|
|
|
|
## Architecture Notes
|
|
|
|
The LSP client is registered in three steps inside `lsp-typst.el`:
|
|
|
|
1. **Language-ID mapping** — `typst-ts-mode` is mapped to the language id `"typst"` via `lsp-language-id-configuration`.
|
|
2. **Dependency definition** — The `typst` dependency is defined, pointing to either a system binary or a downloadable `tinymist` binary.
|
|
3. **Client registration** — `lsp-register-client` creates the client with:
|
|
- `:language-id` → `"typst"`
|
|
- `:major-modes` → `(nix-ts-mode)` (see **Known Quirks** below)
|
|
- `:activation-modes` → `lsp-activate-on "typst"`
|
|
- `:server-id` → `'typst`
|
|
- Connection via `lsp-stdio-connection` calling `lsp-typst-server-command` + args
|
|
- Initialization sends configuration via `lsp--set-configuration`
|
|
|
|
## Known Quirks
|
|
|
|
- **Suspicious `:major-modes` value:** The client registration lists `(nix-ts-mode)` as the major mode, which looks like a copy-paste artifact. The actual activation gate is `lsp-activate-on "typst"`, but if you're cleaning this up, it should probably be `(typst-ts-mode)`.
|
|
- **Only tinymist is supported:** The package is written specifically for **tinymist** (the successor to `typst-lsp`). Do not add support for the older `typst-lsp` server without explicit discussion.
|
|
|
|
## What Not to Touch
|
|
|
|
- **`flake.lock`** — Auto-generated by Nix. Regenerate with `nix flake update`. Never edit manually.
|
|
|
|
## Testing Status
|
|
|
|
**No tests exist.** The `Eask` test script is a placeholder:
|
|
|
|
```shell
|
|
echo "Error: no test specified" && exit 1
|
|
```
|
|
|
|
Any testing setup would need to be created from scratch (likely a `test/` directory with ERT tests).
|
|
|
|
## Decision Records
|
|
|
|
- **tinymist** is the only supported LSP server. The package was written after `typst-lsp` was deprecated in favor of tinymist.
|
|
- **No CI is configured** (no `.github/`, no `.gitlab-ci.yml`).
|
|
- **No README** exists — this `AGENTS.md` and the package commentary in `lsp-typst.el` serve as documentation.
|
|
- **Self-hosted git:** The canonical repository is on a Gitea/Forgejo instance at `labs.phundrak.com`, not GitHub.
|