references.go

package codegraph

import (
	"context"
	"fmt"

	"github.com/compforge/codegraph/internal/analysis"
)

// A binding is located at a source use, even when other uses share its name.
// Owner participates in the key so a resolver cannot silently reparent a use.
type referenceKey struct {
	owner      analysis.Ref
	kind       RelationKind
	path       string
	start, end int
}

// publishReferences derives occurrence views directly from semantic evidence.
// +spec=Unpublished owners and import items do not change occurrence identity or binding.
func (a *graphAssembler) publishReferences(ctx context.Context) error {
	wanted := false
	for _, kind := range []NodeKind{CallSite, ReadSite, WriteSite, TypeUse, CaptureSite, ResourceUse, DecoratorUse} {
		if permits(a.opts.Admission, kind) {
			wanted = true
			break
		}
	}
	if !wanted {
		return nil
	}
	a.stage = "source-use"
	files, ids, nodes := a.files, a.ids, a.nodes
	bindings := map[referenceKey][]analysis.Edge{}
	for _, e := range a.index.Edges {
		switch RelationKind(e.Kind) {
		case Calls, Reads, Writes, UsesType, Captures, UsesResource, Extends, Implements, Decorates:
			key := referenceKey{e.Source, RelationKind(e.Kind), e.Path, e.Span.Start, e.Span.End}
			bindings[key] = append(bindings[key], e)
		}
	}
	addRelation := a.addRelation
	addReference := func(f analysis.Facts, kind RelationKind, name, receiver string, span analysis.Span, owner int, direct analysis.Ref, decorated int, resource *ResourceReference) error {
		if err := ctx.Err(); err != nil {
			return err
		}
		nodeKind := kind.OccurrenceKind()
		if nodeKind == "" || !permits(a.opts.Admission, nodeKind) {
			return nil
		}
		// Source identity depends on this occurrence, never on available targets
		// or precision, so supplementing documents does not rename existing uses.
		role := string(kind)
		if resource != nil {
			role = "resource"
		}
		id := "node:" + identity(f.Path, nodeKind, role, span.Start, span.End, name, receiver)
		if _, exists := nodes[id]; exists {
			return nil
		}

		ownerRef := analysis.SourceRef(f.Path, owner)
		parent := ids[ownerRef]
		if _, exists := a.index.Entities[ownerRef]; !exists {
			return fmt.Errorf("unpublished source-use owner: %s at %d", f.Path, span.Start)
		}
		loc := location(f, span)
		if err := a.addNode(Node{ID: id, Kind: nodeKind, ReferenceKind: ReferenceKind(kind), Name: name, Receiver: receiver, Resource: resource, Language: f.Language, Location: &loc}); err != nil {
			return err
		}
		a.references++
		if err := addRelation(Relation{Source: id, Target: parent, Kind: OccursIn, Location: loc,
			Confidence: Exact, Evidence: []Evidence{{Basis: "source_occurrence", Confidence: Exact}}}); err != nil {
			return err
		}
		if decorated >= 0 {
			if err := addRelation(Relation{Source: id, Target: ids[analysis.DeclarationRef(f.Path, decorated)], Kind: Decorates, Location: loc, Confidence: Exact, Evidence: []Evidence{{Basis: "source_modifier", Confidence: Exact}}}); err != nil {
				return err
			}
		}
		if direct != (analysis.Ref{}) {
			target := ids[direct]
			return addRelation(Relation{Source: id, Target: target, Kind: BindsTo, Location: loc, Confidence: Exact, Evidence: []Evidence{{Basis: "local_import_binding", Confidence: Exact}}})
		}
		key := referenceKey{ownerRef, kind, f.Path, span.Start, span.End}
		for _, binding := range bindings[key] {
			if resource != nil && !binding.Target.IsDocument() {
				continue
			}
			// Derive both graph views from the same resolver output. This is a
			// projection of evidence, never an independent name-based resolution.
			relation := a.relation(binding)
			relation.ID = ""
			relation.Source, relation.Kind = id, BindsTo
			if err := addRelation(relation); err != nil {
				return err
			}
		}
		return nil
	}
	for _, path := range sortedFiles(files) {
		f := files[path]
		for _, r := range f.ResourceReferences {
			resource := &ResourceReference{Expression: r.Expression, Path: r.Path}
			if err := addReference(f, UsesResource, r.Name, r.Receiver, r.Span, r.Owner, analysis.Ref{}, -1, resource); err != nil {
				return err
			}
		}
		for _, call := range f.Calls {
			if err := addReference(f, Calls, call.Name, call.Receiver, call.Span, analysis.EnclosingDeclaration(f, call.Span), directImport(a.index, f, call.Name, call.Receiver, call.Span, call.Imported), -1, nil); err != nil {
				return err
			}
		}
		for _, ref := range f.References {
			if !ref.Candidate(f) {
				continue
			}
			var kinds []RelationKind
			// A compound assignment or capture can establish several operations
			// at one token. The index, not a second resolver, owns that decision.
			for _, kind := range []RelationKind{Reads, Writes, UsesType, Captures, Decorates} {
				key := referenceKey{analysis.SourceRef(f.Path, ref.Owner), kind, f.Path, ref.Start, ref.End}
				if len(bindings[key]) > 0 {
					kinds = append(kinds, kind)
				}
			}
			if len(kinds) == 0 {
				switch ref.UseKind() {
				case analysis.NameUse, analysis.CompositeKeyUse:
					kinds = []RelationKind{Reads}
				case analysis.ReadWriteUse:
					kinds = []RelationKind{Reads, Writes}
				default:
					if ref.Kind.IsPublic() {
						kinds = []RelationKind{ref.Kind}
					}
				}
			}
			for _, kind := range kinds {
				decorated := -1
				if kind == Decorates {
					decorated = ref.Decorated
				}
				if err := addReference(f, kind, ref.Name, ref.Receiver, ref.Span, ref.Owner, directImport(a.index, f, ref.Name, ref.Receiver, ref.Span, !ref.Bound), decorated, nil); err != nil {
					return err
				}
			}
		}
		for _, hint := range f.TypeRelations {
			if err := addReference(f, RelationKind(hint.Kind), hint.Name, hint.Module, hint.Span, hint.Owner, directImport(a.index, f, hint.Name, hint.Module, hint.Span, !hint.Blocked), -1, nil); err != nil {
				return err
			}
		}
	}
	return nil
}

func directImport(index *analysis.Index, f analysis.Facts, name, receiver string, span analysis.Span, allowed bool) analysis.Ref {
	if allowed && receiver == "" {
		if ref, ok := analysis.LocalImport(f, name, span); ok {
			return ref
		}
		if f.Language == "go" {
			for i := range f.Imports {
				ref := analysis.ImportItemRef(f.Path, i, -1)
				item := index.Entities[ref]
				if item.Binding != nil && item.Binding.Form == "namespace" && item.Binding.LocalName == name {
					return ref
				}
			}
		}
	}
	return analysis.Ref{}
}