store

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 3, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CanonicalSectionNames added in v0.3.2

func CanonicalSectionNames() []string

CanonicalSectionNames returns the ordered list of canonical ADR section names.

func MaxADRLength added in v0.3.2

func MaxADRLength() int

MaxADRLength returns the maximum allowed ADR length for use by tool handlers.

func Now

func Now() string

Now returns the current time in ISO 8601 format.

func ParseADRSections added in v0.3.2

func ParseADRSections(content string) map[string]string

ParseADRSections splits ADR content by canonical section headers. Only canonical headers (PURPOSE, STACK, ARCHITECTURE, PATTERNS, TRADEOFFS, PHILOSOPHY) are recognized as split boundaries. Other ## headers within content are treated as literal text within the current section.

func RenderADR added in v0.3.2

func RenderADR(sections map[string]string) string

RenderADR joins sections into markdown with canonical sections first (in order), followed by any non-canonical sections alphabetically.

func UnmarshalProps added in v0.1.0

func UnmarshalProps(data string) map[string]any

UnmarshalProps deserializes JSON properties. Exported for use by cypher executor.

func ValidateADRContent added in v0.3.2

func ValidateADRContent(content string) error

ValidateADRContent checks that content contains all 6 canonical sections. Returns an error listing any missing sections.

func ValidateADRSectionKeys added in v0.3.2

func ValidateADRSectionKeys(sections map[string]string) error

ValidateADRSectionKeys checks that all keys in the map are canonical section names. Returns an error listing any invalid keys.

Types

type ADRecord added in v0.3.2

type ADRecord struct {
	Project   string `json:"project"`
	Content   string `json:"content"`
	CreatedAt string `json:"created_at"`
	UpdatedAt string `json:"updated_at"`
}

ADRecord holds a stored Architecture Decision Record.

type ArchitectureInfo added in v0.3.2

type ArchitectureInfo struct {
	Languages   []LanguageCount    `json:"languages,omitempty"`
	Packages    []PackageSummary   `json:"packages,omitempty"`
	EntryPoints []EntryPointInfo   `json:"entry_points,omitempty"`
	Routes      []RouteInfo        `json:"routes,omitempty"`
	Hotspots    []HotspotFunction  `json:"hotspots,omitempty"`
	Boundaries  []CrossPkgBoundary `json:"boundaries,omitempty"`
	Services    []ServiceLink      `json:"services,omitempty"`
	Layers      []PackageLayer     `json:"layers,omitempty"`
	Clusters    []ClusterInfo      `json:"clusters,omitempty"`
	FileTree    []FileTreeEntry    `json:"file_tree,omitempty"`
}

ArchitectureInfo holds the result of a codebase architecture analysis.

type ClusterInfo added in v0.3.2

type ClusterInfo struct {
	ID        int      `json:"id"`
	Label     string   `json:"label"`
	Members   int      `json:"members"`
	Cohesion  float64  `json:"cohesion"`
	TopNodes  []string `json:"top_nodes"`
	Packages  []string `json:"packages"`
	EdgeTypes []string `json:"edge_types"`
}

ClusterInfo describes a community detected by the Louvain algorithm.

type CrossPkgBoundary added in v0.3.2

type CrossPkgBoundary struct {
	From      string `json:"from"`
	To        string `json:"to"`
	CallCount int    `json:"call_count"`
}

CrossPkgBoundary represents cross-package call volume.

type Edge

type Edge struct {
	ID         int64
	Project    string
	SourceID   int64
	TargetID   int64
	Type       string
	Properties map[string]any
}

Edge represents a graph edge stored in SQLite.

type EdgeInfo

type EdgeInfo struct {
	FromName   string
	ToName     string
	Type       string
	Confidence float64
}

EdgeInfo is a simplified edge for output.

type EntryPointInfo added in v0.3.2

type EntryPointInfo struct {
	Name          string `json:"name"`
	QualifiedName string `json:"qualified_name"`
	File          string `json:"file"`
}

EntryPointInfo describes an entry point function.

type FileHash

type FileHash struct {
	Project string
	RelPath string
	SHA256  string
}

FileHash represents a stored file content hash for incremental reindex.

type FileTreeEntry added in v0.3.2

