easy-slack/docs/neovim.md

# Neovim pour Ruby depuis SlackBuilds.org

> Nécessite `sbopkg`.

Neovim est un éditeur de texte modal dérivé de Vim. La configuration ci-dessous reste volontairement simple : Telescope est utilisé pour naviguer entre les fichiers et les buffers, `ripgrep` pour rechercher dans le projet, Grug Far pour rechercher et remplacer dans plusieurs fichiers, `nvim-autopairs` pour fermer automatiquement les paires, et le client LSP intégré de Neovim pour Ruby, les diagnostics, la navigation et les signatures de méthodes.

## Installation

Neovim est disponible sur SlackBuilds.org. Générez la queue des dépendances :

```sh
# sqg -p neovim
```

Puis lancez l'installation :

```sh
# sbopkg -i neovim
```

Si `sbopkg` trouve à la fois le paquet et une queue du même nom, choisissez **Q** pour utiliser la queue et installer les dépendances dans le bon ordre.

Installez également `ripgrep`, utilisé par Telescope pour rechercher dans le projet :

```sh
# sqg -p ripgrep
# sbopkg -i ripgrep
```

Sous Wayland, installez `wl-clipboard` pour permettre à Neovim d'utiliser le presse-papiers système :

```sh
# sbopkg -i wl-clipboard
```

Pour un affichage homogène des symboles, vous pouvez également installer JetBrains Mono Nerd Font :

```sh
# sbopkg -i ttf-nerd-fonts-jetbrains-mono
```

La variante **JetBrainsMono Nerd Font Mono** est adaptée à l'affichage dans un terminal.

Vérifiez ensuite les installations :

```sh
$ nvim --version
$ rg --version
```

## Configuration

Créez le dossier de configuration :

```sh
$ mkdir -p ~/.config/nvim
```

Créez ou éditez `~/.config/nvim/init.lua` :

```sh
$ nvi ~/.config/nvim/init.lua
```

Utilisez cette configuration :

```lua
-- Telescope remplace Netrw.
vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1

-- Leader
vim.g.mapleader = " "
vim.g.maplocalleader = ","

-- Affichage
vim.opt.number = true
vim.opt.signcolumn = "yes"
vim.opt.cursorline = true
vim.opt.splitkeep = "screen"
vim.opt.splitright = true
vim.opt.splitbelow = true
vim.opt.shortmess:append("I")
vim.opt.winborder = "rounded"
vim.opt.pumborder = "rounded"
vim.cmd.colorscheme("retrobox")

-- Apparence homogène des menus et fenêtres flottantes.
vim.api.nvim_set_hl(0, "NormalFloat", { link = "Pmenu" })
vim.api.nvim_set_hl(0, "FloatBorder", { link = "PmenuBorder" })

-- Telescope reprend l'apparence des fenêtres flottantes.
vim.api.nvim_set_hl(0, "TelescopeNormal", { link = "NormalFloat" })
vim.api.nvim_set_hl(0, "TelescopeBorder", { link = "FloatBorder" })
vim.api.nvim_set_hl(0, "TelescopeSelection", { link = "PmenuSel" })

-- Indentation
vim.opt.expandtab = true
vim.opt.shiftwidth = 2
vim.opt.tabstop = 2

-- Presse-papiers système
vim.opt.clipboard = "unnamedplus"

-- Autocomplétion de la ligne de commande
vim.opt.wildmode = "noselect:lastused,full"

vim.api.nvim_create_autocmd("CmdlineChanged", {
  pattern = { ":", "/", "?" },
  callback = function()
    vim.fn.wildtrigger()
  end,
})

-- Plugins
vim.pack.add({
  "https://github.com/nvim-lua/plenary.nvim",
  "https://github.com/MagicDuck/grug-far.nvim",
  "https://github.com/windwp/nvim-autopairs",
  {
    src = "https://github.com/nvim-telescope/telescope.nvim",
    version = "v0.2.1",
  },
})

-- Auto-fermeture des paires
require("nvim-autopairs").setup()

-- Telescope
local builtin = require("telescope.builtin")
local sorters = require("telescope.sorters")

require("telescope").setup({
  defaults = {
    preview = false,
    file_sorter = sorters.get_substr_matcher,
    generic_sorter = sorters.get_substr_matcher,
  },
})

vim.keymap.set("n", "<Leader>f", builtin.find_files, {
  desc = "Files",
})

vim.keymap.set("n", "<Leader>b", builtin.buffers, {
  desc = "Buffers",
})

vim.keymap.set("n", "<Leader>g", builtin.live_grep, {
  desc = "Grep",
})

vim.keymap.set("n", "<Leader>w", builtin.grep_string, {
  desc = "Word",
})

vim.keymap.set("n", "<Leader>l", builtin.resume, {
  desc = "Last search",
})

vim.keymap.set("n", "<Leader>d", builtin.diagnostics, {
  desc = "Diagnostics",
})

-- Grug Far
vim.keymap.set({ "n", "x" }, "<Leader>r", function()
  require("grug-far").open()
end, {
  desc = "Replace",
})

-- Ouvre Telescope au démarrage sauf si un fichier est explicitement ouvert.
vim.api.nvim_create_autocmd("VimEnter", {
  once = true,
  callback = function()
    local argc = vim.fn.argc()

    if argc == 1 and vim.fn.isdirectory(vim.fn.argv(0)) == 1 then
      vim.api.nvim_set_current_dir(vim.fn.fnamemodify(vim.fn.argv(0), ":p"))
      vim.cmd.enew()
    elseif argc > 0 then
      return
    end

    builtin.find_files()
  end,
})

-- Ruby LSP
vim.lsp.config("ruby_lsp", {
  cmd = { "ruby-lsp" },
  filetypes = { "ruby" },
  root_markers = { "Gemfile", ".git" },
  -- Contournement temporaire pour Ruby LSP 0.26.11 : dans un projet Ruby
  -- plat, Ruby Indexer peut construire le motif {}/**/*.rb et indexer un
  -- même fichier sous deux chemins différents. Cette exclusion neutralise
  -- uniquement ce motif ; les fichiers Ruby restent indexés normalement.
  init_options = {
    indexing = {
      excludedPatterns = { "{}/**/*.rb" },
    },
  },
})

vim.lsp.enable("ruby_lsp")

```

