gem-contribute 0.1.0 → 0.3.0

data/lib/gem_contribute/host_adapters/github_adapter.rb

@@ -6,36 +6,48 @@ require "uri"
 
 module GemContribute
   module HostAdapters
-    # GitHub adapter. v0.1 implements the unauthenticated read methods
-    # (issues, community_profile, file_contents). The auth-required methods
-    # raise AuthRequired so the calling layer (CLI in Stage 2, TUI in Stage 3)
-    # can trigger device flow. See ADR-0001 and ADR-0004.
+    # GitHub adapter. Implements the `HostAdapter` interface for github.com.
+    # Public read methods work anonymously; auth-required methods raise
+    # `AuthRequired` without a cached token (ADR-0001 / ADR-0004).
     #
-    # `token` is optional and reserved for Stage 2; when present it's sent as
-    # `Authorization: Bearer …` to lift the rate limit and unlock fork/etc.
+    # `token` is optional. When present it's sent as `Authorization: Bearer …`
+    # to lift the rate limit and unlock fork / comment / etc.
+    #
+    # Class length: this adapter wraps a growing surface area of GitHub
+    # endpoints. The 150-line metric isn't a useful constraint here — we'd
+    # just split into arbitrary sub-modules — so it's disabled below with
+    # this rationale.
+    # rubocop:disable Metrics/ClassLength
     class GitHubAdapter < HostAdapter
       API_BASE = "https://api.github.com"
       ACCEPT = "application/vnd.github+json"
       API_VERSION = "2022-11-28"
       MAX_REDIRECTS = 3
 
+      # GitHub's POST /forks returns 202 immediately; the fork resource may
+      # 404 for a few seconds while propagation finishes. Bound the wait at
+      # 12 × 5s = 60s.
+      FORK_READINESS_RETRIES = 12
+      FORK_READINESS_INTERVAL = 5
+
       RateLimit = Data.define(:limit, :remaining, :reset_at)
 
       attr_reader :rate_limit
 
-      def initialize(cache: Cache.new, http: Net::HTTP, token: nil)
+      def initialize(cache: Cache.new, http: Net::HTTP, token: nil,
+                     sleeper: ->(s) { Kernel.sleep(s) })
         super()
         @cache = cache
         @http = http
         @token = token
+        @sleeper = sleeper
         @rate_limit = nil
       end
 
       # @return [Hash] a single issue's full payload (uncached — submit only).
-      def issue(owner, repo, number)
-        ensure_known_host!(Project.new(gem_name: repo, host: "github.com",
-                                       owner: owner, repo: repo, metadata: {}))
-        get_json("/repos/#{owner}/#{repo}/issues/#{number}")
+      def issue(project, number)
+        ensure_known_host!(project)
+        get_json("/repos/#{project.owner}/#{project.repo}/issues/#{number}")
       end
 
       # @return [Array<Hash>] open issues filtered to the given labels (if any)
@@ -76,35 +88,24 @@ module GemContribute
         @cache.write("files", cache_key, body)
       end
 
-      # POST /repos/:owner/:repo/forks. Returns the fork's parsed body
-      # (clone_url, owner.login, name, etc.). GitHub responds 202 (accepted)
-      # immediately even if the fork is still propagating; callers that need
-      # to clone right after may want to poll readiness — see
-      # `fork_ready?` below.
+      # Idempotent, blocking fork. If the viewer already owns a fork at the
+      # same name, returns it as `reused: true` without a POST. Otherwise
+      # POSTs to /repos/:owner/:repo/forks and polls until the fork is
+      # reachable. Returns a `HostAdapter::ForkResult`.
       def fork(project)
         raise AuthRequired, "github.com" unless @token
 
-        ensure_known_host!(project)
-        post_json("/repos/#{project.owner}/#{project.repo}/forks")
-      end
-
-      # GET /repos/:viewer/:repo. True iff the viewer already owns a fork of
-      # the upstream repo at the same name.
-      def already_forked?(project)
-        raise AuthRequired, "github.com" unless @token
-
         ensure_known_host!(project)
         viewer = viewer_login
-        get_json("/repos/#{viewer}/#{project.repo}")
-        true
-      rescue AdapterError => e
-        return false if e.message.include?("404")
+        return existing_fork_result(viewer, project) if fork_exists?(viewer, project.repo)
 
-        raise
+        body = post_json("/repos/#{project.owner}/#{project.repo}/forks")
+        wait_until_fork_ready(viewer, project.repo)
+        new_fork_result(viewer, project, body)
       end
 
