Code Graph in tatara-memory (sub-project A) Implementation Plan¶

package codegraph

import "testing"

func TestClampDepth(t *testing.T) {
    cases := []struct {
        name string
        in   int
        want int
    }{
        {"zero defaults", 0, defaultDepth},
        {"negative defaults", -3, defaultDepth},
        {"within range kept", 5, 5},
        {"over max clamped", 99, maxDepth},
        {"max kept", maxDepth, maxDepth},
    }
    for _, c := range cases {
        t.Run(c.name, func(t *testing.T) {
            if got := clampDepth(c.in); got != c.want {
                t.Fatalf("clampDepth(%d) = %d, want %d", c.in, got, c.want)
            }
        })
    }
}

func TestNormalizeDir(t *testing.T) {
    cases := map[string]string{
        "out": "out",
        "in":  "in",
        "":    "out",
        "OUT": "out",
        "bad": "out",
    }
    for in, want := range cases {
        if got := normalizeDir(in); got != want {
            t.Fatalf("normalizeDir(%q) = %q, want %q", in, got, want)
        }
    }
}

// Package codegraph stores and serves a deterministic code-structure graph
// (entities and edges) emitted by the repo ingester, scoped per repository and
// reconciled at file granularity.
package codegraph

import (
    "errors"
    "strings"
)

// ErrEntityNotFound is returned when a requested entity does not exist.
var ErrEntityNotFound = errors.New("codegraph: entity not found")

// ErrInvalidScope is returned when a push is malformed or contains an entity or
// edge whose owning file is not in the push's declared file set.
var ErrInvalidScope = errors.New("codegraph: invalid push scope")

// Relation constants used by the named-traversal endpoints. The producer
// (sub-project B) emits the full relation vocabulary; this service only needs
// the relations it groups into traversal sets.
const (
    relCalls        = "calls"
    relImports      = "imports"
    relReferences   = "references"
    relDependsOn    = "depends_on"
    relValueRef     = "value_ref"
    relIncludes     = "includes"
    relSubchart     = "subchart"
    relModuleSource = "module_source"
)

var (
    callRelations       = []string{relCalls}
    dependencyRelations = []string{relImports, relReferences, relDependsOn}
    resourceRelations   = []string{relDependsOn, relReferences, relValueRef, relIncludes, relSubchart, relModuleSource}
)

const (
    defaultDepth = 3
    maxDepth     = 10
)

// Entity is a node in the code graph (a package, type, function, resource,
// template, value key, file, or repo root). The ID is a canonical
// "<lang>:<kind>:<fqn>" string and is treated as opaque by the store.
type Entity struct {
    ID          string            `json:"id"`
    Name        string            `json:"name"`
    Type        string            `json:"type"`
    Description string            `json:"description,omitempty"`
    FilePath    string            `json:"file_path"`
    Properties  map[string]string `json:"properties,omitempty"`
}

// Edge is a directed, typed relationship between two entities. SrcFile is the
// file that owns the edge (where the reference originates) and is the unit of
// file-granular replacement.
type Edge struct {
    From       string            `json:"from"`
    To         string            `json:"to"`
    Relation   string            `json:"relation"`
    SrcFile    string            `json:"src_file"`
    Properties map[string]string `json:"properties,omitempty"`
}

// GraphPush is one ingest request: the changed file set plus the entities and
// edges those files own. Reconciliation deletes the prior graph owned by Files
// then inserts Entities and Edges, in one transaction.
type GraphPush struct {
    Repo     string   `json:"repo"`
    Commit   string   `json:"commit,omitempty"`
    Files    []string `json:"files"`
    Entities []Entity `json:"entities"`
    Edges    []Edge   `json:"edges"`
}

// PushResult summarises a completed reconciliation.
type PushResult struct {
    Repo             string `json:"repo"`
    Files            int    `json:"files"`
    EntitiesUpserted int    `json:"entities_upserted"`
    EdgesUpserted    int    `json:"edges_upserted"`
}

// EntityDetail is an entity plus its immediate outgoing and incoming edges.
type EntityDetail struct {
    Entity
    OutEdges []Edge `json:"out_edges"`
    InEdges  []Edge `json:"in_edges"`
}

// PathNode is an entity reached during a traversal, with the depth (>=1) at
// which it was first found.
type PathNode struct {
    Entity
    Depth int `json:"depth"`
}

func clampDepth(d int) int {
    if d <= 0 {
        return defaultDepth
    }
    if d > maxDepth {
        return maxDepth
    }
    return d
}

