types

type BlastRadiusResult struct {
	Target     Node                              // the node whose blast radius was computed
	ByRepo     map[string][]CallerWithProvenance // repo URL -> callers in that repo
	TotalCount int                               // total number of callers across all repos
	Truncated  bool                              // true if traversal hit the max depth limit
}

type CalleeResult struct {
	Node  Node
	Depth int // 1 = direct callee, 2 = callee of a callee, etc.
}

type CallerResult struct {
	Node  Node
	Depth int // 1 = direct caller, 2 = caller of a caller, etc.
}

type CallerWithProvenance struct {
	Caller     Node
	Depth      int
	Confidence float64          // minimum confidence along the call path (0.0 to 1.0)
	Provenance []EdgeProvenance // ordered provenance chain from caller to target
}

type DiffResult struct {
	OldSnapshot  Hash
	NewSnapshot  Hash
	EdgesAdded   []Edge // edges present in NewSnapshot but not OldSnapshot
	EdgesRemoved []Edge // edges present in OldSnapshot but not NewSnapshot
	NodesAdded   []Node // nodes present in NewSnapshot but not OldSnapshot
	NodesRemoved []Node // nodes present in OldSnapshot but not NewSnapshot
}

type Edge struct {
	EdgeHash   Hash    // content-addressed identity: sha256(sourceHash || targetHash || edgeType || provenance)
	SourceHash Hash    // hash of the source node (caller, importer, implementor)
	TargetHash Hash    // hash of the target node (callee, imported package, interface)
	EdgeType   string  // relationship kind: "calls", "imports", "implements", "references"
	Confidence float64 // quality score from 0.0 to 1.0; ast_inferred=0.7, lsp_resolved=0.9, ast_resolved=1.0
	Provenance string  // how the edge was derived: "ast_resolved", "ast_inferred", "lsp_resolved", etc.
	// CallSite fields store the source location of the call expression (not the
	// target declaration). These positions are used by LSP enrichment: the enricher
	// sends GetDefinition at (CallSiteFile, CallSiteLine, CallSiteCol) to confirm
	// or correct the target. Zero values mean no call-site info is available.
	CallSiteLine int    // 1-indexed line of the call expression in the source file
	CallSiteCol  int    // 0-indexed column of the call expression
	CallSiteFile string // relative file path (within the repo) containing the call expression
	// Runtime observation fields. Zero values for static edges.
	ObservationCount int   // total observations in current window (0 for static edges)
	LastObserved     int64 // unix timestamp of last observation (0 for static edges)
}

type EdgeEvent struct {
	EventID      int64  // auto-increment primary key
	EdgeHash     Hash   // hash of the edge that was added or removed
	EventType    string // "added" or "removed"
	SnapshotHash Hash   // the snapshot during which this event occurred
	SourceCommit string // git commit that triggered the event
	IndexerVer   string // version of the indexer that produced this event (e.g., "v1")
	Timestamp    int64  // unix timestamp of the event
	// Full edge data stored so removed-edge diffs work without joining
	// back to the edges table (removed edges are deleted from edges).
	SourceHash Hash    // source node hash (nullable for pre-migration events)
	TargetHash Hash    // target node hash
	EdgeType   string  // calls, imports, etc.
	Confidence float64 // confidence score
	Provenance string  // provenance tier
}

type EdgeProvenance struct {
	Source         string  // derivation method: "ast_resolved", "ast_inferred", "lsp_resolved", etc.
	Confidence     float64 // confidence score of this provenance step (0.0 to 1.0)
	IndexerVersion string  // version of the indexer that produced this edge
	SourceCommit   string  // git commit hash at the time of extraction
	SourceFileHash Hash    // hash of the source file from which the edge was extracted
	Timestamp      int64   // unix timestamp of extraction
}