-      # GET /user. Used by `auth status` and `already_forked?`. Returns the
-      # authenticated user's login string (e.g. "cdhagmann").
+      # GET /user. Used by `auth status` and internally by `fork`. Returns
+      # the authenticated user's login string (e.g. "cdhagmann").
       def viewer_login
         raise AuthRequired, "github.com" unless @token
 
@@ -112,12 +113,88 @@ module GemContribute
         body.fetch("login")
       end
 
-      # GET /repos/:viewer/:repo, returning true once GitHub has finished
-      # provisioning the fork. The fork endpoint returns 202 immediately;
-      # the resource may 404 for a few seconds before becoming live.
-      def fork_ready?(viewer, repo_name)
+      # POST /repos/:owner/:repo/issues/:n/comments. Returns the created
+      # comment payload (id, body, html_url, ...). Used by `fix` to post
+      # the "working on this" announcement.
+      def comment(project, issue:, body:)
+        raise AuthRequired, "github.com" unless @token
+
+        ensure_known_host!(project)
+        post_json("/repos/#{project.owner}/#{project.repo}/issues/#{issue}/comments",
+                  { "body" => body })
+      end
+
+      # GET /repos/:owner/:repo/issues/:n/comments. Returns an array of
+      # comment payloads. Uncached (callers may want fresh data, e.g. to
+      # check for an idempotency marker).
+      def issue_comments(project, number)
         raise AuthRequired, "github.com" unless @token
 
+        ensure_known_host!(project)
+        get_json("/repos/#{project.owner}/#{project.repo}/issues/#{number}/comments")
+      end
+
+      # GET /search/issues. Wraps GitHub's issue search; works without auth
+      # (subject to the 60/hr anonymous rate limit). Returns an array of
+      # issue payloads (the search response's `items` key). Cached under the
+      # `issues` namespace using the query as the key. Used to find issues
+      # already claimed via the gem-contribute marker.
+      def search_issues(query)
+        cache_key = "search:#{query}"
+        cached = @cache.fetch("issues", cache_key)
+        return cached if cached
+
+        raw = get_json("/search/issues", q: query)
+        items = raw.fetch("items", [])
+        @cache.write("issues", cache_key, items)
+      end
+
+      # Builds GitHub's pre-filled compare URL. The browser-based PR flow
+      # (ADR-0011) means the user reviews the title/body before submitting,
+      # so this method just templates — it doesn't post.
+      def pull_request_url(upstream, head_owner:, head_branch:, title:, body:)
+        ensure_known_host!(upstream)
+        same_repo = head_owner == upstream.owner
+        head = same_repo ? head_branch : "#{head_owner}:#{head_branch}"
+        params = { "expand" => "1", "title" => title, "body" => body }
+        "https://github.com/#{upstream.owner}/#{upstream.repo}/compare/#{head}?" \
+          "#{URI.encode_www_form(params)}"
+      end
+
+      # Pure URL templating — no auth, no network. Used by Operations to
+      # construct the `upstream` remote and by CLI verbs for summary output.
+      def clone_url(owner, repo)
+        "https://github.com/#{owner}/#{repo}.git"
+      end
+
+      def repo_url(owner, repo)
+        "https://github.com/#{owner}/#{repo}"
+      end
+
+      private
+
+      def existing_fork_result(viewer, project)
+        ForkResult.new(
+          clone_url: clone_url(viewer, project.repo),
+          fork_url: repo_url(viewer, project.repo),
+          viewer: viewer,
+          reused: true
+        )
+      end
+
+      def new_fork_result(viewer, project, body)
+        ForkResult.new(
+          clone_url: body.fetch("clone_url", clone_url(viewer, project.repo)),
+          fork_url: body.fetch("html_url", repo_url(viewer, project.repo)),
+          viewer: viewer,
+          reused: false
+        )
+      end
+
+      # GET /repos/:viewer/:repo. True iff the viewer already owns a repo at
+      # that name (which, for the fork flow, means an existing fork of the
+      # upstream).
+      def fork_exists?(viewer, repo_name)
         get_json("/repos/#{viewer}/#{repo_name}")
         true
       rescue AdapterError => e
@@ -126,7 +203,18 @@ module GemContribute
         raise
       end
 