type FileTreeEntry struct {
	Path     string `json:"path"`
	Type     string `json:"type"`
	Children int    `json:"children"`
}

FileTreeEntry describes a node in the condensed file tree.

type HotspotFunction added in v0.3.2

type HotspotFunction struct {
	Name          string `json:"name"`
	QualifiedName string `json:"qualified_name"`
	FanIn         int    `json:"fan_in"`
}

HotspotFunction is a function with high fan-in.

type ImpactSummary added in v0.3.1

type ImpactSummary struct {
	Critical        int  `json:"critical"`
	High            int  `json:"high"`
	Medium          int  `json:"medium"`
	Low             int  `json:"low"`
	Total           int  `json:"total"`
	HasCrossService bool `json:"has_cross_service"`
}

ImpactSummary aggregates risk counts from a BFS traversal.

func BuildImpactSummary added in v0.3.1

func BuildImpactSummary(hops []*NodeHop, edges []EdgeInfo) ImpactSummary

BuildImpactSummary computes risk distribution from deduplicated node hops.

type LabelCount

type LabelCount struct {
	Label string `json:"label"`
	Count int    `json:"count"`
}

LabelCount is a label with its count.

type LanguageCount added in v0.3.2

type LanguageCount struct {
	Language  string `json:"language"`
	FileCount int    `json:"file_count"`
}

LanguageCount counts files per language.

type Node

type Node struct {
	ID            int64
	Project       string
	Label         string
	Name          string
	QualifiedName string
	FilePath      string
	StartLine     int
	EndLine       int
	Properties    map[string]any
}

Node represents a graph node stored in SQLite.

type NodeHop

type NodeHop struct {
	Node *Node
	Hop  int
}

NodeHop is a node with its BFS hop distance.

func DeduplicateHops added in v0.3.1

func DeduplicateHops(hops []*NodeHop) []*NodeHop

DeduplicateHops removes duplicate nodes from BFS results, keeping the minimum hop (highest risk) for each node.

type PackageLayer added in v0.3.2

type PackageLayer struct {
	Name   string `json:"name"`
	Layer  string `json:"layer"`
	Reason string `json:"reason"`
}

PackageLayer classifies a package into an architectural layer.

type PackageSummary added in v0.3.2

type PackageSummary struct {
	Name      string `json:"name"`
	NodeCount int    `json:"node_count"`
	FanIn     int    `json:"fan_in"`
	FanOut    int    `json:"fan_out"`
}

PackageSummary summarizes a package with its connectivity.

type Project

type Project struct {
	Name      string
	IndexedAt string
	RootPath  string
}

Project represents an indexed project.

type ProjectInfo added in v0.2.0

type ProjectInfo struct {
	Name     string
	DBPath   string
	RootPath string
}

ProjectInfo holds metadata about a discovered project database.

type Querier added in v0.1.0

type Querier interface {
	Exec(query string, args ...any) (sql.Result, error)
	Query(query string, args ...any) (*sql.Rows, error)
	QueryRow(query string, args ...any) *sql.Row
}

Querier abstracts *sql.DB and *sql.Tx so store methods work in both contexts.

type RiskLevel added in v0.3.1

type RiskLevel string

RiskLevel classifies impact based on BFS hop depth.

const (
	RiskCritical RiskLevel = "CRITICAL"
	RiskHigh     RiskLevel = "HIGH"
	RiskMedium   RiskLevel = "MEDIUM"
	RiskLow      RiskLevel = "LOW"
)

func HopToRisk added in v0.3.1

func HopToRisk(hop int) RiskLevel

HopToRisk maps a BFS hop depth to a risk level.

type RouteInfo added in v0.3.2

type RouteInfo struct {
	Method  string `json:"method"`
	Path    string `json:"path"`
	Handler string `json:"handler"`
}

RouteInfo describes an HTTP route.

type SchemaInfo

type SchemaInfo struct {
	NodeLabels           []LabelCount `json:"node_labels"`
	RelationshipTypes    []TypeCount  `json:"relationship_types"`
	RelationshipPatterns []string     `json:"relationship_patterns"`
	SampleFunctionNames  []string     `json:"sample_function_names"`
	SampleClassNames     []string     `json:"sample_class_names"`
	SampleQualifiedNames []string     `json:"sample_qualified_names"`
}

