// Copyright 2017 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

syntax = "proto3";

import "recipe_engine/recipes_cfg.proto";

package recipe_engine;

// Doc is the namespace for all documentation messages. The messages here can be
// produced by the 'doc' subcommand.
//
// Messages in this namespace have some common fields:
//   name - the name of the object. Unless specified, this is the 'local' name,
//     or how you would refer to the object within the file.
//   relpath - the forward-slash-delimited path from the root of the repo to
//     this documented object.
//   lineno - the line number of this documented object within the file. Line
//     numbers start from 1.
//   docstring - the docstring of the item :). This should be pretty obvious.
//     check the comment in cases where it's not.
message Doc {
  message Known {
    // The url of the repo that this object comes from.
    string url = 1;

    oneof kind {
      Func func = 2;
      Class klass = 3; // class is reserved in python
    }

    message Object {
      oneof kind {
        // This is a string representation of the object.
        string generic = 1;

        // This can be looked up in the known_objects map.
        string known = 2;
      }
    }
  }

  // Schema defines a very simple recursive schema system used by the
  // recipe_engine. These correspond to types in the recipe_engine's config.py
  // file.
  //
  // These are named Schema instead of Config because they don't contain any
  // values (with the exception of defaults). At some point in the future the
  // schema and config concerns will be separated.
  message Schema {
    // These are the primitive allowed types. They correspond to the types
    // allowed by JSON.
    enum SimpleType {
      STRING = 0;
      NUMBER = 1;
      BOOLEAN = 2;
      OBJECT = 3;
      ARRAY = 4;
      NULL = 5;
    }

    // Struct defines a dictionary with a fixed set of keys, each of which has
    // a specific schema.
    message Struct {
      // A mapping of member to schema
      map<string, Schema> type_map = 1;
    }

    // Sequence defines a list of schema'd objects.
    //
    // Note this is currently equivalent to config.ConfigList.
    message Sequence {
      Schema inner_type = 1;
    }

    // List defines a list of simply-typed objects.
    message List {
      // The simple pythonic type that this list may contain. If specified
      // multiple times, the List may contain any of the types.
      repeated SimpleType inner_type = 1;
    }

    // Set defines a set() of simply-typed objects.
    message Set {
      // The simple pythonic type that this set may contain. If specified
      // multiple times, the Set may contain any of the types.
      repeated SimpleType inner_type = 1;
    }

    // Dict defines a mapping of string to simple type.
    message Dict {
      // The simple pythonic type that this dict may contain as values. If
      // specified multiple times, the Dict may contain any of the types.
      repeated SimpleType value_type = 1;
    }

    // Single defines a single value (non-collection) simple type.
    message Single {
      // The simple pythonic type that this value may contain. If
      // specified multiple times, the Single may contain any of the types.
      repeated SimpleType inner_type = 1;

      // Indicates that omitting this value is an error.
      bool required = 2;

      // The default value (as JSON) if the value for this is omitted.
      string default_json = 3;
    }

    // Static defines a single static piece of data.
    message Static {
      // The value of the Static (as JSON).
      string default_json = 1;
    }

    // Enum defines an element of the schema which must be one of a fixed set of
    // values.
    message Enum {
      // The JSON encoded list of accepted values.
      repeated string values_json = 1;

      // Indicates that omitting this value is an error.
      bool required = 2;
    }

    oneof kind {
      Struct struct = 1;
      Sequence sequence = 2;
      List list = 3;
      Set set = 4;
      Dict dict = 5;
      Single single = 6;
      Static static = 7;
      Enum enum = 8;
    }
  }


  // Documents one of the `DEPS = [...]` assignments which may show up in
  // a recipe file, or in a recipe module's __init__.py file.
  message Deps {
    string relpath = 1;
    int32 lineno = 2;

    // A simple tuple of repo_name and module name. This should be enough to
    // calculate a link to this module.
    message ModuleLink {
      string repo_name = 1;
      string name = 2;
    }

    // The list of recipe modules which are named in this Deps (e.g.
    // ModuleLink("recipe_engine", "path")).
    repeated ModuleLink module_links = 3;
  }

  // Parameter is the documentation for a single parameter (Property).
  message Parameter {
    // The docstring (e.g. the help param) of the parameter.
    string docstring = 1;

    // The schema for the data in this parameter.
    Schema kind = 2;

    // A JSON string which is the default value for this Parameter. If empty it
    // means that this Parameter is required.
    string default_json = 3;
  }

  // Parameters is the documentation for a PROPERTIES dictionary.
  message Parameters {
    string relpath = 1;
    int32 lineno = 2;

    // Mapping of parameter name (e.g. what the user would pass in the input
    // JSON) to parameter.
    map<string, Parameter> parameters = 3;
  }

  // Documentation for a regular python class.
  message Class {
    string name = 1;
    string relpath = 2;
    int32 lineno = 3;
    string docstring = 4;

    // The list of base classes this class has (if any). A base class may either
    // be 'known' or 'generic'. 'known' bases refer to classes defined in the
    // known_objects map.
    repeated Known.Object bases = 5;

    // a mapping of visible inner classes (e.g. class definitions nested within
    // this class).
    map<string, Class> classes = 6;

    // a mapping of visible methods in this class.
    map<string, Func> funcs = 7;
  }

  // Documentation for a regular python function.
  message Func {
    string name = 1;
    string relpath = 2;
    int32 lineno = 3;
    string docstring = 4;

    // The list of decorators this function has (if any). A decorator may either
    // be 'known' or 'generic'. 'known' decorators refer to decorators defined
    // in the known_objects map.
    repeated Known.Object decorators = 5;

    // The rendered python ast node for the whole function signature, e.g.:
    //   "arg, other_arg, default=True, **kwargs"
    string signature = 6;
  }

  // Documentation for a recipe module.
  message Module {
    // The unqualified name of this recipe module (e.g. "path")
    string name = 1;
    string relpath = 2;
    string docstring = 3;

    // The dependencies (other modules) for this module.
    Deps deps = 4;

    // The PARAMETERS (formerly known as PROPERTIES) for this module.
    Parameters parameters = 5;

    // The primary class (RecipeApi) for this module.
    Class api_class = 6;

    // Other classes defined in api.py
    map<string, Class> classes = 7;

    // Other functions defined in api.py
    map<string, Func> funcs = 8;

    // The claimed python version compatibility level of this module.
    string python_version_compatibility = 9;
  }

  // Documentation for a recipe.
  message Recipe {
    reserved  6; // ReturnSchema, was removed
    // the name of this recipe within this repo (e.g. 'foo')
    string name = 1;
    string relpath = 2;
    string docstring = 3;

    // dependencies (to recipe modules) this recipe has.
    Deps deps = 4;

    // the documentation for any PARAMETERS this recipe has.
    //
    // NOTE: these are currently called PROPERTIES, soon to be renamed.
    Parameters parameters = 5;

    // A mapping of visible class names to class documentation.
    map<string, Class> classes = 7;

    // A mapping of visible function names to function documentation. Excludes
    // GenTests function.
    map<string, Func> funcs = 8;

    // A map of known items (e.g. core portions of the recipe engine) to their
    // documentation.
    map<string, Known> known_objects = 9;

    // The claimed python version compatibility level of this recipe.
    string python_version_compatibility = 10;
  }

  // Documentation for a recipe repo, including docs for all recipes
  // and recipe_module's in that repo.
  message Repo {
    // This is the name of the repo that's being documented.
    string repo_name = 1;

    // This is a mapping from repo_name to RepoSpec, including the
    // spec for the main repo (as indicated by `repo_name`).
    //
    // Contains lots of goodies like the path within the repo to where the
    // recipes start, and the dependencies of the repos.
    map<string, recipe_engine.RepoSpec> specs = 2;

    // the full contents of the 'README.recipes.md' file at the base of the repo
    // plus recipe_root.
    string docstring = 3;

    // a map of all of this repo's recipe_module names to their documentation.
    map<string, Module> recipe_modules = 4;

    // a map of all of this repo's recipe names to their documentation.
    map<string, Recipe> recipes = 5;

    // A map of known items (e.g. core portions of the recipe engine) to their
    // documentation.
    map<string, Known> known_objects = 6;
  }
}