feat: add symbol-level nodes to RAG tree (root→community→file→symbol)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tae2089

internal/ragindex/builder.go

@@ -47,6 +47,13 @@ func (b *Builder) indexDir() string {
 	return b.IndexDir
 }
 
+// nodeInfo는 Builder 내부에서 노드의 파일 정보를 담는 구조체이다.
+type nodeInfo struct {
+	FilePath      string
+	Name          string
+	QualifiedName string
+}
+
 // Build는 DB에서 커뮤니티와 멤버 노드를 읽어 doc-index.json을 생성한다.
 // 반환값: (커뮤니티 수, 파일 수, 에러)
 func (b *Builder) Build() (int, int, error) {
@@ -59,30 +66,34 @@ func (b *Builder) Build() (int, int, error) {
 	}
 	slog.Debug("커뮤니티 로드 완료", "count", len(communities))
 
-	// 2. 1-pass: 모든 커뮤니티의 고유 파일 경로 수집
+	// 2. 1-pass: 모든 커뮤니티의 고유 node ID 수집
 	allNodeIDs := make([]uint, 0)
 	for _, comm := range communities {
 		for _, m := range comm.Members {
 			allNodeIDs = append(allNodeIDs, m.NodeID)
 		}
 	}
 
-	// 노드 ID → 파일 경로 매핑
-	nodeFileMap := make(map[uint]string)
+	// 노드 ID → nodeInfo 매핑
+	nodeInfoMap := make(map[uint]nodeInfo)
 	if len(allNodeIDs) > 0 {
 		var nodes []model.Node
 		if err := b.DB.Where("id IN ?", allNodeIDs).Find(&nodes).Error; err != nil {
 			return 0, 0, fmt.Errorf("load all nodes: %w", err)
 		}
 		for _, n := range nodes {
-			nodeFileMap[n.ID] = n.FilePath
+			nodeInfoMap[n.ID] = nodeInfo{
+				FilePath:      n.FilePath,
+				Name:          n.Name,
+				QualifiedName: n.QualifiedName,
+			}
 		}
 	}
 
 	// 고유 파일 경로 목록 수집
 	filePathSet := make(map[string]struct{})
-	for _, fp := range nodeFileMap {
-		filePathSet[fp] = struct{}{}
+	for _, info := range nodeInfoMap {
+		filePathSet[info.FilePath] = struct{}{}
 	}
 	allFilePaths := make([]string, 0, len(filePathSet))
 	for fp := range filePathSet {
@@ -95,6 +106,12 @@ func (b *Builder) Build() (int, int, error) {
 		return 0, 0, fmt.Errorf("batchFileSummaries: %w", err)
 	}
 
+	// 4. @intent 태그를 가진 symbol 노드 배치 조회
+	symbolsByFile, err := b.batchSymbolNodes(allNodeIDs, nodeInfoMap)
+	if err != nil {
+		return 0, 0, fmt.Errorf("batchSymbolNodes: %w", err)
+	}
+
 	root := &TreeNode{
 		ID:       "root",
 		Label:    "Root",
@@ -104,7 +121,7 @@ func (b *Builder) Build() (int, int, error) {
 
 	uniqueFiles := make(map[string]struct{})
 
-	// 4. 2-pass: 커뮤니티별 TreeNode 구성
+	// 5. 2-pass: 커뮤니티별 TreeNode 구성
 	for _, comm := range communities {
 		slog.Debug("커뮤니티 처리 중", "key", comm.Key, "members", len(comm.Members))
 
@@ -119,8 +136,8 @@ func (b *Builder) Build() (int, int, error) {
 			// 이 커뮤니티의 고유 파일 경로 수집
 			commFilePathSet := make(map[string]struct{})
 			for _, m := range comm.Members {
-				if fp, ok := nodeFileMap[m.NodeID]; ok {
-					commFilePathSet[fp] = struct{}{}
+				if info, ok := nodeInfoMap[m.NodeID]; ok {
+					commFilePathSet[info.FilePath] = struct{}{}
 				}
 			}
 			slog.Debug("파일 경로 그룹 완료", "community", comm.Key, "files", len(commFilePathSet))
@@ -134,7 +151,7 @@ func (b *Builder) Build() (int, int, error) {
 					Label:    filepath.Base(filePath),
 					Summary:  summary,
 					DocPath:  docPath,
-					Children: []*TreeNode{},
+					Children: symbolsByFile[filePath],
 				}
 				uniqueFiles[filePath] = struct{}{}
 				commNode.Children = append(commNode.Children, fileNode)
@@ -144,14 +161,14 @@ func (b *Builder) Build() (int, int, error) {
 		root.Children = append(root.Children, commNode)
 	}
 
-	// 5. Index 구조체 구성
+	// 6. Index 구조체 구성
 	idx := &Index{
 		Version: 1,
 		BuiltAt: time.Now().UTC(),
 		Root:    root,
 	}
 
-	// 6. doc-index.json 파일 기록 (원자적 쓰기)
+	// 7. doc-index.json 파일 기록 (원자적 쓰기)
 	if err := b.writeIndex(idx); err != nil {
 		return 0, 0, fmt.Errorf("writeIndex: %w", err)
 	}
@@ -219,6 +236,53 @@ func (b *Builder) batchFileSummaries(filePaths []string) (map[string]string, err
 }
 
 
+// batchSymbolNodes는 @intent 태그를 가진 노드를 filePath → []*TreeNode 맵으로 반환한다.
+// 노드당 첫 번째 @intent 값만 summary로 사용한다.
+func (b *Builder) batchSymbolNodes(nodeIDs []uint, infoMap map[uint]nodeInfo) (map[string][]*TreeNode, error) {
+	result := make(map[string][]*TreeNode)
+	if len(nodeIDs) == 0 {
+		return result, nil
+	}
+
+	type intentRow struct {
+		NodeID        uint
+		QualifiedName string
+		Name          string
+		FilePath      string
+		Value         string
+	}
+
+	var rows []intentRow
+	if err := b.DB.Table("nodes").
+		Select("nodes.id as node_id, nodes.qualified_name, nodes.name, nodes.file_path, doc_tags.value").
+		Joins("JOIN annotations ON annotations.node_id = nodes.id").
+		Joins("JOIN doc_tags ON doc_tags.annotation_id = annotations.id").
+		Where("nodes.id IN ? AND doc_tags.kind = ?", nodeIDs, string(model.TagIntent)).
+		Order("nodes.file_path ASC, doc_tags.ordinal ASC, doc_tags.id ASC").
+		Scan(&rows).Error; err != nil {
+		return nil, fmt.Errorf("batch symbol nodes: %w", err)
+	}
+
+	// 첫 번째 @intent 태그만 사용 (node_id 기준 deduplicate)
+	seen := make(map[uint]struct{})
+	for _, r := range rows {
+		if _, ok := seen[r.NodeID]; ok {
+			continue
+		}
+		seen[r.NodeID] = struct{}{}
+
+		symNode := &TreeNode{
+			ID:       fmt.Sprintf("symbol:%s", r.QualifiedName),
+			Label:    r.Name,
+			Summary:  r.Value,
+			Children: []*TreeNode{},
+		}
+		result[r.FilePath] = append(result[r.FilePath], symNode)
+	}
+
+	return result, nil
+}
+
 // docPath는 파일 경로를 기반으로 docs 디렉토리 내의 문서 경로를 반환한다.
 // 전체 상대 경로 구조를 유지하여 basename 충돌을 방지한다.
 // 예: "internal/mcp/handlers.go" → "docs/internal/mcp/handlers.go.md"

internal/ragindex/builder_test.go

@@ -385,6 +385,120 @@ func TestPruneTree_NilRoot(t *testing.T) {
 	}
 }
 
+// TestBuilder_SymbolNodes: @intent 태그를 가진 노드가 file 하위에 symbol 노드로 나타남을 검증한다.
+func TestBuilder_SymbolNodes(t *testing.T) {
+	db := setupDB(t)
+	tmpDir := t.TempDir()
+
+	// community 생성
+	comm := model.Community{Key: "auth", Label: "Auth Service", Description: "인증"}
+	if err := db.Create(&comm).Error; err != nil {
+		t.Fatalf("create community: %v", err)
+	}
+
+	// file 노드 생성 (community 멤버)
+	fileNode := model.Node{
+		QualifiedName: "internal/auth/handler.go",
+		Kind:          model.NodeKindFile,
+		Name:          "handler.go",
+		FilePath:      "internal/auth/handler.go",
+		StartLine:     1, EndLine: 100,
+		Language: "go",
+	}
+	if err := db.Create(&fileNode).Error; err != nil {
+		t.Fatalf("create file node: %v", err)
+	}
+	db.Create(&model.CommunityMembership{CommunityID: comm.ID, NodeID: fileNode.ID})
+
+	// function 노드 (같은 파일, community 멤버, @intent 태그 있음)
+	funcNode := model.Node{
+		QualifiedName: "internal/auth/handler.go/HandleLogin",
+		Kind:          model.NodeKindFunction,
+		Name:          "HandleLogin",
+		FilePath:      "internal/auth/handler.go",
+		StartLine:     10, EndLine: 30,
+		Language: "go",
+	}
+	if err := db.Create(&funcNode).Error; err != nil {
+		t.Fatalf("create func node: %v", err)
+	}
+	db.Create(&model.CommunityMembership{CommunityID: comm.ID, NodeID: funcNode.ID})
+
+	// @intent annotation + tag 생성
+	ann := model.Annotation{NodeID: funcNode.ID, Summary: "로그인 핸들러"}
+	db.Create(&ann)
+	db.Create(&model.DocTag{AnnotationID: ann.ID, Kind: model.TagIntent, Value: "로그인 요청을 처리하고 JWT를 반환한다", Ordinal: 0})
+
+	b := &ragindex.Builder{
+		DB:       db,
+		OutDir:   filepath.Join(tmpDir, "docs"),
+		IndexDir: tmpDir,
+	}
+	_, _, err := b.Build()
+	if err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+
+	idx, err := ragindex.LoadIndex(filepath.Join(tmpDir, "doc-index.json"))
+	if err != nil {
+		t.Fatalf("LoadIndex: %v", err)
+	}
+
+	// root → community → file → symbol 계층 확인
+	if len(idx.Root.Children) == 0 {
+		t.Fatal("expected community children")
+	}
+	commNode := idx.Root.Children[0]
+	if len(commNode.Children) == 0 {
+		t.Fatal("expected file children")
+	}
+	fileTreeNode := commNode.Children[0]
+	if len(fileTreeNode.Children) == 0 {
+		t.Fatal("expected symbol children under file node")
+	}
+	sym := fileTreeNode.Children[0]
+	if sym.ID != "symbol:internal/auth/handler.go/HandleLogin" {
+		t.Errorf("symbol ID = %q, want %q", sym.ID, "symbol:internal/auth/handler.go/HandleLogin")
+	}
+	if sym.Label != "HandleLogin" {
+		t.Errorf("symbol Label = %q, want %q", sym.Label, "HandleLogin")
+	}
+	if sym.Summary != "로그인 요청을 처리하고 JWT를 반환한다" {
+		t.Errorf("symbol Summary = %q", sym.Summary)
+	}
+	if sym.DocPath != "" {
+		t.Errorf("symbol DocPath should be empty, got %q", sym.DocPath)
+	}
+}
+
+// TestBuilder_NoSymbolsWithoutIntent: @intent 태그 없는 노드는 symbol 노드로 추가되지 않는다.
+func TestBuilder_NoSymbolsWithoutIntent(t *testing.T) {
+	db := setupDB(t)
+	tmpDir := t.TempDir()
+
+	comm := model.Community{Key: "core", Label: "Core"}
+	db.Create(&comm)
+	node := model.Node{QualifiedName: "core/utils.go/helper", Kind: model.NodeKindFunction, Name: "helper",
+		FilePath: "core/utils.go", StartLine: 1, EndLine: 5, Language: "go"}
+	db.Create(&node)
+	db.Create(&model.CommunityMembership{CommunityID: comm.ID, NodeID: node.ID})
+	// annotation 없음 → @intent 없음
+
+	b := &ragindex.Builder{DB: db, OutDir: filepath.Join(tmpDir, "docs"), IndexDir: tmpDir}
+	if _, _, err := b.Build(); err != nil {
+		t.Fatalf("Build: %v", err)
+	}
+
+	idx, _ := ragindex.LoadIndex(filepath.Join(tmpDir, "doc-index.json"))
+	if len(idx.Root.Children) == 0 || len(idx.Root.Children[0].Children) == 0 {
+		t.Fatal("expected file node")
+	}
+	fileNode := idx.Root.Children[0].Children[0]
+	if len(fileNode.Children) != 0 {
+		t.Errorf("expected 0 symbol children, got %d", len(fileNode.Children))
+	}
+}
+
 // TestFindNode: FindNode가 재귀적으로 트리에서 노드를 찾는지 검증한다.
 func TestFindNode(t *testing.T) {
 	root := &ragindex.TreeNode{