feat: add bounded pagination contracts across analysis and MCP

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

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

Author: tae2089

internal/analysis/changes/service.go

@@ -3,9 +3,11 @@ package changes
 
 import (
 	"context"
+	"sort"
 
 	"github.com/tae2089/code-context-graph/internal/ctxns"
 	"github.com/tae2089/code-context-graph/internal/model"
+	"github.com/tae2089/code-context-graph/internal/paging"
 	"gorm.io/gorm"
 )
 
@@ -32,6 +34,13 @@ type RiskEntry struct {
 	RiskScore float64
 }
 
+// Result carries one bounded page of risk entries plus pagination metadata.
+// @intent expose paged change-risk results while keeping legacy callers working with []RiskEntry.
+type Result struct {
+	Items      []RiskEntry
+	Pagination paging.Page
+}
+
 // Service coordinates git-based change detection and graph-backed scoring.
 // @intent identify changed nodes and score how risky they are to modify
 type Service struct {
@@ -66,7 +75,59 @@ func (s *Service) Analyze(ctx context.Context, repoDir, baseRef string) ([]RiskE
 		return nil, err
 	}
 
-	return computeRiskScores(s.db, ctx, hits)
+	risks, err := computeRiskScores(s.db, ctx, hits)
+	if err != nil {
+		return nil, err
+	}
+	sortRiskEntries(risks)
+	return risks, nil
+}
+
+// AnalyzePage detects changed functions and returns one bounded page of risk entries.
+// @intent push pagination into the change-risk service so handlers expose stable limit/offset windows.
+// @domainRule entries are sorted by descending risk_score, then file_path, then qualified_name for stable ordering.
+func (s *Service) AnalyzePage(ctx context.Context, repoDir, baseRef string, req paging.Request) (Result, error) {
+	normalized, err := paging.Normalize(req)
+	if err != nil {
+		return Result{}, err
+	}
+	all, err := s.Analyze(ctx, repoDir, baseRef)
+	if err != nil {
+		return Result{}, err
+	}
+	total := len(all)
+	if normalized.Offset >= total {
+		return Result{Items: []RiskEntry{}, Pagination: paging.BuildPage(normalized, 0, false)}, nil
+	}
+	end := normalized.Offset + normalized.Limit + 1
+	if end > total {
+		end = total
+	}
+	window := all[normalized.Offset:end]
+	hasMore := len(window) > normalized.Limit
+	if hasMore {
+		window = window[:normalized.Limit]
+	}
+	out := make([]RiskEntry, len(window))
+	copy(out, window)
+	return Result{Items: out, Pagination: paging.BuildPage(normalized, len(out), hasMore)}, nil
+}
+
+// sortRiskEntries orders entries deterministically for stable pagination windows.
+// @intent guarantee identical limit/offset slices regardless of map iteration order in computeRiskScores.
+func sortRiskEntries(entries []RiskEntry) {
+	sort.SliceStable(entries, func(i, j int) bool {
+		if entries[i].RiskScore != entries[j].RiskScore {
+			return entries[i].RiskScore > entries[j].RiskScore
+		}
+		if entries[i].Node.FilePath != entries[j].Node.FilePath {
+			return entries[i].Node.FilePath < entries[j].Node.FilePath
+		}
+		if entries[i].Node.StartLine != entries[j].Node.StartLine {
+			return entries[i].Node.StartLine < entries[j].Node.StartLine
+		}
+		return entries[i].Node.QualifiedName < entries[j].Node.QualifiedName
+	})
 }
 
 // collectDiffHunks retrieves changed files and their diff hunks from git,

internal/analysis/changes/service_test.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/tae2089/code-context-graph/internal/ctxns"
 	"github.com/tae2089/code-context-graph/internal/model"
+	"github.com/tae2089/code-context-graph/internal/paging"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 	gormlogger "gorm.io/gorm/logger"
@@ -204,3 +205,88 @@ func TestAnalyze_RespectsNamespace(t *testing.T) {
 		t.Errorf("expected FooA, got %s", got[0].Node.Name)
 	}
 }
