semantic/proto/code_analysis.proto

syntax = "proto3";

package github.semantic;

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, 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;
}

// 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;
}

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

message DiffTreeResponse {
  repeated DiffTree diffs = 1;
  DebugInfo error_info = 2;
}

// Diff summaries
message SummarizeDiffRequest  {
  repeated BlobPair blobPairs = 1;
}

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

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;
}

// Call Graphs
message CallGraphRequest {
  Project project = 1;
}

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

// Import Graphs
message ImportGraphRequest {
  Project project = 1;
}

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

// Health Check
message HealthCheckRequest {
  string service = 1;
}

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