iris

a language implementation for PureScript

---

Iris is a language implementation for PureScript, powered by an incremental, query-based build system. Instead of a sequence of compiler phases, Iris models compilation and semantic information as incrementally computed queries. These queries are used extensively to implement code intelligence features in the language server.

The build system is designed with interactive editing in mind. To support this, it tracks dependencies between inputs and queries, caches query results, deduplicates in-progress work across threads, and supports cooperative cancellation when inputs change. Crucially, many query results are designed to be incrementally reusable. For example, the compiler uses stable identities in lieu of source ranges to enable minimal recomputation across trivial formatting changes.

The language server component implements core code intelligence features such as completion, jump to definition, hover information, find references, workspace symbol search, and diagnostics.

Language server configuration

Run iris lsp --stdio to start the language server. The lsp subcommand is required; iris alone no longer starts the server, and language-server options must follow lsp. Supply startup settings as inline JSON or a UTF-8 JSON file:

iris lsp --stdio --config '{"diagnostics":{"onChange":true}}'
iris lsp --stdio --config-file ./iris.json

--config and --config-file are mutually exclusive and replace --source-command and --diagnostics-on-open, --diagnostics-on-save, and --diagnostics-on-change. File paths are relative to the process working directory, not the editor's workspace or the configuration file's directory. Settings are read once before the server starts; changing them requires a restart. Configuration files are not watched, and LSP configuration notifications do not reload settings.

The defaults are:

{
  "sources": { "kind": "spago" },
  "diagnostics": {
    "onOpen": true,
    "onSave": true,
    "onChange": false
  }
}

All settings are optional. Missing or null fields retain their defaults; {} and top-level null also select the defaults. Unknown fields and invalid values are errors, reported on stderr with exit status 2 before the LSP starts. Use the configuration JSON Schema for editor validation; associate it through editor settings rather than adding a $schema property.

To replace spago.lock source discovery with a command:

{
  "sources": {
    "kind": "command",
    "program": "spago",
    "arguments": ["sources"]
  }
}

program is an executable name or path containing a non-whitespace character; it is passed unchanged. arguments is an optional array of individual strings (default []). No shell parsing or expansion occurs. The command runs in the server's process working directory and must print one source path or glob per line; relative output paths are resolved from the first LSP workspace folder, falling back to the process working directory. Only use trusted configurations: source commands execute with the server's permissions. Diagnostic settings control the corresponding document-event triggers, not all diagnostic publishing.

Editor features

Iris provides code intelligence for PureScript projects through its VS Code extension.

Completion

Automatic imports

Live diagnostics

Inferred types

Go to definition

Find references

Rename

Document symbols

Workspace symbols

Typed-hole suggestions

Document highlights

Semantic highlighting

Installation

On Linux and macOS:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://raw.githubusercontent.com/purefunctor/purescript-iris/main/install.sh | sh

On Windows PowerShell:

irm https://raw.githubusercontent.com/purefunctor/purescript-iris/main/install.ps1 | iex

The installers verify the release's GitHub build-provenance attestation when GitHub CLI is available. They display a warning and continue when it is not installed. These installers require v0.1.0 or later; to install v0.0.x, use the installer from that release's Git tag. Set IRIS_VERSION to a release tag or IRIS_INSTALL_DIR to an installation directory to override the defaults.