def.proto

syntax = "proto3";
package graph;

import "github.com/gogo/protobuf/gogoproto/gogo.proto";

option (gogoproto.goproto_getters_all) = false;
option (gogoproto.unmarshaler_all) = true;
option (gogoproto.marshaler_all) = true;
option (gogoproto.sizer_all) = true;

// DefKey specifies a definition, either concretely or abstractly. A concrete
// definition key has a non-empty CommitID and refers to a definition defined in a
// specific commit. An abstract definition key has an empty CommitID and is
// considered to refer to definitions from any number of commits (so long as the
// Repo, UnitType, Unit, and Path match).
//
// You can think of CommitID as the time dimension. With an empty CommitID, you
// are referring to a definition that may or may not exist at various times. With a
// non-empty CommitID, you are referring to a specific definition of a definition at
// the time specified by the CommitID.
message DefKey {
    // Repo is the VCS repository that defines this definition.
    string Repo = 1 [(gogoproto.jsontag) = "Repo,omitempty"];


    // CommitID is the ID of the VCS commit that this definition was defined in. The
    // CommitID is always a full commit ID (40 hexadecimal characters for git
    // and hg), never a branch or tag name.
    string CommitID = 2 [(gogoproto.jsontag) = "CommitID,omitempty"];

    // UnitType is the type name of the source unit (obtained from unit.Type(u))
    // that this definition was defined in.
    string UnitType = 3 [(gogoproto.jsontag) = "UnitType,omitempty"];

    // Unit is the name of the source unit (obtained from u.Name()) that this
    // definition was defined in.
    string Unit = 4 [(gogoproto.jsontag) = "Unit,omitempty"];

    // Path is a unique identifier for the def, relative to the source unit.
    // It should remain stable across commits as long as the def is the
    // "same" def. Its Elasticsearch mapping is defined separately (because
    // it is a multi_field, which the struct tag can't currently represent).
    //
    // Path encodes no structural semantics. Its only meaning is to be a stable
    // unique identifier within a given source unit. In many languages, it is
    // convenient to use the namespace hierarchy (with some modifications) as
    // the Path, but this may not always be the case. I.e., don't rely on Path
    // to find parents or children or any other structural propreties of the
    // def hierarchy). See Def.TreePath instead.
    string Path = 5 [(gogoproto.jsontag) = "Path"];
};

// Def is a definition in code.
message Def {
    // DefKey is the natural unique key for a def. It is stable
    // (subsequent runs of a grapher will emit the same defs with the same
    // DefKeys).
    DefKey Key = 1 [(gogoproto.nullable) = false, (gogoproto.embed) = true, (gogoproto.jsontag) = ""];

    // Name of the definition. This need not be unique.
    string Name = 2 [(gogoproto.jsontag) = "Name"];

    // Kind is the kind of thing this definition is. This is
    // language-specific. Possible values include "type", "func",
    // "var", etc.
    string Kind = 3 [(gogoproto.jsontag) = "Kind,omitempty"];
    string File = 4 [(gogoproto.jsontag) = "File"];
    uint32 DefStart = 5 [(gogoproto.jsontag) = "DefStart"];
    uint32 DefEnd = 6 [(gogoproto.jsontag) = "DefEnd"];

    // Exported is whether this def is part of a source unit's
    // public API. For example, in Java a "public" field is
    // Exported.
    bool Exported = 7 [(gogoproto.jsontag) = "Exported,omitempty"];

    // Local is whether this def is local to a function or some
    // other inner scope. Local defs do *not* have module,
    // package, or file scope. For example, in Java a function's
    // args are Local, but fields with "private" scope are not
    // Local.
    bool Local = 8 [(gogoproto.jsontag) = "Local,omitempty"];

    // Test is whether this def is defined in test code (as opposed to main
    // code). For example, definitions in Go *_test.go files have Test = true.
    bool Test = 9 [(gogoproto.jsontag) = "Test,omitempty"];

    // Data contains additional language- and toolchain-specific information
    // about the def. Data is used to construct function signatures,
    // import/require statements, language-specific type descriptions, etc.
    bytes Data = 10 [(gogoproto.casttype) = "sourcegraph.com/sqs/pbtypes.RawMessage", (gogoproto.jsontag) = "Data,omitempty"];

    // Docs are docstrings for this Def. This field is not set in the
    // Defs produced by graphers; they should emit docs in the
    // separate Docs field on the graph.Output struct.
    repeated DefDoc Docs = 11 [(gogoproto.jsontag) = "Docs,omitempty"];

    // TreePath is a structurally significant path descriptor for a def. For
    // many languages, it may be identical or similar to DefKey.Path.
    // However, it has the following constraints, which allow it to define a
    // def tree.
    //
    // A tree-path is a chain of '/'-delimited components. A component is either a
    // def name or a ghost component.
    // - A def name satifies the regex [^/-][^/]*
    // - A ghost component satisfies the regex -[^/]*
    // Any prefix of a tree-path that terminates in a def name must be a valid
    // tree-path for some def.
    // The following regex captures the children of a tree-path X: X(/-[^/]*)*(/[^/-][^/]*)
    string TreePath = 17 [(gogoproto.jsontag) = "TreePath,omitempty"];
};

// DefDoc is documentation on a Def.
message DefDoc {
    // Format is the the MIME-type that the documentation is stored
    // in. Valid formats include 'text/html', 'text/plain',
    // 'text/x-markdown', text/x-rst'.
    string Format = 1 [(gogoproto.jsontag) = "Format"];

    // Data is the actual documentation text.
    string Data = 2 [(gogoproto.jsontag) = "Data"];
};

// DefFormatStrings contains the various def format strings.
message DefFormatStrings {
	QualFormatStrings Name = 1 [(gogoproto.nullable) = false];
	QualFormatStrings Type = 2 [(gogoproto.nullable) = false];
	string NameAndTypeSeparator = 3;
	string Language = 4;
	string DefKeyword = 5;
	string Kind = 6;
}

// QualFormatStrings holds the formatted string for each Qualification for a def
// (for either Name or Type).
message QualFormatStrings {
	string Unqualified = 1;
	string ScopeQualified = 2;
	string DepQualified = 3;
	string RepositoryWideQualified = 4;
	string LanguageWideQualified = 5;
}