docs(eval): annotate evaluation reports and queries

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

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

Author: tae2089

internal/cli/eval.go

@@ -1,3 +1,4 @@
+// @index CLI command for parser and search evaluation against golden corpora.
 package cli
 
 import (
@@ -13,6 +14,7 @@ import (
 	"github.com/tae2089/code-context-graph/internal/parse/treesitter"
 )
 
+// @intent expose parser and search evaluation workflows from the CLI with one shared command surface.
 func newEvalCmd(deps *Deps) *cobra.Command {
 	var corpusDir string
 	var suite string
@@ -54,6 +56,7 @@ func newEvalCmd(deps *Deps) *cobra.Command {
 	return cmd
 }
 
+// @intent adapt the configured search backend to the eval package's simple search callback contract.
 func makeSearchFn(ctx context.Context, deps *Deps) eval.SearchFunc {
 	return func(query string, limit int) ([]string, error) {
 		if deps.DB == nil || deps.SearchBackend == nil {
@@ -68,6 +71,7 @@ func makeSearchFn(ctx context.Context, deps *Deps) eval.SearchFunc {
 }
 
 // extToLangWalkers converts extension-keyed walkers (e.g. ".go") to language-keyed (e.g. "go").
+// @intent normalize parser walker lookup so eval suites can address languages consistently.
 func extToLangWalkers(walkers map[string]*treesitter.Walker) map[string]*treesitter.Walker {
 	if walkers == nil {
 		return nil
@@ -87,6 +91,7 @@ func extToLangWalkers(walkers map[string]*treesitter.Walker) map[string]*treesit
 	return result
 }
 
+// @intent convert search result nodes into stable eval comparison keys.
 func nodeToKeys(nodes []model.Node) []string {
 	keys := make([]string, len(nodes))
 	for i, n := range nodes {

internal/eval/metrics.go

@@ -1,7 +1,10 @@
+// @index Ranking and classification metrics for parser and search evaluation.
 package eval
 
 import "math"
 
+// ClassificationMetrics holds precision, recall, and F1 counts for one comparison.
+// @intent expose set-based scoring fields used by parser node and edge evaluation.
 type ClassificationMetrics struct {
 	TruePositive  int
 	FalsePositive int
@@ -11,6 +14,8 @@ type ClassificationMetrics struct {
 	F1            float64
 }
 
+// ComputeClassification computes set-based precision, recall, and F1 for expected versus actual keys.
+// @intent provide one reusable metric primitive for both parser node and edge evaluation.
 func ComputeClassification(expected, actual []string) ClassificationMetrics {
 	expectedSet := make(map[string]bool, len(expected))
 	for _, e := range expected {
@@ -48,6 +53,7 @@ func ComputeClassification(expected, actual []string) ClassificationMetrics {
 	return m
 }
 
+// @intent measure how many of the top-k ranked results are relevant.
 func PrecisionAtK(ranked []string, relevant map[string]bool, k int) float64 {
 	if k <= 0 || len(ranked) == 0 || len(relevant) == 0 {
 		return 0
@@ -65,6 +71,7 @@ func PrecisionAtK(ranked []string, relevant map[string]bool, k int) float64 {
 	return float64(hits) / float64(n)
 }
 
+// @intent measure how much of the relevant set appears within the top-k ranked results.
 func RecallAtK(ranked []string, relevant map[string]bool, k int) float64 {
 	if k <= 0 || len(ranked) == 0 || len(relevant) == 0 {
 		return 0
@@ -82,6 +89,7 @@ func RecallAtK(ranked []string, relevant map[string]bool, k int) float64 {
 	return float64(hits) / float64(len(relevant))
 }
 
+// @intent score the position of the first relevant result for ranking evaluation.
 func MRR(ranked []string, relevant map[string]bool) float64 {
 	for i, r := range ranked {
 		if relevant[r] {
@@ -91,6 +99,7 @@ func MRR(ranked []string, relevant map[string]bool) float64 {
 	return 0
 }
 
+// @intent compare ranked retrieval quality against an ideal ordering using discounted gain.
 func NDCG(ranked []string, relevant map[string]bool, k int) float64 {
 	if k <= 0 || len(relevant) == 0 {
 		return 0

internal/eval/parser.go

@@ -1,3 +1,4 @@
+// @index Golden corpus loading and normalization helpers for parser evaluation.
 package eval
 
 import (
@@ -9,6 +10,7 @@ import (
 	"github.com/tae2089/code-context-graph/internal/model"
 )
 
+// @intent load every language-specific golden corpus file from the eval corpus directory tree.
 func LoadGoldenDir(dir string) ([]GoldenCorpus, error) {
 	var corpora []GoldenCorpus
 	entries, err := os.ReadDir(dir)
@@ -45,6 +47,7 @@ func LoadGoldenDir(dir string) ([]GoldenCorpus, error) {
 	return corpora, nil
 }
 
+// @intent persist normalized parser output as a golden snapshot for future comparisons.
 func WriteGolden(path string, corpus GoldenCorpus) error {
 	data, err := json.MarshalIndent(corpus, "", "  ")
 	if err != nil {
@@ -53,6 +56,7 @@ func WriteGolden(path string, corpus GoldenCorpus) error {
 	return os.WriteFile(path, append(data, '\n'), 0o644)
 }
 
+// @intent project eval nodes into stable comparison keys for set-based metrics.
 func NodeKeys(nodes []EvalNode) []string {
 	keys := make([]string, len(nodes))
 	for i, n := range nodes {
@@ -61,6 +65,7 @@ func NodeKeys(nodes []EvalNode) []string {
 	return keys
 }
 
+// @intent project eval edges into stable comparison keys for set-based metrics.
 func EdgeKeys(edges []EvalEdge) []string {
 	keys := make([]string, len(edges))
 	for i, e := range edges {
@@ -69,6 +74,7 @@ func EdgeKeys(edges []EvalEdge) []string {
 	return keys
 }
 
+// @intent summarize parser accuracy for one language corpus by comparing expected and actual nodes and edges.
 func CompareCorpus(expected, actual GoldenCorpus) LanguageReport {
 	nodeMetrics := ComputeClassification(NodeKeys(expected.Nodes), NodeKeys(actual.Nodes))
 	edgeMetrics := ComputeClassification(EdgeKeys(expected.Edges), EdgeKeys(actual.Edges))
@@ -80,6 +86,7 @@ func CompareCorpus(expected, actual GoldenCorpus) LanguageReport {
 	}
 }
 
+// @intent normalize parsed graph nodes into corpus-stable eval records independent of absolute paths.
 func NormalizeNodes(nodes []model.Node, baseDir string) []EvalNode {
 	out := make([]EvalNode, 0, len(nodes))
 	for _, n := range nodes {
@@ -102,6 +109,7 @@ func NormalizeNodes(nodes []model.Node, baseDir string) []EvalNode {
 	return out
 }
 
+// @intent normalize parsed graph edges into corpus-stable eval records keyed by qualified names.
 func NormalizeEdges(edges []model.Edge, nodeMap map[uint]string) []EvalEdge {
 	out := make([]EvalEdge, 0, len(edges))
 	for _, e := range edges {

internal/eval/runner.go

@@ -1,3 +1,4 @@
+// @index Eval runner orchestration for parser and search benchmark suites.
 package eval
 
 import (
@@ -13,6 +14,8 @@ import (
 	"github.com/tae2089/code-context-graph/internal/parse/treesitter"
 )
 
+// RunOptions collects corpus paths, parser walkers, and output settings for one eval invocation.
+// @intent configure parser/search evaluation suites from CLI without leaking command details.
 type RunOptions struct {
 	CorpusDir string
 	Suite     string
@@ -23,6 +26,8 @@ type RunOptions struct {
 	Writer    io.Writer
 }
 
+// Run executes the requested evaluation suites and writes the chosen report format.
+// @intent provide one orchestration entry point for CLI-driven parser and search evaluation.
 func Run(ctx context.Context, opts RunOptions) (*Report, error) {
 	report := &Report{Suite: opts.Suite}
 
@@ -44,13 +49,15 @@ func Run(ctx context.Context, opts RunOptions) (*Report, error) {
 	return report, writeTable(opts.Writer, report)
 }
 
+// @intent route parser evaluation into update or comparison mode without duplicating top-level flow control.
 func runParserEval(ctx context.Context, opts RunOptions, report *Report) error {
 	if opts.Update {
 		return runParserUpdate(ctx, opts)
 	}
 	return runParserCompare(ctx, opts, report)
 }
 
+// @intent regenerate golden parser snapshots from the current parser implementation.
 func runParserUpdate(ctx context.Context, opts RunOptions) error {
 	entries, err := os.ReadDir(opts.CorpusDir)
 	if err != nil {
@@ -102,6 +109,7 @@ func runParserUpdate(ctx context.Context, opts RunOptions) error {
 	return nil
 }
 
+// @intent compare current parser output against stored golden corpora and accumulate language reports.
 func runParserCompare(ctx context.Context, opts RunOptions, report *Report) error {
 	corpora, err := LoadGoldenDir(opts.CorpusDir)
 	if err != nil {
@@ -158,6 +166,7 @@ func runParserCompare(ctx context.Context, opts RunOptions, report *Report) erro
 	return nil
 }
 
+// @intent run ranking metrics over the search corpus when a search backend is available.
 func runSearchEval(_ context.Context, opts RunOptions, report *Report) error {
 	queryPath := fmt.Sprintf("%s/queries.json", opts.CorpusDir)
 	qc, err := LoadQueryCorpus(queryPath)
@@ -177,6 +186,7 @@ func runSearchEval(_ context.Context, opts RunOptions, report *Report) error {
 	return nil
 }
 
+// @intent map parsed node IDs to qualified names so edge normalization can avoid DB lookups.
 func buildNodeMap(nodes []model.Node) map[uint]string {
 	m := make(map[uint]string, len(nodes))
 	for _, n := range nodes {
@@ -185,16 +195,19 @@ func buildNodeMap(nodes []model.Node) map[uint]string {
 	return m
 }
 
+// @intent centralize file reads used by parser evaluation so tests can characterize failures consistently.
 func readFileContent(path string) ([]byte, error) {
 	return os.ReadFile(path)
 }
 
+// @intent emit the eval report as pretty-printed JSON for machine consumption.
 func writeJSON(w io.Writer, report *Report) error {
 	enc := json.NewEncoder(w)
 	enc.SetIndent("", "  ")
 	return enc.Encode(report)
 }
 
+// @intent render a compact human-readable summary of parser and search evaluation metrics.
 func writeTable(w io.Writer, report *Report) error {
 	if len(report.Languages) > 0 {
 		fmt.Fprintf(w, "=== Parser Evaluation ===\n\n")

internal/eval/schema.go

@@ -1,5 +1,8 @@
+// @index Data schemas for parser golden corpora and search evaluation reports.
 package eval
 
+// EvalNode is the normalized parser node shape used in golden corpora.
+// @intent capture corpus-stable node identity independent of absolute paths.
 type EvalNode struct {
 	ID        string `json:"id"`
 	Kind      string `json:"kind"`
@@ -9,45 +12,61 @@ type EvalNode struct {
 	EndLine   int    `json:"end_line,omitempty"`
 }
 
+// Key derives a stable string key for node-level evaluation comparisons.
+// @intent provide a deterministic identifier for set-based parser metrics.
 func (n EvalNode) Key() string {
 	return n.Kind + ":" + n.Name + "@" + n.File
 }
 
+// EvalEdge is the normalized parser edge shape used in golden corpora.
+// @intent capture corpus-stable edge identity for parser comparisons.
 type EvalEdge struct {
 	Kind string `json:"kind"`
 	From string `json:"from"`
 	To   string `json:"to"`
 }
 
+// Key derives a stable string key for edge-level evaluation comparisons.
+// @intent provide a deterministic identifier for set-based parser metrics.
 func (e EvalEdge) Key() string {
 	return e.Kind + ":" + e.From + "->" + e.To
 }
 
+// GoldenCorpus stores one parser snapshot for a source file in a language corpus.
+// @intent persist expected parser output for regression comparison.
 type GoldenCorpus struct {
 	Language string     `json:"language"`
 	File     string     `json:"file"`
 	Nodes    []EvalNode `json:"nodes"`
 	Edges    []EvalEdge `json:"edges"`
 }
 
+// QueryCase defines one search evaluation query and its relevant expected results.
+// @intent describe a single ranked-retrieval test case for search evaluation.
 type QueryCase struct {
 	Query    string   `json:"query"`
 	Relevant []string `json:"relevant"`
 	K        int      `json:"k,omitempty"`
 }
 
+// QueryCorpus groups search evaluation cases loaded from one corpus directory.
+// @intent represent the full search evaluation suite as one loadable artifact.
 type QueryCorpus struct {
 	CorpusDir string      `json:"corpus_dir"`
 	Queries   []QueryCase `json:"queries"`
 }
 
+// LanguageReport summarizes parser accuracy metrics for one language corpus.
+// @intent expose per-language node and edge metrics in the eval report.
 type LanguageReport struct {
 	Language    string                `json:"language"`
 	NodeMetrics ClassificationMetrics `json:"node_metrics"`
 	EdgeMetrics ClassificationMetrics `json:"edge_metrics"`
 	Files       int                   `json:"files"`
 }
 
+// SearchReport holds aggregate ranking metrics across the search evaluation corpus.
+// @intent surface average P@K, recall, MRR, and nDCG over all search queries.
 type SearchReport struct {
 	QueriesTotal int     `json:"queries_total"`
 	AvgPAt1      float64 `json:"avg_p_at_1"`
@@ -58,6 +77,8 @@ type SearchReport struct {
 	AvgNDCGAt5   float64 `json:"avg_ndcg_at_5"`
 }
 
+// Report bundles parser and search evaluation output into one CLI-facing payload.
+// @intent represent the complete eval result returned to CLI and JSON consumers.
 type Report struct {
 	Suite     string           `json:"suite"`
 	Languages []LanguageReport `json:"languages,omitempty"`

internal/eval/search.go

@@ -1,12 +1,17 @@
+// @index Search evaluation corpus loading and ranking metric orchestration.
 package eval
 
 import (
 	"encoding/json"
 	"os"
 )
 
+// SearchFunc abstracts search execution so evaluation can run against any backend.
+// @intent decouple ranking metrics from concrete search implementations.
 type SearchFunc func(query string, limit int) ([]string, error)
 
+// LoadQueryCorpus loads search evaluation cases from a JSON corpus file.
+// @intent ingest the search query corpus before running ranking evaluation.
 func LoadQueryCorpus(path string) (QueryCorpus, error) {
 	data, err := os.ReadFile(path)
 	if err != nil {
@@ -19,6 +24,7 @@ func LoadQueryCorpus(path string) (QueryCorpus, error) {
 	return qc, nil
 }
 
+// @intent execute ranked retrieval metrics across all search evaluation cases.
 func EvaluateQueries(cases []QueryCase, searchFn SearchFunc) (SearchReport, error) {
 	if len(cases) == 0 {
 		return SearchReport{}, nil