func normalizeDir(dir string) string {
    if strings.ToLower(dir) == "in" {
        return "in"
    }
    return "out"
}

package codegraph_test

import (
    "strings"
    "testing"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestMigrationSQLExists(t *testing.T) {
    sql := codegraph.MigrationSQL()
    for _, want := range []string{"code_entities", "code_edges", "CREATE TABLE IF NOT EXISTS"} {
        if !strings.Contains(sql, want) {
            t.Fatalf("migration SQL missing %q", want)
        }
    }
}

package codegraph

import (
    "context"
    "database/sql"
    _ "embed"
)

//go:embed migrations/0001_codegraph.sql
var migration0001 string

// MigrationSQL returns the DDL for the code-graph schema.
func MigrationSQL() string {
    return migration0001
}

// Migrate applies the code-graph schema to db, creating tables if they do not exist.
func Migrate(ctx context.Context, db *sql.DB) error {
    _, err := db.ExecContext(ctx, migration0001)
    return err
}

//go:build integration

package codegraph_test

import (
    "context"
    "database/sql"
    "os"
    "testing"

    _ "github.com/jackc/pgx/v5/stdlib"
    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func openPG(t *testing.T) *sql.DB {
    t.Helper()
    dsn := os.Getenv("TATARA_TEST_PG_DSN")
    if dsn == "" {
        t.Skip("TATARA_TEST_PG_DSN not set; skipping integration test")
    }
    db, err := sql.Open("pgx", dsn)
    require.NoError(t, err)
    t.Cleanup(func() { _ = db.Close() })
    return db
}

func freshStore(t *testing.T) (*codegraph.PGStore, context.Context) {
    t.Helper()
    ctx := context.Background()
    db := openPG(t)
    require.NoError(t, codegraph.Migrate(ctx, db))
    _, err := db.ExecContext(ctx, `DELETE FROM code_edges; DELETE FROM code_entities;`)
    require.NoError(t, err)
    return codegraph.NewPGStore(db), ctx
}

func ent(id, typ, file string) codegraph.Entity {
    return codegraph.Entity{ID: id, Name: id, Type: typ, FilePath: file, Properties: map[string]string{"language": "go"}}
}

func TestReconcileInsertsAndReplacesPerFile(t *testing.T) {
    s, ctx := freshStore(t)

    // Initial push: two files, two entities, one edge a->b owned by a.go.
    res, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:  "r",
        Files: []string{"a.go", "b.go"},
        Entities: []codegraph.Entity{
            ent("go:func:r/a.A", "go_func", "a.go"),
            ent("go:func:r/b.B", "go_func", "b.go"),
        },
        Edges: []codegraph.Edge{
            {From: "go:func:r/a.A", To: "go:func:r/b.B", Relation: "calls", SrcFile: "a.go"},
        },
    })
    require.NoError(t, err)
    require.Equal(t, 2, res.EntitiesUpserted)
    require.Equal(t, 1, res.EdgesUpserted)

    n, err := s.CountEntities(ctx, "r")
    require.NoError(t, err)
    require.Equal(t, 2, n)

    // Re-push only a.go: A now calls nothing. b.go and its entity untouched.
    _, err = s.Reconcile(ctx, codegraph.GraphPush{
        Repo:     "r",
        Files:    []string{"a.go"},
        Entities: []codegraph.Entity{ent("go:func:r/a.A", "go_func", "a.go")},
        Edges:    nil,
    })
    require.NoError(t, err)

    // b.go entity still present (not in the changed file set).
    n, err = s.CountEntities(ctx, "r")
    require.NoError(t, err)
    require.Equal(t, 2, n)

    // The a->b edge (owned by a.go) was removed.
    callees, err := s.Neighbors(ctx, "r", "go:func:r/a.A", []string{"calls"}, "out", 3)
    require.NoError(t, err)
    require.Empty(t, callees)
}

package codegraph

import "context"

// Store is the persistence interface for the code graph.
type Store interface {
    Reconcile(ctx context.Context, p GraphPush) (PushResult, error)
    SearchEntities(ctx context.Context, repo, q, typ string, limit int) ([]Entity, error)
    GetEntity(ctx context.Context, repo, id string) (EntityDetail, error)
    Neighbors(ctx context.Context, repo, id string, relations []string, dir string, depth int) ([]PathNode, error)
    FileImports(ctx context.Context, repo, path string) ([]Edge, error)
    CountEntities(ctx context.Context, repo string) (int, error)
}

package codegraph

