nelson-lsp

📄Description

nelson-lsp est un serveur JSON-RPC Language Server Protocol sur l'entree standard et la sortie standard.

L'executable est destine a etre lance par un editeur ou un environnement de developpement. Il n'ouvre pas d'invite interactive et ne lit pas de fichiers source depuis la ligne de commande. Le client envoie les messages Language Server Protocol sur stdin avec l'en-tete standard Content-Length, et le serveur ecrit les reponses et notifications JSON-RPC sur stdout.

Le serveur maintient un modele leger de document et de workspace. Les documents ouverts sont indexes avec leur texte courant, leur version, leurs diagnostics, leurs symboles, leurs fonctions locales, leurs classes, leurs imports et leurs variables locales. Les racines de workspace sont indexees separement; chaque racine garde les fichiers .m trouves, les fonctions publiques, les fonctions locales, les classes, les chemins de modules et un cache invalide par date de fichier, hash de contenu et configuration lint.

Le serveur publie les diagnostics de l'analyseur de code Nelson pour les buffers ouverts. Les diagnostics utilisent nelson-lint comme source et exposent l'identifiant de regle, la severite, le message, la plage de texte, des data stables pour les actions de code ulterieures, les liens d'aide codeDescription, relatedInformation et les tags LSP pour les elements inutilises ou obsoletes lorsque c'est applicable.

Les editeurs qui utilisent les diagnostics en pull peuvent appeler textDocument/diagnostic pour un document ou workspace/diagnostic pour tous les fichiers sous les racines de workspace initialisees. Les diagnostics workspace reutilisent l'analyse recursive, respectent la configuration partagee d'inclusion et d'exclusion, et prennent en charge les notifications de progression partielle.

Les corrections rapides sont renvoyees par textDocument/codeAction. Si un diagnostic porte des edits de texte surs, le serveur renvoie une action quickfix qui applique ces edits. Pour chaque diagnostic non supprime, le serveur propose aussi une action de suppression locale qui ajoute %#ok<ID> sur la ligne du diagnostic et une action de suppression fichier en tete du fichier.

Les actions source incluent source.fixAll.nelson-lint pour toutes les corrections lint sures d'un document, source.organizeImports pour nettoyer les imports et source.nelson.generateHelpSkeleton pour generer une commande de squelette d'aide. Certains diagnostics peuvent aussi proposer des corrections plus riches, comme creer un fichier de fonction manquant ou ajouter un stub de fonction locale.

Le formatage est expose par textDocument/formatting, textDocument/rangeFormatting et textDocument/onTypeFormatting. Le serveur utilise le meme coeur de formatage Nelson que nelson-format et renvoie des edits utilisables pour le format-on-save et le formatage declenche par l'editeur.

La surface de navigation et d'edition prend en charge textDocument/hover, textDocument/completion, completionItem/resolve, textDocument/signatureHelp, textDocument/definition, textDocument/declaration, textDocument/implementation, textDocument/references, textDocument/documentHighlight, textDocument/prepareRename et textDocument/rename. Le renommage est volontairement limite aux edits locaux dans le document courant.

Les completions couvrent les mots-cles Nelson, les snippets, les variables locales, les fonctions locales, les fonctions du workspace, les classes et les chemins de modules connus. Les requetes hover renvoient les informations de regle de l'analyseur lorsque le curseur est sur un diagnostic, ou les informations de symbole lorsque le curseur est sur un symbole local ou workspace connu.

La surface IDE structurelle prend en charge textDocument/documentSymbol, workspace/symbol, textDocument/foldingRange, textDocument/selectionRange, textDocument/semanticTokens/full, textDocument/codeLens et textDocument/documentLink. Les semantic tokens identifient les mots-cles, fonctions, variables, classes, proprietes, methodes, chaines et commentaires.

Les code lenses exposent des actions preparees pour lancer le fichier courant, lancer les tests du module et inspecter le nombre d'issues du document courant. Les liens de document sont renvoyes pour les chemins de type fichier trouves dans le texte source.

Le provider workspace/executeCommand accepte nelson.runFile, nelson.runSelection, nelson.runTestsForModule, nelson.openHelp, nelson.lintWorkspace, nelson.clearLspCache et nelson.createFunctionFile. Les commandes renvoient des donnees structurees que le client peut executer ou afficher; le serveur ne modifie pas les fichiers sauf si le client applique explicitement un workspace edit ou un resultat de commande renvoye.

La surface actuelle du protocole prend en charge initialize, shutdown, exit, $/cancelRequest, workspace/didChangeConfiguration, workspace/didChangeWorkspaceFolders, workspace/executeCommand, workspace/symbol, textDocument/didOpen, textDocument/didChange, textDocument/didSave, textDocument/didClose, textDocument/willSaveWaitUntil, textDocument/diagnostic, workspace/diagnostic, textDocument/formatting, textDocument/rangeFormatting, textDocument/onTypeFormatting, textDocument/codeAction, codeAction/resolve, textDocument/hover, textDocument/completion, completionItem/resolve, textDocument/signatureHelp, textDocument/definition, textDocument/declaration, textDocument/implementation, textDocument/references, textDocument/documentHighlight, textDocument/prepareRename, textDocument/rename, textDocument/documentSymbol, textDocument/foldingRange, textDocument/selectionRange, textDocument/semanticTokens/full, textDocument/codeLens et textDocument/documentLink.

