// Copyright (c) 2015, the Dart project authors.  Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

/**
 * This file is an "idl" style description of the summary format.  It is not
 * executed directly; instead it is parsed and transformed into code that
 * implements the summary format.
 *
 * The code generation process introduces the following non-typical semantics:
 * - Fields of type List are never null, and have a default value of the empty
 *   list.
 * - Fields of type int are never null, and have a default value of zero.
 * - Fields of type String are never null, and have a default value of ''.
 * - Fields of type bool are never null, and have a default value of false.
 * - Fields whose type is an enum are never null, and have a default value of
 *   the first value declared in the enum.
 *
 * Terminology used in this document:
 * - "Unlinked" refers to information that can be determined from reading the
 *   .dart file for the library itself (including all parts) and no other
 *   files.
 * - "Prelinked" refers to information that can be determined from reading the
 *   unlinked information for the library itself and the unlinked information
 *   for all direct imports (plus the transitive closure of exports reachable
 *   from those direct imports).
 * - "Linked" refers to information that can be determined only from reading
 *   the unlinked and prelinked information for the library itself and the
 *   transitive closure of its imports.
 *
 * TODO(paulberry): currently the summary format only contains unlinked and
 * prelinked information.
 *
 * Except as otherwise noted, synthetic elements are not stored in the summary;
 * they are re-synthesized at the time the summary is read.
 */
library analyzer.tool.summary.idl;

/**
 * Annotation describing information which is not part of Dart semantics; in
 * other words, if this information (or any information it refers to) changes,
 * static analysis and runtime behavior of the library are unaffected.
 *
 * TODO(paulberry): some informative information is currently missing from the
 * summary format.
 */
const informative = null;

/**
 * Annotation describing information which is not part of the public API to a
 * library; in other words, if this information (or any information it refers
 * to) changes, libraries outside this one are unaffected.
 *
 * TODO(paulberry): currently the summary format does not contain private
 * information.
 */
const private = null;

/**
 * Information about a dependency that exists between one library and another
 * due to an "import" declaration.
 */
class PrelinkedDependency {
  /**
   * The relative URI used to import one library from the other.
   */
  String uri;
}

/**
 * Pre-linked summary of a library.
 */
class PrelinkedLibrary {
  /**
   * The unlinked library summary.
   */
  UnlinkedLibrary unlinked;

  /**
   * The libraries that this library depends on (either via an explicit import
   * statement or via the implicit dependencies on `dart:core` and
   * `dart:async`).  The first element of this array is a pseudo-dependency
   * representing the library itself (it is also used for "dynamic").
   *
   * TODO(paulberry): consider removing this entirely and just using
   * [UnlinkedLibrary.imports].
   */
  List<PrelinkedDependency> dependencies;

  /**
   * For each import in [UnlinkedLibrary.imports], an index into [dependencies]
   * of the library being imported.
   *
   * TODO(paulberry): if [dependencies] is removed, this can be removed as
   * well, since there will effectively be a one-to-one mapping.
   */
  List<int> importDependencies;

  /**
   * For each reference in [UnlinkedLibrary.references], information about how
   * that reference is resolved.
   */
  List<PrelinkedReference> references;
}

/**
 * Enum used to indicate the kind of entity referred to by a
 * [PrelinkedReference].
 */
enum PrelinkedReferenceKind {
  /**
   * The entity is a class or enum.
   */
  classOrEnum,

  /**
   * The entity is a typedef.
   */
  typedef,

  /**
   * The entity is a variable or executable.
   */
  other,

  /**
   * The entity being referred to does not exist.
   */
  unresolved
}

/**
 * Information about the resolution of an [UnlinkedReference].
 */
class PrelinkedReference {
  /**
   * Index into [UnlinkedLibrary.dependencies] indicating which imported library
   * declares the entity being referred to.
   */
  int dependency;

  /**
   * The kind of the entity being referred to.
   */
  PrelinkedReferenceKind kind;
}

/**
 * Unlinked summary information about a class declaration.
 */
class UnlinkedClass {
  /**
   * Name of the class.
   */
  String name;

