Elsa

ELSA -EMACS LISP静态分析仪

（现在您最喜欢的公主！）

ELSA是一个工具，可以在不加载或运行的情况下分析您的代码。它是100％无副作用的，我们努​​力保持这种方式，因此您可以安全地分析任何ELISP代码。

Elsa在Emacs LISP（完全可选）的顶部添加了一个强大的类型系统。在您甚至尝试运行代码之前，当事物不匹配时，可以跟踪类型并提供有用的提示。

目录

• 动机
• 项目状态
• 非排量功能列表
  • 检测死亡代码
  • 执行样式规则
  • 寻找可疑代码
  • 轨道表达式类型
  • 了解功能超负荷
• 我该如何运行
  • 伊斯克
  • 桶
  • 语言服务器协议（LSP）
  • makem.sh
  • Emake
  • 蝇检查/蝇胶集成
• 配置
  • 分析扩展
  • 规则集
• 类型注释
• 我该如何为这个项目做出贡献
• 常问问题
  • 徽标怎么了？
• 对于开发人员
  • 如何为您的最爱包装编写扩展名
  • 如何编写规则集
• 致谢

动机

动态编程语言，例如Emacs Lisp，JavaScript和Python，比Java或C ++等静态键入语言具有许多优势。由于其动态性质，它们允许更快地开发和原型制作，这使得更容易快速编写和测试代码。

但是，动态语言缺乏静态键入语言提供的类型检查和安全功能。这可能会导致在开发过程中难以捕获的错误并可能导致生产问题。通过在动态语言之上添加类型系统，我们可以享受动态和静态语言的好处。

ELSA是EMACS LISP的类型系统和分析仪，旨在在保留LISP的灵活性和表现力的同时提供类型系统的好处。对于JavaScript或Python类型的提示，它类似于Python的TypeScript，因为它提供了一种将静态类型检查添加到动态键入语言中的方法。

Elsa试图惯用并使用尽可能多的可用信息，例如Edebug声明，Defmethod专业人士或EIEIO类插槽类型，因此需要将需要注释的代码数量最小化。

项目状态

我们目前处于Beta阶段。 API，类型系统和注释非常稳定。我们支持多种安装和运行分析仪的方法。

Elsa缺乏内置功能（大约有1500个）和变量的大量类型注释。因此，分析结果仍然是最佳的。

事情可能在任何时候都可能破裂。

非排量功能列表

这是一些更有趣的功能的非详尽列表。

屏幕截图中的错误突出显示由Elsa FlyCheck扩展程序提供。

您在这里看到的一切实际上都可以使用，这不仅是为了展示！

检测死亡代码

检测可疑的分支逻辑

以短路形式找到无法达到的代码

执行样式规则

提供有用的技巧，使代码清洁器

使用规则集添加您自己项目的自定义规则

使格式保持一致

寻找可疑代码

查找对免费/未绑定变量的引用

不要分配自由变量

检测始终是正确或错误的条件

确保功能通过足够的参数

确保功能不会传递得太多参数

轨道表达式类型

检查传递给函数的参数类型以兼容

了解类型守卫和谓词的类型变窄

了解功能超负荷

downcase可以拿起字符串并返回字符串或取int并返回int。因为我们传递了一个字符串变量s ，所以我们可以歧义必须使用哪些函数的过载，并且可以将函数的返回类型得出为string而不是(or string int) 。

如果我们通过一个不匹配任何过载的输入，ELSA将显示出有用的报告，即哪些过载和哪些参数不匹配。

我该如何运行

Elsa可以与EASK，CASK，MAKEM.SH或EMAKE一起运行。在执行分析之前，请参阅有关如何配置项目的配置部分。

ELSA项目为EASK，CASK和LSP方法提供了支持。对于makem.sh和emake支持，请直接联系这些软件包的作者。

如果使用EASK或CASK，则可以使用Flycheck和FlyMake集成（请参见下文）。