import (
    "context"
    "database/sql"
    "encoding/json"
)

// PGStore is a PostgreSQL-backed implementation of Store.
type PGStore struct {
    db *sql.DB
}

// NewPGStore returns a PGStore backed by the given database connection.
func NewPGStore(db *sql.DB) *PGStore {
    return &PGStore{db: db}
}

func marshalProps(p map[string]string) string {
    if len(p) == 0 {
        return "{}"
    }
    b, err := json.Marshal(p)
    if err != nil {
        return "{}"
    }
    return string(b)
}

func scanProps(raw []byte) map[string]string {
    if len(raw) == 0 {
        return nil
    }
    var m map[string]string
    if err := json.Unmarshal(raw, &m); err != nil {
        return nil
    }
    return m
}

// Reconcile deletes the prior graph owned by p.Files then inserts p.Entities and
// p.Edges, all in a single transaction.
func (s *PGStore) Reconcile(ctx context.Context, p GraphPush) (PushResult, error) {
    tx, err := s.db.BeginTx(ctx, nil)
    if err != nil {
        return PushResult{}, err
    }
    defer func() { _ = tx.Rollback() }()

    for _, f := range p.Files {
        if _, err := tx.ExecContext(ctx, `DELETE FROM code_edges WHERE repo=$1 AND src_file=$2`, p.Repo, f); err != nil {
            return PushResult{}, err
        }
        if _, err := tx.ExecContext(ctx, `DELETE FROM code_entities WHERE repo=$1 AND file_path=$2`, p.Repo, f); err != nil {
            return PushResult{}, err
        }
    }

    for _, e := range p.Entities {
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO code_entities(repo, id, name, type, description, file_path, properties)
            VALUES ($1,$2,$3,$4,$5,$6,$7::jsonb)
            ON CONFLICT (repo, id) DO UPDATE SET
                name=EXCLUDED.name, type=EXCLUDED.type, description=EXCLUDED.description,
                file_path=EXCLUDED.file_path, properties=EXCLUDED.properties`,
            p.Repo, e.ID, e.Name, e.Type, e.Description, e.FilePath, marshalProps(e.Properties)); err != nil {
            return PushResult{}, err
        }
    }

    for _, e := range p.Edges {
        if _, err := tx.ExecContext(ctx, `
            INSERT INTO code_edges(repo, from_id, to_id, relation, src_file, properties)
            VALUES ($1,$2,$3,$4,$5,$6::jsonb)
            ON CONFLICT (repo, from_id, to_id, relation) DO UPDATE SET
                src_file=EXCLUDED.src_file, properties=EXCLUDED.properties`,
            p.Repo, e.From, e.To, e.Relation, e.SrcFile, marshalProps(e.Properties)); err != nil {
            return PushResult{}, err
        }
    }

    if err := tx.Commit(); err != nil {
        return PushResult{}, err
    }
    return PushResult{
        Repo:             p.Repo,
        Files:            len(p.Files),
        EntitiesUpserted: len(p.Entities),
        EdgesUpserted:    len(p.Edges),
    }, nil
}

// CountEntities returns the number of entities stored for a repo.
func (s *PGStore) CountEntities(ctx context.Context, repo string) (int, error) {
    var n int
    err := s.db.QueryRowContext(ctx, `SELECT count(*) FROM code_entities WHERE repo=$1`, repo).Scan(&n)
    return n, err
}

// SearchEntities is implemented in Task 4.
func (s *PGStore) SearchEntities(ctx context.Context, repo, q, typ string, limit int) ([]Entity, error) {
    return nil, nil
}

// GetEntity is implemented in Task 4.
func (s *PGStore) GetEntity(ctx context.Context, repo, id string) (EntityDetail, error) {
    return EntityDetail{}, ErrEntityNotFound
}

// Neighbors is implemented in Task 4.
func (s *PGStore) Neighbors(ctx context.Context, repo, id string, relations []string, dir string, depth int) ([]PathNode, error) {
    return nil, nil
}

// FileImports is implemented in Task 4.
func (s *PGStore) FileImports(ctx context.Context, repo, path string) ([]Edge, error) {
    return nil, nil
}

//go:build integration

package codegraph_test

import (
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

func TestReadMethods(t *testing.T) {
    s, ctx := freshStore(t)

    // A -> B -> C call chain (each owned by its own file), plus a dangling
    // edge C -> D where D was never inserted (orphan, must be filtered).
    _, err := s.Reconcile(ctx, codegraph.GraphPush{
        Repo:  "r",
        Files: []string{"a.go", "b.go", "c.go"},
        Entities: []codegraph.Entity{
            ent("go:func:r/a.A", "go_func", "a.go"),
            ent("go:func:r/b.B", "go_func", "b.go"),
            ent("go:func:r/c.C", "go_func", "c.go"),
        },
        Edges: []codegraph.Edge{
            {From: "go:func:r/a.A", To: "go:func:r/b.B", Relation: "calls", SrcFile: "a.go"},
            {From: "go:func:r/b.B", To: "go:func:r/c.C", Relation: "calls", SrcFile: "b.go"},
            {From: "go:func:r/c.C", To: "go:func:r/d.D", Relation: "calls", SrcFile: "c.go"},
        },
    })
    require.NoError(t, err)

    // SearchEntities by name fragment + type filter.
    found, err := s.SearchEntities(ctx, "r", "B", "go_func", 10)
    require.NoError(t, err)
    require.Len(t, found, 1)
    require.Equal(t, "go:func:r/b.B", found[0].ID)

    // GetEntity returns the entity plus its in/out edges.
    det, err := s.GetEntity(ctx, "r", "go:func:r/b.B")
    require.NoError(t, err)
    require.Equal(t, "go:func:r/b.B", det.ID)
    require.Len(t, det.OutEdges, 1) // B -> C
    require.Len(t, det.InEdges, 1)  // A -> B

    // GetEntity for a missing id is ErrEntityNotFound.
    _, err = s.GetEntity(ctx, "r", "go:func:r/nope")
    require.ErrorIs(t, err, codegraph.ErrEntityNotFound)

    // Callees of A to depth 3 = {B, C}; the orphan D is filtered out.
    out, err := s.Neighbors(ctx, "r", "go:func:r/a.A", []string{"calls"}, "out", 3)
    require.NoError(t, err)
    ids := map[string]int{}
    for _, n := range out {
        ids[n.ID] = n.Depth
    }
    require.Equal(t, 1, ids["go:func:r/b.B"])
    require.Equal(t, 2, ids["go:func:r/c.C"])
    require.NotContains(t, ids, "go:func:r/d.D")

    // Callers of C (direction in) to depth 3 = {B, A}.
    in, err := s.Neighbors(ctx, "r", "go:func:r/c.C", []string{"calls"}, "in", 3)
    require.NoError(t, err)
    inIDs := map[string]bool{}
    for _, n := range in {
        inIDs[n.ID] = true
    }
    require.True(t, inIDs["go:func:r/b.B"])
    require.True(t, inIDs["go:func:r/a.A"])

    // Depth 1 from A = {B} only.
    d1, err := s.Neighbors(ctx, "r", "go:func:r/a.A", []string{"calls"}, "out", 1)
    require.NoError(t, err)
    require.Len(t, d1, 1)
    require.Equal(t, "go:func:r/b.B", d1[0].ID)
}

// SearchEntities returns entities in repo matching an optional name/description
// fragment and optional exact type, ordered by name.
func (s *PGStore) SearchEntities(ctx context.Context, repo, q, typ string, limit int) ([]Entity, error) {
    rows, err := s.db.QueryContext(ctx, `
        SELECT id, name, type, description, file_path, properties
        FROM code_entities
        WHERE repo=$1
          AND ($2='' OR name ILIKE '%'||$2||'%' OR description ILIKE '%'||$2||'%')
          AND ($3='' OR type=$3)
        ORDER BY name
        LIMIT $4`, repo, q, typ, limit)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    var out []Entity
    for rows.Next() {
        e, err := scanEntity(rows)
        if err != nil {
            return nil, err
        }
        out = append(out, e)
    }
    return out, rows.Err()
}

// GetEntity returns one entity plus its immediate outgoing and incoming edges.
func (s *PGStore) GetEntity(ctx context.Context, repo, id string) (EntityDetail, error) {
    row := s.db.QueryRowContext(ctx, `
        SELECT id, name, type, description, file_path, properties
        FROM code_entities WHERE repo=$1 AND id=$2`, repo, id)
    e, err := scanEntity(row)
    if err != nil {
        if errors.Is(err, sql.ErrNoRows) {
            return EntityDetail{}, ErrEntityNotFound
        }
        return EntityDetail{}, err
    }
    out, err := s.queryEdges(ctx,
        `SELECT from_id, to_id, relation, src_file, properties FROM code_edges WHERE repo=$1 AND from_id=$2`,
        repo, id)
    if err != nil {
        return EntityDetail{}, err
    }
    in, err := s.queryEdges(ctx,
        `SELECT from_id, to_id, relation, src_file, properties FROM code_edges WHERE repo=$1 AND to_id=$2`,
        repo, id)
    if err != nil {
        return EntityDetail{}, err
    }
    return EntityDetail{Entity: e, OutEdges: out, InEdges: in}, nil
}

// neighborsOutQuery walks from->to (forward). neighborsInQuery walks to->from
// (reverse). Two fixed queries avoid building SQL by string concatenation
// (gosec G202). Orphan targets are dropped by the join to code_entities.
const neighborsOutQuery = `
    WITH RECURSIVE walk(id, depth) AS (
        SELECT $2::text, 0
        UNION
        SELECT e.to_id, w.depth + 1
        FROM walk w
        JOIN code_edges e ON e.repo=$1 AND e.from_id=w.id
         AND e.relation = ANY(string_to_array($3, ','))
        WHERE w.depth < $4
    )
    SELECT DISTINCT ON (en.id) en.id, en.name, en.type, en.description, en.file_path, en.properties, w.depth
    FROM walk w
    JOIN code_entities en ON en.repo=$1 AND en.id=w.id
    WHERE w.depth > 0
    ORDER BY en.id, w.depth`

const neighborsInQuery = `
    WITH RECURSIVE walk(id, depth) AS (
        SELECT $2::text, 0
        UNION
        SELECT e.from_id, w.depth + 1
        FROM walk w
        JOIN code_edges e ON e.repo=$1 AND e.to_id=w.id
         AND e.relation = ANY(string_to_array($3, ','))
        WHERE w.depth < $4
    )
    SELECT DISTINCT ON (en.id) en.id, en.name, en.type, en.description, en.file_path, en.properties, w.depth
    FROM walk w
    JOIN code_entities en ON en.repo=$1 AND en.id=w.id
    WHERE w.depth > 0
    ORDER BY en.id, w.depth`

// Neighbors walks edges of the given relations from id, in the given direction
// ("out" follows from->to, "in" follows to->from), up to depth hops.
func (s *PGStore) Neighbors(ctx context.Context, repo, id string, relations []string, dir string, depth int) ([]PathNode, error) {
    query := neighborsOutQuery
    if dir == "in" {
        query = neighborsInQuery
    }
    rows, err := s.db.QueryContext(ctx, query, repo, id, strings.Join(relations, ","), depth)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    var out []PathNode
    for rows.Next() {
        var n PathNode
        var raw []byte
        if err := rows.Scan(&n.ID, &n.Name, &n.Type, &n.Description, &n.FilePath, &raw, &n.Depth); err != nil {
            return nil, err
        }
        n.Properties = scanProps(raw)
        out = append(out, n)
    }
    return out, rows.Err()
}

// FileImports returns the import edges that originate in the given file.
func (s *PGStore) FileImports(ctx context.Context, repo, path string) ([]Edge, error) {
    return s.queryEdges(ctx,
        `SELECT from_id, to_id, relation, src_file, properties FROM code_edges WHERE repo=$1 AND src_file=$2 AND relation='imports'`,
        repo, path)
}

func (s *PGStore) queryEdges(ctx context.Context, query string, args ...any) ([]Edge, error) {
    rows, err := s.db.QueryContext(ctx, query, args...)
    if err != nil {
        return nil, err
    }
    defer func() { _ = rows.Close() }()
    return scanEdges(rows)
}

type rowScanner interface {
    Scan(dest ...any) error
}

func scanEntity(r rowScanner) (Entity, error) {
    var e Entity
    var raw []byte
    if err := r.Scan(&e.ID, &e.Name, &e.Type, &e.Description, &e.FilePath, &raw); err != nil {
        return Entity{}, err
    }
    e.Properties = scanProps(raw)
    return e, nil
}

func scanEdges(rows *sql.Rows) ([]Edge, error) {
    var out []Edge
    for rows.Next() {
        var e Edge
        var raw []byte
        if err := rows.Scan(&e.From, &e.To, &e.Relation, &e.SrcFile, &raw); err != nil {
            return nil, err
        }
        e.Properties = scanProps(raw)
        out = append(out, e)
    }
    return out, rows.Err()
}

package codegraph_test

import (
    "context"
    "testing"

    "github.com/prometheus/client_golang/prometheus"
    "github.com/stretchr/testify/require"

    "github.com/szymonrychu/tatara-memory/internal/codegraph"
)

type fakeStore struct {
    pushed   codegraph.GraphPush
    lastRel  []string
    lastDir  string
    lastDep  int
}

func (f *fakeStore) Reconcile(_ context.Context, p codegraph.GraphPush) (codegraph.PushResult, error) {
    f.pushed = p
    return codegraph.PushResult{Repo: p.Repo, Files: len(p.Files), EntitiesUpserted: len(p.Entities), EdgesUpserted: len(p.Edges)}, nil
}
func (f *fakeStore) SearchEntities(_ context.Context, _, _, _ string, _ int) ([]codegraph.Entity, error) {
    return nil, nil
}
func (f *fakeStore) GetEntity(_ context.Context, _, _ string) (codegraph.EntityDetail, error) {
    return codegraph.EntityDetail{}, nil
}
func (f *fakeStore) Neighbors(_ context.Context, _, _ string, relations []string, dir string, depth int) ([]codegraph.PathNode, error) {
    f.lastRel, f.lastDir, f.lastDep = relations, dir, depth
    return nil, nil
}
func (f *fakeStore) FileImports(_ context.Context, _, _ string) ([]codegraph.Edge, error) {
    return nil, nil
}
func (f *fakeStore) CountEntities(_ context.Context, _ string) (int, error) { return 0, nil }

func newSvc() (*codegraph.Service, *fakeStore) {
    fs := &fakeStore{}
    return codegraph.NewService(fs, codegraph.NewMetrics(prometheus.NewRegistry())), fs
}

func TestPushRejectsEntityOutsideFiles(t *testing.T) {
    svc, _ := newSvc()
    _, err := svc.Push(context.Background(), codegraph.GraphPush{
        Repo:     "r",
        Files:    []string{"a.go"},
        Entities: []codegraph.Entity{{ID: "x", FilePath: "b.go"}},
    })
    require.ErrorIs(t, err, codegraph.ErrInvalidScope)
}

func TestPushRejectsEdgeOutsideFiles(t *testing.T) {
    svc, _ := newSvc()
    _, err := svc.Push(context.Background(), codegraph.GraphPush{
        Repo:  "r",
        Files: []string{"a.go"},
        Edges: []codegraph.Edge{{From: "x", To: "y", Relation: "calls", SrcFile: "b.go"}},
    })
    require.ErrorIs(t, err, codegraph.ErrInvalidScope)
}

func TestPushRequiresRepoAndFiles(t *testing.T) {
    svc, _ := newSvc()
    _, err := svc.Push(context.Background(), codegraph.GraphPush{Repo: "", Files: []string{"a.go"}})
    require.ErrorIs(t, err, codegraph.ErrInvalidScope)
    _, err = svc.Push(context.Background(), codegraph.GraphPush{Repo: "r", Files: nil})
    require.ErrorIs(t, err, codegraph.ErrInvalidScope)
}

func TestPushOK(t *testing.T) {
    svc, fs := newSvc()
    res, err := svc.Push(context.Background(), codegraph.GraphPush{
        Repo:     "r",
        Files:    []string{"a.go"},
        Entities: []codegraph.Entity{{ID: "x", FilePath: "a.go"}},
        Edges:    []codegraph.Edge{{From: "x", To: "y", Relation: "calls", SrcFile: "a.go"}},
    })
    require.NoError(t, err)
    require.Equal(t, 1, res.EntitiesUpserted)
    require.Equal(t, "r", fs.pushed.Repo)
}

func TestNamedTraversalsUseCorrectRelationSets(t *testing.T) {
    svc, fs := newSvc()
    ctx := context.Background()

    _, _ = svc.Callers(ctx, "r", "id", 0)
    require.Equal(t, []string{"calls"}, fs.lastRel)
    require.Equal(t, "in", fs.lastDir)
    require.Equal(t, 3, fs.lastDep) // depth 0 -> default 3

    _, _ = svc.Callees(ctx, "r", "id", 50)
    require.Equal(t, "out", fs.lastDir)
    require.Equal(t, 10, fs.lastDep) // depth 50 -> clamped to max 10

    _, _ = svc.Dependents(ctx, "r", "id", 2)
    require.Equal(t, []string{"imports", "references", "depends_on"}, fs.lastRel)
    require.Equal(t, "in", fs.lastDir)

    _, _ = svc.ResourceGraph(ctx, "r", "id", 1)
    require.Equal(t, []string{"depends_on", "references", "value_ref", "includes", "subchart", "module_source"}, fs.lastRel)
    require.Equal(t, "out", fs.lastDir)
}