Grapher Output

Src will invoke the grapher, providing a JSON representation of a source unit (*unit.SourceUnit) in through stdin.

Output Schema

The output is a single JSON object with three fields that represent lists of Definitions, References, and Documentation data respectively. This should be printed to stdout.

type Output struct {
    Defs []*Def     `protobuf:"bytes,1,rep,name=defs" json:"Defs,omitempty"`
    Refs []*Ref     `protobuf:"bytes,2,rep,name=refs" json:"Refs,omitempty"`
    Docs []*Doc     `protobuf:"bytes,3,rep,name=docs" json:"Docs,omitempty"`
    Anns []*ann.Ann `protobuf:"bytes,4,rep,name=anns" json:"Anns,omitempty"`
}

Def Object Structure

// Def is a definition in code.
type Def struct {
    // 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 `protobuf:"bytes,1,opt,name=key,embedded=key" json:""`
    // Name of the definition. This need not be unique.
    Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"Name"`
    // Kind is the kind of thing this definition is. This is
    // language-specific. Possible values include "type", "func",
    // "var", etc.
    Kind     string `protobuf:"bytes,3,opt,name=kind,proto3" json:"Kind,omitempty"`
    File     string `protobuf:"bytes,4,opt,name=file,proto3" json:"File"`
    DefStart uint32 `protobuf:"varint,5,opt,name=start,proto3" json:"DefStart"`
    DefEnd   uint32 `protobuf:"varint,6,opt,name=end,proto3" json:"DefEnd"`
    // Exported is whether this def is part of a source unit's
    // public API. For example, in Java a "public" field is
    // Exported.
    Exported bool `protobuf:"varint,7,opt,name=exported,proto3" json:"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.
    Local bool `protobuf:"varint,8,opt,name=local,proto3" json:"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.
    Test bool `protobuf:"varint,9,opt,name=test,proto3" json:"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.
    Data sourcegraph_com_sqs_pbtypes.RawMessage `protobuf:"bytes,10,opt,name=data,proto3,customtype=sourcegraph.com/sqs/pbtypes.RawMessage" json:"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.
    Docs []*DefDoc `protobuf:"bytes,11,rep,name=docs" json:"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(/-[^/]*)*(/[^/-][^/]*)
    TreePath string `protobuf:"bytes,17,opt,name=tree_path,proto3" json:"TreePath,omitempty"`
}

Ref Object Structure

// Ref represents a reference from source code to a Def.
type Ref struct {
    // DefRepo is the repository URI of the Def that this Ref refers
    // to.
    DefRepo string `protobuf:"bytes,1,opt,name=def_repo,proto3" json:"DefRepo,omitempty"`
    // DefUnitType is the source unit type of the Def that this Ref refers to.
    DefUnitType string `protobuf:"bytes,3,opt,name=def_unit_type,proto3" json:"DefUnitType,omitempty"`
    // DefUnit is the name of the source unit that this ref exists in.
    DefUnit string `protobuf:"bytes,4,opt,name=def_unit,proto3" json:"DefUnit,omitempty"`
    // Path is the path of the Def that this ref refers to.
    DefPath string `protobuf:"bytes,5,opt,name=def_path,proto3" json:"DefPath"`
    // Repo is the VCS repository in which this ref exists.
    Repo string `protobuf:"bytes,6,opt,name=repo,proto3" json:"Repo,omitempty"`
    // CommitID is the ID of the VCS commit that this ref exists
    // in. The CommitID is always a full commit ID (40 hexadecimal
    // characters for git and hg), never a branch or tag name.
    CommitID string `protobuf:"bytes,7,opt,name=commit_id,proto3" json:"CommitID,omitempty"`
    // UnitType is the type name of the source unit that this ref
    // exists in.
    UnitType string `protobuf:"bytes,8,opt,name=unit_type,proto3" json:"UnitType,omitempty"`
    // Unit is the name of the source unit that this ref exists in.
    Unit string `protobuf:"bytes,9,opt,name=unit,proto3" json:"Unit,omitempty"`
    // Def is true if this Ref spans the name of the Def it points to.
    Def bool `protobuf:"varint,17,opt,name=def,proto3" json:"Def,omitempty"`
    // File is the filename in which this Ref exists.
    File string `protobuf:"bytes,10,opt,name=file,proto3" json:"File,omitempty"`
    // Start is the byte offset of this ref's first byte in File.
    Start uint32 `protobuf:"varint,11,opt,name=start,proto3" json:"Start"`
    // End is the byte offset of this ref's last byte in File.
    End uint32 `protobuf:"varint,12,opt,name=end,proto3" json:"End"`
}

Docs Object Structure

// Doc is documentation on a Def.
type Doc struct {
    // DefKey points to the Def that this documentation pertains to.
    DefKey `protobuf:"bytes,1,opt,name=key,embedded=key" json:""`
    // 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'.
    Format string `protobuf:"bytes,2,opt,name=format,proto3" json:"Format"`
    // Data is the actual documentation text.
    Data string `protobuf:"bytes,3,opt,name=data,proto3" json:"Data"`
    // File is the filename where this Doc exists.
    File string `protobuf:"bytes,4,opt,name=file,proto3" json:"File,omitempty"`
    // Start is the byte offset of this Doc's first byte in File.
    Start uint32 `protobuf:"varint,5,opt,name=start,proto3" json:"Start,omitempty"`
    // End is the byte offset of this Doc's last byte in File.
    End uint32 `protobuf:"varint,6,opt,name=end,proto3" json:"End,omitempty"`
}

Example: Grapher output on jashkenas/underscore

{
  "Defs": [
    {
      "Path": "commonjs/test/arrays.js",
      "TreePath": "-commonjs/test/arrays.js",
      "Kind": "module",
      "Exported": true,
      "Data": {
        "Kind": "commonjs-module",
        "Key": {
          "namespace": "commonjs",
          "module": "test/arrays.js",
          "path": ""
        },
        "jsgSymbolData": {
          "nodejs": {
            "moduleExports": true
          }
        },
        "Type": "{}",
        "IsFunc": false
      },
      "Name": "test/arrays",
      "File": "test/arrays.js",
      "DefStart": 0,
      "DefEnd": 0
    },
    ...
  ],
  "Refs" : [
    {
      "DefRepo": "",
      "DefUnitType": "",
      "DefUnit": "",
      "DefPath": "commonjs/underscore.js/-/union",
      "File": "test/arrays.js",
      "Start": 7610,
      "End": 7615
    },
    ...
  ],
  "Docs" : [
    {
      "Path": "commonjs/test/vendor/qunit.js/-/jsDump/parsers/functionArgs",
      "Format": "",
      "Data": "function calls it internally, it's the arguments part of the function"
    },
    ...
  ]