SchemaInfo contains graph schema statistics.

type SearchOutput added in v0.0.2

type SearchOutput struct {
	Results []*SearchResult
	Total   int
}

SearchOutput wraps search results with total count for pagination.

type SearchParams

type SearchParams struct {
	Project            string
	Label              string
	NamePattern        string // regex matched against short name only
	QNPattern          string // regex matched against qualified name only
	FilePattern        string
	Relationship       string
	Direction          string // "inbound", "outbound", "any"
	MinDegree          int
	MaxDegree          int
	Limit              int
	Offset             int
	ExcludeEntryPoints bool     // when true, exclude nodes with is_entry_point=true
	IncludeConnected   bool     // when true, load connected node names (expensive, off by default)
	ExcludeLabels      []string // labels to exclude from results
	SortBy             string   // "relevance" (default), "name", "degree"
	CaseSensitive      bool     // false (zero value) = case-insensitive by default
}

SearchParams defines structured search parameters.

type SearchResult

type SearchResult struct {
	Node           *Node
	InDegree       int
	OutDegree      int
	ConnectedNames []string
}

SearchResult is a node with edge degree info.

type ServiceLink struct {
	From  string `json:"from"`
	To    string `json:"to"`
	Type  string `json:"type"`
	Count int    `json:"count"`
}

ServiceLink represents a cross-service link (HTTP or async).

type Store

type Store struct {
	// contains filtered or unexported fields
}

Store wraps a SQLite connection for graph storage.

func Open

func Open(project string) (*Store, error)

Open opens or creates a SQLite database for the given project in the default cache dir.

func OpenInDir added in v0.2.0

func OpenInDir(dir, project string) (*Store, error)

OpenInDir opens or creates a SQLite database for the given project in a specific directory.

func OpenMemory

func OpenMemory() (*Store, error)

OpenMemory opens an in-memory SQLite database (for testing).

func OpenPath

func OpenPath(dbPath string) (*Store, error)

OpenPath opens a SQLite database at the given path.

func (*Store) AllNodes

func (s *Store) AllNodes(project string) ([]*Node, error)

AllNodes returns all nodes for a project.

func (*Store) BFS

func (s *Store) BFS(startNodeID int64, direction string, edgeTypes []string, maxDepth, maxResults int) (*TraverseResult, error)

BFS performs breadth-first traversal following edges of given types using a recursive CTE, replacing the previous per-node Go-side loop with a single SQL round-trip. direction: "outbound" follows source->target, "inbound" follows target->source. maxDepth caps the BFS depth, maxResults caps total visited nodes.

func (*Store) BeginBulkWrite added in v0.2.0

func (s *Store) BeginBulkWrite(ctx context.Context)

BeginBulkWrite switches to MEMORY journal mode for faster bulk writes. Call EndBulkWrite when done to restore WAL mode. MEMORY mode is rollback-safe on crash (unlike journal_mode=OFF).

func (*Store) Checkpoint added in v0.1.4

func (s *Store) Checkpoint(ctx context.Context)

Checkpoint forces a WAL checkpoint, moving pages from WAL to the main DB, then runs PRAGMA optimize so the query planner has up-to-date statistics. PRAGMA optimize (SQLite 3.46+) auto-limits sampling per index, only re-analyzing stale stats. Cost is absorbed during indexing rather than the first read query.

func (*Store) Close

func (s *Store) Close() error

Close closes the database connection.

func (*Store) CountEdges

func (s *Store) CountEdges(project string) (int, error)

CountEdges returns the number of edges in a project.

func (*Store) CountEdgesByType added in v0.2.0

func (s *Store) CountEdgesByType(project, edgeType string) (int, error)

CountEdgesByType returns the number of edges of a given type for a project.

func (*Store) CountNodes

func (s *Store) CountNodes(project string) (int, error)

CountNodes returns the number of nodes in a project.

func (*Store) DB

func (s *Store) DB() *sql.DB

DB returns the underlying sql.DB (for advanced queries).

func (*Store) DBPath added in v0.1.4

func (s *Store) DBPath() string

DBPath returns the filesystem path to the SQLite database.

func (*Store) DeleteADR added in v0.3.2