> Le bloc `init_options` contient un contournement temporaire pour Ruby LSP 0.26.11 : dans certains petits projets Ruby plats, Ruby Indexer peut construire le motif `{}/**/*.rb` et indexer un même fichier sous deux chemins différents. Cette exclusion neutralise uniquement ce motif ; les fichiers Ruby restent indexés normalement. Lorsque le problème sera corrigé dans Ruby LSP/Ruby Indexer, le bloc `init_options` pourra être retiré.

Neovim gère les plugins avec `vim.pack`. `plenary.nvim` est une dépendance de Telescope, `nvim-autopairs` ferme automatiquement les parenthèses, crochets, accolades et guillemets, et Grug Far utilise `ripgrep` pour la recherche et le remplacement. Les diagnostics, les signatures de méthodes et la navigation Ruby utilisent directement le client LSP intégré à Neovim. Aucune complétion LSP automatique n'est activée.

Le réglage `vim.opt.clipboard = "unnamedplus"` relie le registre par défaut de Neovim au presse-papiers système. Sous Wayland, Neovim utilise `wl-copy` et `wl-paste` fournis par `wl-clipboard`. Vous pouvez vérifier le fournisseur détecté avec :

```text
:checkhealth vim.provider
```

La section `Clipboard` doit indiquer qu'un outil de presse-papiers a été trouvé.

## Ruby

Installez d'abord Ruby avec `rbenv` en suivant la fiche [Ruby avec rbenv](ruby.md), puis utilisez le même Ruby pour les outils ci-dessous.

### Ruby LSP

Installez `ruby-lsp` avec le Ruby utilisé par votre environnement :

```sh
$ gem install ruby-lsp
```

Ouvrez un fichier Ruby, puis vérifiez que le client LSP est bien détecté dans Neovim :

```text
:checkhealth vim.lsp
```

### RuboCop

Installez RuboCop avec le Ruby utilisé par votre environnement :

```sh
$ gem install rubocop
```

Vérifiez son installation :

```sh
$ rubocop -V
```

Créez `~/.rubocop.yml` pour activer automatiquement les nouvelles règles ajoutées comme `pending` par RuboCop :

```sh
$ nvi ~/.rubocop.yml
```

Ajoutez ensuite :

```yaml
AllCops:
  NewCops: enable
```

RuboCop est utilisé manuellement pour mettre en forme le code et effectuer des vérifications ciblées.

Pour appliquer uniquement les règles de mise en forme à l'ensemble du projet :

```sh
$ rubocop --only Layout -A
```

Pour afficher uniquement les remarques de style :

```sh
$ rubocop --only Style --format simple
```

Pour rechercher les ambiguïtés et erreurs potentielles signalées par les règles `Lint` :

```sh
$ rubocop --lint --format simple
```

## Utilisation

Placez-vous dans le dossier du projet et lancez Neovim :

```sh
$ cd ~/src/projet
$ nvim .
```

Sans fichier explicitement indiqué, Telescope s'ouvre directement. Si un fichier est passé sur la ligne de commande, Neovim l'ouvre normalement :

```sh
$ nvim lib/game.rb
```