-      private
+      def wait_until_fork_ready(viewer, repo_name)
+        ready = FORK_READINESS_RETRIES.times.any? do |i|
+          break true if fork_exists?(viewer, repo_name)
+
+          @sleeper.call(FORK_READINESS_INTERVAL) unless i == FORK_READINESS_RETRIES - 1
+          false
+        end
+        return if ready
+
+        raise AdapterError,
+              "fork not reachable after #{FORK_READINESS_RETRIES * FORK_READINESS_INTERVAL}s"
+      end
 
       def issue_cache_key(project, labels)
         label_segment = Array(labels).sort.join(",")
@@ -211,5 +299,6 @@ module GemContribute
         )
       end
     end
+    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/gem_contribute/operations/announce.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module GemContribute
+  module Operations
+    # Bootstrap step 4: post (or skip) a "working on this" comment on the
+    # upstream issue. The marker is an HTML comment in the body so re-runs
+    # detect prior posts deterministically.
+    #
+    # Format: `<!-- gem-contribute:<verb> v<n> -->`. Output-free per
+    # ADR-0012; callers render the outcome.
+    #
+    # Returns:
+    #   Success(:posted)  — comment was posted
+    #   Success(:skipped) — gating said no, OR the marker was already present
+    #   Failure([:announce_failed, message]) — adapter raised; the caller
+    #     usually treats this as a non-fatal warning rather than a fix failure
+    class Announce
+      include Dry::Monads[:result]
+
+      WORKING_MARKER = "<!-- gem-contribute:working v1 -->"
+      WORKING_BODY = <<~BODY.freeze
+        #{WORKING_MARKER}
+        👋 I've started working on this. I'll open a PR shortly.
+
+        <sub>Posted via [gem-contribute](https://github.com/cdhagmann/gem-contribute).</sub>
+      BODY
+
+      def call(adapter:, project:, issue:, allow:)
+        return Success(:skipped) unless allow
+        return Success(:skipped) if already_announced?(adapter, project, issue)
+
+        adapter.comment(project, issue: issue, body: WORKING_BODY)
+        Success(:posted)
+      rescue GemContribute::AdapterError => e
+        Failure([:announce_failed, e.message])
+      end
+
+      private
+
+      def already_announced?(adapter, project, issue)
+        comments = adapter.issue_comments(project, issue)
+        comments.any? { |c| c["body"].to_s.include?(WORKING_MARKER) }
+      rescue GemContribute::AdapterError
+        # If we can't fetch comments, assume not announced and let the
+        # post attempt fail safely on its own.
+        false
+      end
+    end
+  end
+end

data/lib/gem_contribute/operations/branch.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module GemContribute
+  module Operations
+    # Bootstrap step 3: create the per-issue working branch in the fork
+    # clone. The branch name is `gem-contribute/issue-<N>`. Output-free
+    # per ADR-0012.
+    #
+    # Note: `git checkout -b` fails if the branch already exists, which
+    # surfaces as `Failure([:adapter_error, ...])` here. That preserves
+    # the pre-extraction behaviour where re-running `fix` on an issue
+    # whose branch already exists locally errored out — see [#10] for
+    # the friendlier-message follow-up.
+    class Branch
+      include Dry::Monads[:result]
+
+      Result = Data.define(:name)
+      PREFIX = "gem-contribute/issue-"
+
+      def initialize(git: Git.new)
+        @git = git
+      end
+
+      def call(path:, issue:)
+        name = "#{PREFIX}#{issue}"
+        @git.checkout_branch(path, name)
+        Success(Result.new(name: name))
+      rescue GemContribute::AdapterError => e
+        Failure([:adapter_error, e.message])
+      end
+    end
+  end
+end

data/lib/gem_contribute/operations/clone.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+require "fileutils"
+
+module GemContribute
+  module Operations
+    # Bootstrap step 2: clone the fork into `<root>/<owner>/<repo>` (reusing
+    # an existing clone if one is there), and ensure an `upstream` remote
+    # points at the canonical project. Returns a `Result` carrying the
+    # local path and a `reused` flag, or a tagged `Failure`.
+    #
+    # The "reuse if `.git` exists" rule and the upstream-remote convention
+    # are gem-contribute policy on top of git, not git itself — that's why
+    # they live here rather than in `Git`.
+    class Clone
+      include Dry::Monads[:result]
+
+      Result = Data.define(:path, :reused)
+
+      def initialize(git: Git.new)
+        @git = git
+      end
+
+      def call(adapter:, project:, fork_clone_url:, root:)
+        target = File.join(root, project.owner, project.repo)
+        reused = File.directory?(File.join(target, ".git"))
+
+        unless reused
+          FileUtils.mkdir_p(File.dirname(target))
+          @git.clone(fork_clone_url, target)
+        end
+
+        @git.add_remote(target, "upstream", adapter.clone_url(project.owner, project.repo))
+        Success(Result.new(path: target, reused: reused))
+      rescue GemContribute::AdapterError => e
+        Failure([:adapter_error, e.message])
+      end
+    end
+  end
+end

data/lib/gem_contribute/operations/fix_pipeline.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "dry/operation"
+require "dry/monads"
+
+module GemContribute
+  module Operations
+    # Composes the four `fix` steps — Fork → Clone → Branch → Announce —
+    # using `dry-operation`. Each `step` short-circuits on Failure;
+    # Announce is called outside `step` because its Failure is
+    # informational (the fix has already happened) and should not
+    # propagate as a pipeline-level Failure.
+    #
+    # The pipeline itself is output-free per ADR-0012 — no spinners, no
+    # progress lines, no stdout. Callers (the CLI verb today; a TUI
+    # Command tomorrow) render the outcome.
+    #
+    # Inputs:
+    #   adapter         — HostAdapter instance (already authenticated)
+    #   project         — Project struct
+    #   issue           — String/Integer issue number (used in branch name)
+    #   root            — Clone-root directory
+    #   allow_announce  — Boolean. Verb-level gating (e.g. --no-comment,
+    #                     `comment_on_fix?` config) is collapsed into this
+    #                     bool by the caller. The pipeline additionally
+    #                     skips announce when `viewer == project.owner`
+    #                     (you don't need to announce on your own repo).
+    #
+    # Returns Success(hash) on the happy path:
+    #   { fork: Operations::Fork::Result,
+    #     clone: Operations::Clone::Result,
+    #     branch: Operations::Branch::Result,
+    #     announce: Result (Success(:posted | :skipped) | Failure([:announce_failed, msg])) }
+    class FixPipeline < Dry::Operation
+      def initialize(fork: nil, clone: nil, branch: nil, announce: nil, git: nil)
+        super()
+        git ||= Git.new
+        @fork = fork || Operations::Fork.new
+        @clone = clone || Operations::Clone.new(git: git)
+        @branch = branch || Operations::Branch.new(git: git)
+        @announce = announce || Operations::Announce.new
+      end
+
+      # `Dry::Operation` wraps the method's final return value in `Success`,
+      # so the body returns a raw hash. `step` unwraps Success and short-
+      # circuits on Failure; Announce is called outside `step` because its
+      # Failure is informational (the fix has already happened).
+      def call(adapter:, project:, issue:, root:, allow_announce:)
+        fork_result = step @fork.call(adapter: adapter, project: project)
+        clone_result = step @clone.call(
+          adapter: adapter, project: project,
+          fork_clone_url: fork_result.clone_url, root: root
+        )
+        branch_result = step @branch.call(path: clone_result.path, issue: issue)
+
+        allow = allow_announce && fork_result.viewer != project.owner
+        announce_result = @announce.call(
+          adapter: adapter, project: project, issue: issue, allow: allow
+        )
+
+        {
+          fork: fork_result,
+          clone: clone_result,
+          branch: branch_result,
+          announce: announce_result
+        }
+      end
+    end
+  end
+end

data/lib/gem_contribute/operations/fork.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "dry/monads"
+
+module GemContribute
+  module Operations
+    # Bootstrap step 1: ensure the viewer owns a fork of `project` (creating
+    # one if needed). Returns a `Result` describing what happened, or a
+    # tagged `Failure` for the caller to render. Does no filesystem work
+    # — that's `Operations::Clone`'s job. Does no I/O — that's the caller's
+    # job (per ADR-0012).
+    class Fork
+      include Dry::Monads[:result]
+
+      Result = Data.define(:clone_url, :fork_url, :upstream_url, :viewer, :reused)
+
+      def call(adapter:, project:)
+        fork = adapter.fork(project)
+        Success(
+          Result.new(
+            clone_url: fork.clone_url,
+            fork_url: fork.fork_url,
+            upstream_url: adapter.repo_url(project.owner, project.repo),
+            viewer: fork.viewer,
+            reused: fork.reused
+          )
+        )
+      rescue GemContribute::AuthRequired
+        Failure(:unauthenticated)
+      rescue GemContribute::AdapterError => e
+        Failure([:adapter_error, e.message])
+      end
+    end
+  end
+end

data/lib/gem_contribute/output/null.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module GemContribute
+  module Output
+    # No-op output sink. Inject into CLI verbs in tests that don't care
+    # about output (or want to assert on a separate capturing double).
+    #
+    # `#progress` accepts a block (mirroring `Output::Standard#progress`)
+    # and yields it; the spinner machinery is skipped entirely.
+    class Null
+      def info(_message) = nil
+      def warn(_message) = nil
+      def error(_message) = nil
+
+      def progress(_message)
+        block_given? ? yield : nil
+      end
+    end
+  end
+end

data/lib/gem_contribute/output/standard.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "tty-spinner"
+
+module GemContribute
+  module Output
+    # Semantic output abstraction for CLI verbs (per ADR-0012). Wraps
+    # stdout/stderr behind verb-shaped methods so the look-and-feel can
+    # evolve independently of the service layer.
+    #
+    # `#warn` and `#error` both write to stderr without prefixing — the
+    # caller's message already carries its own framing ("Note: ...",
+    # "warning: ...", "fix failed: ..."). The semantic split exists so a
+    # later styling pass (color, severity icons) has somewhere to hang.
+    #
+    # `#progress` has two forms:
+    #
+    #   * No block — equivalent to #info. Use when there's nothing to
+    #     wrap, e.g. you're announcing intent before a sequence of calls.
+    #   * Block form — runs the block while showing a tty-spinner in
+    #     interactive terminals. In non-TTY contexts (CI, piped output,
+    #     test StringIOs) it falls back to a plain line + yield. The
+    #     block's return value is the method's return value.
+    class Standard
+      def initialize(out: $stdout, err: $stderr)
+        @out = out
+        @err = err
+      end
+
+      def info(message)
+        @out.puts(message)
+      end
+
+      def progress(message, &)
+        return @out.puts(message) unless block_given?
+        return puts_and_yield(message, &) unless interactive?
+
+        spin(message, &)
+      end
+
+      def warn(message)
+        @err.puts(message)
+      end
+
+      def error(message)
+        @err.puts(message)
+      end
+
+      private
+
+      def interactive?
+        @out.respond_to?(:tty?) && @out.tty?
+      end
+
+      def puts_and_yield(message)
+        @out.puts(message)
+        yield
+      end
+
+      def spin(message)
+        spinner = TTY::Spinner.new("[:spinner] #{message}", output: @out, format: :dots)
+        spinner.auto_spin
+        begin
+          yield
+        ensure
+          spinner.stop
+        end
+      end
+    end
+  end
+end

data/lib/gem_contribute/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GemContribute
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/gem_contribute.rb

@@ -1,15 +1,19 @@
 # frozen_string_literal: true
 
+require "zeitwerk"
 require_relative "gem_contribute/version"
 require_relative "gem_contribute/errors"
 
-module GemContribute
-  autoload :LockedGem, "gem_contribute/locked_gem"
-  autoload :Project, "gem_contribute/project"
+loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/gem_contribute/version.rb")
+loader.ignore("#{__dir__}/gem_contribute/errors.rb")
+loader.inflector.inflect(
+  "cli" => "CLI",
+  "github_adapter" => "GitHubAdapter"
+)
+loader.setup
 
-  # The canonical Project for gem-contribute itself. Used by the CLI to
-  # short-circuit resolution (gem-contribute isn't on RubyGems yet) and
-  # to auto-inject the tool into its own scan results.
+module GemContribute
   SELF_PROJECT = Project.new(
     gem_name: "gem-contribute",
     host: "github.com",
@@ -17,16 +21,4 @@ module GemContribute
     repo: "gem-contribute",
     metadata: { self_injected: true }
   ).freeze
-  autoload :LockfileParser, "gem_contribute/lockfile_parser"
-  autoload :Cache, "gem_contribute/cache"
-  autoload :Resolver, "gem_contribute/resolver"
-  autoload :HostAdapter, "gem_contribute/host_adapter"
-  autoload :Auth, "gem_contribute/auth"
-  autoload :Config, "gem_contribute/config"
-  autoload :TokenStore, "gem_contribute/token_store"
-  autoload :CLI, "gem_contribute/cli"
-
-  module HostAdapters
-    autoload :GitHubAdapter, "gem_contribute/host_adapters/github_adapter"
-  end
 end