type ExtractOptions struct {
	RepoURL    string // the repo URL (or local path) as registered in the store
	RepoHash   Hash   // sha256(RepoURL)
	CommitHash string // git commit hash being indexed
	FilePath   string // file path relative to the repository root
	FileHash   Hash   // content-addressed file hash: sha256(repoHash || path || contentHash)
	Content    []byte // raw file contents
	ModuleRoot string // absolute path to the module/repo root on disk (for go.mod resolution)
	// ModuleToRepoURL maps Go module paths to stored repo URLs. This is
	// populated by the indexer from the repos table so extractors can
	// resolve cross-repo call targets to the correct stored repo URL
	// rather than using heuristic inference from the import path.
	// Example: "github.com/org/repo" -> "/Users/user/code/repo"
	ModuleToRepoURL map[string]string

	// ParsedTree is an optional pre-parsed tree-sitter root node (*sitter.Node).
	// When set, extractors should use this instead of parsing the file again.
	// The indexer sets this when multiple extractors share the same language,
	// eliminating redundant parsing. Extractors that receive a non-nil ParsedTree
	// MUST NOT close the tree (the indexer owns it).
	ParsedTree ParsedTree
}

type ExtractResult struct {
	Nodes []Node
	Edges []Edge
	// ParsedTree is set by tree-sitter extractors after parsing. The indexer
	// reads this and passes it to subsequent extractors handling the same file,
	// eliminating redundant parsing. Only the FIRST extractor to parse sets this;
	// subsequent extractors receive it via opts.ParsedTree and leave this nil.
	ParsedTree ParsedTree `json:"-"`
}

type Extractor interface {
	// Name returns a human-readable identifier for this extractor (e.g., "go", "go-treesitter").
	Name() string
	// CanHandle returns true if this extractor can process the file at the given path.
	// The path is relative to the repository root.
	CanHandle(path string) bool
	// Extract parses the file described by opts and returns extracted nodes and edges.
	// Returns an empty result (not an error) if no symbols are found.
	Extract(ctx context.Context, opts ExtractOptions) (*ExtractResult, error)
}

type File struct {
	FileHash    Hash   // sha256(repoHash || relativePath || contentHash)
	RepoHash    Hash   // hash of the containing Repo
	Path        string // path relative to the repository root
	ContentHash Hash   // sha256 of the raw file contents; used for skip-if-unchanged checks
}

type GraphStore interface {
	// Write operations (upsert semantics via INSERT OR REPLACE).
	PutNode(ctx context.Context, n Node) error
	PutEdge(ctx context.Context, e Edge) error
	PutFile(ctx context.Context, f File) error
	PutRepo(ctx context.Context, r Repo) error
	RecordEdgeEvent(ctx context.Context, ev EdgeEvent) error
	CreateSnapshot(ctx context.Context, s Snapshot) error

	// Point lookups by hash. Return nil when not found (no error).
	GetNode(ctx context.Context, hash Hash) (*Node, error)
	GetEdge(ctx context.Context, hash Hash) (*Edge, error)
	GetSnapshot(ctx context.Context, hash Hash) (*Snapshot, error)
	GetRepo(ctx context.Context, hash Hash) (*Repo, error)

	// Query operations.
	NodesByName(ctx context.Context, qualifiedPrefix string) ([]Node, error)
	EdgesFrom(ctx context.Context, sourceHash Hash, edgeType string) ([]Edge, error)
	EdgesTo(ctx context.Context, targetHash Hash, edgeType string) ([]Edge, error)
	DanglingEdges(ctx context.Context) ([]Edge, error)
	AllRepos(ctx context.Context) ([]Repo, error)
	NodesByQualifiedName(ctx context.Context, qualifiedName string) ([]Node, error)
	NodesByFileHash(ctx context.Context, fileHash Hash) ([]Node, error)

	// Delete operations for incremental re-indexing and garbage collection.
	// GC operations: delete nodes/edges not in the keep set.
	DeleteNodesNotIn(ctx context.Context, keep map[Hash]struct{}) (int64, error)
	DeleteEdgesNotIn(ctx context.Context, keep map[Hash]struct{}) (int64, error)
	DeleteEdge(ctx context.Context, hash Hash) error
	DeleteNodesByFile(ctx context.Context, fileHash Hash) (int, error)
	DeleteEdgesBySourceFile(ctx context.Context, fileHash Hash) ([]Edge, error)
	EdgesBySourceFile(ctx context.Context, fileHash Hash) ([]Edge, error)
	DeleteSnapshot(ctx context.Context, hash Hash) error

	// Graph traversals (implemented as recursive CTEs in SQLite).
	TransitiveCallers(ctx context.Context, target Hash, maxDepth int, snapshot Hash) ([]CallerResult, error)
	TransitiveCallees(ctx context.Context, source Hash, maxDepth int, snapshot Hash) ([]CalleeResult, error)
	BlastRadius(ctx context.Context, target Hash, snapshot Hash) (*BlastRadiusResult, error)

	// Snapshot operations.
	SnapshotDiff(ctx context.Context, oldRoot, newRoot Hash) (*DiffResult, error)
	StaleEdges(ctx context.Context, snapshot Hash) ([]Edge, error)
	LatestSnapshot(ctx context.Context, repoHash Hash) (*Snapshot, error)

	// File queries.
	FilesByRepo(ctx context.Context, repoHash Hash) ([]File, error)
	FileByPath(ctx context.Context, repoHash Hash, path string) (*File, error)
	NodesByFilePath(ctx context.Context, repoHash Hash, path string) ([]Node, error)
	StaleNodesByFiles(ctx context.Context, repoHash Hash, paths []string) ([]Node, error)

	// Notes: metadata that never affects Merkle computation (git notes pattern).
	// PutNote upserts a note (object_hash + key is the composite key).
	PutNote(ctx context.Context, n Note) error
	// GetNote retrieves a single note by object hash and key. Returns nil if not found.
	GetNote(ctx context.Context, objectHash Hash, key string) (*Note, error)
	// GetNotes retrieves all notes attached to an object.
	GetNotes(ctx context.Context, objectHash Hash) ([]Note, error)
	// GetNotesByKey retrieves all notes with the given key across all objects.
	GetNotesByKey(ctx context.Context, key string) ([]Note, error)
	// DeleteNote removes a single note by object hash and key.
	DeleteNote(ctx context.Context, objectHash Hash, key string) error
	// DeleteNotesByObject removes all notes attached to an object.
	DeleteNotesByObject(ctx context.Context, objectHash Hash) error

	// Close releases the underlying database connection.
	Close() error
}