Les commandes suivantes suffisent pour commencer :

| Commande | Action |
| --- | --- |
| `i` | Passer en mode insertion |
| `Esc` | Revenir en mode normal |
| `v` | Commencer une sélection visuelle |
| `y` (mode visuel) | Copier la sélection dans le presse-papiers système |
| `yy` | Copier la ligne courante dans le presse-papiers système |
| `p` | Coller depuis le presse-papiers système |
| `:w` | Enregistrer |
| `:q` | Quitter |
| `Space f` | Rechercher et ouvrir un fichier du projet |
| `Space b` | Afficher les buffers ouverts |
| `Space g` | Rechercher du texte dans le projet avec `ripgrep` |
| `Space w` | Rechercher dans le projet le mot sous le curseur |
| `Space l` | Reprendre la dernière vue Telescope |
| `Space d` | Afficher les diagnostics connus par Neovim avec Telescope |
| `Space r` | Ouvrir Grug Far pour rechercher et remplacer |
| `Ctrl-]` | Aller à la définition |
| `Ctrl-t` | Revenir après un saut vers une définition |
| `K` | Afficher les informations LSP sur le symbole sous le curseur |
| `Ctrl-s` | Afficher la signature de la méthode en mode insertion (raccourci LSP natif) |
| `Ctrl-x Ctrl-o` | Afficher manuellement la complétion LSP en mode insertion |
| `u` | Annuler |

### IRB

Pour explorer Ruby, découvrir des méthodes, consulter leur documentation ou tester rapidement du code, gardez de préférence IRB dans un split de Konsole dédié, en dessous de Neovim :

```sh
$ irb
```

IRB fournit sa propre complétion. `Tab` parcourt les propositions et `Shift-Tab` revient à la proposition précédente.

Quelques commandes utiles :

| Commande | Action |
| --- | --- |
| `show_doc Array#select` | Afficher la documentation avec RI |
| `ls objet` | Afficher les méthodes, constantes et variables accessibles |
| `show_source nom` | Afficher le code source lorsqu'il est disponible |
| `help` | Afficher les commandes IRB |
| `exit` | Quitter IRB |

IRB reste l'outil privilégié pour explorer Ruby. Dans Neovim, `K`, `Ctrl-s` et `Ctrl-x Ctrl-o` servent surtout à obtenir rapidement des informations contextuelles sans quitter le fichier en cours.

### Grug Far

`Space r` ouvre Grug Far dans un split vertical. En mode visuel, la sélection courante est utilisée pour préremplir le texte recherché.

Les raccourcis principaux dans Grug Far sont :

| Commande | Action |
| --- | --- |
| `,r` | Appliquer le remplacement |
| `,c` | Fermer Grug Far |
| `Entrée` | Ouvrir l'emplacement du résultat sous le curseur |

La virgule correspond ici à `<localleader>`, défini dans la configuration avec `vim.g.maplocalleader = ","`.

Pour vérifier l'installation ou diagnostiquer un problème :

```text
:checkhealth grug-far
```

### Telescope

Dans Telescope :

| Commande | Action |
| --- | --- |
| `Ctrl-n` ou `↓` | Résultat suivant |
| `Ctrl-p` ou `↑` | Résultat précédent |
| `Entrée` | Ouvrir le résultat |
| `Ctrl-v` | Ouvrir dans un split vertical |
| `Ctrl-x` | Ouvrir dans un split horizontal |
| `Ctrl-t` | Ouvrir dans un nouvel onglet |
| `Ctrl-c` | Fermer Telescope |

Pour vérifier l'installation ou diagnostiquer un problème :

```text
:checkhealth telescope
```

La ligne de commande de Neovim propose automatiquement les complétions pour les commandes `:` et les recherches `/` et `?`.

## Ignorer des fichiers du projet

Pour masquer certains fichiers ou dossiers dans les recherches de Telescope sans modifier `.gitignore`, créez un fichier `.rgignore` à la racine du projet. Cette règle reste propre aux recherches locales et ne change pas les fichiers suivis par Git.

Par exemple, pour ignorer le dossier `doc/` :

```sh
$ printf 'doc/\n' > .rgignore
```

`ripgrep` prendra ce fichier en compte pour les recherches effectuées par Telescope lorsqu'il est utilisé comme moteur de recherche.

## Maintenance

Pour rechercher les mises à jour disponibles pour les plugins gérés par `vim.pack` :

```text
:lua vim.pack.update()
```

Vérifiez les changements proposés, puis utilisez `:write` pour les accepter. Redémarrez ensuite Neovim pour utiliser les plugins mis à jour.

Pour contrôler l'état du gestionnaire de plugins :

```text
:checkhealth vim.pack
```

[Retour au guide principal](../README.md)