Prevent duplication of top-level files under the root package in subtree builds

Author: tae2089

internal/wikiindex/builder.go

@@ -251,6 +251,9 @@ func (b *Builder) folderChildren(ctx context.Context, folderPath string) ([]*rag
 	}
 	entries := map[string]lazyEntry{}
 	for _, node := range nodes {
+		if node.Kind == model.NodeKindPackage && isRootPackagePath(node.FilePath) {
+			continue
+		}
 		childPath, immediate, ok := immediateChildPath(folderPath, node.FilePath)
 		if !ok {
 			continue
@@ -505,6 +508,13 @@ func immediateChildPath(parentPath, filePath string) (string, bool, bool) {
 	return childPath, len(parts) == 1, true
 }
 
+// @intent identify package nodes that represent the repository root rather than a sidebar child.
+// @domainRule the root package is folded into the Wiki root so top-level files are not duplicated under a synthetic "." package.
+func isRootPackagePath(filePath string) bool {
+	filePath = strings.Trim(path.Clean(filePath), "/")
+	return filePath == "." || filePath == ""
+}
+
 // @intent collect graph node IDs for batch annotation lookup.
 func nodeIDs(nodes []model.Node) []uint {
 	ids := make([]uint, 0, len(nodes))

internal/wikiindex/builder_test.go

@@ -221,6 +221,29 @@ func TestBuilder_BuildSubtreeReturnsBoundedLazyChildren(t *testing.T) {
 	}
 }
 
+func TestBuilder_BuildSubtreeDoesNotDuplicateTopLevelFilesUnderRootPackage(t *testing.T) {
+	db := setupDB(t)
+	createNode(t, db, model.Node{QualifiedName: "github.com/example/project", Kind: model.NodeKindPackage, Name: "project", FilePath: ".", StartLine: 1, EndLine: 1, Language: "go"})
+	createNode(t, db, model.Node{QualifiedName: "context.go", Kind: model.NodeKindFile, Name: "context.go", FilePath: "context.go", StartLine: 1, EndLine: 40, Language: "go"})
+	createNode(t, db, model.Node{QualifiedName: "trace.Context", Kind: model.NodeKindFunction, Name: "Context", FilePath: "context.go", StartLine: 10, EndLine: 20, Language: "go"})
+
+	builder := &wikiindex.Builder{DB: db, OutDir: "docs"}
+	root, err := builder.BuildSubtree(context.Background(), "", 1)
+	if err != nil {
+		t.Fatalf("BuildSubtree root: %v", err)
+	}
+	if pkg := ragindex.FindNode(root, "package:."); pkg != nil {
+		t.Fatalf("root package should be folded into root, got %#v", pkg)
+	}
+	fileNode := ragindex.FindNode(root, "file:context.go")
+	if fileNode == nil {
+		t.Fatalf("expected top-level file under root: %#v", root.Children)
+	}
+	if !fileNode.HasChildren || len(fileNode.Children) != 0 {
+		t.Fatalf("top-level file lazy state = %#v", fileNode)
+	}
+}
+
 func TestBuilder_RespectsExclude(t *testing.T) {
 	db := setupDB(t)
 	tmpDir := t.TempDir()