Roadmap UI

2026-07-12 18:47:52 +02:00
parent a18f8287fe
commit fe9fd3064d
4 changed files with 129 additions and 5 deletions
--- a/ac-cli/src/main/resources/agenticcode.properties
+++ b/ac-cli/src/main/resources/agenticcode.properties
@@ -4,4 +4,4 @@
 server.url=http://localhost:8787
 # Stamped by deploy.sh (stamp_cli_version) from ac-code-server's agenticcode.version
 # at build time. "dev" means this jar wasn't built via deploy.sh.
-version=8
+version=9
--- a/ac-code-server/src/main/resources/application.properties
+++ b/ac-code-server/src/main/resources/application.properties
@@ -3,7 +3,7 @@ quarkus.http.port=8787
 # AgenticCode's own release counter (not the Maven project version) — bump this by hand for each
 # release. Single source of truth for the startup log line, GET /api/version, and the MCP
 # 'version' tool/server-info (referenced below via property expression, not duplicated).
-agenticcode.version=8
+agenticcode.version=9

 # MCP server (HTTP/SSE transport) — tools exposed at http://<host>:8787/mcp/sse
 quarkus.mcp.server.server-info.name=agenticcode
--- a/x-docs/roadmap.md
+++ b/x-docs/roadmap.md
@@ -16,9 +16,8 @@ answerable because Tier 1 pre-indexes coarse references globally.

 Items **36–42 are done** (Tier-1 reference index + tri-state status, Tier-2 lazy
 deep-ingest, depth/node caps, unresolved-reference nodes, Tier-3 source-from-disk
-
-+ stale check, and the `refresh` surface) — see `x-docs/features.md`. The only
-  open item in this track:
+with stale check, and the `refresh` surface) — see `x-docs/features.md`. The only
+open item in this track:

 - [ ] **43. Automatic invalidation (deferred)** — file-watch / hash-based
  staleness detection that auto-transitions changed modules back to