  /**
   * Index into [UnlinkedLibrary.units] indicating which compilation unit the
   * class is declared in.
   */
  @informative
  int unit;

  /**
   * Type parameters of the class, if any.
   */
  List<UnlinkedTypeParam> typeParameters;

  /**
   * Supertype of the class, or `null` if either (a) the class doesn't
   * explicitly declare a supertype (and hence has supertype `Object`), or (b)
   * the class *is* `Object` (and hence has no supertype).
   */
  UnlinkedTypeRef supertype;

  /**
   * Mixins appering in a `with` clause, if any.
   */
  List<UnlinkedTypeRef> mixins;

  /**
   * Interfaces appearing in an `implements` clause, if any.
   */
  List<UnlinkedTypeRef> interfaces;

  /**
   * Field declarations contained in the class.
   */
  List<UnlinkedVariable> fields;

  /**
   * Executable objects (methods, getters, and setters) contained in the class.
   */
  List<UnlinkedExecutable> executables;

  /**
   * Indicates whether the class is declared with the `abstract` keyword.
   */
  bool isAbstract;

  /**
   * Indicates whether the class is declared using mixin application syntax.
   */
  bool isMixinApplication;
}

/**
 * Unlinked summary information about a `show` or `hide` combinator in an
 * import or export declaration.
 */
class UnlinkedCombinator {
  /**
   * List of names which are shown.  Empty if this is a `hide` combinator.
   */
  List<String> shows;

  /**
   * List of names which are hidden.  Empty if this is a `show` combinator.
   */
  List<String> hides;
}

/**
 * Unlinked summary information about an enum declaration.
 */
class UnlinkedEnum {
  /**
   * Name of the enum type.
   */
  String name;

  /**
   * Values listed in the enum declaration, in declaration order.
   */
  List<UnlinkedEnumValue> values;

  /**
   * Index into [UnlinkedLibrary.units] indicating which compilation unit the
   * enum is declared in.
   */
  @informative
  int unit;
}

/**
 * Unlinked summary information about a single enumerated value in an enum
 * declaration.
 */
class UnlinkedEnumValue {
  /**
   * Name of the enumerated value.
   */
  String name;
}

/**
 * Enum used to indicate the kind of an executable.
 */
enum UnlinkedExecutableKind {
  /**
   * Executable is a function or method.
   */
  functionOrMethod,

  /**
   * Executable is a getter.
   */
  getter,

  /**
   * Executable is a setter.
   */
  setter,

  /**
   * Executable is a constructor.
   */
  constructor
}

/**
 * Unlinked summary information about a function, method, getter, or setter
 * declaration.
 */
class UnlinkedExecutable {
  /**
   * Name of the executable.  For setters, this includes the trailing "=".  For
   * named constructors, this excludes the class name and excludes the ".".
   * For unnamed constructors, this is the empty string.
   */
  String name;

  /**
   * Index into [UnlinkedLibrary.units] indicating which compilation unit the
   * executable is declared in.  Zero for executables which are nested inside
   * another declaration (i.e. local functions and method declarations).
   */
  @informative
  int unit;

  /**
   * Type parameters of the executable, if any.  Empty if support for generic
   * method syntax is disabled.
   */
  List<UnlinkedTypeParam> typeParameters;

  /**
   * Declared return type of the executable.  Absent if the return type is
   * `void`.  Note that when strong mode is enabled, the actual return type may
   * be different due to type inference.
   */
  UnlinkedTypeRef returnType;

  /**
   * Parameters of the executable, if any.  Note that getters have no
   * parameters (hence this will be the empty list), and setters have a single
   * parameter.
   */
  List<UnlinkedParam> parameters;

  /**
   * The kind of the executable (function/method, getter, setter, or
   * constructor).
   */
  UnlinkedExecutableKind kind;

  /**
   * Indicates whether the executable is declared using the `abstract` keyword.
   */
  bool isAbstract;

  /**
   * Indicates whether the executable is declared using the `static` keyword.
   *
   * Note that for top level executables, this flag is false, since they are
   * not declared using the `static` keyword (even though they are considered
   * static for semantic purposes).
   */
  bool isStatic;

