docs: rewrite installation with architecture overview, troubleshooting, and cross-references

2026-07-19 15:09:58 +02:00
parent 03548dab7d
commit 1acac2b73c
1 changed files with 112 additions and 58 deletions
@@ -15,26 +15,52 @@ A Neovim/LazyVim plugin that launches the [`tia-lsp`](https://gitea.l-tech.rs/la
 | **Attribute Block Toggle** | Interactive expand/collapse of `{...}` blocks with `<Leader>xa` |
 | **Tree-sitter Highlighting** | Syntax highlighting via tree-sitter queries |

+## Architecture
+
+This plugin is part of a three-repo ecosystem:
+
+```
+tia-lsp.nvim       ← Neovim plugin (you are here) — launches the LSP client,
+│                     adds editor features (auto-# prefix, blink.cmp source,
+│                     attribute toggle, workspace scanning, ...)
+▼
+tia-lsp            ← Standalone LSP server — reads JSON-RPC over stdio,
+│                     provides hover, completion, diagnostics, formatting
+│                     Requires: lua src/main.lua + compiled parser.so
+▲
+tia-mason-registry ← mason.nvim recipe — tells mason how to download tia-lsp,
+                      compile parser.so, and create the tia-lsp executable
+```
+
+- **tia-lsp** ([repo](https://gitea.l-tech.rs/lazar/tia-lsp)) — the actual language server, editor-agnostic
+- **tia-mason-registry** ([repo](https://gitea.l-tech.rs/lazar/tia-mason-registry)) — a single `package.yaml` for mason
+- **tia-lsp.nvim** (this repo) — the Neovim-specific integration
+
 ## Installation

-The plugin auto-detects the mason-installed `tia-lsp` executable via `vim.fn.exepath("tia-lsp")` and falls back to `lua <server_path>` for manual installs.
+The plugin auto-detects the mason-installed `tia-lsp` executable via `vim.fn.exepath("tia-lsp")`. If not found, it falls back to running `lua <server_path>` (configurable).

 ### LazyVim + Mason (Recommended)

-1. Add the mason registry as a lazy.nvim plugin:
-   ```lua
-   -- ~/.config/nvim/lua/plugins/tia-mason-registry.lua
-   return {
+Mason downloads and builds the `tia-lsp` server; this plugin configures the LSP client.
+
+**Step 1: Add the mason registry as a lazy.nvim plugin**
+
+mason needs a local copy of the registry to read the install recipe. Adding it as a lazy.nvim plugin gets it cloned automatically:
+
+```lua
+-- ~/.config/nvim/lua/plugins/tia-mason-registry.lua
+return {
  url = "https://gitea.l-tech.rs/lazar/tia-mason-registry.git",
  name = "tia-mason-registry",
-     lazy = false,  -- must be available before mason setup
-   }
-   ```
+}
+```

-2. Register the registry with mason:
-   ```lua
-   -- ~/.config/nvim/lua/plugins/mason.lua
-   return {
+**Step 2: Register the registry with mason**
+
+```lua
+-- ~/.config/nvim/lua/plugins/mason.lua
+return {
  "mason-org/mason.nvim",
  opts = {
    registries = {
@@ -42,50 +68,67 @@ The plugin auto-detects the mason-installed `tia-lsp` executable via `vim.fn.exe
      "github:mason-org/mason-registry",
    },
  },
-   }
-   ```
+}
+```

-3. Add the plugin:
-   ```lua
-   -- ~/.config/nvim/lua/plugins/tia-lsp.lua
-   return {
-     "lazar/tia-lsp.nvim",
+> **Why this works:** lazy.nvim clones `tia-mason-registry` to `~/.local/share/nvim/lazy/tia-mason-registry`. The `file:` registry path points mason to that directory, where it finds `packages/tia-lsp/package.yaml`. Mason needs [`yq`](https://github.com/mikefarah/yq) to parse YAML custom registries — install it once: `:MasonInstall yq`
+
+**Step 3: Install the LSP server**
+
+```
+:MasonInstall tia-lsp
+```
+
+This clones `tia-lsp` from the source repo, compiles `parser.so` (tree-sitter), and places the `tia-lsp` executable on PATH.
+
+**Step 4: Add this plugin**
+
+```lua
+-- ~/.config/nvim/lua/plugins/tia-lsp.lua
+return {
+  "https://gitea.l-tech.rs/lazar/tia-lsp.nvim",
  ft = "scl",
  lazy = true,
  dependencies = {
    "neovim/nvim-lspconfig",
    "nvim-treesitter/nvim-treesitter",
-       "saghen/blink.cmp",
+    "saghen/blink.cmp",            -- optional, for completion
  },
-     config = function()
-       require("tia_lsp").setup({
+  opts = {
    lsp = {
-           on_attach = function(client, bufnr)
-             -- custom keymaps
-           end,
+      -- on_attach = function(client, bufnr) ... end,
    },
-         cmp = true,              -- Enable blink.cmp integration
-         workspace_types = true,  -- Enable workspace UDT scanning
-         auto_prefix = true,      -- Enable auto-# prefixing
-         debug = false,
-       })
-     end,
-   }
-   ```
+    cmp = true,              -- enable blink.cmp integration
+    workspace_types = true,  -- scan project for UDTs and DBs
+    auto_prefix = true,      -- auto-# prefix for local variables
+  },
+}
+```

-4. Install:
-   ```
-   :MasonInstall yq       " one-time prerequisite for file: registry
-   :MasonInstall tia-lsp  " installs the LSP server
-   ```
+**Step 5: Verify**

-5. Verify: open a `.scl` file and run `:LspInfo` — `tia_lsp` should be attached.
+Open a `.scl` file and run `:LspInfo`. `tia_lsp` should be attached. Run `:checkhealth` for detailed diagnostics.
+
+---

 ### Manual Setup (without Mason)

+Clone and build the server manually, then point the plugin at it.
+
+```bash
+# 1. Clone the LSP server
+git clone --depth 1 https://gitea.l-tech.rs/lazar/tia-lsp.git ~/tia-lsp
+
+# 2. Compile the tree-sitter parser (required for parsing SCL)
+cc -fPIC -I ~/tia-lsp/src/tree_sitter -c ~/tia-lsp/src/parser.c -o ~/tia-lsp/parser.o
+cc -shared ~/tia-lsp/parser.o -o ~/tia-lsp/parser.so
+```
+
+Then configure the plugin. The plugin first looks for `tia-lsp` on PATH; if not found, it falls back to running `lua <server_path>`. The tree-sitter parser is loaded from `parser.so` adjacent to the server.
+
 ```lua
 require("tia_lsp").setup({
-  server_path = "/path/to/tia-lsp/src/main.lua",  -- only used if tia-lsp is not on PATH
+  server_path = "~/tia-lsp/src/main.lua",  -- fallback if tia-lsp not on PATH
  ts_parser_url = "https://gitea.l-tech.rs/lazar/tia-lsp.git",
  cmp = true,
  workspace_types = true,
@@ -97,7 +140,7 @@ require("tia_lsp").setup({

 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `server_path` | string | `~/dev/tia-lsp/src/main.lua` | Path to LSP server (only used if `tia-lsp` is not on PATH) |
+| `server_path` | string | `~/dev/tia-lsp/src/main.lua` | Path to LSP server (fallback when `tia-lsp` not on PATH; change for manual installs) |
 | `ts_parser_url` | string | `file://~/dev/tia-lsp` | URL passed to nvim-treesitter for the SCL parser source |
 | `lsp.on_attach` | function | `nil` | Custom LSP attach callback |
 | `lsp.formatting` | boolean | `false` | Enable format command |
@@ -211,6 +254,17 @@ tia-lsp.nvim/
 - **blink.cmp** — Optional, for completion
 - **Lua 5.1+** — LSP server runtime

+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| `:MasonInstall tia-lsp` fails with "unknown package" | Custom registry not registered with mason | Check the `registries` list in your mason config includes the `file:` path to the cloned registry |
+| `:MasonInstall tia-lsp` fails with "yq: command not found" | Mason needs `yq` to parse the YAML registry | Run `:MasonInstall yq` to install it, then retry `:MasonInstall tia-lsp` |
+| `tia_lsp` not attached after opening `.scl` | Server not on PATH or `server_path` points to wrong location | Run `:LspInfo` to see what server is configured. Check `vim.fn.exepath("tia-lsp")` returns a path |
+| LSP starts but no syntax highlighting | Tree-sitter parser (`parser.so`) not found | mason install generates it automatically. For manual setups, run the `cc` commands in the Manual Setup section |
+| `parser.so` load error at startup | Compiled for wrong architecture or Lua version | Recompile: clean the old `.so` and run the `cc` build commands again |
+| LSP starts but no completions/hover | Server can't find its modules | Mason installs to a managed directory. If using manual setup, ensure `src/` contents are present next to `main.lua` |
+
 ## Testing

 ```bash