docs(analysis): annotate flow and impact helpers

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent)

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

Author: tae2089

internal/analysis/flows/builder.go

@@ -79,6 +79,9 @@ func (b *Builder) Rebuild(ctx context.Context, cfg Config) ([]Stats, error) {
 	return result, err
 }
 
+// deleteFlows removes all flows and memberships within the namespace.
+// @intent clear stale flow records before a fresh rebuild
+// @sideEffect deletes rows from flow_memberships and flows tables
 func deleteFlows(tx *gorm.DB, ns string) error {
 	var ids []uint
 	if err := tx.Model(&model.Flow{}).Where("namespace = ?", ns).Pluck("id", &ids).Error; err != nil {
@@ -93,6 +96,8 @@ func deleteFlows(tx *gorm.DB, ns string) error {
 	return tx.Where("id IN ?", ids).Delete(&model.Flow{}).Error
 }
 
+// findEntrypoints returns function and test nodes with no inbound calls edges.
+// @intent locate likely flow entry points by selecting nodes nothing else calls
 func findEntrypoints(tx *gorm.DB, ns string) ([]model.Node, error) {
 	var nodes []model.Node
 	inboundCalls := tx.Model(&model.Edge{}).

internal/analysis/flows/flows.go

@@ -1,3 +1,4 @@
+// @index Flow tracing engine that walks call edges into reusable flow records.
 package flows
 
 import (
@@ -21,10 +22,14 @@ type Tracer struct {
 	store EdgeReader
 }
 
+// TraceOptions bounds how far a single flow trace is allowed to expand.
+// @intent let callers cap traversal cost when tracing large call graphs
 type TraceOptions struct {
 	MaxNodes int
 }
 
+// TraceResult wraps a built flow with the metadata needed to detect truncation.
+// @intent communicate truncation status alongside the produced flow
 type TraceResult struct {
 	Flow          *model.Flow
 	Truncated     bool
@@ -52,6 +57,13 @@ func (t *Tracer) TraceFlow(ctx context.Context, startNodeID uint) (*model.Flow,
 	return result.Flow, nil
 }
 
+// TraceFlowBounded performs the BFS traversal that backs TraceFlow with explicit limits.
+// @intent expose a flow trace variant that can stop early when MaxNodes is reached
+// @param startNodeID graph node where traversal begins
+// @param opts traversal limits applied during BFS
+// @return TraceResult with the built flow and truncation metadata
+// @domainRule only calls edges enqueue new BFS nodes
+// @ensures Truncated is true only when MaxNodes stopped traversal
 func (t *Tracer) TraceFlowBounded(ctx context.Context, startNodeID uint, opts TraceOptions) (*TraceResult, error) {
 	visited := map[uint]bool{}
 	var members []model.FlowMembership

internal/analysis/impact/impact.go

@@ -24,11 +24,15 @@ type Analyzer struct {
 	store EdgeReader
 }
 
+// RadiusOptions caps how far ImpactRadiusBounded is allowed to expand.
+// @intent let callers limit BFS depth and visited node count for safety
 type RadiusOptions struct {
 	MaxDepth int
 	MaxNodes int
 }
 
+// RadiusResult reports the resolved nodes and whether limits truncated traversal.
+// @intent surface the visited node set together with truncation metadata
 type RadiusResult struct {
 	Nodes         []model.Node
 	Truncated     bool
@@ -60,6 +64,14 @@ func (a *Analyzer) ImpactRadius(ctx context.Context, nodeID uint, depth int) ([]
 	return result.Nodes, nil
 }
 
+// ImpactRadiusBounded performs the bidirectional BFS that backs ImpactRadius with explicit caps.
+// @intent expose a limit-aware blast radius traversal for cost-sensitive callers
+// @param nodeID starting node for the BFS
+// @param depth maximum BFS hop count (further capped by opts.MaxDepth)
+// @param opts traversal limits applied during BFS
+// @return RadiusResult with visited nodes and truncation metadata
+// @domainRule traverses outgoing and incoming edges in lock step at each depth
+// @ensures Truncated is true when MaxNodes stopped traversal or post-trim
 func (a *Analyzer) ImpactRadiusBounded(ctx context.Context, nodeID uint, depth int, opts RadiusOptions) (*RadiusResult, error) {
 	if opts.MaxDepth > 0 && depth > opts.MaxDepth {
 		depth = opts.MaxDepth

internal/analysis/incremental/incremental.go

@@ -36,6 +36,8 @@ type AnnotatingParser interface {
 	Language() string
 }
 
+// annotationWriter is the optional store capability needed to persist comment-derived annotations.
+// @intent allow incremental sync to skip annotation writes when the underlying store does not support them.
 type annotationWriter interface {
 	UpsertAnnotation(ctx context.Context, ann *model.Annotation) error
 }
@@ -66,6 +68,9 @@ type Syncer struct {
 	logger  *slog.Logger
 }
 
+// releaseContent drops the in-memory file content for one path so the sync loop can free memory early.
+// @intent prevent the FileInfo map from holding all source bytes after a file has been processed.
+// @mutates files[filePath].Content
 func releaseContent(files map[string]FileInfo, filePath string) {
 	info, ok := files[filePath]
 	if !ok {
@@ -147,6 +152,10 @@ func (s *Syncer) SyncWithExistingStore(ctx context.Context, syncStore Store, fil
 	return s.syncWithExisting(ctx, syncStore, files, existingFiles)
 }
 
+// syncWithExisting performs the actual diff-and-apply pass against the supplied store.
+// @intent compare hashes for known files, parse new/changed ones, and remove deleted entries in one pass.
+// @sideEffect upserts nodes/edges/annotations and deletes removed files through syncStore.
+// @mutates graph nodes, edges, annotations
 func (s *Syncer) syncWithExisting(ctx context.Context, syncStore Store, files map[string]FileInfo, existingFiles []string) (*SyncStats, error) {
 	stats := &SyncStats{}
 
@@ -242,6 +251,8 @@ func (s *Syncer) syncWithExisting(ctx context.Context, syncStore Store, files ma
 	return stats, nil
 }
 
+// resolveParser picks an extension-specific parser when configured, otherwise the legacy single parser.
+// @intent let multi-language projects sync without losing the single-parser fallback for callers using New.
 func (s *Syncer) resolveParser(filePath string) Parser {
 	if len(s.parsers) > 0 {
 		ext := strings.ToLower(filepath.Ext(filePath))
@@ -252,6 +263,10 @@ func (s *Syncer) resolveParser(filePath string) Parser {
 	return s.parser
 }
 
+// restoreAnnotations re-binds parsed comment blocks to the freshly persisted nodes for one file.
+// @intent keep doc comments associated with their owning declarations after incremental reparses.
+// @sideEffect upserts annotation rows through the store's annotation writer.
+// @mutates graph annotations
 func (s *Syncer) restoreAnnotations(ctx context.Context, syncStore Store, filePath string, content []byte, nodes []model.Node, comments []treesitter.CommentBlock, language string) error {
 	writer, ok := syncStore.(annotationWriter)
 	if !ok || language == "" {
@@ -298,6 +313,8 @@ func (s *Syncer) restoreAnnotations(ctx context.Context, syncStore Store, filePa
 	return nil
 }
 
+// annotationBindingKey produces a stable lookup key combining qualified name and start line.
+// @intent disambiguate overloaded or repeated declarations sharing the same qualified name.
 func annotationBindingKey(qualifiedName string, startLine int) string {
 	return qualifiedName + ":" + strconv.Itoa(startLine)
 }