note.proto

// API Protos for Code Notes.

syntax = "proto2";

package shipshape_proto;

option java_outer_classname = "NotesProto";
option java_package = "com.google.shipshape.proto";

import "shipshape/proto/textrange.proto";
import "shipshape/proto/source_context.proto";

// This proto defines a "Note", which will be used in external-facing APIs as
// the mechanism to return specific annotations about source code. Notes will be
// generated by analysis tools such as shipshape, or else by a tracking storage
// layer from dynamic data.

// A Note is an arbitrary annotation, attached to a location in a
// source file, an entire file, or a particular snapshot (e.g. associated with
// either a code review or a revision).
// Code Notes include (human) review comments, robot comments, and UI-visible
// annotations generated from dynamic information.
message Note {
  // An identifier for the category of this note (e.g. Lint).
  // Should be distinct and contain no spaces.
  // Pascalcase (e.g. ErrorProne) preferred.
  // TODO(supertri): How will we prevent duplicate category names?
  optional string category = 1;
  optional string subcategory = 2;

  // The location of the Note in the code for which the notes have been
  // requested.
  optional Location location = 3;

  // A short plain text human readable description of the Note.
  // For example "Line is greater than 80 characters" for a Lint warning,
  // the text of the code review comment, or "Error logged in production:
  // cannot connect to Foo" for a Note about dynamic logs data.
  optional string description = 4;

  // Optional link to more detailed information about the message or analyzer.
  optional string more_info = 5;

  // Additional category or environment specific data for the note.
  optional AdditionalData additional_data = 6;

  // Optional suggested fixes for the note. If multiple ones are present,
  // they should be ordered by descending preference.
  repeated Fix fix = 7;

  // Severity of the annotation, used to distinguish build/compiler
  // errors, i.e. where a binary fails to be built (BUILD_ERROR),
  // other actionable results (WARNING), and informational notes (OTHER).
  // TODO(supertri): Is there any other kind of prioritization we need?
  enum Severity {
    // Build did not succeed because of this issue.
    BUILD_ERROR = 1;
    // Actionable problem, e.g. that a developer needs to fix.
    WARNING = 2;

    // There are 3 possibilities in the Java library Diagnostic.Kind enum
    // in addition to WARNING and ERROR (one is called "OTHER").
    // This value gives a way to propagate these other diagnostic types with a
    // default label which avoids incorrectly marking them as one of the other
    // 2 categories.
    OTHER = 3;
  }

  // Severity of this note, e.g., a compiler diagnostic.
  // Distinguishes between Notes representing build errors or other actionable
  // problems, and informational Notes. Useful for UI because
  // different annotations may need various levels of attention from the user.
  optional Severity severity = 8 [default = WARNING];

}

// A location within a specific file, a single file, or a snapshot.
message Location {
  // The context in which to interpret the path and the range, e.g. the
  // location of a specific revision in a repo.
  // TODO(supertri): Replace with source API SourceContext proto when ready.
  optional source.v1.SourceContext source_context = 1;

  // A path of a file within the given context. If only context and path are
  // present, the location refers to an entire file or path.
  // If the path ends in "/" it indicates a directory, otherwise a file name.
  optional string path = 2;

  // A range within the given file. If a range is set, a path must also be set.
  optional shipshape_proto.TextRange range = 3;
}

// A suggested fix for a note.
message Fix {
  // An optional short human readable description that may be shown in a UI.
  optional string description = 1;

  // The context in which to interpret the path and the range inside the
  // replacement, e.g. the location of a specific revision in a repo.
  // Must match the source_context in the enclosing note.
  optional source.v1.SourceContext source_context = 2;

  // A delta to be applied to a specific file(s).
  // Replacements must be grouped by file and within the file ordered by
  // the range. Replacements for a given fix must not overlap.
  repeated Replacement replacement = 3;
}

// A replacement to be applied to a single location. The location of the
// Replacement may be an arbitrary file.
// Replacements are independent, that is if there are multiple ones touching
// the same file, the location always refers to the original file rather than
// the file with other Replacements applied.
message Replacement {
  // A path of a file within the given context. If only path is
  // present, the location refers to an entire file or path.
  // If the path ends in "/" it indicates a directory, otherwise a file name.
  optional string path = 1;

  // The range of text to replace with this fix; can be specified either with
  // bytes or lines.
  optional FixRange range = 2;

  // The new content to put in the given location. The length of the
  // replacement does not need to be identical with the text to be
  // replaced. The encoding must be the same as in the original file.
  optional string new_content = 3;
}

// Defines a range of lines or bytes in a text.
// Indexing starts at position 0, the start position is inclusive and the
// end position is exclusive.
message FixRange {
  message Position {
    // Positions can either be line-based or byte-based.
    // Offset is from the start of the file.
    optional uint32 line = 1;
    optional uint32 byte = 2;
  }
  // If the start position specifies the byte field, then the end position
  // also should.
  // Similarly, if the start position specifies the line field, then the end
  // position also should.
  // The start position (in either specification) must be less than or equal
  // to the end position.
  // Indexing starts at position 0, the start position is inclusive and the
  // end position is exclusive.
  optional Position start = 1;
  optional Position end = 2;
}

// A collection of fields containing additional category or environment-specific
// data.
message AdditionalData  {
  // The time this note was generated. Used to disambiguate when analysis tools
  // produce notes nondeterministically.
  optional uint64 generation_timestamp_millis = 1;
}