defmodule Patch.Mock.Code do
  @moduledoc """
  Patch mocks out modules by generating mock modules and recompiling them for a `target` module.

  Patch's approach to mocking a module provides some powerful affordances.

  - Private functions can be mocked.
  - Internal function calls are effected by mocks regardless of the function's visibility without
    having to change the way code is written.
  - Private functions can be optionally exposed in the facade to make it possible to test a
    private function directly without changing its visibility in code.

  # Mocking Strategy

  There are 4 logical modules and 1 GenServer that are involved when mocking a module.

  The 4 logical modules:

  - `target` - The module to be mocked.
  - `facade` - The `target` module is replaced by a `facade` module that intercepts all external
    calls and redirects them to the `delegate` module.
  - `original` - The `target` module is preserved as the `original` module, with the important
    transformation that all local calls are redirected to the `delegate` module.
  - `delegate` - This module is responsible for checking with the `server` to see if a call is
    mocked and should be intercepted.  If so, the mock value is returned, otherwise the `original`
    function is called.

  Each `target` module has an associated GenServer, a `Patch.Mock.Server` that has keeps state
  about the history of function calls and holds the mock data to be returned on interception.  See
  `Patch.Mock.Server` for more information.

  ## Example Target Module

  To better understand how Patch works, consider the following example module.

  ```elixir
  defmodule Example do
    def public_function(argument_1, argument_2) do
      {:public, private_function(argument_1, argument_2)}
    end

    defp private_function(argument_1, argument_2) do
      {:private, argument_1, argument_2}
    end
  end
  ```

  ### `facade` module

  The `facade` module is automatically generated based off the exports of the `target` module.
  It takes on the name of the `provided` module.

  For each exported function, a function is generated in the `facade` module that calls the
  `delegate` module.

  ```elixir
  defmodule Example do
    def public_function(argument_1, argument_2) do
      Patch.Mock.Delegate.For.Example.public_function(argument_1, argument_2)
    end
  end
  ```

  ### `delegate` module

  The `delegate` module is automatically generated based off all the functions of the `target`
  module.  It takes on a name based off the `target` module, see `Patch.Mock.Naming.delegate/1`.

  For each function, a function is generated in the `delegate` module that calls
  `Patch.Mock.Server.delegate/3` delegating to the server named for the `target` module, see
  `Patch.Mock.Naming.server/1`.

  ```elixir
  defmodule Patch.Mock.Delegate.For.Example do
    def public_function(argument_1, argument_2) do
      Patch.Mock.Server.delegate(
        Patch.Mock.Server.For.Example,
        :public_function,
        [argument_1, argument_2]
      )
    end

    def private_function(argument_1, argument_2) do
      Patch.Mock.Server.delegate(
        Patch.Mock.Server.For.Example,
        :private_function,
        [argument_1, argument_2]
      )
    end
  end
  ```

  ### `original` module

  The `original` module takes on a name based off the `provided` module, see
  `Patch.Mock.Naming.original/1`.

  The code is transformed in the following ways.
    - All local calls are converted into remote calls to the `delegate` module.
    - All functions are exported

  ```elixir
  defmodule Patch.Mock.Original.For.Example do
    def public_function(argument_1, argument_2) do
      {:public, Patch.Mock.Delegate.For.Example.private_function(argument_1, argument_2)}
    end

    def private_function(argument_1, argument_2) do
      {:private, argument_1, argument_2}
    end
  end
  ```

  ## External Function Calls

  First, let's examine how calls from outside the module are treated.

  ### Public Function Calls

  Code calling `Example.public_function/2` has the following call flow.

  ```text
  [Caller] -> facade -> delegate -> server -> mocked? -> yes   (Intercepted)
           [Mock Value] <----------------------------|----'
                                                      -> no -> original   (Run Original Code)
           [Original Value] <--------------------------------------'
  ```

  Calling a public function will either return the mocked value if it exists, or fall back to
  calling the original function.

  ### Private Function Calls

  Code calling `Example.private_function/2` has the following call flow.

  ```text
  [Caller] --------------------------> facade
           [UndefinedFunctionError] <-----'
  ```

  Calling a private function continues to be an error from the external caller's point of view.

  The `expose` option does allow the facade to expose private functions, in those cases the call
  flow just follows the public call flow.

  ## Internal Calls

  Next, let's examine how calls from outside the module are treated.

  ### Public Function Calls

  Code in the `original` module calling public functions have their code transformed to call the
  `delegate` module.

  ```text
  original -> delegate -> server -> mocked? -> yes   (Intercepted)
           [Mock Value] <------------------|----'
                                            -> no -> original   (Run Original Code)
           [Original Value] <----------------------------'
  ```

  Since the call is redirected to the `delegate`, calling a public function will either return the
  mocked value if it exists, or fall back to calling the original function.

  ### Private Function Call Flow

  Code in the `original` module calling private functions have their code transformed to call the
  `delegate` module

  ```text
  original -> delegate -> server -> mocked? -> yes   (Intercepted)
           [Mock Value] <------------------|----'
                                            -> no -> original   (Run Original Code)
           [Original Value] <----------------------------'
  ```

  Since the call is redirected to the `delegate`, calling a private function will either return the
  mocked value if it exists, or fall back to calling the original function.

  ## Code Generation

  For additional details on how Code Generation works, see the `Patch.Mock.Code.Generate` module.
  """

  alias Patch.Mock
  alias Patch.Mock.Code.Generate
  alias Patch.Mock.Code.Query
  alias Patch.Mock.Code.Unit

  @type binary_error ::
          :badfile
          | :nofile
          | :not_purged
          | :on_load_failure
          | :sticky_directory

  @type chunk_error ::
          :chunk_too_big
          | :file_error
          | :invalid_beam_file
          | :key_missing_or_invalid
          | :missing_backend
          | :missing_chunk
          | :not_a_beam_file
          | :unknown_chunk

  @type load_error ::
          :embedded
          | :badfile
          | :nofile
          | :on_load_failure

  @type compiler_option :: term()

  @type form :: term()
  @type export_classification :: :builtin | :generated | :normal
  @type exports :: Keyword.t(arity())

  @typedoc """
  Sum-type of all valid options
  """
  @type option :: Mock.exposes_option()

  @doc """
  Extracts the abstract_forms from a module
  """
  @spec abstract_forms(module :: module) ::
          {:ok, [form()]}
          | {:error, :abstract_forms_unavailable}
          | {:error, chunk_error()}
          | {:error, load_error()}
  def abstract_forms(module) do
    with :ok <- ensure_loaded(module),
         {:ok, binary} <- binary(module) do
      case :beam_lib.chunks(binary, [:abstract_code]) do
        {:ok, {_, [abstract_code: {:raw_abstract_v1, abstract_forms}]}} ->
          {:ok, abstract_forms}

        {:error, :beam_lib, details} ->
          reason = elem(details, 0)
          {:error, reason}

        _ ->
          {:error, :abstract_forms_unavailable}
      end
    end
  end

  @doc """
  Extracts the attribtues from a module
  """
  @spec attributes(module :: module()) ::
          {:ok, Keyword.t()}
          | {:error, :attributes_unavailable}
  def attributes(module) do
    with :ok <- ensure_loaded(module) do
      try do
        Keyword.get(module.module_info(), :attributes, [])
      catch
        _, _ ->
          {:error, :attributes_unavailable}
      end
    end
  end

  @doc """
  Classifies an exported mfa into one of the following classifications

  - :builtin - Export is a BIF.
  - :generated - Export is a generated function.
  - :normal - Export is a user defined function.
  """
  @spec classify_export(module :: module(), function :: atom(), arity :: arity()) :: export_classification()
  def classify_export(_, :module_info, 0), do: :generated
  def classify_export(_, :module_info, 1), do: :generated
  def classify_export(module, function, arity) do
    if :erlang.is_builtin(module, function, arity) do
      :builtin
    else
      :normal
    end
  end


  @doc """
  Compiles the provided abstract_form with the given compiler_options

  In addition to compiling, the module will be loaded.
  """
  @spec compile(abstract_forms :: [form()], compiler_options :: [compiler_option()]) ::
          :ok
          | {:error, binary_error()}
          | {:error, {:abstract_forms_invalid, [form()], term()}}
  def compile(abstract_forms, compiler_options \\ []) do
    case :compile.forms(abstract_forms, [:return_errors | compiler_options]) do
      {:ok, module, binary} ->
        load_binary(module, binary)

      {:ok, module, binary, _} ->
        load_binary(module, binary)

      errors ->
        {:error, {:abstract_forms_invalid, abstract_forms, errors}}
    end
  end

  @doc """
  Extracts the compiler options from a module.
  """
  @spec compiler_options(module :: module()) ::
          {:ok, [compiler_option()]}
          | {:error, :compiler_options_unavailable}
          | {:error, chunk_error()}
          | {:error, load_error()}
  def compiler_options(module) do
    with :ok <- ensure_loaded(module),
         {:ok, binary} <- binary(module) do
      case :beam_lib.chunks(binary, [:compile_info]) do
        {:ok, {_, [compile_info: info]}} ->
          filtered_options =
            case Keyword.fetch(info, :options) do
              {:ok, options} ->
                filter_compiler_options(options)

              :error ->
                []
            end

          {:ok, filtered_options}

        {:error, :beam_lib, details} ->
          reason = elem(details, 0)
          {:error, reason}

        _ ->
          {:error, :compiler_options_unavailable}
      end
    end
  end

  @doc """
  Extracts the exports from the provided abstract_forms for the module.

  The exports returned can be controlled by the exposes argument.
  """
  @spec exports(abstract_forms :: [form()], module :: module(), exposes :: Mock.exposes()) :: exports()
  def exports(abstract_forms, module, :public) do
    exports = Query.exports(abstract_forms)
    filter_exports(module, exports, :normal)
  end

  def exports(abstract_forms, module, :all) do
    exports = Query.functions(abstract_forms)
    filter_exports(module, exports, :normal)
  end

  def exports(abstract_forms, module, exposes) do
    exports = exposes ++ Query.exports(abstract_forms)
    filter_exports(module, exports, :normal)
  end

  @doc """
  Given a module and a list of exports filters the list of exports to those that
  have the given classification.

  See `classify_export/3` for information about export classification
  """
  @spec filter_exports(module :: module, exports :: exports(), classification :: export_classification()) :: exports()
  def filter_exports(module, exports, classification) do
    Enum.filter(exports, fn {name, arity} ->
      classify_export(module, name, arity) == classification
    end)
  end

  @doc """
  Freezes a module by generating a copy of it under a frozen name with all remote calls to the
  `target` module re-routed to the frozen module.
  """
  @spec freeze(module :: module) :: :ok | {:error, term}
  def freeze(module) do
    with {:ok, compiler_options} <- compiler_options(module),
         {:ok, _} <- unstick_module(module),
         {:ok, abstract_forms} <- abstract_forms(module),
         frozen_forms = Generate.frozen(abstract_forms, module),
         :ok <- compile(frozen_forms, compiler_options) do
      :ok
    end
  end

  @doc """
  Mocks a module by generating a set of modules based on the `target` module.

  The `target` module's Unit is returned on success.
  """
  @spec module(module :: module(), options :: [option()]) :: {:ok, Unit.t()} | {:error, term}
  def module(module, options \\ []) do
    exposes = options[:exposes] || :public

    with {:ok, compiler_options} <- compiler_options(module),
         {:ok, sticky?} <- unstick_module(module),
         {:ok, abstract_forms} <- abstract_forms(module),
         local_exports = exports(abstract_forms, module, :all),
         remote_exports = exports(abstract_forms, module, exposes),
         delegate_forms = Generate.delegate(abstract_forms, module, local_exports),
         facade_forms = Generate.facade(abstract_forms, module, remote_exports),
         original_forms = Generate.original(abstract_forms, module, local_exports),
         :ok <- compile(delegate_forms),
         :ok <- compile(original_forms, compiler_options),
         :ok <- compile(facade_forms) do
      unit = %Unit{
        abstract_forms: abstract_forms,
        compiler_options: compiler_options,
        module: module,
        sticky?: sticky?
      }

      {:ok, unit}
    end
  end

  @doc """
  Purges a module from the code server
  """
  @spec purge(module :: module()) :: boolean()
  def purge(module) do
    :code.purge(module)
    :code.delete(module)
  end

  @doc """
  Marks a module a sticky
  """
  @spec stick_module(module :: module()) :: :ok | {:error, load_error()}
  def stick_module(module) do
    :code.stick_mod(module)
    ensure_loaded(module)
  end

  @doc """
  Unsticks a module

  Returns `{:ok, was_sticky?}` on success, `{:error, reason}` otherwise
  """
  @spec unstick_module(module :: module()) ::
          {:ok, boolean()}
          | {:error, load_error()}
  def unstick_module(module) do
    with :ok <- ensure_loaded(module) do
      if :code.is_sticky(module) do
        {:ok, :code.unstick_mod(module)}
      else
        {:ok, false}
      end
    end
  end

  ## Private

  @spec binary(module :: module()) :: {:ok, binary()} | {:error, :binary_unavailable}
  defp binary(module) do
    case :code.get_object_code(module) do
      {^module, binary, _} ->
        {:ok, binary}

      :error ->
        {:error, :binary_unavailable}
    end
  end

  @spec ensure_loaded(module :: module()) :: :ok | {:error, load_error()}
  defp ensure_loaded(module) do
    with {:module, ^module} <- Code.ensure_loaded(module) do
      :ok
    end
  end

  @spec filter_compiler_options(options :: [term()]) :: [term()]
  defp filter_compiler_options(options) do
    Enum.filter(options, fn
      {:parse_transform, _} ->
        false

      :makedeps_side_effects ->
        false

      :from_core ->
        false

      _ ->
        true
    end)
  end

  @spec load_binary(module :: module(), binary :: binary()) ::
          :ok
          | {:error, binary_error()}
  defp load_binary(module, binary) do
    with {:module, ^module} <- :code.load_binary(module, ~c'', binary) do
      :ok
    end
  end
end
