kythe.io@v0.0.68-0.20240422202219-7225dbc01741/kythe/go/util/metadata/metadata.go

/*
 * Copyright 2017 The Kythe Authors. All rights reserved.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

// Package metadata provides support code for processing Kythe metadata
// records, of the type generated by instrumented code generators for
// cross-language linkage.
package metadata // import "kythe.io/kythe/go/util/metadata"

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"strconv"
	"strings"

	"kythe.io/kythe/go/util/schema/edges"

	"google.golang.org/protobuf/encoding/protojson"

	protopb "google.golang.org/protobuf/types/descriptorpb"
	spb "kythe.io/kythe/proto/storage_go_proto"
)

// TODO(fromberger): Add a link to the format documentation here.

// Rules are a collection of metadata rules.
type Rules []Rule

// MarshalJSON encodes the specified rule set as a JSON file.
func (rs Rules) MarshalJSON() ([]byte, error) {
	f := file{
		Type: fileType,
		Meta: make([]rule, len(rs)),
	}
	for i, r := range rs {
		kind := r.EdgeOut
		if r.Reverse {
			kind = edges.Mirror(kind)
		}
		rtype := "nop"
		if r.EdgeIn == edges.DefinesBinding {
			rtype = "anchor_defines"
		}
		var v json.RawMessage
		if r.VName != nil {
			var err error
			v, err = protojson.Marshal(r.VName)
			if err != nil {
				return nil, err
			}
		}
		f.Meta[i] = rule{
			Type:     rtype,
			Begin:    r.Begin,
			End:      r.End,
			VName:    v,
			Edge:     kind,
			Semantic: r.Semantic,
		}
	}
	return json.Marshal(f)
}

// Semantic is a reexport of protopb.GeneratedCodeInfo_Annotation_Semantic
type Semantic = protopb.GeneratedCodeInfo_Annotation_Semantic

// Reexport of the Semantic enum values
var (
	SemanticNone  Semantic = protopb.GeneratedCodeInfo_Annotation_NONE
	SemanticSet   Semantic = protopb.GeneratedCodeInfo_Annotation_SET
	SemanticAlias Semantic = protopb.GeneratedCodeInfo_Annotation_ALIAS
)

// A Rule denotes a single metadata rule, associating type linkage information
// for an anchor spanning a given range of text.
type Rule struct {
	// The Begin and End fields represent a half-closed interval of byte
	// positions to match. Begin is inclusive, End is exclusive.
	Begin, End int

	EdgeIn  string     // edge kind to match over the anchor spanned
	EdgeOut string     // outbound edge kind to emit
	VName   *spb.VName // the vname to create an edge to or from
	Reverse bool       // whether to draw to vname (false) or from it (true)

	Semantic *Semantic // whether to apply special semantics.
}

// The types below are intermediate structures used for JSON marshaling.

const fileType = "kythe0" // protocol marker

// A file represents an encoded set of rules in JSON notation.
type file struct {
	Type string `json:"type"` // required: must equal fileType
	Meta []rule `json:"meta,omitempty"`
}

// A rule is the encoded format of a single rule.
type rule struct {
	Type  string          `json:"type"`
	Begin int             `json:"begin"`
	End   int             `json:"end"`
	Edge  string          `json:"edge,omitempty"`
	VName json.RawMessage `json:"vname,omitempty"`

	Semantic *Semantic `json:"semantic,omitempty"`
}

// Parse parses a single JSON metadata object from r and returns the
// corresponding rules. It is an error if there are extra data after the
// metadata object, or if the type tag of the object does not match the current
// format code.
func Parse(r io.Reader) (Rules, error) {
	dec := json.NewDecoder(r)
	var f file
	if err := dec.Decode(&f); err != nil {
		return nil, fmt.Errorf("metadata: invalid file: %v", err)
	} else if _, err := dec.Token(); err != io.EOF {
		return nil, errors.New("metadata: extra junk at end of input")
	} else if f.Type != fileType {
		return nil, fmt.Errorf("metadata: wrong type tag: %q", f.Type)
	}

	rs := make(Rules, len(f.Meta))
	for i, meta := range f.Meta {
		var v *spb.VName
		if len(meta.VName) != 0 {
			var msg spb.VName
			if err := protojson.Unmarshal(meta.VName, &msg); err != nil {
				return nil, err
			}
			v = &msg
		}
		rs[i] = Rule{
			Begin:    meta.Begin,
			End:      meta.End,
			EdgeOut:  edges.Canonical(meta.Edge),
			Reverse:  edges.IsReverse(meta.Edge),
			VName:    v,
			Semantic: meta.Semantic,
		}
		switch t := meta.Type; t {
		case "nop":
			// ok, no special behaviour
		case "anchor_defines":
			rs[i].EdgeIn = edges.DefinesBinding
		default:
			return nil, fmt.Errorf("metadata: unknown rule type: %q", t)
		}
	}
	return rs, nil
}

// FromGeneratedCodeInfo constructs a set of rules from the corresponding
// protobuf descriptor message and the vname of the metadata file from which
// the generated descriptor was loaded.
func FromGeneratedCodeInfo(msg *protopb.GeneratedCodeInfo, vname *spb.VName) Rules {
	rs := make(Rules, len(msg.Annotation))
	for i, anno := range msg.Annotation {
		// Convert the path to a dot-separated string, e.g., 1.0.3.2,
		// for use in the vname signature.
		sig := make([]string, len(anno.Path))
		for i, elt := range anno.Path {
			sig[i] = strconv.Itoa(int(elt))
		}

		// TODO(fromberger): Work out how to derive the correct corpus and root
		// labels. When the protobuf source file is in the same corpus as its
		// metadata, this will work as-is.
		//
		// If the protobuf inputs live in a different corpus, it will be
		// necessary to make the extractor map the metadata file to the correct
		// corpus and root at build time. Since the metadata file does not get
		// pointed to directly, this ensures we get the right contact.
		//
		// This does NOT solve how to deal with generated .proto files, but
		// that is a much less common case, and we can address it separately.
		vname := &spb.VName{
			Corpus:    vname.GetCorpus(),
			Root:      vname.GetRoot(),
			Path:      anno.GetSourceFile(),
			Language:  "protobuf",
			Signature: strings.Join(sig, "."),
		}
		rs[i] = Rule{
			EdgeIn:   edges.DefinesBinding,
			EdgeOut:  edges.Generates,
			Reverse:  true,
			Begin:    int(anno.GetBegin()),
			End:      int(anno.GetEnd()),
			VName:    vname,
			Semantic: anno.Semantic,
		}
	}
	return rs
}