La reponse initialize annonce une synchronisation incrementale du texte, les notifications d'ouverture et de fermeture, les diagnostics en pull, les diagnostics workspace, le formatage de document, le formatage de plage, le formatage on-type, les actions de code avec support de resolution, les informations de hover, la completion avec support de resolution, l'aide de signature, la navigation vers definition, declaration et implementation, les references, les highlights de document, le prepare-rename, les symboles de document, les symboles workspace, les folding ranges, les selection ranges, les semantic tokens, les code lenses, les liens de document, les commandes execute, les dossiers workspace et les notifications de sauvegarde. textDocument/didChange accepte les changements de document complet et les patches incrementaux avec plage de texte dans l'ordre envoye par le client.

Lorsqu'un client envoie des versions de document, les diagnostics publies pour les documents ouverts incluent la meme version. Les diagnostics workspace utilisent null comme version pour les fichiers analyses depuis le disque et la version courante pour les buffers ouverts.

Les diagnostics workspace prennent en charge partialResultToken. Lorsque le token est present, le serveur envoie les elements de diagnostic via une notification de resultat partiel $/progress et renvoie une liste finale vide pour cette requete.

Les requetes de hover sur un diagnostic actif renvoient du Markdown avec l'identifiant de regle, le nom de regle, la severite, la categorie, la fixabilite, une description courte, le message du diagnostic et le lien d'aide lorsqu'il existe.

Les URI de fichier au format file:/// sont converties en chemins locaux avant l'analyse. Les autres schemas d'URI sont analyses comme un buffer en memoire nomme buffer.m.

La configuration est partagee avec l'analyseur de code. Lorsqu'un espace de travail contient un fichier de configuration de lint Nelson, les diagnostics suivent les memes severites et seuils que checkcode, codeIssues et nelson-lint.

Les editeurs peuvent aussi envoyer workspace/didChangeConfiguration. Le serveur accepte les reglages lint sous settings.nelson.lint, settings.nelsonLint, settings.nelson-lint, ou dans un objet de premier niveau contenant rules ou files. Les champs pris en charge reprennent la forme de la configuration lint pour rules, files.include et files.exclude; ces reglages sont appliques au-dessus de la configuration workspace pour les diagnostics suivants et les buffers ouverts sont rafraichis.

L'annulation suit la notification Language Server Protocol $/cancelRequest. Si une requete en attente est annulee avant son traitement, le serveur renvoie une erreur JSON-RPC avec le code -32800.

💡Exemples

Demarrer le serveur depuis un client editeur.

nelson-lsp

Configuration typique d'une commande editeur.

{
  "command": "nelson-lsp",
  "args": [],
  "transport": "stdio",
  "filetypes": ["nelson", "m"]
}

Corps minimal d'une requete initialize envoyee apres l'en-tete Content-Length.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "processId": null,
    "rootUri": "file:///C:/work/project",
    "capabilities": {}
  }
}

Ouvrir un document et recevoir les diagnostics.

{
  "jsonrpc": "2.0",
  "method": "textDocument/didOpen",
  "params": {
    "textDocument": {
      "uri": "file:///C:/work/project/example.m",
      "languageId": "nelson",
      "version": 1,
      "text": "function y = example(x)\ny = x + 1;\nend\n"
    }
  }
}

Demander les corrections rapides et suppressions pour le buffer courant.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "textDocument/codeAction",
  "params": {
    "textDocument": {
      "uri": "file:///C:/work/project/example.m"
    },
    "range": {
      "start": { "line": 0, "character": 0 },
      "end": { "line": 0, "character": 0 }
    },
    "context": {
      "diagnostics": []
    }
  }
}

Appliquer un changement incremental avec une plage de texte.

{
  "jsonrpc": "2.0",
  "method": "textDocument/didChange",
  "params": {
    "textDocument": {
      "uri": "file:///C:/work/project/example.m",
      "version": 2
    },
    "contentChanges": [
      {
        "range": {
          "start": { "line": 1, "character": 5 },
          "end": { "line": 1, "character": 5 }
        },
        "text": " + 1"
      }
    ]
  }
}

Demander les edits de formatage avant sauvegarde.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "textDocument/willSaveWaitUntil",
  "params": {
    "textDocument": {
      "uri": "file:///C:/work/project/example.m"
    },
    "reason": 1
  }
}

Mettre a jour les reglages lint depuis un editeur.

{
  "jsonrpc": "2.0",
  "method": "workspace/didChangeConfiguration",
  "params": {
    "settings": {
      "nelson": {
        "lint": {
          "rules": {
            "NLS0010": { "level": "allow" }
          }
        }
      }
    }
  }
}

Demander les diagnostics workspace apres initialize.

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "workspace/diagnostic",
  "params": {
    "previousResultIds": []
  }
}

Demander les completions a la position courante du curseur.

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "textDocument/completion",
  "params": {
    "textDocument": {
      "uri": "file:///C:/work/project/example.m"
    },
    "position": { "line": 1, "character": 4 }
  }
}

Demander une commande preparee via le provider de commandes LSP.

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "workspace/executeCommand",
  "params": {
    "command": "nelson.runFile",
    "arguments": ["file:///C:/work/project/example.m"]
  }
}