func (s *Store) DeleteADR(project string) error

DeleteADR removes a stored ADR for a project.

func (*Store) DeleteEdgesByProject

func (s *Store) DeleteEdgesByProject(project string) error

DeleteEdgesByProject deletes all edges for a project.

func (*Store) DeleteEdgesBySourceFile added in v0.1.0

func (s *Store) DeleteEdgesBySourceFile(project, filePath, edgeType string) error

DeleteEdgesBySourceFile deletes edges of a given type where the source node belongs to a specific file. Used for incremental re-indexing of CALLS edges.

func (*Store) DeleteEdgesByType

func (s *Store) DeleteEdgesByType(project, edgeType string) error

DeleteEdgesByType deletes all edges of a given type for a project.

func (*Store) DeleteFileHash

func (s *Store) DeleteFileHash(project, relPath string) error

DeleteFileHash deletes a single file hash entry.

func (*Store) DeleteFileHashes

func (s *Store) DeleteFileHashes(project string) error

DeleteFileHashes deletes all file hashes for a project.

func (*Store) DeleteNodesByFile

func (s *Store) DeleteNodesByFile(project, filePath string) error

DeleteNodesByFile deletes all nodes for a specific file in a project.

func (*Store) DeleteNodesByLabel

func (s *Store) DeleteNodesByLabel(project, label string) error

DeleteNodesByLabel deletes all nodes with a given label in a project.

func (*Store) DeleteNodesByProject

func (s *Store) DeleteNodesByProject(project string) error

DeleteNodesByProject deletes all nodes for a project.

func (*Store) DeleteProject

func (s *Store) DeleteProject(name string) error

DeleteProject deletes a project and all associated data (CASCADE).

func (*Store) EndBulkWrite added in v0.2.0

func (s *Store) EndBulkWrite(ctx context.Context)

EndBulkWrite restores WAL journal mode and NORMAL synchronous after bulk writes.

func (*Store) FindArchitectureDocs added in v0.3.2

func (s *Store) FindArchitectureDocs(project string) ([]string, error)

FindArchitectureDocs discovers existing architecture documentation files in a project. Returns file paths matching common architecture doc patterns.

func (*Store) FindEdgesBySource

func (s *Store) FindEdgesBySource(sourceID int64) ([]*Edge, error)

FindEdgesBySource finds all edges from a given source node.

func (*Store) FindEdgesBySourceAndType

func (s *Store) FindEdgesBySourceAndType(sourceID int64, edgeType string) ([]*Edge, error)

FindEdgesBySourceAndType finds edges from a source with a specific type.

func (*Store) FindEdgesBySourceIDs added in v0.2.0

func (s *Store) FindEdgesBySourceIDs(sourceIDs []int64, edgeTypes []string) (map[int64][]*Edge, error)

FindEdgesBySourceIDs returns all edges where source_id is in the given set, optionally filtered by edge types. Groups results by source_id for efficient lookup.

func (*Store) FindEdgesByTarget

func (s *Store) FindEdgesByTarget(targetID int64) ([]*Edge, error)

FindEdgesByTarget finds all edges to a given target node.

func (*Store) FindEdgesByTargetAndType

func (s *Store) FindEdgesByTargetAndType(targetID int64, edgeType string) ([]*Edge, error)

FindEdgesByTargetAndType finds edges to a target with a specific type.

func (*Store) FindEdgesByTargetIDs added in v0.2.0

func (s *Store) FindEdgesByTargetIDs(targetIDs []int64, edgeTypes []string) (map[int64][]*Edge, error)

FindEdgesByTargetIDs returns all edges where target_id is in the given set, optionally filtered by edge types. Groups results by target_id.

func (*Store) FindEdgesByType added in v0.1.3

func (s *Store) FindEdgesByType(project, edgeType string) ([]*Edge, error)

FindEdgesByType returns all edges of a given type for a project.

func (*Store) FindEdgesByURLPath added in v0.1.3

func (s *Store) FindEdgesByURLPath(project, pathSubstring string) ([]*Edge, error)

FindEdgesByURLPath returns edges where url_path contains the given substring. Uses the generated column index for prefix matches, falls back to json_extract for substring.

func (*Store) FindNodeByID

