From 41403426b0b4dd0b28111e946543788a444c3a88 Mon Sep 17 00:00:00 2001
From: Kirill Andreev <hindmost.one@gmail.com>
Date: Thu, 4 Jun 2020 16:06:51 +0400
Subject: [PATCH] Add project overview

---
 tools/lsp/README.md | 55 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 49 insertions(+), 6 deletions(-)

diff --git a/tools/lsp/README.md b/tools/lsp/README.md
index c9a4260b1..40b50c04e 100644
--- a/tools/lsp/README.md
+++ b/tools/lsp/README.md
@@ -1,4 +1,52 @@
 
+## What
+
+A language server for all three dialects of LIGO.
+
+## Design choices
+
+The server contains 2 big parts:
+1) Grammars
+2) Server itself.
+
+Grammars are in separate folders, in form of tree-sitter grammars.
+They are compiled via `tree-sitter generate` command in their respective folder.
+
+Then they are linked as `parser.c` file with GHC toolchain.
+Because GHC is unable to link from outside of project folder, the `parser.c` is
+symlinked into `vendor/` directory.
+
+Right now only one parser is linked there; the name of symlink should be changed
+in future.
+
+Server part invokes the TS-parser and then constructs a tree of haskell datatypes
+from the TS-tree. Then it is fed into `AST.Parser` (name will be changed), which
+constructs an universal AST from the tree of the respective language.
+
+Parser uses the root `Parser` module which provides the combinators and monad
+to deal with `ParseTree`, produced from TS output.
+
+The tree it produces has:
+1) An `ASTInfo` at each node, which contains the `Range` of that node and
+   preceeding comments. Sadly, but the comments after all the code in the module
+   are lost.
+2) Some structure;
+3) Ability to be just an `Error` instead of all above. An error contains `Range`
+   as well.
+
+It is possible to update the scopes in the tree, using `updateTree` function,
+which is a specialised custom `traverse`.
+
+It is also possible to get the zipper-like chain of trees, covering some node,
+in ascending order - using `spineTo` function. If you have already pinned
+the scopes, you can just take first one and pull the scope out of it. Unless
+it is an `Error` node. We probably need th error nodes to be `Functor`s
+as well as any other structures used to build the tree.
+
+On top of all that is an event loop for handling messages from some lsp-client.
+
+## For developers
+
 To compile and run, the following tools are needed:
 
 1) tree-sitter-clr (the Node.js one was usied during development)
@@ -19,9 +67,4 @@ cd ../squirrel
 stack install
 ```
 
-To use the executable, do
-```
-squirrel <filename>.ligo
-```
-
-At this stage of development, it first prints the dump of tree-sitter parse tree, then its attempts to build actual parse tree.
\ No newline at end of file
+The executable is a language server.
\ No newline at end of file