plugin.proto

// Copyright 2017 Google LLC. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// gnostic can be extended with plugins.
// A plugin is uset a program that reads a Request from stdin
// and writes a Response to stdout.
//
// A plugin executable needs only to be placed somewhere in the path.  The
// plugin should be named "gnostic_$NAME", and will then be used when the
// flag "--${NAME}_out" is passed to gnostic.

syntax = "proto3";

import "google/protobuf/any.proto";

package gnostic.plugin.v1;

// This option lets the proto compiler generate Java code inside the package
// name (see below) instead of inside an outer class. It creates a simpler
// developer experience by reducing one-level of name nesting and be
// consistent with most programming languages that don't support outer classes.
option java_multiple_files = true;

// The Java outer classname should be the filename in UpperCamelCase. This
// class is only used to hold proto descriptor, so developers don't need to
// work with it directly.
option java_outer_classname = "GnosticPlugin";

// The Java package name must be proto package name with proper prefix.
option java_package = "org.gnostic.v1";

// A reasonable prefix for the Objective-C symbols generated from the package.
// It should at a minimum be 3 characters long, all uppercase, and convention
// is to use an abbreviation of the package name. Something short, but
// hopefully unique enough to not conflict with things that may come along in
// the future. 'GPB' is reserved for the protocol buffer implementation itself.
//
option objc_class_prefix = "GNO";

// The Go package name.
option go_package = "./plugins;gnostic_plugin_v1";

// The version number of gnostic.
message Version {
  int32 major = 1;
  int32 minor = 2;
  int32 patch = 3;
  // A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should
  // be empty for mainline stable releases.
  string suffix = 4;
}

// A parameter passed to the plugin from (or through) gnostic.
message Parameter {
  // The name of the parameter as specified in the option string
  string name = 1;

  // The parameter value as specified in the option string
  string value = 2;
}

// An encoded Request is written to the plugin's stdin.
message Request {

  // filename or URL of the original source document
  string source_name = 1;

  // Output path specified in the plugin invocation.
  string output_path = 2;

  // Plugin parameters parsed from the invocation string.
  repeated Parameter parameters = 3;

  // The version number of gnostic.
  Version compiler_version = 4;

  // API models
  repeated google.protobuf.Any models = 5;
}

// Plugins can return messages to be collated and reported by gnostic.
message Message {

  enum Level {
    UNKNOWN = 0;
    INFO = 1;
    WARNING = 2;
    ERROR = 3;
    FATAL = 4;
  }

  // message severity
  Level level = 1;

  // a unique message identifier
  string code = 2;

  // message text
  string text = 3;

  // an associated key path in an API description
  repeated string keys = 4;
}

message Messages { repeated Message messages = 1; }

// The plugin writes an encoded Response to stdout.
message Response {

  // Error message.  If non-empty, the plugin failed.
  // The plugin process should exit with status code zero
  // even if it reports an error in this way.
  //
  // This should be used to indicate errors which prevent the plugin from
  // operating as intended.  Errors which indicate a problem in gnostic
  // itself -- such as the input Document being unparseable -- should be
  // reported by writing a message to stderr and exiting with a non-zero
  // status code.
  repeated string errors = 1;

  // file output, each file will be written by gnostic to an appropriate
  // location.
  repeated File files = 2;

  // informational messages to be collected and reported by gnostic.
  repeated Message messages = 3;
}

// File describes a file generated by a plugin.
message File {

  // name of the file
  string name = 1;

  // data to be written to the file
  bytes data = 2;
}