Release Notes: v0.1.0¶

Release Date: 2026-04-11

Highlights¶

Git-friendly graph database: One-file-per-entity storage with deterministic JSON for minimal diffs
Edge confidence system: Support for EXTRACTED (AST), INFERRED (LLM), and AMBIGUOUS relationships

Core Types¶

Node¶

The graph.Node type represents entities in the graph:

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

node := &graph.Node{
    ID:    "func_main.go.HandleRequest",
    Type:  graph.NodeTypeFunction,
    Label: "HandleRequest",
    Attrs: map[string]string{
        "package":     "main",
        "source_file": "main.go",
        "line":        "42",
    },
}

Node Type Constants:

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

Edge¶

The graph.Edge type represents relationships between nodes:

edge := &graph.Edge{
    From:       "func_main",
    To:         "func_helper",
    Type:       graph.EdgeTypeCalls,
    Confidence: graph.ConfidenceExtracted,
}

For LLM-inferred relationships:

edge := &graph.Edge{
    From:            "pkg_auth",
    To:              "pkg_crypto",
    Type:            graph.EdgeTypeDependsOn,
    Confidence:      graph.ConfidenceInferred,
    ConfidenceScore: 0.85,
    Attrs: map[string]string{
        "reason": "Auth package likely uses crypto for password hashing",
    },
}

Edge Type Constants:

Constant	Value
`EdgeTypeCalls`	`calls`
`EdgeTypeImports`	`imports`
`EdgeTypeImplements`	`implements`
`EdgeTypeExtends`	`extends`
`EdgeTypeUses`	`uses`
`EdgeTypeContains`	`contains`
`EdgeTypeDependsOn`	`depends_on`
`EdgeTypeReferences`	`references`

Confidence Levels¶

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

Filesystem Store¶

The store.FSStore provides persistence with one JSON file per entity:

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

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

// Write nodes and edges
fs.WriteNode(node)
fs.WriteEdge(edge)

// Load entire graph
g, err := fs.LoadGraph()

Storage Layout:

.graphfs/
├── nodes/
│   ├── func_main.json
│   └── pkg_auth.json
└── edges/
    ├── func_main__calls__func_helper.json
    └── pkg_auth__imports__pkg_crypto.json

Canonical JSON¶

The format package ensures deterministic JSON output:

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

data, err := format.MarshalCanonical(node)
// Output has sorted keys, 2-space indent, no trailing newline

This produces clean git diffs when graph structure changes.

Schema Validation¶

The schema package validates graph data:

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

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

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

// Validate entire graph with referential integrity
errs := validator.ValidateGraph(g)

Installation¶

go get github.com/plexusone/graphfs@v0.1.0

What's Next¶

See TASKS.md for the development roadmap:

Phase 2: Custom schema definitions, duplicate/cycle detection
Phase 3: Semantic diff, graph traversal queries, path finding
Phase 4: Git integration (pre-commit hooks, PR annotations)
Phase 5: Graph merging, incremental updates, export formats