LSP-Tool für semantische Codesuche (nach vorherigem Spike)

[webmatze]

Priorität: 3 — das aufwendigste Einzelfeature der Roadmap und das mit dem unsichersten Nutzen-Verhältnis. Bewusst als letztes eingeordnet. Vor der Umsetzung sollte ein Spike klären, ob sich der Aufwand gegenüber grep tatsächlich auszahlt.

Referenz: Claude Code v2.0.74 (LSP-Tool für Go-to-Definition, Find-References, Hover), v2.1.0 (Tool wurde fälschlich aktiviert, wenn keine Server konfiguriert waren), v2.1.153 (Race Condition beim Start).

Motivation

smith findet Code heute ausschließlich über grep und glob. Das ist textuell und kennt keine Semantik:

• „Wo wird Registry#execute_single_call aufgerufen?" → grep findet auch Kommentare, Strings und gleichnamige Methoden anderer Klassen
• „Was ist der Typ hier?" → gar nicht beantwortbar
• „Alle Implementierungen von Approver" → nur mit Glück über Namenskonventionen

Ein LSP-Client macht daraus präzise Anfragen und spart Kontext: Statt 200 Grep-Treffer zu lesen und zu filtern, kommen fünf exakte Referenzen zurück. Bei Crystal ist das besonders reizvoll, weil crystalline als Language Server existiert.

Realistische Einschätzung (bitte vor der Umsetzung lesen)

Dieses Feature hat ein schlechteres Aufwand/Nutzen-Verhältnis als jedes andere in dieser Roadmap:

• LSP ist ein umfangreiches Protokoll mit Initialisierung, Dokument-Synchronisation, Positionskodierung (UTF-16!) und servereigenen Eigenheiten
• Jede Sprache braucht einen eigenen Server, der installiert sein muss
• Der Nutzen hängt stark von der Serverqualität ab; crystalline ist gut, aber nicht mit rust-analyzer oder gopls vergleichbar
• Ein großer Teil des Nutzens lässt sich mit gutem grep plus einem präzisen Prompt erreichen

Empfehlung: Erst einen Spike mit einer Sprache (Crystal via crystalline) und einer Operation (find references) bauen, im Alltag messen, ob es tatsächlich Kontext spart — und erst danach entscheiden, ob ausgebaut wird. Das Ergebnis dieses Spikes gehört als Kommentar in dieses Issue.

Spezifikation (nach positivem Spike)

Konfiguration

[[lsp.servers]]
name       = "crystal"
command    = "crystalline"
args       = ["--stdio"]
extensions = [".cr"]

[[lsp.servers]]
name       = "typescript"
command    = "typescript-language-server"
args       = ["--stdio"]
extensions = [".ts", ".tsx"]

Ohne konfigurierte Server wird das Tool nicht registriert — genau der Bug, den Claude Code in v2.1.0 fixen musste. Kein Tool anbieten, das nichts kann.

Tool lsp

{ "type": "object",
  "properties": {
    "operation": { "enum": ["definition", "references", "hover", "symbols", "diagnostics"] },
    "path":      { "type": "string" },
    "symbol":    { "type": "string", "description": "Symbol name; alternative to line/character" },
    "line":      { "type": "integer" },
    "character": { "type": "integer" }
  },
  "required": ["operation", "path"] }

Wichtig für die Brauchbarkeit: Modelle denken in Symbolnamen, nicht in Zeilen/Spalten. Das Tool sollte symbol unterstützen und intern über documentSymbol die Position auflösen. Ein Tool, das exakte Koordinaten verlangt, wird vom Modell kaum korrekt bedient.

Rückgabeformat

Kompakt und für ein Modell lesbar, nicht rohes LSP-JSON:

References to Registry#execute_single_call (3):
  src/smith/tools/registry.cr:77   res = execute_single_call(call)
  src/smith/tools/registry.cr:129  res = execute_single_call(call)
  spec/tools/registry_spec.cr:44   registry.execute_single_call(...)

Fallstricke

• Positionskodierung: LSP verwendet standardmäßig UTF-16-Codeunits für Spalten. Bei ASCII-Quelltext fällt das nie auf und bricht dann bei der ersten Datei mit Umlauten oder Emoji. Von Anfang an korrekt umrechnen.
• Dokument-Synchronisation: Der Server muss den aktuellen Dateiinhalt kennen. Nach jedem write_file/edit_file ist ein didChange/didSave nötig, sonst arbeitet der Server auf veraltetem Stand und liefert falsche Positionen — was schlimmer ist als keine Antwort.
• Start-Latenz: Große Projekte indizieren mehrere Sekunden bis Minuten. Server lazy beim ersten lsp-Call starten, nicht beim Sessionstart, und Anfragen bis zur Bereitschaft zurückstellen (CC v2.1.153).
• Lebenszyklus: wie bei MCP — Shutdown inklusive Signal::INT-Handler, keine Waisenprozesse.

Umsetzung

src/smith/lsp/protocol.cr    # JSON-RPC über stdio, Content-Length-Framing (nicht zeilenbasiert wie MCP!)
src/smith/lsp/client.cr      # initialize, didOpen/didChange, Requests
src/smith/lsp/manager.cr     # Server pro Sprache, Lebenszyklus
src/smith/tools/lsp_tool.cr