--- a/x-docs/ui-proposal.md
+++ b/x-docs/ui-proposal.md
@@ -0,0 +1,125 @@
+# Proposal: Web-UI zum Verstehen & Navigieren des Codes
+
+**Status:** Diskussionsgrundlage (noch keine Implementierung). Dieses Dokument hält
+die abgestimmte Vision, Architektur, die nötigen Backend-Voraussetzungen und einen
+Milestone-Plan fest. Sprache: Deutsch (Diskussionskontext); bei Bedarf auf Englisch
+umstellbar — der Rest von `x-docs/` ist englisch.
+
+## 1. Ziel & Kontext
+
+Eine React/TypeScript-Weboberfläche, die den AgenticCode-Graphen für **Menschen**
+begreifbar macht: durch Legacy-Quellen (v. a. Software AG Natural) navigieren, den
+Code *sehen* (Call-Graph, Datenfluss, DB-Zugriffe) und ihn verstehen. Sie setzt auf
+der bestehenden REST-API auf (`/api/projects/{p}/…`).
+
+**Primärer Nutzer & Hauptziel (abgestimmt):** Entwickler, die Legacy-**Natural
+verstehen, um es nach Java zu migrieren**. Der Wert liegt darin, das Verhalten eines
+Moduls schnell vollständig zu erfassen: Wer ruft es? Was ruft es (inkl. dynamischer
+`CALLNAT`)? Welche Felder fließen wohin? Welche DB-Tabellen liest/schreibt es? Was
+bricht, wenn ich etwas ändere?
+
+## 2. Abgestimmte Entscheidungen (prägen die Architektur)
+
+| Frage             | Entscheidung                     | Konsequenz                                                               |
+|-------------------|----------------------------------|--------------------------------------------------------------------------|
+| Primärnutzer/Ziel | Migration Natural→Java           | Leitmotiv „Migrations-Dossier" pro Modul (M3/M4)                         |
+| Projektgröße      | Groß (`upms` ~1000–6000+ Module) | **Query-getrieben**, WebGL-Viz, serverseitiger Subgraph                  |
+| API-Vertrag       | **OpenAPI zuerst**               | SmallRye-OpenAPI am Server + generierter TS-Client (kein Typ-Drift)      |
+| Lazy-Ingest       | **Automatisch + Statusanzeige**  | Navigation triggert Deep-Ingest transparent; Status/Ladezustände überall |
+
+## 3. Architektur-Grundsätze
+
+- **Query-getrieben, nie „ganzen Graphen laden".** Bei 6000+ Modulen wird immer nur
+  eine begrenzte Nachbarschaft um den aktuellen Knoten geladen.
+- **WebGL-Graph-Rendering.** `Sigma.js` (auf `graphology`) für Tausende Knoten
+  flüssig. `React Flow` bleibt für *kuratierte* Kleindiagramme (ein Datenfluss-Pfad,
+  eine direkte Nachbarschaft), ist aber für den großen Graphen ungeeignet (DOM-basiert).
+- **OpenAPI-first.** Der Server bekommt eine OpenAPI-Spec; der TS-Client wird generiert
+  (`openapi-typescript` + `openapi-fetch`). Ein stabiler Vertrag statt handgepflegter Typen.
+- **Auto-Ingest mit Statusanzeige.** Klick auf ein noch flaches Modul triggert den
+  Deep-Ingest transparent; die UI zeigt `INGESTING` und lädt nach. Refresh explizit verfügbar.
+- **Stabile Identität statt Node-ID.** Node-`id`s werden bei Re-Ingest neu vergeben —
+  die UI keyed auf `name + sourceFile` und refetcht nach einem Ingest.
+
+## 4. Technischer Stack (Vorschlag)
+
+- **React + TypeScript + Vite**, **React Router** (URL-getriebener State → teilbare
+  Deep-Links auf einen Knoten/eine Ansicht).
+- **Datenschicht:** TanStack Query über den generierten OpenAPI-Client.
+- **Graph-Viz:** Sigma.js/graphology (+ `graphology-layout-forceatlas2`/dagre-artige
+  Layouts); React Flow für Kleindiagramme.
+- **Code-Viewer:** CodeMirror 6 mit **eigenem Natural-Sprachmodus** (kein OSS-Highlighting
+  vorhanden) + Java eingebaut.
+- **Styling:** Tailwind oder CSS-Module (Detail offen).
+
+## 5. Backend-Voraussetzungen (die die UI erzwingt)
+
+Diese Punkte sind Bring-Schulden am Server, bevor die UI tragfähig ist:
+
+1. **OpenAPI-Spec** (`quarkus-smallrye-openapi`) + saubere Annotation der Response-DTOs.
+2. **Ego-Graph-Endpoint** — `GET /modules/{name}/graph?depth=&direction=&limit=`, der
+   einen **begrenzten Subgraphen** (Nodes + Edges) um einen Knoten liefert. Heute gibt
+   es nur `call-tree`/`callers`/`callees` getrennt; die Viz braucht einen echten,
+   gebündelten Nachbarschafts-Endpoint. *(Neuer Roadmap-Kandidat.)*
+3. **Ingest-Status im Response** — die UI muss `ingestStatus`/`ingestDepth` je Modul
+   kennen (großteils vorhanden über `moduleIngestState`/`inspect_node`).
+4. **CORS/Serving** — SPA-Auslieferung + CORS-Konfiguration am Quarkus-Server.
+5. Später: **Auth/Multi-User** (heute keine), **Cross-Project**-Sichten.
+
+**Verfügbar & wiederverwendbar (heute):** `list_modules`, `module_context`,
+`callers`/`callees`, `call-tree`, `db-accesses`/`sql-statements`, `data-structures`/
+`fields`/`columns`, `dispatch-table`, `search/identifier|value|annotation`,
+`variables/{n}/reads|writes|flow-forward|flow-backward|field-flow`, `nodes/{id}`,
+`modules|nodes/{…}/source`, `refresh`.
+
+## 6. Kern-Ansichten (was der Mensch tun können soll)
+
+1. **Projekt- & Modul-Explorer** — Liste/Baum, Filter (Sprache, `moduleKind`,
+   `sourceFile`), globale Suche.
+2. **Modul-Detail** — `module_context` gebündelt: Funktionen, Caller/Callee, DB-Zugriffe,
+   Datenstrukturen, Ingest-Status, Refresh.
+3. **Quelltext-Viewer mit Graph-Overlay** — Syntax-Highlighting; klickbare Identifier →
+   Definition/Referenzen; `CALLNAT`/`PERFORM`-Ziele als Links; dynamische/unaufgelöste
+   Referenzen markiert.
+4. **Interaktiver Call-Graph (Sigma/WebGL)** — Ego-Graph, Expand/Collapse, Dispatch- &
+   `unresolved`-Styling, Auto-Layout.
+5. **Datenfluss-Visualisierung** — `flow-forward/backward`/`field-flow` als Pfad/Sankey.
+6. **DB-Zugriffs-Karte** — Matrix/Graph Modul ↔ Tabelle (READ/WRITE), Dispatch-Tabellen, SQL.
+7. **Impact-Analyse** — „Feld/Tabelle ändern → betroffene Module".
+8. **Migrations-Dossier** — pro Modul alle obigen Facetten gebündelt als „Portier-Steckbrief".
+
+## 7. Milestones
+
+- **M0 · Fundament + API-Vertrag** — OpenAPI am Server + generierter TS-Client;
+  **Ego-Graph-Endpoint**; CORS/SPA-Serving; React/Vite-Grundgerüst; Projekt-/Modul-Liste
+    + Suche; Ingest-Status-Badges + Refresh. → *Browsen & Lesen; kritischer Pfad.*
+- **M1 · Navigation** — Quelltext-Viewer (CodeMirror 6 + Natural-Modus), klickbare
+  Identifier (Def/Refs), Caller/Callee-Panels, lazy Call-Tree, Deep-Links.
+- **M2 · Call-Graph-Visualisierung** — Ego-Graph interaktiv (Sigma), Expand/Collapse,
+  Dispatch/Unresolved-Styling, Layout.
+- **M3 · Migrations-Dossier** — Datenstrukturen/Felder, DB-Zugriffs-Matrix,
+  Dispatch-Tabellen, SQL — pro Modul gebündelt.
+- **M4 · Datenfluss & Impact** — Flow-Visualisierung, Impact-Analyse „was bricht?".
+- **M5 · Verständnis-Booster** — Quelle + geparste Struktur nebeneinander, Notizen/
+  gespeicherte Views, Diff nach Refresh, optional LLM-Zusammenfassungen aus `module_context`.
+- **M6 · Skalierung & Politur** — Virtualisierung/Große-Graph-Performance, Multi-Projekt,
+  Auth, Theming, Export (SVG/PNG/Report).
+
+**Kritischer Pfad:** M0 (OpenAPI + Ego-Graph-Endpoint) trägt alles Weitere.
+
+## 8. Risiken & offene Punkte
+
+- **Latenz durch Auto-Ingest** bei großen Projekten: Erkunden triggert Deep-Ingests; der
+  Concurrency-Cap (Default 2) kann unter Mehr-Nutzer-Last transient flachere Antworten
+  liefern. Für 1 Analyst ok; sonst Cap konfigurierbar/erhöhen.
+- **`STALE_SOURCE` & Warm-Nebenwirkung:** eine wärmende Abfrage (z. B. `search_identifier`)
+  re-ingestiert und re-hasht ein Modul und **löscht damit dessen Staleness** — die UI muss
+  Ingest-Status als „wahr im Moment der Abfrage" behandeln.
+- **Node-ID-Instabilität** nach Re-Ingest (Keying auf `name+sourceFile`).
+- **Natural-Highlighting** existiert nicht fertig — eigener CodeMirror-Modus nötig.
+- **Auth/Multi-User** und **Deploy-Modell** (Standalone-SPA vs. eingebettet) noch offen.
+
+## 9. Nicht in diesem Vorhaben
+
+- Änderungen an der Parser-/Ingest-Semantik (die UI ist ein Konsument).
+- Schreibender Zugriff auf den Code (read-only Verständnis-Tool; Notizen sind UI-seitig).