defmodule OpenAPI.Config do
  @moduledoc """
  Configuration for the code generator

  ## Configuration

  This section is an overview of the available configuration options. For a more in-depth discussion
  of output module naming, see **Naming** below. See also type `t:t()` below for the exact type
  specification of each option.

  * `base_location` (string, **required**): Relative path (from the base of the Mix project where
    the code generator is run) to output files. When creating a standalone client library, this
    will often be `lib/`.

  * `base_module` (module, **required**): Base module for all output files. For example, a base
    module of `Example` will output schemas like `Example.MySchema` and operation files like
    `Example.MyOperations`. When outputting a standalone client library, this will often be the
    base module of the library.

  * `default_client` (module): Module to call when making a web request. This code generator has
    no opinion on how HTTP requests are made. Instead, you must provide a client module that
    implements a `request/1` function and performs the request and decodes the response. By default,
    a module `[base_module].Client` will be used.

  * `group` (list of modules): Namespaces to use when grouping modules. For example, two schemas
    `SchemaOne` and `SchemaTwo` grouped by the `Schema` module would become `Schema.One` and
    `Schema.Two`. Defaults to no grouping.

  * `ignore` (list of modules, strings, or regular expressions): Schemas to ignore when outputting
    well-defined Elixir structs. Schemas that are ignored will be replaced with a `map` type when
    referenced elsewhere in the code. When provided as a module or string, the ignore pattern must
    **exactly** match the name of the schema **after any merges**. Defaults to no schemas ignored.

  * `merge` (list of two-tuples): Source and destination modules for schemas that should be merged
    into a single file. See **Merging** below for examples. Defaults to no schemas merged.

  * `operation_location` (string): Relative path, after the `base_location`, to output operation
    files. This may useful if you want to hide generated operation files in a subdirectory of a
    larger project. Defaults to outputting operation files to the `base_location`.

  * `rename` (list of rename pattern and action tuples): Renaming actions to take on schema names.
    The two elements of each tuple will be fed as the second and third arguments to
    `String.replace/4` along with the schema name. See **Renaming** below for examples. Defaults
    to no schemas renamed.

  * `schema_location` (string): Relative path, after the `base_location`, to output schema files.
    This may useful if you want to hide generated schema files in a subdirectory of a larger
    project. Defaults to outputting schema files to the `base_location`.

  * `types` (keyword list): Overrides to the types defined by the generator. Each value should be
    a tuple `{module, type}` such as `{MyModule, :t}`.

    * `error`: Override the error type for all operations. APIs often define their own error
      schemas, which may differ between operations. Use this option to define a single, consistent
      error type for all operations. For example, a value `{MyError, :t}` would cause operations
      to return `{:ok, ...} | {:error, MyError.t()}`.

  ## Naming

  Most of the configuration of this project relates to the manipulation of schema names. It is
  important to understand the order of operations. As an example, imagine an OpenAPI description
  has the following schemas:

    * `#/components/schemas/simple-user`
    * `#/components/schemas/user`
    * `#/components/schemas/user-preferences`

  And the following configuration:

      config :oapi_generator, default: [
        base_location: "lib/",
        base_module: Example,
        group: [User],
        ignore: [],
        merge: [{"SimpleUser", "User"}]
        rename: [{~r/Preferences/, "Settings"}]
      ]

  In this case, naming would proceed as follows:

  1. Schemas in the OpenAPI descriptions are turned into Elixir modules:
    ```
  #/components/schemas/simple-user       =>  SimpleUser.t()
  #/components/schemas/user              =>  User.t()
  #/components/schemas/user-preferences  =>  UserPreferences.t()
    ```

  2. Merge settings are applied based on the original names of the schemas:
    ```
  SimpleUser.t()  =>  User.simple()
    ```

  3. Ignore settings are applied based on the merged module names (no changes in this example).

  4. Rename settings are applied based on the merged module names:
    ```
  UserPreferences.t()  =>  UserSettings.t()
    ```

  5. Group settings are applied based on the renamed module names:
    ```
  UserSettings.t()  =>  User.Settings.t()
    ```

  6. The base module is applied to get the final names:
    ```
  User.simple()      =>  Example.User.simple()
  User.t()           =>  Example.User.t()
  User.Settings.t()  =>  Example.User.Settings.t()
    ```

  All of the schemas are then written to appropriate files based on the `base_location` and
  `schema_location` settings. Note that `User.simple()` and `User.t()` will end up in the same file
  as a result of the merge, sharing the same struct for their responses (with distinct typespecs).

  ### Merging

  OpenAPI descriptions may have multiple schemas that are closely related or even duplicated.
  Merging gives the power to consolidate these schemas into a single struct that is easy to use.

  For example, the GitHub API description has schemas `repository`, `full-repository`, and
  `nullable-repository`. While the "full" repository adds additional properties, the "nullable"
  variant is just that: all of the same properties, but the schema is nullable. This kind of oddity
  in the OpenAPI specification is exactly what makes most generated code difficult to use.

  The following merge settings would help clean this up:

      merge: [
        {"FullRepository", "Repository"},
        {~r/^Nullable/, ""}
      ]

  In the first line, we tell the generator to merge `FullRepository` into `Repository` (the original
  module names based on the names of the schemas). Because the destination module appears at the
  end of the original module, the word "Repository" will be dropped from the type:

  ```
  FullRepository => Repository :: Repository.full()
  ```

  This renaming of the type is automatic for prefixes and suffixes. If no overlap is found, then the
  full (underscored) schema name will be used for the type:

  ```
  SimpleUser        => User        :: User.simple()
  PullRequestSimple => PullRequest :: PullRequest.simple()
  MySchema          => Unrelated   :: Unrelated.my_schema()
  ```

  If the destination module is later renamed or grouped, the merged schemas will processed in the
  same way.

  ### Collapsing

  In the second line of the configuration above, we merge two nearly-identical schemas
  `NullableRepository` and `Repository`. Because these schemas have the same fields, there will not
  be a `Repository.nullable()` type generated; instead, references will use `Repository.t()`.
  Despite this deduplication, other parts of the code will continue to know that the original
  schema had `nullable: true` and respond accordingly.

  ### Ignoring

  Sometimes, schemas are best treated as plain maps. In these cases, they can be ignored using a
  regular expression, exact string, or exact module:

      ignore: [
        ~r/^Unnecessary/,
        "SomeSchema",
        AnotherSchema
      ]

  Any references to an ignored schema will be replaced with a `map()` type.

  ### Grouping

  Schemas in an OpenAPI description can have extensively long names. For example, GitHub has a
  schema called `actions-cache-usage-by-repository`. Along with all other actions-related schemas,
  we can cut down the top-level module namespace by grouping on `Actions` or even further:

      group: [
        Actions,
        Actions.CacheUsage
      ]

  Even simple renaming and groups can take a raw OpenAPI description and turn it into a library
  that feels friendly to users.
  """

  @typedoc "List of module namespaces to create when grouping"
  @type group_options :: [module]

  @typedoc "Patterns or exact matches of schemas to ignore"
  @type ignore_pattern :: Regex.t() | String.t() | module

  @typedoc "List of patterns or exact matches of schemas to ignore"
  @type ignore_options :: [ignore_pattern]

  @typedoc "Before (pattern or exact match) and after (replacement action) for merging schemas by module"
  @type merge_options :: [{Regex.t() | String.t() | module, String.t()}]

  @typedoc "Search pattern for renaming schemas by module"
  @type rename_pattern :: String.pattern() | Regex.t()

  @typedoc "Replacement action for renaming schemas by module"
  @type rename_action :: String.t() | (String.t() -> String.t())

  @typedoc "List of replacement searches and actions for renaming schemas by module"
  @type rename_options :: [{rename_pattern, rename_action}]

  @typedoc "Configuration for the code generator"
  @type t :: %__MODULE__{
          base_location: String.t(),
          base_module: module,
          default_client: module,
          group: group_options,
          ignore: ignore_options,
          merge: merge_options,
          operation_location: String.t(),
          rename: rename_options,
          schema_location: String.t(),
          types: keyword
        }

  defstruct [
    :base_location,
    :base_module,
    :default_client,
    :group,
    :ignore,
    :merge,
    :operation_location,
    :rename,
    :schema_location,
    :types
  ]

  @doc false
  @spec new(keyword) :: t
  def new(opts) do
    base_module = get_base_module(opts[:base_module])

    %__MODULE__{
      base_location: get_base_location(opts[:base_location]),
      base_module: base_module,
      default_client: get_default_client(opts[:default_client], base_module),
      group: get_group(opts[:group]),
      ignore: get_ignore(opts[:ignore]),
      merge: get_merge(opts[:merge]),
      operation_location: get_operation_location(opts[:operation_location]),
      rename: get_rename(opts[:rename]),
      schema_location: get_schema_location(opts[:schema_location]),
      types: get_types(opts[:types])
    }
  end

  @spec get_base_location(any) :: String.t() | no_return
  defp get_base_location(nil), do: raise(ArgumentError, "Option :base_location is required")
  defp get_base_location(value) when is_binary(value), do: value

  defp get_base_location(value),
    do: raise(ArgumentError, "Option :base_location expects a string, got #{inspect(value)}")

  @spec get_base_module(any) :: module | no_return
  defp get_base_module(nil), do: raise(ArgumentError, "Option :base_module is required")
  defp get_base_module(value) when is_atom(value), do: value

  defp get_base_module(value),
    do: raise(ArgumentError, "Option :base_module expects a module, got #{inspect(value)}")

  @spec get_default_client(any, module) :: module | no_return
  defp get_default_client(nil, base_module), do: Module.concat([base_module, Client])
  defp get_default_client(value, _base_module) when is_atom(value), do: value

  @spec get_group(any) :: [module] | no_return
  defp get_group(nil), do: []

  defp get_group(value) when is_list(value) do
    if Enum.all?(value, &is_atom/1) do
      value
    else
      raise ArgumentError, "Option :group expects a list of modules"
    end
  end

  @spec get_ignore(any) :: [ignore_pattern] | no_return
  defp get_ignore(nil), do: []

  defp get_ignore(value) when is_list(value) do
    if Enum.all?(value, fn
         %Regex{} -> true
         string when is_binary(string) -> true
         atom when is_atom(atom) -> true
         _ -> false
       end) do
      value
    else
      raise ArgumentError,
            "Option :ignore expects a list of regular expressions, strings, or modules"
    end
  end

  @spec get_merge(any) :: merge_options | no_return
  defp get_merge(nil), do: []

  defp get_merge(value) when is_list(value) do
    if Enum.all?(value, fn
         {%Regex{}, after_merge} ->
           is_atom(after_merge) or is_binary(after_merge)

         {before_merge, after_merge} ->
           (is_atom(before_merge) or is_binary(before_merge)) and
             (is_atom(after_merge) or is_binary(after_merge))
       end) do
      value
    else
      raise ArgumentError,
            "Option :merge expects a list of tuples with patterns and replacements"
    end
  end

  @spec get_operation_location(any) :: String.t() | no_return
  defp get_operation_location(nil), do: ""
  defp get_operation_location(value) when is_binary(value), do: value

  defp get_operation_location(value),
    do: raise(ArgumentError, "Option :operation_location expects a string, got #{inspect(value)}")

  @spec get_rename(any) :: [{rename_pattern, rename_action}] | no_return
  defp get_rename(nil), do: []

  defp get_rename(value) when is_list(value) do
    if Enum.all?(value, fn
         {compiled_pattern, _action} when is_tuple(compiled_pattern) -> true
         {string, _action} when is_binary(string) -> true
         {list, _action} when is_list(list) -> true
         {%Regex{}, _action} -> true
         _ -> false
       end) do
      value
    else
      raise ArgumentError,
            "Option :rename expects a list of tuples with patterns and replacements"
    end
  end

  @spec get_schema_location(any) :: String.t() | no_return
  defp get_schema_location(nil), do: ""
  defp get_schema_location(value) when is_binary(value), do: value

  defp get_schema_location(value),
    do: raise(ArgumentError, "Option :schema_location expects a string, got #{inspect(value)}")

  @spec get_types(any) :: keyword | no_return
  defp get_types(nil), do: []
  defp get_types(value) when is_list(value), do: value

  defp get_types(value),
    do: raise(ArgumentError, "Option :types expects a keyword list, got #{inspect(value)}")
end