David Snelling
8c2b57a488
Introduces the brain.graph namespace and its first op, subgraph() — bounded
multi-hop neighborhood extraction returning a hydrated GraphView (nodes with hop
depth + type/subtype, edges as Relations, a truncated flag). The one-call answer
to 'show me everything around this node, N hops out' the graph-viz path needs.
- brain.graph.subgraph(seeds, { depth, direction, type, subtype, includeInternal,
includeSystem, maxNodes, maxEdges, hydrateNodes }). seeds: id or id[].
- Feature-detect routing: when a GraphAccelerationProvider is registered
(isGraphAccelerationProvider on the 'graphAcceleration' provider) it routes to
native traverse() and hydrates the columnar Subgraph (node ints↔ids paired with
depth position-preserving, edge verb ints → Relations); otherwise a pure-TS BFS
fallback expands each frontier through the O(degree) related() adjacency.
- Both paths produce the identical GraphView, so CI exercises the shape via the
fallback; the native path is cross-layer-tested against cor's provider.
- New public types: GraphView, GraphNode, SubgraphOptions, GraphApi (the surface
grows: export/rank/path/communities follow). isGraphAccelerationProvider guard
added to plugin.ts.
Test: graph-subgraph.test.ts — depth tracking, direction, type filter, default-
hides-internal, node hydration on/off, maxNodes truncation, multi-seed.
101 lines
4.7 KiB
TypeScript
101 lines
4.7 KiB
TypeScript
/**
|
|
* @module tests/unit/brainy/graph-subgraph
|
|
* @description Graph engine #25: `brain.graph.subgraph()` — bounded multi-hop
|
|
* neighborhood extraction. These exercise the pure-TS fallback (no native
|
|
* GraphAccelerationProvider is registered in CI); the native path returns the
|
|
* same `GraphView` shape, cross-layer-tested against the provider.
|
|
*
|
|
* Graph under test (RelatedTo unless noted):
|
|
* e → a → b → c , a →(ReportsTo) d , a →(internal) f
|
|
*/
|
|
|
|
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
|
|
import { Brainy } from '../../../src/index.js'
|
|
import { NounType, VerbType } from '../../../src/types/graphTypes.js'
|
|
import { createTestConfig } from '../../helpers/test-factory.js'
|
|
|
|
describe('brain.graph.subgraph() (graph engine #25)', () => {
|
|
let brain: Brainy
|
|
let a: string, b: string, c: string, d: string, e: string, f: string
|
|
|
|
beforeEach(async () => {
|
|
brain = new Brainy(createTestConfig())
|
|
await brain.init()
|
|
a = await brain.add({ type: NounType.Person, subtype: 'employee', data: 'A' })
|
|
b = await brain.add({ type: NounType.Person, subtype: 'employee', data: 'B' })
|
|
c = await brain.add({ type: NounType.Person, subtype: 'employee', data: 'C' })
|
|
d = await brain.add({ type: NounType.Project, subtype: 'milestone', data: 'D' })
|
|
e = await brain.add({ type: NounType.Person, subtype: 'employee', data: 'E' })
|
|
f = await brain.add({ type: NounType.Person, subtype: 'employee', data: 'F' })
|
|
await brain.relate({ from: a, to: b, type: VerbType.RelatedTo, subtype: 'colleague' })
|
|
await brain.relate({ from: b, to: c, type: VerbType.RelatedTo, subtype: 'colleague' })
|
|
await brain.relate({ from: a, to: d, type: VerbType.ReportsTo, subtype: 'direct' })
|
|
await brain.relate({ from: e, to: a, type: VerbType.RelatedTo, subtype: 'colleague' })
|
|
await brain.relate({ from: a, to: f, type: VerbType.RelatedTo, subtype: 'colleague', visibility: 'internal' })
|
|
})
|
|
|
|
afterEach(async () => {
|
|
await brain.close()
|
|
})
|
|
|
|
it('depth-1 returns the seed + immediate neighbors (both directions) with depths', async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 1 })
|
|
const byId = new Map(view.nodes.map((n) => [n.id, n]))
|
|
// a is the seed (depth 0); b, d (out) and e (in) are 1 hop. f is internal → hidden.
|
|
expect(new Set(byId.keys())).toEqual(new Set([a, b, d, e]))
|
|
expect(byId.get(a)?.depth).toBe(0)
|
|
expect(byId.get(b)?.depth).toBe(1)
|
|
expect(byId.get(e)?.depth).toBe(1)
|
|
// Edges among them.
|
|
const pairs = view.edges.map((r) => `${r.from}->${r.to}`).sort()
|
|
expect(pairs).toEqual([`${a}->${b}`, `${a}->${d}`, `${e}->${a}`].sort())
|
|
})
|
|
|
|
it('depth-2 expands one more hop (c via b), tracking depth', async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 2 })
|
|
const byId = new Map(view.nodes.map((n) => [n.id, n]))
|
|
expect(byId.has(c)).toBe(true)
|
|
expect(byId.get(c)?.depth).toBe(2)
|
|
expect(view.edges.some((r) => r.from === b && r.to === c)).toBe(true)
|
|
})
|
|
|
|
it("direction:'out' follows only outgoing edges", async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 1, direction: 'out' })
|
|
const ids = new Set(view.nodes.map((n) => n.id))
|
|
expect(ids).toEqual(new Set([a, b, d])) // e (e→a, incoming) excluded
|
|
})
|
|
|
|
it('composes with a verb-type filter', async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 1, type: VerbType.ReportsTo })
|
|
expect(view.edges.map((r) => `${r.from}->${r.to}`)).toEqual([`${a}->${d}`])
|
|
expect(new Set(view.nodes.map((n) => n.id))).toEqual(new Set([a, d]))
|
|
})
|
|
|
|
it('includeInternal surfaces the hidden edge/node', async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 1, includeInternal: true })
|
|
expect(view.nodes.some((n) => n.id === f)).toBe(true)
|
|
expect(view.edges.some((r) => r.to === f)).toBe(true)
|
|
})
|
|
|
|
it('hydrates node type/subtype by default; skips it with hydrateNodes:false', async () => {
|
|
const hydrated = await brain.graph.subgraph(a, { depth: 1 })
|
|
const dNode = hydrated.nodes.find((n) => n.id === d)
|
|
expect(dNode?.type).toBe(NounType.Project)
|
|
expect(dNode?.subtype).toBe('milestone')
|
|
|
|
const bare = await brain.graph.subgraph(a, { depth: 1, hydrateNodes: false })
|
|
expect(bare.nodes.every((n) => n.type === undefined)).toBe(true)
|
|
})
|
|
|
|
it('caps the result and flags truncated when maxNodes is hit', async () => {
|
|
const view = await brain.graph.subgraph(a, { depth: 2, maxNodes: 2 })
|
|
expect(view.truncated).toBe(true)
|
|
expect(view.nodes.length).toBeLessThanOrEqual(2)
|
|
})
|
|
|
|
it('accepts multiple seeds', async () => {
|
|
const view = await brain.graph.subgraph([a, c], { depth: 0 })
|
|
// depth 0 = just the seeds, no expansion.
|
|
expect(new Set(view.nodes.map((n) => n.id))).toEqual(new Set([a, c]))
|
|
})
|
|
})
|