func (s *Store) FindNodeByID(id int64) (*Node, error)

FindNodeByID finds a node by its primary key ID.

func (*Store) FindNodeByQN

func (s *Store) FindNodeByQN(project, qualifiedName string) (*Node, error)

FindNodeByQN finds a node by project and qualified name.

func (*Store) FindNodeIDsByQNs added in v0.1.4

func (s *Store) FindNodeIDsByQNs(project string, qns []string) (map[string]int64, error)

FindNodeIDsByQNs returns a map of qualifiedName → ID for the given QNs in a project.

func (*Store) FindNodesByFile

func (s *Store) FindNodesByFile(project, filePath string) ([]*Node, error)

FindNodesByFile finds all nodes in a given file.

func (*Store) FindNodesByFileOverlap added in v0.3.1

func (s *Store) FindNodesByFileOverlap(project, fileSuffix string, startLine, endLine int) ([]*Node, error)

FindNodesByFileOverlap returns nodes whose line range overlaps [startLine, endLine]. The fileSuffix is matched with LIKE '%' || ? against the file_path column to handle relative/absolute path differences.

func (*Store) FindNodesByIDs added in v0.2.0

func (s *Store) FindNodesByIDs(ids []int64) (map[int64]*Node, error)

FindNodesByIDs returns a map of nodeID → *Node for the given IDs.

func (*Store) FindNodesByLabel

func (s *Store) FindNodesByLabel(project, label string) ([]*Node, error)

FindNodesByLabel finds all nodes with a given label in a project.

func (*Store) FindNodesByName

func (s *Store) FindNodesByName(project, name string) ([]*Node, error)

FindNodesByName finds nodes by project and name.

func (*Store) FindNodesByQNSuffix added in v0.3.3

func (s *Store) FindNodesByQNSuffix(project, suffix string) ([]*Node, error)

FindNodesByQNSuffix finds nodes whose qualified_name ends with "."+suffix. Matches at QN segment boundaries to prevent partial word matches.

func (*Store) GetADR added in v0.3.2

func (s *Store) GetADR(project string) (*ADRecord, error)

GetADR retrieves a stored ADR for a project.

func (*Store) GetArchitecture added in v0.3.2

func (s *Store) GetArchitecture(project string, aspects []string) (*ArchitectureInfo, error)

GetArchitecture computes architecture aspects for a project. When aspects contains "all" or is empty, all aspects are computed.

func (*Store) GetFileHashes

func (s *Store) GetFileHashes(project string) (map[string]string, error)

GetFileHashes returns all file hashes for a project.

func (*Store) GetProject

func (s *Store) GetProject(name string) (*Project, error)

GetProject returns a project by name.

func (*Store) GetSchema

func (s *Store) GetSchema(project string) (*SchemaInfo, error)

GetSchema returns graph schema statistics for a project.

func (*Store) InsertEdge

func (s *Store) InsertEdge(e *Edge) (int64, error)

InsertEdge inserts an edge (dedup by source_id, target_id, type).

func (*Store) InsertEdgeBatch added in v0.1.4

func (s *Store) InsertEdgeBatch(edges []*Edge) error

InsertEdgeBatch inserts multiple edges in batched multi-row INSERTs.

func (*Store) ListFilesForProject added in v0.1.0

func (s *Store) ListFilesForProject(project string) ([]string, error)

ListFilesForProject returns all distinct file paths indexed for a project.

func (*Store) ListProjects

func (s *Store) ListProjects() ([]*Project, error)

ListProjects returns all indexed projects.

func (*Store) NodeDegree added in v0.3.3

func (s *Store) NodeDegree(nodeID int64) (inbound, outbound int)

NodeDegree returns inbound and outbound CALLS edge counts for a node.

func (*Store) NodeNeighborNames added in v0.3.3

func (s *Store) NodeNeighborNames(nodeID int64, limit int) (callerNames, calleeNames []string)

NodeNeighborNames returns the names of callers and callees for a node, considering CALLS, HTTP_CALLS, and ASYNC_CALLS edge types.

func (*Store) Search

func (s *Store) Search(params *SearchParams) (*SearchOutput, error)

Search executes a parameterized search query with pagination support.

func (*Store) StoreADR added in v0.3.2

