cr-analyzer

cr-analyzer is a lightweight Language Server Protocol (LSP) server for the Crystal language. It parses source files with the Crystal parser and builds a semantic index without invoking the full compiler, aiming for fast, editor-friendly feedback.

Status

Active development. Implemented LSP features include completion (with resolve), go-to-declaration/definition/type definition/implementation, hover, signature help, document symbols, document highlight, references, inline values, selection range, call hierarchy (incoming/outgoing), rename (best-effort), diagnostics (push + pull), workspace symbols, and full-text document sync (didOpen/didChange/didSave). Other LSP features are planned.

Features

• Workspace scan of project sources, lib, and Crystal stdlib.
• Go to declaration/definition for:
  • types (class/module/enum)
  • methods and overloads (arity aware)
  • constructors (new -> initialize/self.new)
  • instance/class/local variables
  • aliases and enum members
• Go to type definition (best-effort type inference from annotations/assignments).
• Go to implementation for subclasses, includers, and method overrides.
• References (locals, ivars/cvars, types, enum members).
• Document symbols (outline) and workspace symbols.
• Hover with signature + documentation.
• Signature help with active parameter selection.
• Document highlight for locals/ivars/cvars and type paths.
• Selection ranges based on AST nesting.
• Inline values (variables in range).
• Call hierarchy (incoming/outgoing).
• Type hierarchy (prepare/super/sub types).
• Rename (prepare + apply; best-effort for locals, ivars, methods, type paths in workspace).
• Diagnostics:
  • Syntax/parser errors (Crystal parser or facet parser fallback).
  • Facet-based diagnostics + lint-style warnings (TODO/FIXME, empty rescue, trailing whitespace, duplicate require, missing final newline, mixed indentation, unused def/block args).
  • Both push and pull diagnostic flows supported.
• Completion:
  • member methods on . and ::
  • instance/class/local variables
  • type/namespace and enum member completions (aliases included)
  • keyword completions based on context
  • require path suggestions
  • completion resolve for docs and signatures

Limitations

• No full compiler type checking or macro expansion. Type inference is best-effort based on annotations and simple assignments.
• Macro expansion is limited to built-in macros (getter, setter, property, record) and a small interpreter for user-defined macros.
• Rename is best-effort and currently scoped to workspace files (stdlib is not edited).

Usage

1. Install dependencies:

shards install

2. Run the server over stdio:

crystal run src/bin/cra.cr

Or build the binary:

shards build
./bin/cr-analyzer

3. Configure your editor to launch the command above as an LSP server.

Documentation site

• Hosted docs (GitHub Pages): https://mikeoz32.github.io/cr-analyzer
• Local preview with MkDocs:

  pip install mkdocs mkdocs-material
  mkdocs serve

stdlib scanning

The server uses CRYSTAL_PATH or CRYSTAL_HOME to locate the stdlib. If unset it falls back to /usr/share/crystal/src.

Development

• Run specs: crystal spec
• Quick client harness: uv run main.py (uses the Python env in pyproject.toml)
• Debug: CRA_DUMP_ROOTS=1 to dump index roots after initial scan

Docs

• docs/architecture.md
• docs/semantic-index.md
• docs/lsp-server.md
• docs/roadmap.md

Contributing

Please open an issue or PR with a clear description and tests when possible.

Contributors

• Mike Oz - creator and maintainer