Documentation
¶
Index ¶
- func CanonicalSectionNames() []string
- func MaxADRLength() int
- func Now() string
- func ParseADRSections(content string) map[string]string
- func RenderADR(sections map[string]string) string
- func UnmarshalProps(data string) map[string]any
- func ValidateADRContent(content string) error
- func ValidateADRSectionKeys(sections map[string]string) error
- type ADRecord
- type ArchitectureInfo
- type ClusterInfo
- type CrossPkgBoundary
- type Edge
- type EdgeInfo
- type EntryPointInfo
- type FileHash
- type FileTreeEntry
- type HotspotFunction
- type ImpactSummary
- type LabelCount
- type LanguageCount
- type Node
- type NodeHop
- type PackageLayer
- type PackageSummary
- type Project
- type ProjectInfo
- type Querier
- type RiskLevel
- type RouteInfo
- type SchemaInfo
- type SearchOutput
- type SearchParams
- type SearchResult
- type ServiceLink
- type Store
- func (s *Store) AllNodes(project string) ([]*Node, error)
- func (s *Store) BFS(startNodeID int64, direction string, edgeTypes []string, ...) (*TraverseResult, error)
- func (s *Store) BeginBulkWrite(ctx context.Context)
- func (s *Store) Checkpoint(ctx context.Context)
- func (s *Store) Close() error
- func (s *Store) CountEdges(project string) (int, error)
- func (s *Store) CountEdgesByType(project, edgeType string) (int, error)
- func (s *Store) CountNodes(project string) (int, error)
- func (s *Store) DB() *sql.DB
- func (s *Store) DBPath() string
- func (s *Store) DeleteADR(project string) error
- func (s *Store) DeleteEdgesByProject(project string) error
- func (s *Store) DeleteEdgesBySourceFile(project, filePath, edgeType string) error
- func (s *Store) DeleteEdgesByType(project, edgeType string) error
- func (s *Store) DeleteFileHash(project, relPath string) error
- func (s *Store) DeleteFileHashes(project string) error
- func (s *Store) DeleteNodesByFile(project, filePath string) error
- func (s *Store) DeleteNodesByLabel(project, label string) error
- func (s *Store) DeleteNodesByProject(project string) error
- func (s *Store) DeleteProject(name string) error
- func (s *Store) EndBulkWrite(ctx context.Context)
- func (s *Store) FindArchitectureDocs(project string) ([]string, error)
- func (s *Store) FindEdgesBySource(sourceID int64) ([]*Edge, error)
- func (s *Store) FindEdgesBySourceAndType(sourceID int64, edgeType string) ([]*Edge, error)
- func (s *Store) FindEdgesBySourceIDs(sourceIDs []int64, edgeTypes []string) (map[int64][]*Edge, error)
- func (s *Store) FindEdgesByTarget(targetID int64) ([]*Edge, error)
- func (s *Store) FindEdgesByTargetAndType(targetID int64, edgeType string) ([]*Edge, error)
- func (s *Store) FindEdgesByTargetIDs(targetIDs []int64, edgeTypes []string) (map[int64][]*Edge, error)
- func (s *Store) FindEdgesByType(project, edgeType string) ([]*Edge, error)
- func (s *Store) FindEdgesByURLPath(project, pathSubstring string) ([]*Edge, error)
- func (s *Store) FindNodeByID(id int64) (*Node, error)
- func (s *Store) FindNodeByQN(project, qualifiedName string) (*Node, error)
- func (s *Store) FindNodeIDsByQNs(project string, qns []string) (map[string]int64, error)
- func (s *Store) FindNodesByFile(project, filePath string) ([]*Node, error)
- func (s *Store) FindNodesByFileOverlap(project, fileSuffix string, startLine, endLine int) ([]*Node, error)
- func (s *Store) FindNodesByIDs(ids []int64) (map[int64]*Node, error)
- func (s *Store) FindNodesByLabel(project, label string) ([]*Node, error)
- func (s *Store) FindNodesByName(project, name string) ([]*Node, error)
- func (s *Store) FindNodesByQNSuffix(project, suffix string) ([]*Node, error)
- func (s *Store) GetADR(project string) (*ADRecord, error)
- func (s *Store) GetArchitecture(project string, aspects []string) (*ArchitectureInfo, error)
- func (s *Store) GetFileHashes(project string) (map[string]string, error)
- func (s *Store) GetProject(name string) (*Project, error)
- func (s *Store) GetSchema(project string) (*SchemaInfo, error)
- func (s *Store) InsertEdge(e *Edge) (int64, error)
- func (s *Store) InsertEdgeBatch(edges []*Edge) error
- func (s *Store) ListFilesForProject(project string) ([]string, error)
- func (s *Store) ListProjects() ([]*Project, error)
- func (s *Store) NodeDegree(nodeID int64) (inbound, outbound int)
- func (s *Store) NodeNeighborNames(nodeID int64, limit int) (callerNames, calleeNames []string)
- func (s *Store) Search(params *SearchParams) (*SearchOutput, error)
- func (s *Store) StoreADR(project, content string) error
- func (s *Store) UpdateADRSections(project string, sections map[string]string) (*ADRecord, error)
- func (s *Store) UpsertFileHash(project, relPath, sha256 string) error
- func (s *Store) UpsertFileHashBatch(hashes []FileHash) error
- func (s *Store) UpsertNode(n *Node) (int64, error)
- func (s *Store) UpsertNodeBatch(nodes []*Node) (map[string]int64, error)
- func (s *Store) UpsertProject(name, rootPath string) error
- func (s *Store) WithTransaction(ctx context.Context, fn func(txStore *Store) error) error
- type StoreRouter
- func (r *StoreRouter) AllStores() map[string]*Store
- func (r *StoreRouter) CloseAll()
- func (r *StoreRouter) DeleteProject(name string) error
- func (r *StoreRouter) Dir() string
- func (r *StoreRouter) ForProject(name string) (*Store, error)
- func (r *StoreRouter) HasProject(name string) bool
- func (r *StoreRouter) ListProjects() ([]*ProjectInfo, error)
- type TraverseResult
- type TypeCount
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 ParseADRSections ¶ added in v0.3.2
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
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
UnmarshalProps deserializes JSON properties. Exported for use by cypher executor.
func ValidateADRContent ¶ added in v0.3.2
ValidateADRContent checks that content contains all 6 canonical sections. Returns an error listing any missing sections.
func ValidateADRSectionKeys ¶ added in v0.3.2
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 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 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 ¶
LabelCount is a label with its count.
type LanguageCount ¶ added in v0.3.2
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 ¶
NodeHop is a node with its BFS hop distance.
func DeduplicateHops ¶ added in v0.3.1
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 ProjectInfo ¶ added in v0.2.0
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.
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 ¶
SearchResult is a node with edge degree info.
type ServiceLink ¶ added in v0.3.2
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 OpenInDir ¶ added in v0.2.0
OpenInDir opens or creates a SQLite database for the given project in a specific directory.
func OpenMemory ¶
OpenMemory opens an in-memory SQLite database (for testing).
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
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
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) CountEdges ¶
CountEdges returns the number of edges in a project.
func (*Store) CountEdgesByType ¶ added in v0.2.0
CountEdgesByType returns the number of edges of a given type for a project.
func (*Store) CountNodes ¶
CountNodes returns the number of nodes in a project.
func (*Store) DeleteEdgesByProject ¶
DeleteEdgesByProject deletes all edges for a project.
func (*Store) DeleteEdgesBySourceFile ¶ added in v0.1.0
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 ¶
DeleteEdgesByType deletes all edges of a given type for a project.
func (*Store) DeleteFileHash ¶
DeleteFileHash deletes a single file hash entry.
func (*Store) DeleteFileHashes ¶
DeleteFileHashes deletes all file hashes for a project.
func (*Store) DeleteNodesByFile ¶
DeleteNodesByFile deletes all nodes for a specific file in a project.
func (*Store) DeleteNodesByLabel ¶
DeleteNodesByLabel deletes all nodes with a given label in a project.
func (*Store) DeleteNodesByProject ¶
DeleteNodesByProject deletes all nodes for a project.
func (*Store) DeleteProject ¶
DeleteProject deletes a project and all associated data (CASCADE).
func (*Store) EndBulkWrite ¶ added in v0.2.0
EndBulkWrite restores WAL journal mode and NORMAL synchronous after bulk writes.
func (*Store) FindArchitectureDocs ¶ added in v0.3.2
FindArchitectureDocs discovers existing architecture documentation files in a project. Returns file paths matching common architecture doc patterns.
func (*Store) FindEdgesBySource ¶
FindEdgesBySource finds all edges from a given source node.
func (*Store) FindEdgesBySourceAndType ¶
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 ¶
FindEdgesByTarget finds all edges to a given target node.
func (*Store) FindEdgesByTargetAndType ¶
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
FindEdgesByType returns all edges of a given type for a project.
func (*Store) FindEdgesByURLPath ¶ added in v0.1.3
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 ¶
FindNodeByID finds a node by its primary key ID.
func (*Store) FindNodeByQN ¶
FindNodeByQN finds a node by project and qualified name.
func (*Store) FindNodeIDsByQNs ¶ added in v0.1.4
FindNodeIDsByQNs returns a map of qualifiedName → ID for the given QNs in a project.
func (*Store) FindNodesByFile ¶
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
FindNodesByIDs returns a map of nodeID → *Node for the given IDs.
func (*Store) FindNodesByLabel ¶
FindNodesByLabel finds all nodes with a given label in a project.
func (*Store) FindNodesByName ¶
FindNodesByName finds nodes by project and name.
func (*Store) FindNodesByQNSuffix ¶ added in v0.3.3
FindNodesByQNSuffix finds nodes whose qualified_name ends with "."+suffix. Matches at QN segment boundaries to prevent partial word matches.
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 ¶
GetFileHashes returns all file hashes for a project.
func (*Store) GetProject ¶
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 ¶
InsertEdge inserts an edge (dedup by source_id, target_id, type).
func (*Store) InsertEdgeBatch ¶ added in v0.1.4
InsertEdgeBatch inserts multiple edges in batched multi-row INSERTs.
func (*Store) ListFilesForProject ¶ added in v0.1.0
ListFilesForProject returns all distinct file paths indexed for a project.
func (*Store) ListProjects ¶
ListProjects returns all indexed projects.
func (*Store) NodeDegree ¶ added in v0.3.3
NodeDegree returns inbound and outbound CALLS edge counts for a node.
func (*Store) NodeNeighborNames ¶ added in v0.3.3
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
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
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 ¶
UpsertFileHash stores a file's content hash.
func (*Store) UpsertFileHashBatch ¶ added in v0.1.4
UpsertFileHashBatch inserts or updates multiple file hashes in batched multi-row INSERTs.
func (*Store) UpsertNode ¶
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
UpsertNodeBatch inserts or updates multiple nodes in batched multi-row INSERTs. Returns a map of qualifiedName → ID for all upserted nodes.
func (*Store) UpsertProject ¶
UpsertProject creates or updates a project record.
func (*Store) WithTransaction ¶ added in v0.1.0
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 ¶
TraverseResult holds BFS traversal results.