type Hash [32]byte

type Node struct {
	// NodeHash is the content-addressed identity: sha256(repoURL || packagePath || symbolName || symbolKind).
	// Note: contentHash was removed from the computation; node identity
	// depends only on (repo, package, name, kind).
	NodeHash      Hash
	FileHash      Hash    // reference to the containing File record
	QualifiedName string  // fully qualified name: "{repoURL}://{pkgPath}.{TypeName}.{SymbolName}"
	Kind          string  // one of: function, type, method, interface, const, var
	Line          int     // 1-indexed source line number of the declaration
	Signature     string  // human-readable type signature for display (e.g., "func (SQLiteStore) PutNode()")
	Doc           string  // doc comment preceding the declaration (first 200 chars, language-agnostic)
	LastAuthor    string  // git blame: author of the last commit that touched this symbol's line
	LastCommitAt  int64   // git blame: unix timestamp of the last commit that touched this symbol's line
	CoveragePct   float64 // test coverage percentage for this symbol's lines (0.0-100.0, -1 = not measured)
}

type Note struct {
	ObjectHash Hash   // the content-addressed object this note is attached to
	Key        string // the metadata key (e.g., "community_id", "context_pack")
	Value      string // the metadata value (opaque to the store; callers may use JSON)
	UpdatedAt  int64  // unix timestamp of last write
}

type ParsedTree = any

type Repo struct {
	RepoHash    Hash   // sha256(repoURL); canonical identity for the repo
	RepoURL     string // the URL or path that was passed to IndexRepo
	LastCommit  string // git commit hash from the most recent index run
	LastIndexed int64  // unix timestamp of the most recent index run
}

type Snapshot struct {
	SnapshotHash Hash   // Merkle root: merkle_root(sorted(all_edge_hashes))
	ParentHash   Hash   // hash of the previous snapshot in the chain; zero for the first
	RepoHash     Hash   // hash of the repository this snapshot belongs to
	CommitHash   string // git commit hash at the time of snapshotting
	Timestamp    int64  // unix timestamp when the snapshot was created
	NodeCount    int    // total number of nodes in the graph at snapshot time
	EdgeCount    int    // total number of edges in the graph at snapshot time
	Generation   int    // chain depth: parent.Generation + 1; enables O(1) ancestry checks
}