  /**
   * Indicates whether the executable is declared using the `const` keyword.
   */
  bool isConst;

  /**
   * Indicates whether the executable is declared using the `factory` keyword.
   */
  bool isFactory;
}

/**
 * Unlinked summary information about an export declaration.
 */
class UnlinkedExport {
  /**
   * URI used in the source code to reference the exported library.
   */
  String uri;

  /**
   * Combinators contained in this import declaration.
   */
  List<UnlinkedCombinator> combinators;
}

/**
 * Unlinked summary information about an import declaration.
 */
class UnlinkedImport {
  /**
   * URI used in the source code to reference the imported library.
   */
  String uri;

  /**
   * If [isImplicit] is false, offset of the "import" keyword.  If [isImplicit]
   * is true, zero.
   */
  @informative
  int offset;

  /**
   * Index into [UnlinkedLibrary.prefixes] of the prefix declared by this
   * import declaration, or zero if this import declaration declares no prefix.
   *
   * Note that multiple imports can declare the same prefix.
   */
  int prefix;

  /**
   * Combinators contained in this import declaration.
   */
  List<UnlinkedCombinator> combinators;

  /**
   * Indicates whether the import declaration uses the `deferred` keyword.
   */
  bool isDeferred;

  /**
   * Indicates whether the import declaration is implicit.
   */
  bool isImplicit;
}

/**
 * Unlinked summary of an entire library.
 */
class UnlinkedLibrary {
  /**
   * Top level and prefixed names referred to by this library.
   */
  List<UnlinkedReference> references;

  /**
   * Information about the units constituting this library.  The first unit
   * listed is always the defining compilation unit.
   */
  List<UnlinkedUnit> units;

  /**
   * Name of the library (from a "library" declaration, if present).
   */
  String name;

  /**
   * Classes declared in the library.
   */
  List<UnlinkedClass> classes;

  /**
   * Enums declared in the library.
   */
  List<UnlinkedEnum> enums;

  /**
   * Top level executable objects (functions, getters, and setters) declared in
   * the library.
   */
  List<UnlinkedExecutable> executables;

  /**
   * Export declarations in the library.
   */
  List<UnlinkedExport> exports;

  /**
   * Import declarations in the library.
   */
  List<UnlinkedImport> imports;

  /**
   * Typedefs declared in the library.
   */
  List<UnlinkedTypedef> typedefs;

  /**
   * Top level variables declared in the library.
   */
  List<UnlinkedVariable> variables;

  /**
   * Prefixes introduced by import declarations.  The first element in this
   * array is a pseudo-prefix used by references made with no prefix.
   */
  List<UnlinkedPrefix> prefixes;
}

/**
 * Enum used to indicate the kind of a parameter.
 */
enum UnlinkedParamKind {
  /**
   * Parameter is required.
   */
  required,

  /**
   * Parameter is positional optional (enclosed in `[]`)
   */
  positional,

  /**
   * Parameter is named optional (enclosed in `{}`)
   */
  named
}

/**
 * Unlinked summary information about a function parameter.
 */
class UnlinkedParam {
  /**
   * Name of the parameter.
   */
  String name;

  /**
   * If [isFunctionTyped] is `true`, the declared return type.  If
   * [isFunctionTyped] is `false`, the declared type.  Absent if
   * [isFunctionTyped] is `true` and the declared return type is `void`.  Note
   * that when strong mode is enabled, the actual type may be different due to
   * type inference.
   */
  UnlinkedTypeRef type;

  /**
   * If [isFunctionTyped] is `true`, the parameters of the function type.
   */
  List<UnlinkedParam> parameters;

  /**
   * Kind of the parameter.
   */
  UnlinkedParamKind kind;

  /**
   * Indicates whether this is a function-typed parameter.
   */
  bool isFunctionTyped;

  /**
   * Indicates whether this is an initializing formal parameter (i.e. it is
   * declared using `this.` syntax).
   */
  bool isInitializingFormal;
}