此外，ELSA还实现了语言服务器协议（LSP），可以与LSP模式一起使用。这是最好的选择，因为所有状态均已缓存在服务器中，并且所有操作都非常快。 LSP还揭示了ELSA的功能，否则将无法使用，例如完成（通过lsp-completion-mode ）或上下文悬停类型信息。

下表总结了选项：

特征	伊斯克	桶	makem.sh	Emake
CLI的独立分析	✓	✓	✓	✓
蝇检查集成	✓	✓	⨯	⨯
Flymake集成	✓	⨯	⨯	⨯
语言服务器协议（LSP）	✓	✓	⨯	⨯

注意：当您第一次在项目中运行ELSA时，建议从CLI启动它，因为它需要抓取您使用的所有依赖项并将分析结果保存到缓存文件。如果您有很多依赖项（或者包含诸如org之类的东西），则可能需要几分钟。

结果缓存后，下次您需要它们时，Elsa可以从缓存中加载它们，这通常非常快。

您可以立即启动LSP，但是在进行初始分析的时间内，它将没有响应。

伊斯克

[推荐]使用包装版本（通过lint ）

用EASK执行ELSA的最简单方法：

 eask lint elsa [PATTERNS]

[PATTERNS]是可选的；默认值将凸显所有软件包文件。

[推荐]使用打包版本（通过exec ）

此方法使用EASK并从Melpa安装ELSA。

1. 将(depends-on "elsa")添加到您项目的Eask文件中。
2. 运行eask install-deps 。
3. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...]分析文件。

使用开发版本（通过exec ）

要使用ELSA的开发版本，您可以克隆存储库，并使用eask link功能使用Clone中的代码。

1. git clone https://github.com/emacs-elsa/Elsa.git到您的计算机。
2. 将(depends-on "elsa")添加到您项目的Eask文件中。
3. 运行eask link add elsa <path-to-elsa-repo> 。
4. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...]分析文件。

桶

[推荐]使用包装版本

此方法使用桶并安装Melpa中的ELSA。

1. 添加(depends-on "elsa")到您的项目的Cask文件中。
2. 运行cask install 。
3. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...]分析文件。

使用开发版本

要使用ELSA的开发版本，您可以克隆存储库，并使用cask link功能使用Clone中的代码。

1. git clone https://github.com/emacs-elsa/Elsa.git到您的计算机。
2. 添加(depends-on "elsa")到您的项目的Cask文件中。
3. 运行cask link elsa <path-to-elsa-repo> 。
4. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...]分析文件。

语言服务器协议（LSP）

ELSA的LSP实现目前正在进行中，但是服务器足够稳定，可以使用它很有用。它使覆盖物的速度非常快，因为所有状态都在服务器实例中缓存，并且我们不必从头开始重新阅读整个缓存时间（例如，通过Flycheck或FlyMake运行时）。

ELSA当前支持LSP模式，但它尚未内置在LSP模式本身上，因为它（ELSA LSP）不够稳定。要使用ELSA LSP，请运行(elsa-lsp-register)或Mx elsa-lsp-register用lsp-mode注册客户端。之后，在ELISP缓冲区中使用Mx lsp将启动一个工作区。

目前，支持这些LSP功能

能力	实施的
HoverProvider	提供点下的上下文类型注释
textDocumentsync	Openclose，保存
完工者	工作区功能 范围和工作区的变量 Oref/Oset插槽名称的特殊分辨率

makem.sh

使用makem.sh ，只需从项目根目录中运行此命令，该命令在临时沙箱中安装并运行ELSA：

 ./makem.sh --sandbox lint-elsa

要使用名为.sandbox的非仿期沙盒目录，并避免在每次运行中安装ELSA：

1. 初始化沙箱： ./makem.sh -s.sandbox --install-deps --install-linters 。
2. 运行elsa： ./makem.sh -s.sandbox lint-elsa 。

有关更多信息，请参见makem.sh的文档。

Emake

