# Copyright 2026 Cole Christensen

#

# 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.

defmodule ExGitObjectstore do

  @moduledoc """

  Pure Elixir Git library with pluggable object storage (S3, filesystem, memory).

  Provides git operations without requiring libgit2, git CLI, or any NIF.

  All git data (objects, refs, packs) is stored via a pluggable storage backend.

  ## Building objects

    * `write_tree/2` — write a tree from a list of entries

    * `commit_tree/3` — build and store a commit pointing at a tree

  ## Merge / rebase toolkit

  Complete set of primitives for performing merges and rebases in-process

  without a working directory:

    * `merge_branches/4` — three-way merge two refs into a merge commit (two parents)

    * `squash_merge/4` — three-way merge producing a single-parent commit

    * `cherry_pick/3` — replay a single commit onto a new parent

    * `rebase_commits/4` — replay a list of commits onto a new base

  ## Ref operations

    * `create_branch/3`, `delete_branch/2`

    * `update_branch/4` — atomic compare-and-swap ref update

  ## Graph queries

    * `merge_base/3` — lowest common ancestor of two commits

    * `ancestor?/3` — true if A is an ancestor of B

  ## Commit-graph index

  `ExGitObjectstore.Graph` provides an optional persisted commit-graph

  index with topological generation numbers and corrected commit dates.

  Once built and saved (`Graph.build/1`, `Graph.save/2`), it is loaded

  wholesale into memory for fast ancestry / ahead-behind queries without

  per-commit object reads. See that module and the `Graph.BinaryFormat`

  moduledoc for details.

  """

  alias ExGitObjectstore.{Graph, Merge, Object, ObjectResolver, Ref, Repo, Telemetry, Walk}

  alias ExGitObjectstore.Object.{Blob, Commit, Tree}

  @type sha :: String.t()

  @type ref_name :: String.t()

  @typedoc """

  A structured author/committer identity.

  The `:when` DateTime's `utc_offset + std_offset` produces the timezone;

  sub-minute offsets are rounded to the minute, matching git's own behavior.

  """

  @type identity :: %{

          required(:name) => String.t(),

          required(:email) => String.t(),

          required(:when) => DateTime.t()

        }

  @typedoc """

  Either a structured `identity/0` map or a pre-formatted git wire-format

  string like `"Name <email> 1234567890 +0000"`. Accepted by `commit_tree/3`

  and related APIs. Raw strings pass through unchanged; maps are formatted

  via `format_identity/1`. Pass-through is useful for cherry-pick and rebase,

  where preserving the original commit's author string byte-for-byte avoids

  any parse/format round-trip loss.

  """

  @type identity_or_raw :: identity() | String.t()

  @doc """

  Initialize a new empty repository.

  """

  @spec init(Repo.t()) :: :ok | {:error, term()}

  def init(%Repo{} = repo) do

    Ref.put_head(repo, "ref: refs/heads/main")

  end

  @doc """

  Check if a repository exists (has a HEAD).

  """

  @spec exists?(Repo.t()) :: boolean()

  def exists?(%Repo{} = repo) do

    case Ref.get_head(repo) do

      {:ok, _} -> true

      {:error, _} -> false

    end

  end

  @doc """

  Read and parse a git object by SHA.

  """

  @spec cat_object(Repo.t(), sha()) :: {:ok, Object.t()} | {:error, term()}

  def cat_object(%Repo{} = repo, sha) do

    ObjectResolver.read(repo, sha)

  end

  @doc """

  Write a git object and return its SHA.

  """

  @spec write_object(Repo.t(), Object.t()) :: {:ok, sha()} | {:error, term()}

  def write_object(%Repo{} = repo, object) do

    Object.write(repo, object)

  end

  @doc """

  Resolve a ref (branch name, tag name, or SHA) to a commit SHA.

  """

  @spec resolve(Repo.t(), ref_name() | sha()) :: {:ok, sha()} | {:error, term()}

  def resolve(%Repo{} = repo, ref_or_sha) do

    Ref.resolve(repo, ref_or_sha)

  end

  @doc """

  Get the default branch name.

  """

  @spec default_branch(Repo.t()) :: {:ok, String.t()} | {:error, term()}

  def default_branch(%Repo{} = repo) do

    case Ref.get_head(repo) do

      {:ok, "ref: refs/heads/" <> branch} -> {:ok, branch}

      {:ok, sha} when byte_size(sha) == 40 -> {:ok, sha}

      {:error, _} = err -> err

    end

  end

  @doc """

  List all branches.

  """

  @spec branches(Repo.t()) :: {:ok, [{String.t(), sha()}]} | {:error, term()}

  def branches(%Repo{} = repo) do

    Ref.list(repo, "refs/heads/")

  end

  @doc """

  List all tags.

  """

  @spec tags(Repo.t()) :: {:ok, [{String.t(), sha()}]} | {:error, term()}

  def tags(%Repo{} = repo) do

    Ref.list(repo, "refs/tags/")

  end

  @doc """

  Create a branch pointing to the given SHA.

  """

  @spec create_branch(Repo.t(), String.t(), sha()) :: :ok | {:error, term()}

  def create_branch(%Repo{} = repo, name, sha) do

    Ref.put(repo, "refs/heads/#{name}", sha, nil)

  end

  @doc """

  Delete a branch.

  """

  @spec delete_branch(Repo.t(), String.t()) :: :ok | {:error, term()}

  def delete_branch(%Repo{} = repo, name) do

    Ref.delete(repo, "refs/heads/#{name}")

  end

  @doc """

  Create a lightweight tag pointing to the given SHA.

  """

  @spec create_tag(Repo.t(), String.t(), sha()) :: :ok | {:error, term()}

  def create_tag(%Repo{} = repo, name, sha) do

    Ref.put(repo, "refs/tags/#{name}", sha, nil)

  end

  @doc """

  Delete a tag.

  """

  @spec delete_tag(Repo.t(), String.t()) :: :ok | {:error, term()}

  def delete_tag(%Repo{} = repo, name) do

    Ref.delete(repo, "refs/tags/#{name}")

  end

  @doc """

  Get a commit by SHA or ref.

  """

  @spec commit(Repo.t(), sha() | ref_name()) :: {:ok, {sha(), Commit.t()}} | {:error, term()}

  def commit(%Repo{} = repo, ref_or_sha) do

    with {:ok, sha} <- resolve(repo, ref_or_sha),

         {:ok, %Commit{} = commit} <- cat_object(repo, sha) do

      {:ok, {sha, commit}}

    end

  end

  @doc """

  Get the commit log starting from a ref or SHA.

  ## Options

    * `:max_count` — maximum number of commits (default: all)

    * `:skip` — skip N commits (default: 0)

  """

  @spec log(Repo.t(), sha() | ref_name(), keyword()) ::

          {:ok, [{sha(), Commit.t()}]} | {:error, term()}

  def log(%Repo{} = repo, ref_or_sha, opts \\ []) do

    with {:ok, sha} <- resolve(repo, ref_or_sha) do

      Walk.log(repo, sha, opts)

    end

  end

  @doc """

  Paginated log returning `{:ok, commits, cursor}`. Pass cursor to

  `log_continue/3` for the next page. Each page is O(page_size).

  """

  @spec log_page(Repo.t(), sha() | ref_name(), keyword()) ::

          {:ok, [{sha(), Commit.t()}], [sha()]} | {:error, term()}

  def log_page(%Repo{} = repo, ref_or_sha, opts \\ []) do

    with {:ok, sha} <- resolve(repo, ref_or_sha) do

      Walk.log_page(repo, sha, opts)

    end

  end

  @doc """

  Continue a paginated log from a cursor. Returns `{:ok, [], []}` when done.

  """

  @spec log_continue(Repo.t(), [sha()], keyword()) ::

          {:ok, [{sha(), Commit.t()}], [sha()]} | {:error, term()}

  def log_continue(%Repo{} = repo, cursor, opts \\ []) do

    Walk.log_continue(repo, cursor, opts)

  end

  @doc """

  Get a tree listing at a given path for a ref or SHA.

  Path "/" returns the root tree.

  """

  @spec tree(Repo.t(), sha() | ref_name(), String.t()) ::

          {:ok, Tree.t()} | {:error, term()}

  def tree(%Repo{} = repo, ref_or_sha, path \\ "/") do

    with {:ok, sha} <- resolve(repo, ref_or_sha),

         {:ok, %Commit{} = commit} <- cat_object(repo, sha),

         {:ok, %Tree{} = root_tree} <- cat_object(repo, commit.tree) do

      if path == "/" or path == "" do

        {:ok, root_tree}

      else

        walk_tree_path(repo, root_tree, String.split(path, "/", trim: true))

      end

    end

  end

  @doc """

  Get blob content by SHA.

  """

  @spec blob(Repo.t(), sha()) :: {:ok, binary()} | {:error, term()}

  def blob(%Repo{} = repo, sha) do

    case cat_object(repo, sha) do

      {:ok, %Blob{content: content}} -> {:ok, content}

      {:ok, _other} -> {:error, :not_a_blob}

      {:error, _} = err -> err

    end

  end

  @doc """

  Get the size of a blob by SHA without reading full content.

  Currently reads the full blob — could be optimized with pack header parsing.

  """

  @spec blob_size(Repo.t(), sha()) :: {:ok, non_neg_integer()} | {:error, term()}

  def blob_size(%Repo{} = repo, sha) do

    case blob(repo, sha) do

      {:ok, content} -> {:ok, byte_size(content)}

      {:error, _} = err -> err

    end

  end

  @doc """

  Batch variant of `blob_size/2`.

  Looks up the sizes of many blobs in one call, using bounded concurrency

  to parallelize the backend reads. Returns a map of `sha => size` containing

  only the shas that resolved successfully. Input shas that can't be resolved

  (missing object, `:not_a_blob`, storage error) are silently omitted from

  the result map.

  Input shas are deduplicated before dispatch, so passing the same sha

  multiple times costs the same as passing it once.

  ## Options

    * `:max_concurrency` — maximum number of parallel backend reads.

      Defaults to 16. Match this to your storage backend's sweet spot —

      S3 likes higher concurrency, local filesystem benefits less.

    * `:timeout` — per-sha timeout in milliseconds. Defaults to 30_000.

  ## Why a dedicated bulk API

  Anvil's tree-rendering path (and similar UIs) repeatedly call

  `blob_size/2` once per entry in an `Enum.map`. On an S3-backed store,

  each call is a separate network round-trip — a 1000-file directory

  listing costs ~100s at 100 ms/call. `blob_sizes/2` issues all lookups

  in parallel so the same workload drops to a few seconds.

  This version does *not* optimize the single-blob read cost — it still

  reads full blob content via `blob/2` for each sha. Backends that want

  to compute sizes without transferring blob content (e.g. parsing pack

  headers or using S3 HEAD requests once the format supports it) can

  override this function in a future revision.

  ## Examples

      iex> ExGitObjectstore.blob_sizes(repo, [sha1, sha2, missing_sha])

      {:ok, %{^sha1 => 42, ^sha2 => 100}}  # missing_sha silently dropped

      iex> ExGitObjectstore.blob_sizes(repo, [])

      {:ok, %{}}

  """

  @spec blob_sizes(Repo.t(), [sha()], keyword()) ::

          {:ok, %{optional(sha()) => non_neg_integer()}}

  def blob_sizes(repo, shas, opts \\ [])

  def blob_sizes(%Repo{}, [], _opts), do: {:ok, %{}}

  def blob_sizes(%Repo{} = repo, shas, opts) when is_list(shas) do

    max_concurrency = Keyword.get(opts, :max_concurrency, 16)

    timeout = Keyword.get(opts, :timeout, 30_000)

    result =

      shas

      |> Enum.uniq()

      |> Task.async_stream(

        fn sha ->

          case blob_size(repo, sha) do

            {:ok, size} -> {sha, size}

            {:error, _} -> :skip

          end

        end,

        max_concurrency: max_concurrency,

        timeout: timeout,

        on_timeout: :kill_task,

        ordered: false

      )

      |> Enum.reduce(%{}, fn

        {:ok, {sha, size}}, acc -> Map.put(acc, sha, size)

        {:ok, :skip}, acc -> acc

        {:exit, _reason}, acc -> acc

      end)

    {:ok, result}

  end

  @doc """

  Three-way merge of two commits.

  Finds the merge base (LCA), then merges the trees.

  Returns `{:ok, merged_tree_sha}` on clean merge, or

  `{:error, {:conflicts, [conflict]}}` if there are conflicts.

  """

  @spec merge_commits(Repo.t(), sha(), sha(), keyword()) ::

          {:ok, sha()} | {:error, term()}

  def merge_commits(%Repo{} = repo, ours_sha, theirs_sha, opts \\ []) do

    Merge.merge_commits(repo, ours_sha, theirs_sha, opts)

  end

  @doc """

  Three-way merge of tree objects given base, ours, and theirs tree SHAs.

  """

  @spec merge_trees(Repo.t(), sha(), sha(), sha()) ::

          {:ok, sha()} | {:error, term()}

  def merge_trees(%Repo{} = repo, base_tree_sha, ours_tree_sha, theirs_tree_sha) do

    Merge.merge_trees(repo, base_tree_sha, ours_tree_sha, theirs_tree_sha)

  end

  @doc """

  Write a tree from a list of entries and return its SHA.

  Entries are validated and canonicalized by `Tree.new/1`. Each entry is a map

  with `:mode`, `:name`, and `:sha` — see `ExGitObjectstore.Object.Tree` for

  allowed mode values.

  ## Example

      {:ok, tree_sha} = ExGitObjectstore.write_tree(repo, [

        %{mode: "100644", name: "README.md", sha: readme_blob_sha},

        %{mode: "40000",  name: "src",       sha: src_tree_sha}

      ])

  """

  @spec write_tree(Repo.t(), [Tree.entry()]) :: {:ok, sha()} | {:error, term()}

  def write_tree(%Repo{} = repo, entries) when is_list(entries) do

    Object.write(repo, Tree.new(entries))

  end

  @doc """

  Build and write a commit object pointing at a tree.

  Returns the new commit's SHA. Validates the tree and all parent SHAs exist

  in storage before writing.

  ## Options

    * `:parents` — list of parent commit SHAs. Empty list for a root commit.

    * `:author` (required) — an `identity_or_raw/0`. Pass an `identity/0` map

      and it's formatted to git wire format; pass a pre-formatted string and

      it's used as-is (useful for cherry-pick to preserve author verbatim).

    * `:committer` — same shape as `:author`. Defaults to `:author`.

    * `:message` (required) — commit message. A trailing newline is added if

      missing, per git convention.

    * `:gpgsig` — optional detached GPG signature to embed in the commit.

  ## Errors

    * `{:error, {:missing_option, :author | :message}}` — required option omitted.

    * `{:error, {:missing_tree, sha}}` — tree SHA not in storage.

    * `{:error, {:not_a_tree, sha}}` — SHA exists but isn't a tree.

    * `{:error, {:missing_parent, sha}}` — parent SHA not in storage.

    * `{:error, {:not_a_commit_parent, sha}}` — parent SHA exists but isn't a commit.

  ## Example

      {:ok, commit_sha} =

        ExGitObjectstore.commit_tree(repo, tree_sha,

          parents: [base_sha, head_sha],

          author: %{name: "Alice", email: "a@x.com", when: DateTime.utc_now()},

          message: "Merge head into base"

        )

  """

  @spec commit_tree(Repo.t(), sha(),

          parents: [sha()],

          author: identity_or_raw(),

          committer: identity_or_raw(),

          message: String.t(),

          gpgsig: String.t() | nil

        ) :: {:ok, sha()} | {:error, term()}

  def commit_tree(%Repo{} = repo, tree_sha, opts) when is_binary(tree_sha) and is_list(opts) do

    with {:ok, author} <- fetch_required(opts, :author),

         {:ok, message} <- fetch_required(opts, :message),

         :ok <- validate_tree_exists(repo, tree_sha),

         :ok <- validate_parents_exist(repo, Keyword.get(opts, :parents, [])) do

      commit = %Commit{

        tree: tree_sha,

        parents: Keyword.get(opts, :parents, []),

        author: format_identity(author),

        committer: format_identity(Keyword.get(opts, :committer, author)),

        message: ensure_trailing_newline(message),

        gpgsig: Keyword.get(opts, :gpgsig)

      }

      Object.write(repo, commit)

    end

  end

  @doc """

  Merge `theirs` into `ours`, creating a merge commit.

  Resolves both refs (or SHAs) to commits, performs a three-way merge against

  their merge base, and creates a new commit with the merged tree and both

  commits as parents. On conflict, returns without writing the merge commit.

  **Does not update any ref.** The returned SHA is only written as a commit

  object; persisting it to a branch is the caller's responsibility (e.g.

  `create_branch/3` or a storage-level CAS on `refs/heads/<branch>`).

  Tag refs resolve transitively to their target commit via `resolve/2`.

  Uses the same `identity/0` shape as `commit_tree/3`.

  ## Options

    * `:author` (required) — identity for the merge commit author.

    * `:committer` — defaults to `:author`.

    * `:message` — merge commit message. Defaults to

      `"Merge <theirs_ref> into <ours_ref>\\n"`.

  ## Returns

    * `{:ok, merge_commit_sha}` on clean merge.

    * `{:error, {:conflicts, [%{path, base, ours, theirs}]}}` on conflict

      (no commit is written).

    * `{:error, {:missing_option, :author}}` — required option omitted.

    * `{:error, reason}` for resolution or storage failures.

  ## Example

      {:ok, merge_sha} =

        ExGitObjectstore.merge_branches(repo, "main", "feature",

          author: %{name: "Alice", email: "a@x.com", when: DateTime.utc_now()}

        )

  """

  @spec merge_branches(Repo.t(), ref_name() | sha(), ref_name() | sha(),

          author: identity(),

          committer: identity(),

          message: String.t()

        ) :: {:ok, sha()} | {:error, term()}

  def merge_branches(%Repo{} = repo, ours_ref, theirs_ref, opts) when is_list(opts) do

    with {:ok, author} <- fetch_required(opts, :author),

         {:ok, ours_sha} <- resolve(repo, ours_ref),

         {:ok, theirs_sha} <- resolve(repo, theirs_ref),

         {:ok, merged_tree_sha} <- Merge.merge_commits(repo, ours_sha, theirs_sha) do

      committer = Keyword.get(opts, :committer, author)

      message =

        Keyword.get_lazy(opts, :message, fn ->

          "Merge #{theirs_ref} into #{ours_ref}\n"

        end)

      commit_tree(repo, merged_tree_sha,

        parents: [ours_sha, theirs_sha],

        author: author,

        committer: committer,

        message: message

      )

    end

  end

  # -- Squash / cherry-pick / rebase --

  @doc """

  Squash-merge `head` into `base`, writing a single-parent commit.

  Same three-way merge as `merge_branches/4`, but the resulting commit has

  only `base` as a parent — `head`'s history is collapsed into one commit.

  **Does not update any ref.** Caller is responsible for persisting the

  returned SHA (typically by updating `base`'s branch ref).

  ## Options

    * `:author` (required) — `identity_or_raw/0`.

    * `:committer` — defaults to `:author`.

    * `:message` — defaults to `"Squash merge of <head_ref> into <base_ref>\\n"`.

  ## Returns

    * `{:ok, squash_commit_sha}` on clean merge.

    * `{:error, {:conflicts, [...]}}` on conflict (no commit written).

    * `{:error, {:missing_option, :author}}`, or a resolution/storage error.

  """

  @spec squash_merge(Repo.t(), ref_name() | sha(), ref_name() | sha(),

          author: identity_or_raw(),

          committer: identity_or_raw(),

          message: String.t()

        ) :: {:ok, sha()} | {:error, term()}

  def squash_merge(%Repo{} = repo, base_ref, head_ref, opts) when is_list(opts) do

    with {:ok, author} <- fetch_required(opts, :author),

         {:ok, base_sha} <- resolve(repo, base_ref),

         {:ok, head_sha} <- resolve(repo, head_ref),

         {:ok, merged_tree_sha} <- Merge.merge_commits(repo, base_sha, head_sha) do

      committer = Keyword.get(opts, :committer, author)

      message =

        Keyword.get_lazy(opts, :message, fn ->

          "Squash merge of #{head_ref} into #{base_ref}\n"

        end)

      commit_tree(repo, merged_tree_sha,

        parents: [base_sha],

        author: author,

        committer: committer,

        message: message

      )

    end

  end

  @doc """

  Cherry-pick a single commit onto a new parent.

  Performs a three-way merge with `commit`'s first parent as the base,

  `onto`'s tree as "ours", and `commit`'s tree as "theirs". On success,

  writes a new commit with `onto` as its sole parent, preserving `commit`'s

  original author (and message, unless overridden).

  The GPG signature of the original commit is **not** copied — cherry-picking

  rewrites the commit, which invalidates any signature over the old content.