feat(wikiindex): expose DB wiki tree builder

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

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

Author: tae2089

internal/wikiindex/builder.go

@@ -37,6 +37,23 @@ type Builder struct {
 // @intent generate a UI-oriented tree independent of community detection and PageIndex retrieval.
 // @sideEffect reads graph tables and writes wiki-index.json.
 func (b *Builder) Build(ctx context.Context) (int, int, error) {
+	ns := b.namespace(ctx)
+	ctx = ctxns.WithNamespace(ctx, ns)
+	root, packages, files, err := b.BuildTree(ctx)
+	if err != nil {
+		return 0, 0, err
+	}
+	idx := &ragindex.Index{Version: 1, BuiltAt: time.Now().UTC(), Root: root}
+	if err := b.writeIndex(ns, idx); err != nil {
+		return 0, 0, err
+	}
+	return packages, files, nil
+}
+
+// BuildTree creates the browser-facing package/file/symbol Wiki tree without writing wiki-index.json.
+// @intent let runtime callers synthesize the same Wiki tree directly from DB rows when the JSON index has not been generated.
+// @ensures successful calls return deterministic folder/package/file/symbol ordering matching Build output.
+func (b *Builder) BuildTree(ctx context.Context) (*ragindex.TreeNode, int, int, error) {
 	ns := b.Namespace
 	if ns == "" {
 		ns = ctxns.FromContext(ctx)
@@ -45,10 +62,13 @@ func (b *Builder) Build(ctx context.Context) (int, int, error) {
 		ns = ctxns.DefaultNamespace
 	}
 	ctx = ctxns.WithNamespace(ctx, ns)
+	if b.DB == nil {
+		return nil, 0, 0, trace.New("DB not configured")
+	}
 
 	nodes, annByID, err := b.loadNodes(ctx)
 	if err != nil {
-		return 0, 0, err
+		return nil, 0, 0, err
 	}
 	root := &ragindex.TreeNode{ID: "root", Label: "Root", Kind: "root", Summary: b.ProjectDesc, Children: []*ragindex.TreeNode{}}
 	state := &treeState{
@@ -84,11 +104,19 @@ func (b *Builder) Build(ctx context.Context) (int, int, error) {
 	}
 
 	sortTree(root)
-	idx := &ragindex.Index{Version: 1, BuiltAt: time.Now().UTC(), Root: root}
-	if err := b.writeIndex(ns, idx); err != nil {
-		return 0, 0, err
+	return root, len(state.packages), len(state.files), nil
+}
+
+// @intent resolve the namespace used for both DB reads and wiki-index output paths.
+func (b *Builder) namespace(ctx context.Context) string {
+	ns := b.Namespace
+	if ns == "" {
+		ns = ctxns.FromContext(ctx)
+	}
+	if ns == "" {
+		ns = ctxns.DefaultNamespace
 	}
-	return len(state.packages), len(state.files), nil
+	return ns
 }
 
 // @intent load the graph node set needed for Wiki navigation and summaries.
@@ -126,7 +154,13 @@ func (b *Builder) loadNodes(ctx context.Context) ([]model.Node, map[uint]*model.
 	annByID := map[uint]*model.Annotation{}
 	if len(ids) > 0 {
 		var annotations []model.Annotation
-		if err := b.DB.WithContext(ctx).Where("node_id IN ?", ids).Preload("Tags").Find(&annotations).Error; err != nil {
+		if err := b.DB.WithContext(ctx).
+			Joins("JOIN nodes ON nodes.id = annotations.node_id").
+			Where("annotations.node_id IN ? AND nodes.namespace = ?", ids, ns).
+			Preload("Tags", func(db *gorm.DB) *gorm.DB {
+				return db.Order("ordinal ASC, id ASC")
+			}).
+			Find(&annotations).Error; err != nil {
 			return nil, nil, trace.Wrap(err, "load wiki annotations")
 		}
 		for i := range annotations {

internal/wikiindex/builder_test.go

@@ -2,7 +2,10 @@ package wikiindex_test
 
 import (
 	"context"
+	"errors"
 	"fmt"
+	"io/fs"
+	"os"
 	"path/filepath"
 	"testing"
 
@@ -107,6 +110,79 @@ func TestBuilder_BuildsPackageFileSymbolTree(t *testing.T) {
 	}
 }
 
+func TestBuilder_BuildTreeReturnsWikiTreeWithoutWritingIndex(t *testing.T) {
+	db := setupDB(t)
+	tmpDir := t.TempDir()
+
+	pkg := createNode(t, db, model.Node{QualifiedName: "github.com/example/project/internal/core", Kind: model.NodeKindPackage, Name: "core", FilePath: "internal/core", StartLine: 1, EndLine: 1, Language: "go"})
+	file := createNode(t, db, model.Node{QualifiedName: "internal/core/runtime.go", Kind: model.NodeKindFile, Name: "internal/core/runtime.go", FilePath: "internal/core/runtime.go", StartLine: 1, EndLine: 40, Language: "go"})
+	fn := createNode(t, db, model.Node{QualifiedName: "core.NewRuntime", Kind: model.NodeKindFunction, Name: "NewRuntime", FilePath: "internal/core/runtime.go", StartLine: 10, EndLine: 20, Language: "go"})
+	createTag(t, db, pkg.ID, model.TagIndex, "Core runtime package")
+	createTag(t, db, file.ID, model.TagIndex, "Runtime wiring")
+	createTag(t, db, fn.ID, model.TagIntent, "construct runtime")
+
+	builder := &wikiindex.Builder{DB: db, OutDir: "docs", IndexDir: filepath.Join(tmpDir, ".ccg")}
+	root, packages, files, err := builder.BuildTree(context.Background())
+	if err != nil {
+		t.Fatalf("BuildTree: %v", err)
+	}
+	if packages != 1 || files != 1 {
+		t.Fatalf("counts = packages:%d files:%d, want 1/1", packages, files)
+	}
+	if _, err := os.Stat(filepath.Join(tmpDir, ".ccg", "wiki-index.json")); !errors.Is(err, fs.ErrNotExist) {
+		t.Fatalf("BuildTree wrote wiki-index.json or stat failed: %v", err)
+	}
+	pkgNode := ragindex.FindNode(root, "package:internal/core")
+	if pkgNode == nil || pkgNode.Summary != "Core runtime package" {
+		t.Fatalf("package node = %#v", pkgNode)
+	}
+	fileNode := ragindex.FindNode(root, "file:internal/core/runtime.go")
+	if fileNode == nil || fileNode.DocPath != filepath.Join("docs", "internal/core/runtime.go.md") {
+		t.Fatalf("file node = %#v", fileNode)
+	}
+	symNode := ragindex.FindNode(root, "symbol:core.NewRuntime")
+	if symNode == nil || symNode.Details == nil || symNode.Details.QualifiedName != "core.NewRuntime" {
+		t.Fatalf("symbol node = %#v", symNode)
+	}
+}
+
+func TestBuilder_BuildTreeScopesAnnotationsAndOrdersTags(t *testing.T) {
+	db := setupDB(t)
+	alphaNode := createNode(t, db, model.Node{Namespace: "alpha", QualifiedName: "alpha.Build", Kind: model.NodeKindFunction, Name: "Build", FilePath: "internal/alpha/build.go", StartLine: 1, EndLine: 10, Language: "go"})
+	betaNode := createNode(t, db, model.Node{Namespace: "beta", QualifiedName: "beta.Build", Kind: model.NodeKindFunction, Name: "Build", FilePath: "internal/beta/build.go", StartLine: 1, EndLine: 10, Language: "go"})
+	createAnnotation(t, db, alphaNode.ID,
+		model.DocTag{Kind: model.TagSee, Value: "ccg://alpha/internal/alpha/build.go#Build", Ordinal: 2},
+		model.DocTag{Kind: model.TagIntent, Value: "alpha build intent", Ordinal: 0},
+		model.DocTag{Kind: model.TagDomainRule, Value: "alpha domain rule", Ordinal: 1},
+	)
+	createTag(t, db, betaNode.ID, model.TagIntent, "beta build intent")
+
+	root, _, _, err := (&wikiindex.Builder{DB: db, OutDir: "docs", Namespace: "alpha"}).BuildTree(context.Background())
+	if err != nil {
+		t.Fatalf("BuildTree: %v", err)
+	}
+	if ragindex.FindNode(root, "symbol:beta.Build") != nil {
+		t.Fatalf("beta namespace node leaked into alpha tree: %#v", root)
+	}
+	symNode := ragindex.FindNode(root, "symbol:alpha.Build")
+	if symNode == nil || symNode.Details == nil || symNode.Details.Annotation == nil {
+		t.Fatalf("missing alpha symbol annotation details: %#v", symNode)
+	}
+	gotKinds := []model.TagKind{}
+	for _, tag := range symNode.Details.Annotation.Tags {
+		gotKinds = append(gotKinds, tag.Kind)
+	}
+	wantKinds := []model.TagKind{model.TagIntent, model.TagDomainRule, model.TagSee}
+	if len(gotKinds) != len(wantKinds) {
+		t.Fatalf("tag kinds = %#v, want %#v", gotKinds, wantKinds)
+	}
+	for i := range wantKinds {
+		if gotKinds[i] != wantKinds[i] {
+			t.Fatalf("tag kinds = %#v, want %#v", gotKinds, wantKinds)
+		}
+	}
+}
+
 func TestBuilder_RespectsExclude(t *testing.T) {
 	db := setupDB(t)
 	tmpDir := t.TempDir()