class UnlinkedPrefix {
  /**
   * The name of the prefix, or the empty string in the case of the
   * pseudo-prefix which represents "no prefix".
   */
  String name;
}

/**
 * Unlinked summary information about a name referred to in one library that
 * might be defined in another.
 */
class UnlinkedReference {
  /**
   * Name of the entity being referred to.
   */
  String name;

  /**
   * Prefix used to refer to the entity.  This is an index into
   * [UnlinkedLibrary.prefixes].
   */
  int prefix;
}

/**
 * Unlinked summary information about a typedef declaration.
 */
class UnlinkedTypedef {
  /**
   * Name of the typedef.
   */
  String name;

  /**
   * Index into [UnlinkedLibrary.units] indicating which compilation unit the
   * typedef is declared in.
   */
  @informative
  int unit;

  /**
   * Type parameters of the typedef, if any.
   */
  List<UnlinkedTypeParam> typeParameters;

  /**
   * Return type of the typedef.  Absent if the return type is `void`.
   */
  UnlinkedTypeRef returnType;

  /**
   * Parameters of the executable, if any.
   */
  List<UnlinkedParam> parameters;
}

/**
 * Unlinked summary information about a type parameter declaration.
 */
class UnlinkedTypeParam {
  /**
   * Name of the type parameter.
   */
  String name;

  /**
   * Bound of the type parameter, if a bound is explicitly declared.  Otherwise
   * null.
   */
  UnlinkedTypeRef bound;
}

/**
 * Unlinked summary information about a reference to a type.
 */
class UnlinkedTypeRef {
  /**
   * Index into [UnlinkedLibrary.references] for the type being referred to, or
   * zero if this is a reference to a type parameter.
   */
  int reference;

  /**
   * If this is a reference to a type parameter, one-based index into
   * [UnlinkedClass.typeParameters] or [UnlinkedTypedef.typeParameters] for the
   * parameter being referenced.  Otherwise zero.
   *
   * If generic method syntax is enabled, this may also be a one-based index
   * into [UnlinkedExecutable.typeParameters].  Note that this creates an
   * ambiguity since it allows executables with type parameters to be nested
   * inside other declarations with type parameters (which might themselves be
   * executables).  The ambiguity is resolved by considering this to be a
   * one-based index into a list that concatenates all type parameters that are
   * in scope, listing the outermost type parameters first.
   */
  int paramReference;

  /**
   * If this is an instantiation of a generic type, the type arguments used to
   * instantiate it.  Trailing type arguments of type `dynamic` are omitted.
   */
  List<UnlinkedTypeRef> typeArguments;
}

/**
 * Unlinked summary information about a compilation unit ("part file").  Note
 * that since a declaration can be moved from one part file to another without
 * changing semantics, the declarations themselves aren't stored here; they are
 * stored in [UnlinkedLibrary] and they refer to [UnlinkedUnit]s via an index
 * into [UnlinkedLibrary.units].
 */
class UnlinkedUnit {
  /**
   * String used in the defining compilation unit to reference the part file.
   * Empty for the defining compilation unit itself.
   */
  String uri;
}

/**
 * Unlinked summary information about a top level variable, local variable, or
 * a field.
 */
class UnlinkedVariable {
  /**
   * Name of the variable.
   */
  String name;

  /**
   * Index into [UnlinkedLibrary.units] indicating which compilation unit the
   * variable is declared in.  Zero for variables which are nested inside
   * another declaration (i.e. local variables and fields).
   */
  @informative
  int unit;

  /**
   * Declared type of the variable.  Note that when strong mode is enabled, the
   * actual type of the variable may be different due to type inference.
   */
  UnlinkedTypeRef type;

  /**
   * Indicates whether the variable is declared using the `static` keyword.
   *
   * Note that for top level variables, this flag is false, since they are not
   * declared using the `static` keyword (even though they are considered
   * static for semantic purposes).
   */
  bool isStatic;

  /**
   * Indicates whether the variable is declared using the `final` keyword.
   */
  bool isFinal;

  /**
   * Indicates whether the variable is declared using the `const` keyword.
   */
  bool isConst;
}