feat(graph): filter model — local-graph BFS, subgraph, GraphFilter (T-323)

Adds the pure filtering primitives the graph pane composes: VaultGraph
nodesWithin (depth-bounded BFS over undirected edges = the local graph
around a note) and subgraph (retain a node set + the edges between them),
plus GraphFilter, which combines depth-from-active with tag include/exclude
over a caller-supplied tag map. Flutter-free; runs under dart test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

test/src/graph/graph_filter_test.dart

@@ -0,0 +1,56 @@
+import 'package:clide/src/graph/graph_filter.dart';
+import 'package:clide/src/graph/vault_graph.dart';
+import 'package:test/test.dart';
+
+void main() {
+  final g = VaultGraph.fromOutlinks({
+    'a.md': const ['b.md'],
+    'b.md': const ['c.md'],
+    'c.md': const [],
+    'x.md': const [],
+  }); // a—b—c chain, x isolated
+  final tags = {
+    'a.md': {'project'},
+    'b.md': {'note', 'project'},
+    'c.md': {'note'},
+  };
+
+  test('an empty filter returns the full graph unchanged', () {
+    const f = GraphFilter();
+    expect(identical(f.apply(g, tagsByPath: tags), g), isTrue); // no-op short-circuit
+  });
+
+  test('includeTags keeps only notes carrying a matching tag', () {
+    const f = GraphFilter(includeTags: {'project'});
+    expect(f.apply(g, tagsByPath: tags).nodes.map((n) => n.id), unorderedEquals(['a.md', 'b.md']));
+  });
+
+  test('excludeTags drops notes carrying a matching tag', () {
+    const f = GraphFilter(excludeTags: {'note'});
+    // b and c carry 'note' → dropped; a (project) and x (untagged) survive.
+    expect(f.apply(g, tagsByPath: tags).nodes.map((n) => n.id), unorderedEquals(['a.md', 'x.md']));
+  });
+
+  test('depth keeps the local graph around the active note', () {
+    const f = GraphFilter(depth: 1);
+    expect(f.apply(g, tagsByPath: tags, activePath: 'a.md').nodes.map((n) => n.id), unorderedEquals(['a.md', 'b.md']));
+  });
+
+  test('a depth filter with no active note yields nothing', () {
+    const f = GraphFilter(depth: 2);
+    expect(f.apply(g, tagsByPath: tags, activePath: null).isEmpty, isTrue);
+  });
+
+  test('tag and depth compose by intersection', () {
+    // include project → {a,b}; depth 2 from c → {c,b,a}; intersection → {a,b}.
+    const f = GraphFilter(includeTags: {'project'}, depth: 2);
+    expect(f.apply(g, tagsByPath: tags, activePath: 'c.md').nodes.map((n) => n.id), unorderedEquals(['a.md', 'b.md']));
+  });
+
+  test('copyWith sets and clears the depth, keeping other fields', () {
+    const f = GraphFilter(depth: 2, includeTags: {'project'});
+    expect(f.copyWith(depth: 3).depth, 3);
+    expect(f.copyWith(clearDepth: true).depth, isNull);
+    expect(f.copyWith(clearDepth: true).includeTags, {'project'});
+  });
+}

test/src/graph/vault_graph_test.dart

@@ -48,4 +48,39 @@ void main() {
     expect(g.neighborhood('b.md'), {'b.md', 'a.md', 'c.md'});
     expect(g.neighborhood('x.md'), {'x.md'}); // isolated node
   });
+
+  group('nodesWithin', () {
+    final g = VaultGraph.fromOutlinks({
+      'a.md': const ['b.md'],
+      'b.md': const ['c.md'],
+      'c.md': const [],
+      'x.md': const [],
+    }); // a—b—c chain, x isolated
+
+    test('depth 0 is the root alone', () {
+      expect(g.nodesWithin('a.md', 0), {'a.md'});
+    });
+
+    test('depth grows the frontier over undirected edges, both directions', () {
+      expect(g.nodesWithin('a.md', 1), {'a.md', 'b.md'});
+      expect(g.nodesWithin('a.md', 2), {'a.md', 'b.md', 'c.md'});
+      expect(g.nodesWithin('c.md', 2), {'c.md', 'b.md', 'a.md'}); // walks backwards too
+    });
+
+    test('an isolated node is just itself; an unknown root is empty', () {
+      expect(g.nodesWithin('x.md', 3), {'x.md'});
+      expect(g.nodesWithin('ghost.md', 3), isEmpty);
+    });
+  });
+
+  test('subgraph keeps only the kept nodes and edges between them', () {
+    final g = VaultGraph.fromOutlinks({
+      'a.md': const ['b.md', 'c.md'],
+      'b.md': const ['c.md'],
+      'c.md': const [],
+    });
+    final sub = g.subgraph({'a.md', 'b.md'});
+    expect(sub.nodes.map((n) => n.id), unorderedEquals(['a.md', 'b.md']));
+    expect(sub.edgePairs, [('a.md', 'b.md')]); // a—c and b—c drop with c gone
+  });
 }