func (s *Store) StoreADR(project, content string) error

StoreADR persists an ADR (upsert). The source_hash column is kept as a dead column to avoid ALTER TABLE issues — we write an empty string.

func (*Store) UpdateADRSections added in v0.3.2

func (s *Store) UpdateADRSections(project string, sections map[string]string) (*ADRecord, error)

UpdateADRSections merges the provided sections into the existing ADR. Unmentioned sections are preserved. Returns the updated record. Returns an error if the merged content exceeds maxADRLength.

func (*Store) UpsertFileHash

func (s *Store) UpsertFileHash(project, relPath, sha256 string) error

UpsertFileHash stores a file's content hash.

func (*Store) UpsertFileHashBatch added in v0.1.4

func (s *Store) UpsertFileHashBatch(hashes []FileHash) error

UpsertFileHashBatch inserts or updates multiple file hashes in batched multi-row INSERTs.

func (*Store) UpsertNode

func (s *Store) UpsertNode(n *Node) (int64, error)

UpsertNode inserts or replaces a node (dedup by qualified_name). Note: LastInsertId() can return stale IDs for ON CONFLICT DO UPDATE, causing occasional FK failures in downstream edge inserts. This is accepted for performance — the fallback SELECT only runs when id==0.

func (*Store) UpsertNodeBatch added in v0.1.4

func (s *Store) UpsertNodeBatch(nodes []*Node) (map[string]int64, error)

UpsertNodeBatch inserts or updates multiple nodes in batched multi-row INSERTs. Returns a map of qualifiedName → ID for all upserted nodes.

func (*Store) UpsertProject

func (s *Store) UpsertProject(name, rootPath string) error

UpsertProject creates or updates a project record.

func (*Store) WithTransaction added in v0.1.0

func (s *Store) WithTransaction(ctx context.Context, fn func(txStore *Store) error) error

WithTransaction executes fn within a single SQLite transaction. The callback receives a transaction-scoped Store — all store methods called on txStore use the transaction. The receiver's q field is never mutated, so concurrent read-only handlers (using s.q == s.db) are unaffected.

type StoreRouter added in v0.2.0

type StoreRouter struct {
	// contains filtered or unexported fields
}

StoreRouter manages per-project SQLite databases. Each project gets its own .db file in the cache directory.

func NewRouter added in v0.2.0

func NewRouter() (*StoreRouter, error)

NewRouter creates a StoreRouter, ensuring the cache directory exists. Runs migration from single-DB layout if needed.

func NewRouterWithDir added in v0.2.0

func NewRouterWithDir(dir string) (*StoreRouter, error)

NewRouterWithDir creates a StoreRouter using a custom directory (for testing). No migration is run.

func (*StoreRouter) AllStores added in v0.2.0

func (r *StoreRouter) AllStores() map[string]*Store

AllStores opens all .db files in the cache dir and returns a name→Store map.

func (*StoreRouter) CloseAll added in v0.2.0

func (r *StoreRouter) CloseAll()

CloseAll closes all open Store connections.

func (*StoreRouter) DeleteProject added in v0.2.0

func (r *StoreRouter) DeleteProject(name string) error

DeleteProject closes the Store connection and removes the .db + WAL/SHM files.

func (*StoreRouter) Dir added in v0.2.0

func (r *StoreRouter) Dir() string

Dir returns the cache directory path.

func (*StoreRouter) ForProject added in v0.2.0

func (r *StoreRouter) ForProject(name string) (*Store, error)

ForProject returns the Store for the given project, opening it lazily.

func (*StoreRouter) HasProject added in v0.2.0

func (r *StoreRouter) HasProject(name string) bool

HasProject checks if a .db file exists for the given project (without opening it).

func (*StoreRouter) ListProjects added in v0.2.0

func (r *StoreRouter) ListProjects() ([]*ProjectInfo, error)

ListProjects scans .db files and queries each for metadata.

type TraverseResult

type TraverseResult struct {
	Root    *Node
	Visited []*NodeHop
	Edges   []EdgeInfo
}

TraverseResult holds BFS traversal results.

type TypeCount

type TypeCount struct {
	Type  string `json:"type"`
	Count int    `json:"count"`
}

TypeCount is a relationship type with its count.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL