Add bounded source context analysis with lexical follow-up searches

docs/source-context-analysis-v1.md

@@ -0,0 +1,103 @@
+# Source-Kontextanalyse v1
+
+`project.query` kann mehrere zusammenhängende Suchen und Kontextabfragen bündeln:
+
+```json
+{"kind":"source.context","text":"23487","path_prefix":"src/server/"}
+```
+
+Das Werkzeug durchsucht ausschließlich Git-Objekte am vom Betreiber festgelegten
+Commit. Arbeitskopie, Branchwahl, Remote und Git-Optionen sind nicht durch die LLM
+änderbar. Ein vorhandener lokaler Checkout wird gelesen; dieses Werkzeug führt
+weder Fetch noch Build oder Sourceänderungen aus.
+
+## Ablauf und Ergebnis
+
+1. Ausgangsbegriff suchen; gültige Bezeichner werden als ganze Wörter gesucht,
+   andere Begriffe als feste, groß-/kleinschreibungssensitive Zeichenfolge.
+2. Begrenzt Kandidaten verfolgen: Bezeichner links einer einfachen Zuweisung des
+   Suchbegriffs sowie Funktionsnamen mit konfigurierten Registrierungsprefixen in
+   gefundenen Dateien. Das ist eine lexikalische Heuristik, keine Typauflösung.
+3. Kontextfenster um Treffer und Registrierungskandidaten lesen. Überlappende oder
+   angrenzende Fenster innerhalb derselben Datei zusammenführen.
+
+Dateipfad, Git-Blob, SHA-256 und Dateigröße werden pro Datei einmal angegeben.
+Die Ausschnitte bestehen aus `start_line` und einer Liste einfacher Codezeilen.
+Treffer enthalten Suchreferenzen und eine Angabe, ob ihr Kontext zurückgegeben
+wurde. Pro Suche bleiben Begriff, Bereich, Vollständigkeit und übersprungene
+Inhalte nachvollziehbar. Weitere Namen in zentralen Loader-Dateien werden nicht
+allein deshalb weiterverfolgt, weil dort die gesuchte Registrierung vorkommt.
+
+Das Ergebnis ist Kontext zu möglichen Definitionen, Verweisen und Registrierungen.
+Es behauptet keinen verifizierten Aufrufgraphen, keine tatsächliche Ausführung und
+keine Fehlerursache. Insbesondere können identische Zahlen andere Entitäten oder
+völlig andere Bedeutungen bezeichnen. Das zeigte auch der lokale Probeaufruf für
+23487: Die Fundstelle lag im Wintergrasp-Code; eine Verbindung zum Wolpertinger
+wird daraus nicht abgeleitet.
+
+## Konfiguration
+
+Das Werkzeug wird im Projektprofil ausdrücklich aktiviert:
+
+```toml
+[source_analysis]
+enabled = true
+context_lines = 8
+max_searches = 4
+max_matches = 12
+max_files = 8
+max_blocks = 12
+max_total_lines = 160
+registration_prefixes = ["AddSC_"]
+```
+
+`AddSC_` ist Adapterkonfiguration für Vcore, kein eingebautes Fachwissen im
+Kernsystem. Ohne solche Prefixe bleibt die allgemeine Such-/Aliasfunktion nutzbar.
+`extensions` kann die zugelassenen Textdateiendungen bestimmen; die Defaults
+enthalten unter anderem C/C++, SQL, Python, JavaScript/TypeScript, C#, Java, Go,
+Rust und Lua. Für größere Codebasen ist ein gezielter `path_prefix` sinnvoll.
+
+Die oben genannten Zahlen sind konfigurierbare Sicherheitsdefaults, keine
+Grenzen des Case-Paketformats. Der gemeinsame Zeitrahmen, Dateigrößen-, Suchbytes-
+und Ergebnisbytes-Grenzen kommen zusätzlich aus `ProjectLimits`. Interne Suchen
+erhalten ein begrenztes Teilbudget der Suchbytes. Höchstens die konfigurierte Zahl
+von Suchen, Dateien, Blöcken und Zeilen wird bearbeitet. Überlange Codezeilen
+werden gekürzt und mit ihrer ursprünglichen Zeilennummer als gekürzt markiert.
+Ein überschrittenes Ergebnisbytes-Limit oder ein Timeout erzeugt einen
+kontrollierten Fehler; es wird kein unmarkiert unvollständiger Capture gespeichert.
+
+## Vollständigkeit und Grenzen
+
+`limits_reached` nennt beispielsweise Treffer-, Folgeabfrage-, Datei-, Block- oder
+Zeilengrenzen. Solche Ergebnisse tragen `partial_configured_source_context`.
+`complete_configured_source_context` besagt nur, dass die gewählte begrenzte
+lexikalische Suchkette und ihre Kontextfenster ohne gemeldete Auslassungen
+verarbeitet wurden. Es bedeutet keine vollständige Implementierungsanalyse.
+
+Eine nicht gefundene Zahl schließt weder symbolische Konstanten mit anderer
+Schreibweise, Datenbanksteuerung, generierten Code, andere Dateitypen noch einen
+dynamischen Pfad aus. Eine Registrierungsfunktion ist ein Kandidat; die LLM muss
+ihre tatsächliche Rolle anhand des Codes bewerten. Bei unzureichenden Ausschnitten
+bleiben die bisherigen gezielten Source-Werkzeuge verfügbar.
+
+## Integration und Prüfung
+
+Neue Kontexte mit aktiviertem Werkzeug enthalten dessen Vertrag, Einstellungen
+und die Empfehlung, es vor getrennten Such-/Leseaufrufen zu verwenden. Eine Sperre
+der Grundwerkzeuge gibt es nicht. Bestehende Kontexte behalten ihren damaligen
+Vertrag. Der stabile Werkzeugkontext kann vom bestehenden Cache genutzt werden.
+
+Ein Aufruf ist eine budgetierte `project.query`-Aktion mit begrenzter interner
+Arbeit, ohne zusätzliche LLM-Zusammenfassung. Captures enthalten die ursprüngliche
+Anfrage, Commit-Bindung, Einstellungen samt Hash sowie sämtliche zurückgegebenen
+Codeausschnitte. Sie bleiben als unveränderliche Evidenz im Paket transportierbar.
+Abweichende Einstellungen gegenüber einem begonnenen Kontext werden abgelehnt.
+
+Lokale Tests prüfen Commitbindung trotz veränderter Arbeitskopie, Alias- und
+Registrierungskette, zusammengeführte Fenster, Python-Suche, leere Ergebnisse,
+Path Traversal, Argumentinjektion, Konfigurationsfehler, Zeit-/Bytegrenzen,
+gekennzeichnete Auslassungen, Budget und portable Wiederaufnahme. Ein simulierter
+LLM-Durchlauf prüft die Einbindung in die hybride Schleife. Die opt-in Prüfung am
+Vcore-Checkout vergleicht Hashes und Zeilen direkt mit den festgelegten Git-Objekten.
+Die Auswahl und Bewertung durch eine echte LLM bleibt Gegenstand des nächsten
+regulären Tests; eine Kostenersparnis wird damit noch nicht behauptet.