Synergie: Wird das MCP-Issue zuerst umgesetzt, ist die JSON-RPC-Basis dort bereits vorhanden und sollte geteilt werden. Achtung auf den Unterschied im Framing: MCP über stdio nutzt zeilenbasiertes JSON, LSP nutzt Content-Length-Header. Die Request/Response-Zuordnung und der Lese-Fiber sind aber identisch.

Tests (spec/lsp/)

Gegen einen Fake-LSP-Server in Crystal, keine externe Toolchain in der Testsuite:

• Content-Length-Framing beim Senden und Empfangen, auch bei Nachrichten über mehrere Reads
• UTF-16-Positionsumrechnung für eine Zeile mit Umlauten und Emoji
• symbol → Position über documentSymbol aufgelöst
• Anfrage vor Server-Bereitschaft wird zurückgestellt, nicht verworfen
• Server nicht installiert → klare Meldung, Session läuft weiter
• Keine Server konfiguriert → Tool fehlt in registry.specs
• Shutdown hinterlässt keine Prozesse

Akzeptanzkriterien

• Spike-Ergebnis ist in diesem Issue dokumentiert und positiv
• LSP-Tool nur bei konfigurierten Servern registriert
• Symbolbasierte Anfragen funktionieren ohne manuelle Koordinaten
• UTF-16-Positionen korrekt umgerechnet, mit Test
• Dokument-Synchronisation nach Dateiänderungen
• Keine Waisenprozesse
• Ausgabe ist kompakt und modelltauglich
• crystal spec grün, Format sauber, README-Abschnitt „LSP"

Nicht-Ziele

• Rename/Refactoring über LSP (Schreiboperationen bleiben bei edit_file)
• Code-Completion
• Automatische Installation von Language Servern

[webmatze]

This was generated by AI during triage.

Triage Notes

Dieses Issue kann nicht weiter als bis hierher triagiert werden, weil sein erstes Akzeptanzkriterium — „Spike-Ergebnis ist in diesem Issue dokumentiert und positiv" — noch nicht erfüllbar ist. Der Spike ist jetzt #65 und ready-for-agent; dieses Issue ist als davon blockiert eingetragen.

Was bereits geklärt ist:

• Die JSON-RPC-Grundlage ist zum größten Teil vorhanden. Die MCP-Schicht hat eine abstrakte Transport-Klasse (send/receive/close) mit zeilenbasierter Stdio-Implementierung, ein framing-unabhängiges Protokoll-Modul für Requests und Notifications samt Message-Parser, und einen Client mit Reader-Fiber, Id→Channel-Zuordnung, Request-Deadlines und Aufräumen hängender Anfragen. Der im Body als Warnung formulierte Framing-Unterschied (Content-Length statt Zeilen) ist damit eine Geschwisterklasse an einer bereits existierenden Naht, kein Umbau. Der geschätzte Aufwand des Issues ist an dieser Stelle zu hoch angesetzt.
• Neu ist nur die LSP-Eigenheit: initialize-Handshake, Dokument-Synchronisation, UTF-16-Positionsumrechnung, documentSymbol-Auflösung, Lazy-Start. Der Rest ist Wiederverwendung.
• crystalline ist verfügbar. Auf dieser Maschine nicht installiert, aber in Homebrew als Bottle (0.18.0, kein Source-Build, keine Build-Fehler in den letzten 30 Tagen). Der Spike ist damit delegierbar und braucht keinen Kampf mit einer Toolchain.
• Ein Risiko ist benannt: Das Projekt folgt crystal = "latest", crystalline aus Homebrew ist gegen Homebrews Crystal gebaut. Separate Binaries, müssen also nicht zusammenpassen — aber wenn der Server aktuelle Syntax dieses Repos nicht analysieren kann, beantwortet das die Nutzenfrage sofort.
• Der Rest der Spezifikation bleibt unangetastet. Konfigurationsschema, Tool-Schnittstelle mit symbol-Parameter, kompaktes Ausgabeformat, die vier Fallstricke und die Nicht-Ziele werden nicht in Frage gestellt — sie warten nur.

Was wir noch brauchen (@webmatze), und was #65 liefern soll:

• Spart ein LSP-references gegenüber smiths grep-Tool messbar Kontext? Erwartet wird eine Tabelle über mindestens sechs echte Fragen zu diesem Repo, mit Ausgabegröße in Bytes für beide Wege.
• Wie oft übersieht crystalline einen echten Aufrufer? Das ist die entscheidende Zahl: Weniger Treffer sind nur dann ein Gewinn, wenn keiner davon fehlt. Ein Fehltreffer kostet Tokens, ein übersehener Aufrufer kostet einen Bug.
• Wie lang ist die Kaltstart-Latenz auf diesem Repo, und erzwingt sie den im Body vorgesehenen Lazy-Start?
• Analysiert crystalline 0.18 dieses Repo überhaupt vollständig?
• Wie groß ist der Restaufwand für die LSP-eigenen Teile mit Prototyp-Erfahrung statt aus der Schätzung?

Sobald #65 mit einer Empfehlung geschlossen ist, geht dieses Issue zurück auf needs-triage und wird auf dieser Grundlage entschieden — inklusive der Möglichkeit, es als wontfix zu schließen, wenn die Zahlen für grep sprechen. Das ist ausdrücklich ein akzeptables Ergebnis.