58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
---
|
|
id: graph/flowgraph-class
|
|
name: Implement FlowGraph class skeleton wrapping graphology DirectedGraph
|
|
status: completed
|
|
depends_on:
|
|
- schema/enums
|
|
- schema/node-attrs
|
|
- schema/edge-attrs
|
|
- schema/graph-schemas
|
|
- error/hierarchy
|
|
- setup/project-init
|
|
scope: moderate
|
|
risk: medium
|
|
impact: phase
|
|
level: implementation
|
|
---
|
|
|
|
## Description
|
|
|
|
Create the `FlowGraph` class that wraps a graphology `DirectedGraph` and enforces DAG invariants. This is the core data class. At this stage, implement the constructor, generic type parameters, the `_graph` instance, the `graph` getter, `FlowGraphOptions`, and the `_edgeKey()` helper. Construction factory methods come in dependent tasks.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] `src/graph/construction.ts` exports `FlowGraph` class (or `src/graph/index.ts` if preferred, matching source structure)
|
|
- [ ] Class has type parameters: `NodeAttrs extends TSchema`, `EdgeAttrs extends TSchema`
|
|
- [ ] Constructor creates internal `graphology.DirectedGraph` with options `{ type: "directed", multi: false, allowSelfLoops: false }`
|
|
- [ ] `FlowGraphOptions` interface: `type?: "directed"`, `multi?: false`, `allowSelfLoops?: false`
|
|
- [ ] `get graph(): DirectedGraph` returns the underlying graphology instance
|
|
- [ ] `_edgeKey(source, target): string` produces deterministic keys `${source}->${target}`
|
|
- [ ] `addNode(key, attrs)` — adds node, throws `DuplicateNodeError` on duplicate
|
|
- [ ] `removeNode(key)` — removes node and edges, throws `NodeNotFoundError` if missing
|
|
- [ ] `updateNode(key, attrs)` — partial merge of attributes, throws `NodeNotFoundError` if missing
|
|
- [ ] `hasNode(key): boolean`
|
|
- [ ] `getNodeAttributes(key): NodeAttrs` — throws `NodeNotFoundError` if missing
|
|
- [ ] `addEdge(source, target, attrs?)` — throws `NodeNotFoundError` for missing endpoints, `CycleError` if edge creates cycle, `DuplicateEdgeError` if edge exists
|
|
- [ ] `removeEdge(source, target)` — no-op if edge doesn't exist
|
|
- [ ] `hasEdge(source, target): boolean`
|
|
- [ ] `getEdgeAttributes(source, target): EdgeAttrs` — throws if edge doesn't exist
|
|
- [ ] `nodes(): string[]`, `edges(): string[]`, `order: number`, `size: number`
|
|
- [ ] `forEachNode(callback)`, `forEachEdge(callback)`
|
|
- [ ] `predecessors(nodeId)`, `successors(nodeId)` delegating to `graph.inNeighbors`/`graph.outNeighbors`
|
|
- [ ] Static construction methods (`fromSpecs`, `fromCallEvents`, `fromJSON`) are stubs (throw "not implemented")
|
|
- [ ] Re-exported from `src/graph/index.ts` and `src/index.ts`
|
|
- [ ] Unit tests: constructor, node operations, edge operations, cycle detection on addEdge
|
|
|
|
## References
|
|
|
|
- docs/architecture/flowgraph-api.md — FlowGraph class full API surface, delegation model
|
|
- docs/architecture/schema.md — edge key convention
|
|
- docs/architecture/error-handling.md — throwing contract for mutations
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |