graphfs

README

GraphFS

Git-friendly filesystem graph database with one-file-per-entity storage for minimal diffs.

Features

• 📄 One file per entity - Nodes stored as nodes/{id}.json, edges as edges/{from}__{type}__{to}.json
• 🔒 Deterministic JSON - Sorted keys and consistent formatting for clean git diffs
• 🎯 Confidence levels - Support for EXTRACTED (AST), INFERRED (LLM), and AMBIGUOUS relationships
• 🔌 Pluggable storage - Store interface for custom backends
• ✅ Schema validation - Validate nodes, edges, and referential integrity
• 🔍 Graph traversal - BFS, DFS, and path finding algorithms
• 📊 Graph analysis - Hub detection, community detection (Louvain), graph diff

Installation

go get github.com/plexusone/graphfs

Usage

Creating a Graph

import (
    "github.com/plexusone/graphfs/pkg/graph"
    "github.com/plexusone/graphfs/pkg/store"
)

// Create a filesystem store
fs, err := store.NewFSStore(".graphfs")
if err != nil {
    panic(err)
}

// Create nodes
node := &graph.Node{
    ID:    "func_main",
    Type:  graph.NodeTypeFunction,
    Label: "main",
    Attrs: map[string]string{"package": "main"},
}
fs.WriteNode(node)

// Create edges
edge := &graph.Edge{
    From:       "func_main",
    To:         "func_helper",
    Type:       graph.EdgeTypeCalls,
    Confidence: graph.ConfidenceExtracted,
}
fs.WriteEdge(edge)

Loading a Graph

g, err := fs.LoadGraph()
if err != nil {
    panic(err)
}

fmt.Printf("Nodes: %d, Edges: %d\n", g.NodeCount(), g.EdgeCount())

Validation

import "github.com/plexusone/graphfs/pkg/schema"

validator := schema.NewValidator()
validator.AllowedNodeTypes = []string{"function", "file", "package"}

if err := validator.ValidateNode(node); err != nil {
    fmt.Printf("Invalid node: %v\n", err)
}

// Validate entire graph
errs := validator.ValidateGraph(g)
for _, err := range errs {
    fmt.Printf("Error: %v\n", err)
}

Graph Traversal

import "github.com/plexusone/graphfs/pkg/query"

// Create a traverser from a graph
traverser := query.NewTraverser(g)

// BFS traversal from a node
result := traverser.BFS("func_main", query.Outgoing, 3, nil)
fmt.Printf("Visited %d nodes\n", len(result.Visited))

// Find path between nodes
path := traverser.FindPath("func_main", "func_helper", nil)
fmt.Printf("Path: %v\n", path.Visited)

// DFS with edge type filter
result = traverser.DFS("func_main", query.Both, 5, []string{"calls"})

Graph Analysis

import "github.com/plexusone/graphfs/pkg/analyze"

// Find hub nodes (most connected)
hubs := analyze.FindHubs(nodes, edges, 10, []string{"package", "file"})
for _, hub := range hubs {
    fmt.Printf("%s: %d connections\n", hub.Label, hub.Total)
}

// Detect communities using Louvain algorithm
result := analyze.DetectCommunities(nodes, edges)
fmt.Printf("Found %d communities, modularity: %.3f\n",
    len(result.Communities), result.Modularity)

// Compare two graph snapshots
diff := analyze.DiffGraphs(oldNodes, newNodes, oldEdges, newEdges)
fmt.Printf("Changes: %s\n", diff.Summary)

Storage Format

Nodes

.graphfs/
  nodes/
    func_main.json
    func_helper.json
    pkg_mypackage.json

Each node file contains:

{
  "attrs": {
    "package": "main"
  },
  "id": "func_main",
  "label": "main",
  "type": "function"
}

Edges

.graphfs/
  edges/
    func_main__calls__func_helper.json

Each edge file contains:

{
  "confidence": "EXTRACTED",
  "from": "func_main",
  "to": "func_helper",
  "type": "calls"
}

Node Types

Constant	Value
NodeTypeFunction	function
NodeTypeMethod	method
NodeTypeClass	class
NodeTypeStruct	struct
NodeTypeFile	file
NodeTypePackage	package
NodeTypeModule	module
NodeTypeVariable	variable
NodeTypeConstant	constant
NodeTypeInterface	interface

Edge Types

Constant	Value
EdgeTypeCalls	calls
EdgeTypeImports	imports
EdgeTypeImplements	implements
EdgeTypeExtends	extends
EdgeTypeUses	uses
EdgeTypeContains	contains
EdgeTypeDependsOn	depends_on
EdgeTypeReferences	references
EdgeTypeInjects	injects
EdgeTypeHandlesRoute	handles_route
EdgeTypeHasMany	has_many
EdgeTypeBelongsTo	belongs_to
EdgeTypeAnnotatedWith	annotated_with
EdgeTypeMethodOf	method_of

Confidence Levels

Level	Description
EXTRACTED	Directly extracted from source (AST, imports)
INFERRED	Inferred by LLM or heuristic with confidence score
AMBIGUOUS	Uncertain relationship requiring human review

License

MIT