Spike: LSP-Client für crystalline, `references` gegen `grep` gemessen

[webmatze]

This was generated by AI during triage.

Abgespalten von #32, dessen erstes Akzeptanzkriterium lautet: „Spike-Ergebnis ist in diesem Issue dokumentiert und positiv". Dieses Issue ist dieser Spike. #32 bleibt blockiert, bis hier eine Antwort steht.

Agent Brief

Category: enhancement
Summary: Wegwerf-Prototyp: ein LSP-Client für crystalline, nur find references, gemessen gegen grep an echten Fragen zu diesem Repo. Ergebnis ist eine Empfehlung, kein Feature.

Das ist ausdrücklich ein Spike. Der Code darf hässlich sein, muss nirgends integriert werden und wird nicht gemergt. Gefragt ist eine belastbare Zahl und eine Empfehlung. Wer hier ein sauberes LSP-Subsystem baut, hat die Aufgabe missverstanden.

Was schon da ist und benutzt werden soll

Die JSON-RPC-Grundlage existiert in der MCP-Schicht und deckt den größten Teil dessen ab, was #32 als Aufwand veranschlagt:

• Eine abstrakte Transport-Klasse mit send/receive/close, deren Stdio-Implementierung zeilenbasiert arbeitet. LSPs Content-Length-Framing ist eine Geschwisterklasse an derselben Naht, kein Umbau.
• Ein Protokoll-Modul, das JSON-RPC-Requests und -Notifications baut, plus ein Message-Parser mit Fehler- und Id-Dekodierung. Beides framing-unabhängig.
• Ein Client mit Reader-Fiber, der Antworten über eine Id→Channel-Zuordnung an den wartenden Aufrufer verteilt, mit Deadline pro Request und Aufräumen hängender Anfragen, wenn der Server stirbt.

Für den Spike heißt das: Transport mit Content-Length ergänzen, den Rest ausleihen.

Voraussetzung

crystalline ist auf dieser Maschine nicht installiert, in Homebrew aber als Bottle vorhanden (0.18.0, kein Source-Build). Installation ist ein Kommando. Falls die Installation scheitert oder der Server das Repo nicht analysieren kann, ist das das Spike-Ergebnis — dann bitte genau das berichten und abbrechen, statt zu improvisieren.

Beachte: Das Projekt folgt crystal = "latest" über mise, crystalline aus Homebrew ist gegen Homebrews Crystal gebaut. Beide sind eigene Binaries, müssen also nicht zusammenpassen — aber wenn crystalline an aktueller Syntax dieses Repos scheitert, ist das ein zentraler Befund und gehört in den Bericht.

Was zu bauen ist

Das Minimum, um eine Frage zu beantworten:

1. crystalline als Kindprozess starten, initialize-Handshake mit dem Projektverzeichnis als Root, auf initialized warten.
2. Content-Length-Framing beim Senden und Lesen — auch wenn eine Nachricht über mehrere Reads kommt.
3. textDocument/didOpen für die betroffene Datei.
4. textDocument/references an einer Position, die von Hand bestimmt werden darf. Symbolauflösung über documentSymbol ist ausdrücklich nicht Teil des Spikes — es geht um die Nutzenfrage, nicht um Ergonomie.
5. Die Antwort so ausgeben, dass sie mit grep-Output vergleichbar ist: Datei, Zeile, Zeileninhalt.

Alles andere aus #32 — Hover, Definition, Diagnostics, Dokument-Synchronisation nach Änderungen, UTF-16-Umrechnung, Lazy-Start, Lebenszyklus, mehrere Sprachen — ist out of scope. UTF-16 nur so weit, dass die Testfragen funktionieren; wenn eine Position wegen Umlauten daneben liegt, ist das ein Befund für den Bericht.

Was zu messen ist

Mindestens sechs echte Fragen zu diesem Repo, die ein Agent tatsächlich stellen würde. Vorschläge, gern ergänzen: Aufrufer einer privaten Methode, die in mehreren Klassen gleich heißt; alle Implementierungen einer abstrakten Klasse; alle Nutzungsstellen eines Config-Getters; Aufrufer einer Methode, deren Name auch als String oder in Kommentaren vorkommt.

Pro Frage beides ausführen — grep so, wie smiths grep-Tool es tut, und den LSP-Client — und festhalten:

Spalte	Bedeutung
Frage	die gestellte Frage
Grep-Treffer	Anzahl Zeilen, die smiths grep-Tool zurückgäbe
davon falsch	Kommentare, Strings, gleichnamige Symbole anderer Typen
LSP-Referenzen	Anzahl
davon falsch/fehlend	falsche Treffer und echte Aufrufer, die LSP übersehen hat
Bytes Grep vs. LSP	die Ausgabegröße beider Wege — das ist die Kontextersparnis
Latenz	Zeit bis zur Antwort, kalter und warmer Server getrennt

Die Spalte „fehlend" ist die wichtigste: Ein LSP, der weniger, aber unvollständige Treffer liefert, ist schlechter als grep, nicht besser. Ein Fehltreffer kostet Tokens, ein übersehener Aufrufer kostet einen Bug.

Was zu berichten ist

Ein Kommentar auf #32 mit:

• der Messtabelle
• der Kaltstart-Latenz auf diesem Repo, und ob sie einen Lazy-Start erzwingt
• allem, wo crystalline falsch, unvollständig oder gar nicht geantwortet hat
• dem Aufwand, den die fehlenden Teile aus LSP-Tool für semantische Codesuche (nach vorherigem Spike) #32 realistisch bedeuten, jetzt mit Erfahrung statt Schätzung
• einer klaren Empfehlung: ausbauen, verwerfen, oder ausbauen unter Bedingungen — mit Begründung aus den Zahlen

Eine Empfehlung „könnte man mal" ist kein Ergebnis. Wenn die Zahlen für grep sprechen, ist „verwerfen" die richtige und nützliche Antwort — #32 ist genau deshalb so eingeordnet.

Acceptance criteria

• Ein LSP-Client startet crystalline, übersteht den Handshake und liefert textDocument/references für mindestens eine Position in diesem Repo
• Content-Length-Framing funktioniert auch bei über mehrere Reads verteilten Nachrichten
• Mindestens sechs Fragen sind mit grep und LSP beantwortet und in der Tabelle erfasst, inklusive übersehener Treffer
• Kaltstart- und Warmlauf-Latenz sind getrennt gemessen
• Der Bericht steht als Kommentar an LSP-Tool für semantische Codesuche (nach vorherigem Spike) #32 und endet mit einer eindeutigen Empfehlung
• Der Prototyp-Code ist nicht in src/ gemergt — Wegwerf, außerhalb des Projektbaums oder in einem Branch, der nicht gemergt wird
• Scheitert Installation oder Analyse, ist genau das mit Fehlermeldung berichtet und der Spike gilt als beendet

Out of scope

• Jede Operation außer references
• Symbolauflösung über documentSymbol
• Weitere Sprachen und Server
• Konfigurationsschema, Tool-Registrierung, Lebenszyklus, Shutdown-Handling
• Sauberer, testgedeckter, mergefähiger Code
• Die Umsetzung selbst — die hängt an LSP-Tool für semantische Codesuche (nach vorherigem Spike) #32 und an dieser Empfehlung