semantic/proto/code_analysis.proto

syntax = "proto3";

package github.semantic;

import "python_diff.proto";
import "ruby_diff.proto";
import "typescript_diff.proto";

import "types.proto";
import "terms.proto";
import "error_details.proto";

option java_package = "com.github.semantic.analysis";
option go_package = "github.com/semantic/analysis/;analysis";


// Semantic's CodeAnalysis service provides endpoints for parsing, analyzing, and
// comparing source code.
service CodeAnalysis {
  // Parsing
  //
  // Parse source code blobs and return abstract syntax trees as adjacency list graph.
  rpc ParseTreeGraph (ParseTreeRequest) returns (ParseTreeGraphResponse);
  // Parse source code blobs and return abstract syntax trees.
  rpc ParseTree (ParseTreeRequest) returns (ParseTreeResponse);

  // Diffing
  //
  // Summarize an AST diff of source blobs.
  rpc SummarizeDiff (SummarizeDiffRequest) returns (SummarizeDiffResponse);
  // Diff the ASTs of source blobs
  rpc DiffTree (DiffTreeRequest) returns (DiffTreeResponse);

  // Analyzing
  //
  // Calculate an import graph for a project.
  rpc GraphImports (ImportGraphRequest) returns (ImportGraphResponse);

  // Calculate a call graph for a project.
  rpc GraphCalls (CallGraphRequest) returns (CallGraphResponse);

  // Status and Health
  //
  // Check health & status of the service.
  rpc CheckHealth (HealthCheckRequest) returns (HealthCheckResponse);
}

// Term Requests and Responses
//
message ParseTreeRequest {
  repeated Blob blobs = 1;
}

// A ParseTreeResponse contains a list of syntax trees represented as adjacency
// graphs, one for each blob passed in the request.
message ParseTreeGraphResponse {
  // The list of graphs.
  repeated ParseTreeGraph graphs = 1;
  // Entire response failed (e.g. a timeout)
  DebugInfo error_info = 2;
}

message ParseTreeGraph {
  TermGraph graph = 1;
  string error = 2;
}

// A ParseTreeResponse contains a list of syntax trees, one for each blob passed
// in the request.
message ParseTreeResponse {
  // The list of trees.
  repeated ParseTree trees = 1;
  // Entire response failed (e.g. a timeout)
  DebugInfo error_info = 2;
}

// Diff Request & Responses
//
message SummarizeDiffRequest  {
  repeated BlobPair blobPairs = 1;
}

message SummarizeDiffResponse {
  repeated DiffSummary changes = 1;
  repeated ParseError errors = 2;
  DebugInfo error_info = 3;
}

message DiffTreeRequest  {
  repeated BlobPair blobPairs = 1;
}

message DiffTreeResponse {
  oneof response_type {
    RubyDiffResponse ruby = 1;
    PythonDiffResponse python = 2;
    TypeScriptDiffResponse typescript = 3;
  }
  DebugInfo error_info = 4;
}

message RubyDiffResponse {
  repeated rubydiff.RubyDiff diffs = 1;
}

message PythonDiffResponse {
  repeated pythondiff.PythonDiff diffs = 1;
}

message TypeScriptDiffResponse {
  repeated typescriptdiff.TypeScriptDiff diffs = 1;
}

message CallGraphRequest {
  Project project = 1;
}

message CallGraphResponse {
  ControlFlowGraph graph = 1;
  DebugInfo error_info = 2;
}

message ImportGraphRequest {
  Project project = 1;
}

message ImportGraphResponse {
  ControlFlowGraph graph = 1;
  DebugInfo error_info = 2;
}

message DiffSummary {
  string term = 1;
  string name = 2;
  Span span = 3;
  string change = 4;
}

message ParseError {
  string error = 1;
  Span span = 2;
  string language = 3;
}

message HealthCheckRequest {
  string service = 1;
}

message HealthCheckResponse {
  enum ServingStatus {
    UNKNOWN = 0;
    SERVING = 1;
    NOT_SERVING = 2;
  }
  ServingStatus status = 1;
}