+
+func TestAnalyzePage_AppliesLimitOffsetAndHasMore(t *testing.T) {
+	db := setupDB(t)
+	for i := 1; i <= 5; i++ {
+		seedNode(t, db, uint(i), fmt.Sprintf("Fn%d", i), fmt.Sprintf("f%d.go", i), 1, 50)
+	}
+
+	hunks := []Hunk{}
+	files := []string{}
+	for i := 1; i <= 5; i++ {
+		file := fmt.Sprintf("f%d.go", i)
+		files = append(files, file)
+		hunks = append(hunks, Hunk{FilePath: file, StartLine: 10, EndLine: 20})
+	}
+	for i := 1; i <= 5; i++ {
+		for j := 0; j < i; j++ {
+			seedEdge(t, db, uint(i), uint(100+j))
+		}
+	}
+
+	svc := New(db, &mockGit{files: files, hunks: hunks})
+
+	page1, err := svc.AnalyzePage(context.Background(), ".", "main", paging.Request{Limit: 2, Offset: 0})
+	if err != nil {
+		t.Fatalf("page1: %v", err)
+	}
+	if len(page1.Items) != 2 {
+		t.Fatalf("page1 items = %d, want 2", len(page1.Items))
+	}
+	if !page1.Pagination.HasMore {
+		t.Fatalf("page1 has_more = false, want true")
+	}
+	if page1.Items[0].RiskScore < page1.Items[1].RiskScore {
+		t.Fatalf("page1 not sorted by risk desc: %v", page1.Items)
+	}
+
+	page2, err := svc.AnalyzePage(context.Background(), ".", "main", paging.Request{Limit: 2, Offset: 2})
+	if err != nil {
+		t.Fatalf("page2: %v", err)
+	}
+	if len(page2.Items) != 2 {
+		t.Fatalf("page2 items = %d, want 2", len(page2.Items))
+	}
+	if !page2.Pagination.HasMore {
+		t.Fatalf("page2 has_more = false, want true")
+	}
+
+	page3, err := svc.AnalyzePage(context.Background(), ".", "main", paging.Request{Limit: 2, Offset: 4})
+	if err != nil {
+		t.Fatalf("page3: %v", err)
+	}
+	if len(page3.Items) != 1 {
+		t.Fatalf("page3 items = %d, want 1", len(page3.Items))
+	}
+	if page3.Pagination.HasMore {
+		t.Fatalf("page3 has_more = true, want false")
+	}
+}
+
+func TestAnalyzePage_RejectsLimitAboveMax(t *testing.T) {
+	db := setupDB(t)
+	svc := New(db, &mockGit{})
+	if _, err := svc.AnalyzePage(context.Background(), ".", "main", paging.Request{Limit: paging.MaxLimit + 1}); err == nil {
+		t.Fatal("expected error for over-max limit")
+	}
+}
+
+func TestAnalyzePage_OffsetBeyondTotalReturnsEmpty(t *testing.T) {
+	db := setupDB(t)
+	seedNode(t, db, 1, "Foo", "a.go", 10, 30)
+	svc := New(db, &mockGit{
+		files: []string{"a.go"},
+		hunks: []Hunk{{FilePath: "a.go", StartLine: 12, EndLine: 15}},
+	})
+	page, err := svc.AnalyzePage(context.Background(), ".", "main", paging.Request{Limit: 10, Offset: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 0 {
+		t.Fatalf("items = %d, want 0", len(page.Items))
+	}
+	if page.Pagination.HasMore {
+		t.Fatal("has_more = true, want false")
+	}
+}

internal/analysis/coupling/service.go

@@ -3,9 +3,11 @@ package coupling
 
 import (
 	"context"
+	"sort"
 
 	"github.com/tae2089/code-context-graph/internal/ctxns"
 	"github.com/tae2089/code-context-graph/internal/model"
+	"github.com/tae2089/code-context-graph/internal/paging"
 	"gorm.io/gorm"
 )
 
@@ -18,6 +20,13 @@ type CouplingPair struct {
 	Strength      float64
 }
 
+// Result carries one bounded page of coupling pairs plus pagination metadata.
+// @intent expose paged architecture-coupling results so MCP handlers stop slicing unbounded slices in memory.
+type Result struct {
+	Items      []CouplingPair
+	Pagination paging.Page
+}
+
 // Service analyzes architectural coupling from graph edges.
 // @intent measure dependency strength between detected communities
 type Service struct {
@@ -104,5 +113,53 @@ func (s *Service) Analyze(ctx context.Context) ([]CouplingPair, error) {
 		})
 	}
 
+	sortCouplingPairs(result)
 	return result, nil
 }
+
+// AnalyzePage returns one bounded page of coupling pairs.
+// @intent push pagination into the coupling service so handlers expose stable limit/offset windows without slicing unbounded slices.
+// @domainRule pairs are sorted by descending strength, then descending edge count, then from/to community for stable pagination.
+func (s *Service) AnalyzePage(ctx context.Context, req paging.Request) (Result, error) {
+	normalized, err := paging.Normalize(req)
+	if err != nil {
+		return Result{}, err
+	}
+	all, err := s.Analyze(ctx)
+	if err != nil {
+		return Result{}, err
+	}
+	total := len(all)
+	if normalized.Offset >= total {
+		return Result{Items: []CouplingPair{}, Pagination: paging.BuildPage(normalized, 0, false)}, nil
+	}
+	end := normalized.Offset + normalized.Limit + 1
+	if end > total {
+		end = total
+	}
+	window := all[normalized.Offset:end]
+	hasMore := len(window) > normalized.Limit
+	if hasMore {
+		window = window[:normalized.Limit]
+	}
+	out := make([]CouplingPair, len(window))
+	copy(out, window)
+	return Result{Items: out, Pagination: paging.BuildPage(normalized, len(out), hasMore)}, nil
+}
+
+// sortCouplingPairs orders pairs deterministically for stable pagination windows.
+// @intent guarantee identical limit/offset slices regardless of map iteration order in Analyze.
+func sortCouplingPairs(pairs []CouplingPair) {
+	sort.SliceStable(pairs, func(i, j int) bool {
+		if pairs[i].Strength != pairs[j].Strength {
+			return pairs[i].Strength > pairs[j].Strength
+		}
+		if pairs[i].EdgeCount != pairs[j].EdgeCount {
+			return pairs[i].EdgeCount > pairs[j].EdgeCount
+		}
+		if pairs[i].FromCommunity != pairs[j].FromCommunity {
+			return pairs[i].FromCommunity < pairs[j].FromCommunity
+		}
+		return pairs[i].ToCommunity < pairs[j].ToCommunity
+	})
+}

