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項目，它為我提供了開始該項目的最初動力。我經歷了很多次找到靈感並挑選功能的消息來源。

第二個靈感是打字稿，它使一種相當無趣的語言變成了（不僅）網絡的強大作用。

我從這兩個項目中都藉鑑了大量借用，並延長了我的感激和欽佩。