如果您已经安装了Emake，请运行make lint-elsa 。您可能需要通过EMAKE_SHA1更新到最近的版本。

否则，通过通常的方式安装Emake：

bash <( curl -fsSL https://raw.githubusercontent.com/vermiculus/emake.el/master/new )

此脚本将提示您获取包装的名称，然后引导Emake。现在，您可以使用make lint-elsa进行ELSA的检查。

蝇检查/蝇胶集成

如果使用Flycheck，则可以使用将ELSA与Flycheck集成的Flycheck-Elsa软件包。

对于FlyMake，您可以使用Flymake-esla。

配置

目前，ELSA支持很少的配置。要“ ELSA-ENABLE”您的项目，您必须在项目的根源中添加Elsafile.el 。

Elsa具有扩展和规则集的概念，该概念主要存在于内部，并包裹在一个大“默认”规则集和扩展中。该系统仍在进行中。

以下是您今天可以扩展ELSA的一些方法。

分析扩展

扩展ELSA的一种方法是为更多形式和功能提供特殊分析规则，我们可以利用该功能如何缩小分析的知识。

例如，我们可以说，如果not输入为t ，则返回值始终nil 。这以分析规则的形式编码我们的领域知识。

所有规则均以扩展形式添加。 Elsa对于最常见的内置功能（例如列表操纵（ car ， nth ...），prepicates（ stringp ， atomp ...），逻辑功能（ not ，...）等，Elsa几乎没有核心扩展。它们会自动加载，因为这些函数几乎是每个项目都将使用它们的常见。

为流行的外部软件包（例如Dash.el）提供了其他扩展。要使用它们，请添加到您的Elsafile.el register-extensions表格，就像这样

(register-extensions
 dash
 ; ; more extensions here
 )

当Elsa出现要求表格时，将自动加载扩展。对于(require 'foo)它将寻找elsa-extension-foo.el并尝试加载它。这意味着在实践中，您将不必在大多数第三方软件包中注册扩展名。

规则集

对表格进行分析后，我们拥有所有类型信息，并且准备通过各种检查和规则进一步处理AST。

这些可以是（非排量列表）：

• 风格，例如检查变量是否使用lisp-case代替snake_case 。
• 句法，例如检查我们没有用无用progn if Else Branch。
• 语义，例如检查if不总是对non-nil进行评估的条件（在这种情况下， if形式毫无用处）。

ELSA提供了一些内置的规则集，也可以通过加载扩展名来使用更多规则集。

要注册规则集，请将以下表格添加到Elsafile.el

(register-ruleset
 dead-code
 style
 ; ; more rulesets here
 )

类型注释

在ELISP中，无需用户为其代码提供类型注释。虽然在许多地方可以推断出某个地方，尤其是在用户定义的功能中，我们无法猜测正确的类型（我们只能推断运行时看到的内容）。

阅读类型注释文档，以获取有关如何编写您自己的类型的更多信息。

我该如何为这个项目做出贡献

如果您想从事某件事（不一定在路线图中列出），请打开一个问题，这样我们就不会复制工作。或者只是向我们提供反馈或有用的提示。

您可以通过扩展elsa-typed-builtin.el提供内置功能的类型定义。有很多事情要走。表达我们想要的某些类型可能不存在或受到支持，请打开一个问题，以便我们可以讨论如何建模事物。

常问问题

徽标怎么了？

参见讨论。

对于开发人员

打电话(require 'elsa-font-lock)后，有一个函数elsa-setup-font-lock ，可以从emacs-lisp-mode-hook调用，以设置ELSA类型的其他字体锁定。

如何为您的最爱包装编写扩展名

如何编写规则集

致谢

最大的灵感是Phpstan项目，它为我提供了开始该项目的最初动力。我经历了很多次找到灵感并挑选功能的消息来源。

第二个灵感是打字稿，它使一种相当无趣的语言变成了（不仅）网络的强大作用。

我从这两个项目中都借鉴了大量借用，并延长了我的感激和钦佩。