<img align="right" src="https://raw.githubusercontent.com/nashamri/elsa-logo/master/elsa-logo-transparent.png" width="133" height="100"> Elsa - Emacs Lisp Static Analyser

<p align="center">(Your favourite princess now in Emacs!)</p>

Elsa is a tool that analyses your code without loading or running it. It is 100% side-effect free and we strive to keep it that way, so you can analyse any elisp code from anywhere safely.

Elsa adds a powerful type system on top of Emacs lisp (completely optional). In can track types and provide helpful hints when things don't match up before you even try to run the code.

<!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc -->

Table of Contents

• Motivation
• State of the project
• Non-exhaustive list of features
  • Detect dead code
  • Enforce style rules
  • Look for suspicious code
  • Track types of expressions
  • Understand functional overloads
• How do I run it
  • Eask
  • Cask
  • Language server protocol (LSP)
  • makem.sh
  • EMake
  • Flycheck/Flymake integration
• Configuration
  • Analysis extension
  • Rulesets
• Type annotations
• How can I contribute to this project
• F.A.Q.
  • What's up with the logo?
• For developers
  • How to write an extension for your-favourite-package
  • How to write a ruleset
• Acknowledgments

<!-- markdown-toc end -->

Motivation

Dynamic programming languages, such as Emacs Lisp, JavaScript and Python, have many advantages over statically typed languages like Java or C++. They allow for faster development and prototyping due to their dynamic nature, which makes it easier to write and test code quickly.

However, dynamic languages lack the type checking and safety features that statically typed languages provide. This can lead to errors that are difficult to catch during development and can cause issues in production. By adding a type system on top of a dynamic language, we can enjoy the benefits of both dynamic and static languages.

Elsa is a type system and analyser for Emacs Lisp, which aims to provide the benefits of a type system while retaining the flexibility and expressiveness of Lisp. It is similar to TypeScript for JavaScript or Python Type Hints for Python in that it provides a way to add static type checking to a dynamically typed language.

Elsa tries to be idiomatic and use as much available information as possible, such as edebug declarations, defmethod specializers or EIEIO class slot types, so the amount of code that needs to be annotated is minimized.

State of the project

We are currently in a beta phase. API, the type system and annotations are quite stable. We support multiple ways to install and run the analyser.

Elsa lacks a lot of type annotations for built-in functions (there is about 1500 of them) and variables. The analysis results are therefore still sub optimal.

Things might still break at any point.

Non-exhaustive list of features

Here comes a non-exhaustive list of some more interesting features.

The error highlightings in the screenshots are provided by Elsa Flycheck extension.

Everything you see here actually works, this is not just for show!

Detect dead code

Detect suspicious branching logic

Find unreachable code in short-circuiting forms

Enforce style rules

Provide helpful tips for making code cleaner

Add custom rules for your own project with rulesets

Make formatting consistent

Look for suspicious code

Find references to free/unbound variables

Don't assign to free variables

Detect conditions which are always true or false

Make sure functions are passed enough arguments

Make sure functions are not passed too many arguments

Track types of expressions

Check types of arguments passed to functions for compatibility

Understand type narrowing from type guards and predicates

Understand functional overloads

downcase can take a string and return a string or take an int and return an int. Because we pass a string variable s, we can disambiguate which overload of the function must be used and we can derive the return type of the function as string instead of (or string int).

If we pass an input which doesn't match any overload, Elsa will show a helpful report of what overloads are available and what argument didn't match.

How do I run it

Elsa can be run with [Eask][Eask], [Cask][Cask], [makem.sh][makem] or [EMake][emake]. Before you can perform analysis, see the Configuration section on how to configure the project.

Elsa project provides support for the Eask, Cask and LSP methods. For makem.sh and EMake support, contact the authors of those packages directly.

If you use Eask or Cask, you can use Flycheck and Flymake integrations (see below).

In addition, Elsa also implements Language Server Protocol (LSP) and can be used with [lsp-mode][lsp-mode]. This is the best option because all the state is cached in the server and all the operations are very fast. LSP also exposes features of Elsa otherwise not available, such as completion (via lsp-completion-mode) or contextual hover type information.

The following table summarizes the options:

| Feature | Eask | Cask | makem.sh | EMake | |--------------------------------|------|------|----------|-------| | Stand-alone analysis from CLI | ✓ | ✓ | ✓ | ✓ | | Flycheck integration | ✓ | ✓ | ⨯ | ⨯ | | Flymake integration | ✓ | ⨯ | ⨯ | ⨯ | | Language Server Protocol (LSP) | ✓ | ✓ | ⨯ | ⨯ |

Note: when you run Elsa in a project for the first time, it is recommended to start it from the CLI because it will need to crawl all the dependencies you use and save the analysis results to cache files. This can take a couple of minutes if you have many dependencies (or if you include something like org which pulls in about 300 other packages).

After the results are cached, next time you need them Elsa can load them from cache and this is generally very fast.

You can start the LSP right away but it will be unresponsive during the time it is doing the initial analysis.

Eask

[RECOMMENDED] Using packaged version (via lint)

The easiest way to execute Elsa with [Eask][Eask]:

eask lint elsa [PATTERNS]

[PATTERNS] is optional; the default will lint all your package files.

[RECOMMENDED] Using packaged version (via exec)

This method uses [Eask][Eask] and installs Elsa from [MELPA][MELPA].

1. Add (depends-on "elsa") to Eask file of your project.
2. Run eask install-deps.
3. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] to analyse the file.

Using development version (via exec)

To use the development version of Elsa, you can clone the repository and use the eask link feature to use the code from the clone.

1. git clone https://github.com/emacs-elsa/Elsa.git somewhere to your computer.
2. Add (depends-on "elsa") to Eask file of your project.
3. Run eask link add elsa <path-to-elsa-repo>.
4. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] to analyse the file.

Cask

[RECOMMENDED] Using packaged version

This method uses [Cask][Cask] and installs Elsa from [MELPA][MELPA].

1. Add (depends-on "elsa") to Cask file of your project.
2. Run cask install.
3. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] to analyse the file.

Using development version

To use the development version of Elsa, you can clone the repository and use the cask link feature to use the code from the clone.

1. git clone https://github.com/emacs-elsa/Elsa.git somewhere to your computer.
2. Add (depends-on "elsa") to Cask file of your project.
3. Run cask link elsa <path-to-elsa-repo>.
4. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] to analyse the file.

Language server protocol (LSP)

Elsa's LSP implementation is currently work in progress, b