internal/analysis/coupling/service_test.go

@@ -7,6 +7,7 @@ import (
 	"testing"
 
 	"github.com/tae2089/code-context-graph/internal/model"
+	"github.com/tae2089/code-context-graph/internal/paging"
 	"gorm.io/driver/sqlite"
 	"gorm.io/gorm"
 	gormlogger "gorm.io/gorm/logger"
@@ -205,3 +206,80 @@ func TestAnalyze_NoCommunities(t *testing.T) {
 		t.Fatalf("expected 0, got %d", len(got))
 	}
 }
+
+func seedCrossPair(t *testing.T, db *gorm.DB, fromNode, toNode uint, count int, tag string) {
+	t.Helper()
+	for i := 0; i < count; i++ {
+		if err := db.Create(&model.Edge{FromNodeID: fromNode, ToNodeID: toNode, Kind: model.EdgeKindCalls, Fingerprint: fmt.Sprintf("%s-%d", tag, i)}).Error; err != nil {
+			t.Fatalf("seed edge: %v", err)
+		}
+	}
+}
+
+func TestAnalyzePage_AppliesLimitOffsetAndHasMore(t *testing.T) {
+	db := setupDB(t)
+	for i := uint(1); i <= 4; i++ {
+		seedNode(t, db, i, fmt.Sprintf("N%d", i), fmt.Sprintf("c%d/c.go", i))
+		seedCommunity(t, db, i, fmt.Sprintf("c%d", i), i)
+	}
+	seedCrossPair(t, db, 1, 2, 10, "ab")
+	seedCrossPair(t, db, 1, 3, 7, "ac")
+	seedCrossPair(t, db, 1, 4, 4, "ad")
+	seedCrossPair(t, db, 2, 3, 2, "bc")
+
+	svc := New(db)
+
+	page1, err := svc.AnalyzePage(context.Background(), paging.Request{Limit: 2, Offset: 0})
+	if err != nil {
+		t.Fatalf("page1: %v", err)
+	}
+	if len(page1.Items) != 2 {
+		t.Fatalf("page1 items=%d, want 2", len(page1.Items))
+	}
+	if !page1.Pagination.HasMore {
+		t.Fatalf("page1 has_more=false, want true")
+	}
+	if page1.Items[0].Strength < page1.Items[1].Strength {
+		t.Fatalf("page1 not sorted by strength desc: %+v", page1.Items)
+	}
+
+	page2, err := svc.AnalyzePage(context.Background(), paging.Request{Limit: 2, Offset: 2})
+	if err != nil {
+		t.Fatalf("page2: %v", err)
+	}
+	if len(page2.Items) != 2 {
+		t.Fatalf("page2 items=%d, want 2", len(page2.Items))
+	}
+	if page2.Pagination.HasMore {
+		t.Fatalf("page2 has_more=true, want false")
+	}
+}
+
+func TestAnalyzePage_RejectsLimitAboveMax(t *testing.T) {
+	db := setupDB(t)
+	svc := New(db)
+	if _, err := svc.AnalyzePage(context.Background(), paging.Request{Limit: paging.MaxLimit + 1}); err == nil {
+		t.Fatal("expected error for over-max limit")
+	}
+}
+
+func TestAnalyzePage_OffsetBeyondTotalReturnsEmpty(t *testing.T) {
+	db := setupDB(t)
+	seedNode(t, db, 1, "A1", "a/a.go")
+	seedNode(t, db, 2, "B1", "b/b.go")
+	seedCommunity(t, db, 1, "a", 1)
+	seedCommunity(t, db, 2, "b", 2)
+	seedCrossPair(t, db, 1, 2, 3, "ab")
+
+	svc := New(db)
+	page, err := svc.AnalyzePage(context.Background(), paging.Request{Limit: 10, Offset: 50})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(page.Items) != 0 {
+		t.Fatalf("items=%d, want 0", len(page.Items))
+	}
+	if page.Pagination.HasMore {
+		t.Fatal("has_more=true, want false")
+	}
+}