From 3b67725b7eba23b5c787fcf0badcd7ec2b6d942e Mon Sep 17 00:00:00 2001 From: Jeroen Schweitzer Date: Thu, 2 Jul 2026 09:30:35 +0200 Subject: [PATCH] =?UTF-8?q?feat(graph):=20pql-backed=20GraphController=20?= =?UTF-8?q?=E2=80=94=20files=20+=20outlinks=20to=20VaultGraph=20(T-323)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lists every markdown note (nodes) and fetches each one's outlinks (edges) via the pql.files / pql.outlinks IPC commands, assembling the file->outlinks map that VaultGraph consumes. Coalesces file-change bursts into one debounced reload. 1+N calls, since pql exposes no bulk-outlinks query; acceptable for a spinner-backed, explicitly-opened view. Co-Authored-By: Claude Opus 4.8 (1M context) --- .pql/changelog/ticket_history/2026-07.sql | 7 + .pql/changelog/tickets/2026-07.sql | 5 + lib/builtin/graph/src/graph_controller.dart | 100 +++++++++++++ test/builtin/graph/graph_controller_test.dart | 140 ++++++++++++++++++ 4 files changed, 252 insertions(+) create mode 100644 .pql/changelog/ticket_history/2026-07.sql create mode 100644 .pql/changelog/tickets/2026-07.sql create mode 100644 lib/builtin/graph/src/graph_controller.dart create mode 100644 test/builtin/graph/graph_controller_test.dart diff --git a/.pql/changelog/ticket_history/2026-07.sql b/.pql/changelog/ticket_history/2026-07.sql new file mode 100644 index 00000000..2c2be85c --- /dev/null +++ b/.pql/changelog/ticket_history/2026-07.sql @@ -0,0 +1,7 @@ +INSERT INTO ticket_history (ticket_record_id, field, old_value, new_value, changed_by, changed_at, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06FB2G2KHKT5CJYR0TK1WQGMD0', 'description', 'Tier-5 graph VIEW, absorbed from the former T-7 into the unified canvas epic (T-317). Force-directed layout of the vault (or a filtered subset): nodes are notes, edges are wikilinks. Hover highlights the connected subgraph; click opens the note in the editor. Filter pane: tag include/exclude, file glob, depth-from-active. pql provides the link data (pql backlinks / pql outlinks); rendering is owned in-app (CustomPaint, own-the-rendering-stack). Lives in its own slot per D-47 (context panel), uses MultitabPane (T-83). DISTINCT from the in-card graph TEMPLATE (T-321): T-321 renders a graph passed into the conversation drawing card; this is the full interactive graph pane over the whole vault. Relates to the core renderer (T-318) but has its own force-directed layout. + +PROGRESS (2026-06-29): force-directed layout SOLVER built + tested (lib/src/graph/force_layout.dart, 6 dart-test cases, commit bcef3a6f) — deterministic Fruchterman-Reingold, Flutter-free. REMAINING (the bulk, multi-session): graph data model from pql backlinks/outlinks over the vault; CustomPaint rendering (nodes+edges); pan/zoom; hover-highlight-subgraph; click-opens-note; filter pane (tag/glob/depth); MultitabPane + context-panel slot (D-47) wiring; widget/golden tests. This is a full interactive Tier-5 pane, a fresh-session undertaking — only its solver core is done.', 'Tier-5 graph VIEW, absorbed from the former T-7 into the unified canvas epic (T-317). Force-directed layout of the vault (or a filtered subset): nodes are notes, edges are wikilinks. Hover highlights the connected subgraph; click opens the note in the editor. Filter pane: tag include/exclude, file glob, depth-from-active. pql provides the link data (pql backlinks / pql outlinks); rendering is owned in-app (CustomPaint, own-the-rendering-stack). Lives in its own slot per D-47 (context panel), uses MultitabPane (T-83). DISTINCT from the in-card graph TEMPLATE (T-321): T-321 renders a graph passed into the conversation drawing card; this is the full interactive graph pane over the whole vault. Relates to the core renderer (T-318) but has its own force-directed layout. + +PROGRESS (2026-06-29): force-directed layout SOLVER built + tested (lib/src/graph/force_layout.dart, 6 dart-test cases, commit bcef3a6f) — deterministic Fruchterman-Reingold, Flutter-free. REMAINING (the bulk, multi-session): graph data model from pql backlinks/outlinks over the vault; CustomPaint rendering (nodes+edges); pan/zoom; hover-highlight-subgraph; click-opens-note; filter pane (tag/glob/depth); MultitabPane + context-panel slot (D-47) wiring; widget/golden tests. This is a full interactive Tier-5 pane, a fresh-session undertaking — only its solver core is done. + +PROGRESS (2026-07-02): the graph rendering + interaction foundation is BUILT + tested (4 slices, all committed). (1) force-directed solver — force_layout.dart (bcef3a6f). (2) link-graph model — vault_graph.dart: VaultGraph.fromOutlinks, neighborhood, edgePairs (084bf842). (3) CustomPaint renderer — graph_painter.dart: edges/nodes/labels, hover-dim, fit transform (6bea1723). (4) interactive GraphView — graph_view.dart: hover-highlight + click-to-open, shared GraphViewport hit-testing (c529703b). The graph is a fully working WIDGET (renders + hover + click). REMAINING = the app-integration phase: pql link-data wiring (pql outlinks over the vault -> the file->outlinks map -> VaultGraph), the pane shell (async load + filter: tag/glob/depth + pan/zoom), and MultitabPane + context-panel slot (D-47) + GraphExtension registration.', NULL, '2026-07-02 06:35:03', '2026-07-02 06:35:03.555', '2026-07-02 06:35:03.555', NULL, '33a6fd1c81f2e1142d15ce5791ce3b24', 2) ON CONFLICT(hash) DO NOTHING; diff --git a/.pql/changelog/tickets/2026-07.sql b/.pql/changelog/tickets/2026-07.sql new file mode 100644 index 00000000..146b1d39 --- /dev/null +++ b/.pql/changelog/tickets/2026-07.sql @@ -0,0 +1,5 @@ +INSERT INTO tickets (record_id, type, parent_record_id, title, description, status, priority, assigned_to, team, decision_ref, created_at, updated_at, deleted_at, hash, canonical_version) VALUES ('06FB2G2KHKT5CJYR0TK1WQGMD0', 'story', '06FHAX7FV5KWGZQ31617R63W94', 'Tier-5 graph view (builtin.graph)', 'Tier-5 graph VIEW, absorbed from the former T-7 into the unified canvas epic (T-317). Force-directed layout of the vault (or a filtered subset): nodes are notes, edges are wikilinks. Hover highlights the connected subgraph; click opens the note in the editor. Filter pane: tag include/exclude, file glob, depth-from-active. pql provides the link data (pql backlinks / pql outlinks); rendering is owned in-app (CustomPaint, own-the-rendering-stack). Lives in its own slot per D-47 (context panel), uses MultitabPane (T-83). DISTINCT from the in-card graph TEMPLATE (T-321): T-321 renders a graph passed into the conversation drawing card; this is the full interactive graph pane over the whole vault. Relates to the core renderer (T-318) but has its own force-directed layout. + +PROGRESS (2026-06-29): force-directed layout SOLVER built + tested (lib/src/graph/force_layout.dart, 6 dart-test cases, commit bcef3a6f) — deterministic Fruchterman-Reingold, Flutter-free. REMAINING (the bulk, multi-session): graph data model from pql backlinks/outlinks over the vault; CustomPaint rendering (nodes+edges); pan/zoom; hover-highlight-subgraph; click-opens-note; filter pane (tag/glob/depth); MultitabPane + context-panel slot (D-47) wiring; widget/golden tests. This is a full interactive Tier-5 pane, a fresh-session undertaking — only its solver core is done. + +PROGRESS (2026-07-02): the graph rendering + interaction foundation is BUILT + tested (4 slices, all committed). (1) force-directed solver — force_layout.dart (bcef3a6f). (2) link-graph model — vault_graph.dart: VaultGraph.fromOutlinks, neighborhood, edgePairs (084bf842). (3) CustomPaint renderer — graph_painter.dart: edges/nodes/labels, hover-dim, fit transform (6bea1723). (4) interactive GraphView — graph_view.dart: hover-highlight + click-to-open, shared GraphViewport hit-testing (c529703b). The graph is a fully working WIDGET (renders + hover + click). REMAINING = the app-integration phase: pql link-data wiring (pql outlinks over the vault -> the file->outlinks map -> VaultGraph), the pane shell (async load + filter: tag/glob/depth + pan/zoom), and MultitabPane + context-panel slot (D-47) + GraphExtension registration.', 'in_progress', 'medium', NULL, NULL, NULL, '2026-06-10 11:17:23', '2026-07-02 06:35:03.555', NULL, 'a46ad64b03bc1b4126e9882ed7b81a3a', 2) ON CONFLICT(record_id) DO UPDATE SET type=excluded.type, parent_record_id=excluded.parent_record_id, title=excluded.title, description=excluded.description, status=excluded.status, priority=excluded.priority, assigned_to=excluded.assigned_to, team=excluded.team, decision_ref=excluded.decision_ref, updated_at=excluded.updated_at, deleted_at=excluded.deleted_at, hash=excluded.hash, canonical_version=excluded.canonical_version WHERE excluded.updated_at > tickets.updated_at OR (excluded.updated_at = tickets.updated_at AND excluded.hash > tickets.hash); diff --git a/lib/builtin/graph/src/graph_controller.dart b/lib/builtin/graph/src/graph_controller.dart new file mode 100644 index 00000000..415a206a --- /dev/null +++ b/lib/builtin/graph/src/graph_controller.dart @@ -0,0 +1,100 @@ +/// Loads the whole vault's link graph from pql (T-323): lists every markdown +/// file (nodes), fetches each file's outlinks (edges), and assembles a +/// [VaultGraph]. Exposes loading/error state and coalesces file-change bursts +/// into one refresh. +/// +/// pql has no bulk-outlinks query, so this is 1 `pql.files` + N `pql.outlinks` +/// calls — acceptable for an explicitly-opened, spinner-backed view. Batching +/// is a later optimisation, not a correctness concern. +library; + +import 'dart:async'; + +import 'package:clide/kernel/kernel.dart'; +import 'package:clide/src/graph/vault_graph.dart'; +import 'package:flutter/foundation.dart'; + +class GraphController extends ChangeNotifier { + GraphController({required this.ipc, required this.events, this.glob = '**/*.md', this.refreshDebounce = const Duration(milliseconds: 400)}) { + _eventSub = events.on().listen(_onEvent); + } + + final DaemonClient ipc; + final DaemonBus events; + + /// The file set the graph spans; the default is every markdown note. + final String glob; + + /// A save touches several `files.changed` events in a burst — coalesce them + /// into one full reload rather than rebuilding the graph per file. + final Duration refreshDebounce; + + StreamSubscription? _eventSub; + Timer? _debounce; + + VaultGraph _graph = const VaultGraph([], []); + VaultGraph get graph => _graph; + + bool _loading = false; + bool get loading => _loading; + + String? _error; + String? get error => _error; + + /// List every in-scope file, fetch each one's outlinks, and rebuild the + /// graph. A failed `pql.files` clears the graph and surfaces the error; a + /// failed per-file `pql.outlinks` just contributes no edges for that file. + Future load() async { + _loading = true; + _error = null; + notifyListeners(); + + final filesResp = await ipc.request('pql.files', args: {'glob': glob}); + if (!filesResp.ok) { + _graph = const VaultGraph([], []); + _error = filesResp.error?.message ?? 'pql.files failed'; + _loading = false; + notifyListeners(); + return; + } + + final paths = [ + for (final f in _castList(filesResp.data['files'])) + if (f['path'] is String) f['path'] as String, + ]; + + final outlinks = >{}; + for (final path in paths) { + final resp = await ipc.request('pql.outlinks', args: {'path': path}); + outlinks[path] = resp.ok + ? [ + for (final l in _castList(resp.data['links'])) + if (l['target'] is String) l['target'] as String, + ] + : const []; + } + + _graph = VaultGraph.fromOutlinks(outlinks); + _loading = false; + notifyListeners(); + } + + void _onEvent(DaemonEvent e) { + if (e.subsystem != 'files') return; + _debounce?.cancel(); + _debounce = Timer(refreshDebounce, () => unawaited(load())); + } + + static List> _castList(Object? raw) { + if (raw is! List) return const []; + return [for (final e in raw) (e as Map).cast()]; + } + + @override + void dispose() { + _debounce?.cancel(); + _eventSub?.cancel(); + _eventSub = null; + super.dispose(); + } +} diff --git a/test/builtin/graph/graph_controller_test.dart b/test/builtin/graph/graph_controller_test.dart new file mode 100644 index 00000000..72ee3bb8 --- /dev/null +++ b/test/builtin/graph/graph_controller_test.dart @@ -0,0 +1,140 @@ +import 'package:clide/builtin/graph/src/graph_controller.dart'; +import 'package:clide/clide.dart'; +import 'package:clide/kernel/kernel.dart'; +import 'package:flutter_test/flutter_test.dart'; + +import '../../helpers/fake_ipc.dart'; + +void main() { + group('GraphController.load', () { + late DaemonBus bus; + late FakeDaemonClient ipc; + + setUp(() { + bus = DaemonBus(); + ipc = FakeDaemonClient(log: Logger(), events: bus); + }); + tearDown(() => bus.dispose()); + + IpcResponse ok(Map data) => IpcResponse.ok(id: '1', data: data); + IpcResponse err(String msg) => IpcResponse.err( + id: '1', + error: IpcError(code: IpcExitCode.toolError, kind: IpcErrorKind.toolError, message: msg), + ); + + /// Stubs `pql.files` (from the map's keys) and `pql.outlinks` (per path). + void stubVault(Map> vault) { + ipc.stub( + 'pql.files', + (_) async => ok({ + 'files': [ + for (final p in vault.keys) {'path': p}, + ], + }), + ); + ipc.stub('pql.outlinks', (args) async { + final path = args['path'] as String?; + final links = vault[path] ?? const []; + return ok({ + 'links': [ + for (final t in links) {'target': t}, + ], + }); + }); + } + + test('assembles a graph from files + their outlinks', () async { + stubVault({ + 'a.md': ['b.md'], + 'b.md': [], + }); + final c = GraphController(ipc: ipc, events: bus); + var notified = 0; + c.addListener(() => notified++); + await c.load(); + + expect(c.graph.nodes.map((n) => n.id), containsAll(['a.md', 'b.md'])); + expect(c.graph.edgePairs, [('a.md', 'b.md')]); + expect(c.loading, isFalse); + expect(c.error, isNull); + expect(notified, greaterThan(0)); // loading toggle + final + }); + + test('a pql.files failure clears the graph and surfaces the error', () async { + ipc.stub('pql.files', (_) async => err('index locked')); + final c = GraphController(ipc: ipc, events: bus); + await c.load(); + expect(c.graph.isEmpty, isTrue); + expect(c.error, contains('index locked')); + expect(c.loading, isFalse); + }); + + test('a per-file outlinks failure drops that file\'s edges, keeps the node', () async { + ipc.stub( + 'pql.files', + (_) async => ok({ + 'files': [ + {'path': 'a.md'}, + {'path': 'b.md'}, + ], + }), + ); + ipc.stub('pql.outlinks', (args) async { + if (args['path'] == 'a.md') return err('boom'); + return ok({'links': const []}); + }); + final c = GraphController(ipc: ipc, events: bus); + await c.load(); + expect(c.graph.nodes.map((n) => n.id), containsAll(['a.md', 'b.md'])); + expect(c.graph.edgePairs, isEmpty); // a.md's edges were lost, no crash + expect(c.error, isNull); // a partial failure isn't a load failure + }); + + test('dangling + self links are dropped by the model', () async { + stubVault({ + 'a.md': ['a.md', 'ghost.md', 'b.md'], + 'b.md': [], + }); + final c = GraphController(ipc: ipc, events: bus); + await c.load(); + expect(c.graph.edgePairs, [('a.md', 'b.md')]); + }); + + test('a files event triggers a debounced reload; non-files events do not', () async { + var files = 0; + ipc.stub('pql.files', (_) async { + files++; + return ok({'files': const []}); + }); + ipc.stub('pql.outlinks', (_) async => ok({'links': const []})); + final c = GraphController(ipc: ipc, events: bus, refreshDebounce: Duration.zero); + expect(files, 0); + + bus.emit(DaemonEvent(subsystem: 'git', kind: 'git.status', data: const {}, ts: DateTime.now())); + await Future.delayed(const Duration(milliseconds: 5)); + expect(files, 0); // non-files event ignored + + bus.emit(DaemonEvent(subsystem: 'files', kind: 'files.changed', data: const {'path': 'x.md'}, ts: DateTime.now())); + await Future.delayed(const Duration(milliseconds: 5)); + expect(files, 1); // reload fired + c.dispose(); + }); + + test('a burst of files events coalesces into a single reload', () async { + var files = 0; + ipc.stub('pql.files', (_) async { + files++; + return ok({'files': const []}); + }); + ipc.stub('pql.outlinks', (_) async => ok({'links': const []})); + final c = GraphController(ipc: ipc, events: bus, refreshDebounce: const Duration(milliseconds: 20)); + + for (var i = 0; i < 5; i++) { + bus.emit(DaemonEvent(subsystem: 'files', kind: 'files.changed', data: {'path': '$i.md'}, ts: DateTime.now())); + } + await Future.delayed(const Duration(milliseconds: 40)); + expect(files, 1); // five events, one reload + c.dispose(); + }); + }); +}