prdigest 0.1.0

data/lib/prdigest/config.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "pathname"
+require "tzinfo"
+
+module Prdigest
+  class Config
+    attr_reader :raw, :path
+
+    REPOSITORY_SEGMENT = /\A[A-Za-z0-9_.-]+\z/
+
+    def self.resolve_path(explicit: nil, env: ENV, system_path: "/etc/prdigest/config.yml")
+      return File.expand_path(explicit) if explicit && !explicit.to_s.empty?
+
+      from_env = env["PRDIGEST_CONFIG"].to_s
+      return File.expand_path(from_env) unless from_env.empty?
+      return system_path if File.file?(system_path)
+
+      raise ConfigError, "config path is required (--config, PRDIGEST_CONFIG, or /etc/prdigest/config.yml)"
+    end
+
+    def self.load(path)
+      path = File.expand_path(path)
+      raise ConfigError, "config not found: #{path}" unless File.file?(path)
+
+      raw = YAML.safe_load_file(path, aliases: true)
+      raise ConfigError, "config root must be a mapping" unless raw.is_a?(Hash)
+
+      new(raw, path: path).tap(&:validate!)
+    rescue ConfigError
+      raise
+    rescue StandardError => e
+      raise ConfigError, "cannot load config: #{e.class}"
+    end
+
+    def self.normalize_repos(values, label: "repository")
+      normalized = Array(values).map { |value| value.to_s.strip }
+      raise ConfigError, "#{label} must list at least one owner/name" if normalized.empty?
+
+      invalid = normalized.find do |repository|
+        parts = repository.split("/", -1)
+        parts.length != 2 ||
+          parts.any? { |part| part.empty? || %w[. ..].include?(part) || !part.match?(REPOSITORY_SEGMENT) }
+      end
+      raise ConfigError, "#{label} entry must be owner/name; got #{invalid.inspect}" if invalid
+
+      normalized.each_with_object({}) do |repository, unique|
+        unique[repository.downcase] ||= repository
+      end.values.freeze
+    end
+
+    def initialize(raw, path: nil)
+      @raw = raw
+      @path = path
+    end
+
+    def timezone
+      raw.fetch("timezone", "UTC").to_s
+    end
+
+    def repos
+      self.class.normalize_repos(raw.dig("github", "repos"), label: "github.repos")
+    end
+
+    def github_token(env = ENV)
+      env_name = raw.dig("github", "token_env") || "GITHUB_TOKEN"
+      env[env_name.to_s].to_s
+    end
+
+    def telegram_token(env = ENV)
+      env_name = raw.dig("telegram", "token_env") || "TELEGRAM_BOT_TOKEN"
+      env[env_name.to_s].to_s
+    end
+
+    def chat_id
+      Integer(raw.dig("telegram", "chat_id"))
+    rescue TypeError, ArgumentError
+      nil
+    end
+
+    def chat_id_allowlist
+      Array(raw.dig("telegram", "chat_id_allowlist")).map { |id| Integer(id) }
+    rescue TypeError, ArgumentError
+      []
+    end
+
+    def line_stats?
+      raw.dig("digest", "line_stats") != false
+    end
+
+    def send_empty?
+      raw.dig("digest", "send_empty") != false
+    end
+
+    def empty_message
+      raw.dig("digest", "empty_message") || "Merged PR digest — {date}\nTotal: 0 PRs"
+    end
+
+    def state_path
+      raw.dig("state", "path") || File.expand_path("~/.local/share/prdigest/state.json")
+    end
+
+    def delivery_state_path
+      raw.dig("state", "delivery_path") || File.join(File.dirname(state_path), "deliveries")
+    end
+
+    def schedule_cron
+      raw.dig("schedule", "cron") || "5 9 * * *"
+    end
+
+    def max_catchup_days
+      Integer(raw.dig("schedule", "max_catchup_days") || 7)
+    rescue TypeError, ArgumentError
+      raise ConfigError, "schedule.max_catchup_days must be an integer from 1 to 30"
+    end
+
+    def validate!
+      begin
+        TZInfo::Timezone.get(timezone)
+      rescue TZInfo::InvalidTimezoneIdentifier
+        raise ConfigError, "timezone must be a resolvable IANA identifier"
+      end
+      unless (1..30).cover?(max_catchup_days)
+        raise ConfigError, "schedule.max_catchup_days must be from 1 to 30"
+      end
+      repos
+      raise ConfigError, "telegram.chat_id is required" if chat_id.nil?
+      raise ConfigError, "telegram.chat_id_allowlist must not be empty" if chat_id_allowlist.empty?
+      unless chat_id_allowlist.include?(chat_id)
+        raise ConfigError, "telegram.chat_id must be present in chat_id_allowlist"
+      end
+      self
+    end
+  end
+end

data/lib/prdigest/delivery_checkpoint_store.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+require "date"
+require "digest"
+require "fileutils"
+require "json"
+require "time"
+
+module Prdigest
+  class DeliveryCheckpointStore
+    SCHEMA = "prdigest-delivery-checkpoint"
+    SCHEMA_VERSION = 1
+
+    class Session
+      def initialize(path:, data:)
+        @path = path
+        @data = data
+      end
+
+      def chunks
+        @data.fetch("chunks")
+      end
+
+      def next_chunk
+        @data.fetch("next_chunk")
+      end
+
+      def completed?
+        @data.fetch("status") == "completed"
+      end
+
+      def begin_attempt(index)
+        require_next_chunk!(index)
+        @data["in_flight"] = { "chunk" => index, "started_at" => timestamp }
+        persist!
+      end
+
+      def accept(index)
+        require_in_flight!(index)
+        @data["next_chunk"] = index + 1
+        @data["in_flight"] = nil
+        @data["status"] = next_chunk == chunks.length ? "completed" : "pending"
+        @data["permanent_error"] = nil
+        persist!
+      end
+
+      def reject(index, kind:, message:, permanent:)
+        require_in_flight!(index)
+        @data["in_flight"] = nil
+        if permanent
+          @data["status"] = "blocked"
+          @data["permanent_error"] = {
+            "kind" => kind.to_s,
+            "message" => message.to_s,
+            "failed_chunk" => index
+          }
+        else
+          @data["permanent_error"] = nil
+        end
+        persist!
+      end
+
+      def delivery(failed_chunk: nil)
+        result = {
+          accepted_chunks: next_chunk,
+          total_chunks: chunks.length,
+          status: @data.fetch("status")
+        }
+        result[:failed_chunk] = failed_chunk unless failed_chunk.nil?
+        result
+      end
+
+      private
+
+      def require_next_chunk!(index)
+        return if index == next_chunk && @data["in_flight"].nil? && !completed?
+
+        raise StateError, "delivery checkpoint transition is invalid"
+      end
+
+      def require_in_flight!(index)
+        return if @data.dig("in_flight", "chunk") == index
+
+        raise StateError, "delivery checkpoint transition is invalid"
+      end
+
+      def persist!
+        @data["updated_at"] = timestamp
+        DeliveryCheckpointStore.atomic_write(@path, JSON.pretty_generate(@data))
+      rescue StateError
+        raise
+      rescue StandardError => e
+        raise StateError, "cannot persist delivery checkpoint (#{e.class})"
+      end
+
+      def timestamp
+        Time.now.utc.iso8601(6)
+      end
+    end
+
+    def initialize(root:)
+      @root = File.expand_path(root)
+    end
+
+    def with_checkpoint(date:, chat_id:, scope:, chunks:)
+      normalized_date = Date.iso8601(date.to_s)
+      ensure_root!
+      path = File.join(@root, "#{normalized_date}.json")
+      lock_path = File.join(@root, "#{normalized_date}.lock")
+
+      File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+        File.chmod(0o600, lock_path)
+        unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+          raise SendError.new(
+            "delivery checkpoint is already active",
+            kind: "delivery_checkpoint",
+            delivery: { accepted_chunks: 0, total_chunks: Array(chunks).length, status: "pending" }
+          )
+        end
+
+        data = load_or_create(
+          path,
+          date: normalized_date,
+          chat_id: Integer(chat_id),
+          scope: Array(scope).map(&:to_s),
+          chunks: Array(chunks).map(&:to_s)
+        )
+        fail_if_unavailable!(data)
+        yield Session.new(path: path, data: data)
+      ensure
+        lock.flock(File::LOCK_UN)
+      end
+    rescue SendError, StateError
+      raise
+    rescue StandardError => e
+      raise StateError, "cannot access delivery checkpoint (#{e.class})"
+    end
+
+    def self.atomic_write(path, content)
+      directory = File.dirname(path)
+      temporary = "#{path}.tmp-#{Process.pid}-#{Thread.current.object_id}"
+      File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+        file.write(content)
+        file.flush
+        file.fsync
+      end
+      File.rename(temporary, path)
+      File.chmod(0o600, path)
+      File.open(directory, File::RDONLY, &:fsync)
+    ensure
+      File.unlink(temporary) if temporary && File.exist?(temporary)
+    end
+
+    private
+
+    def ensure_root!
+      FileUtils.mkdir_p(@root, mode: 0o700)
+      File.chmod(0o700, @root)
+    end
+
+    def load_or_create(path, date:, chat_id:, scope:, chunks:)
+      if File.file?(path)
+        data = JSON.parse(File.read(path))
+        validate!(data, date: date, chat_id: chat_id, scope: scope)
+        data
+      else
+        data = {
+          "schema" => SCHEMA,
+          "schema_version" => SCHEMA_VERSION,
+          "date" => date.to_s,
+          "chat_id" => chat_id,
+          "scope" => scope,
+          "chunks" => chunks,
+          "chunks_sha256" => chunk_digest(chunks),
+          "next_chunk" => 0,
+          "status" => chunks.empty? ? "completed" : "pending",
+          "in_flight" => nil,
+          "permanent_error" => nil,
+          "created_at" => Time.now.utc.iso8601(6),
+          "updated_at" => Time.now.utc.iso8601(6)
+        }
+        self.class.atomic_write(path, JSON.pretty_generate(data))
+        data
+      end
+    rescue SendError
+      raise
+    rescue JSON::ParserError, KeyError, TypeError, ArgumentError => e
+      raise SendError.new(
+        "delivery checkpoint is invalid (#{e.class})",
+        kind: "delivery_checkpoint_permanent"
+      )
+    end
+
+    def validate!(data, date:, chat_id:, scope:)
+      expected = {
+        "schema" => SCHEMA,
+        "schema_version" => SCHEMA_VERSION,
+        "date" => date.to_s,
+        "chat_id" => chat_id,
+        "scope" => scope
+      }
+      unless expected.all? { |key, value| data.fetch(key) == value }
+        raise SendError.new(
+          "delivery checkpoint does not match this digest",
+          kind: "delivery_checkpoint_permanent"
+        )
+      end
+
+      chunks = data.fetch("chunks")
+      next_chunk = data.fetch("next_chunk")
+      status = data.fetch("status")
+      valid = chunks.is_a?(Array) && chunks.all? { |chunk| chunk.is_a?(String) } &&
+              data.fetch("chunks_sha256") == chunk_digest(chunks) &&
+              next_chunk.is_a?(Integer) && next_chunk.between?(0, chunks.length) &&
+              valid_transition_state?(data, status: status, next_chunk: next_chunk, total_chunks: chunks.length)
+      raise KeyError, "invalid delivery checkpoint fields" unless valid
+    end
+
+    def valid_transition_state?(data, status:, next_chunk:, total_chunks:)
+      in_flight = data.fetch("in_flight")
+      permanent_error = data.fetch("permanent_error")
+      case status
+      when "pending"
+        next_chunk < total_chunks &&
+          valid_in_flight?(in_flight, next_chunk) &&
+          permanent_error.nil?
+      when "completed"
+        next_chunk == total_chunks && in_flight.nil? && permanent_error.nil?
+      when "blocked"
+        next_chunk < total_chunks && in_flight.nil? &&
+          permanent_error.is_a?(Hash) &&
+          permanent_error["kind"].is_a?(String) &&
+          permanent_error["message"].is_a?(String) &&
+          permanent_error["failed_chunk"] == next_chunk
+      else
+        false
+      end
+    end
+
+    def valid_in_flight?(in_flight, next_chunk)
+      in_flight.nil? ||
+        (in_flight.is_a?(Hash) &&
+         in_flight["chunk"] == next_chunk &&
+         in_flight["started_at"].is_a?(String))
+    end
+
+    def fail_if_unavailable!(data)
+      session = Session.new(path: "", data: data)
+      if data["in_flight"]
+        failed_chunk = data.dig("in_flight", "chunk")
+        raise SendError.new(
+          "Telegram delivery outcome is ambiguous; operator reconciliation is required",
+          kind: "telegram_ambiguous",
+          delivery: session.delivery(failed_chunk: failed_chunk)
+        )
+      end
+
+      return unless data["status"] == "blocked"
+
+      failure = data.fetch("permanent_error")
+      raise SendError.new(
+        failure.fetch("message"),
+        kind: failure.fetch("kind"),
+        delivery: session.delivery(failed_chunk: failure.fetch("failed_chunk"))
+      )
+    end
+
+    def chunk_digest(chunks)
+      ::Digest::SHA256.hexdigest(JSON.generate(chunks))
+    end
+  end
+end

data/lib/prdigest/digest.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Prdigest
+  PullRequest = Data.define(
+    :repository, :number, :title, :url, :author, :merged_at,
+    :additions, :deletions, :commits
+  ) do
+    def initialize(repository:, number:, title:, url:, author:, merged_at:, additions: nil, deletions: nil, commits: nil)
+      super(
+        repository: repository.to_s.freeze,
+        number: Integer(number),
+        title: title.to_s.freeze,
+        url: url.to_s.freeze,
+        author: author.to_s.freeze,
+        merged_at: merged_at.utc.freeze,
+        additions: additions && Integer(additions),
+        deletions: deletions && Integer(deletions),
+        commits: commits && Integer(commits)
+      )
+    end
+  end
+
+  RepositoryDigest = Data.define(:name, :pull_requests)
+
+  DayDigest = Data.define(:date, :repositories, :line_stats) do
+    def self.build(date:, repository_order:, pulls:, line_stats: false)
+      grouped = pulls.group_by(&:repository)
+      sections = repository_order.map do |name|
+        sorted = Array(grouped[name]).sort_by { |pull| [pull.merged_at, pull.number] }.freeze
+        RepositoryDigest.new(name.to_s.freeze, sorted)
+      end.freeze
+      new(Date.iso8601(date.to_s), sections, line_stats == true)
+    end
+
+    def total_prs
+      repositories.sum { |section| section.pull_requests.length }
+    end
+
+    def total_additions
+      stat_total(:additions)
+    end
+
+    def total_deletions
+      stat_total(:deletions)
+    end
+
+    def total_commits
+      stat_total(:commits)
+    end
+
+    private
+
+    def stat_total(name)
+      return nil unless line_stats
+      repositories.sum { |section| section.pull_requests.sum { |pull| pull.public_send(name) } }
+    end
+  end
+end

data/lib/prdigest/github.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require "octokit"
+require "set"
+require "time"
+
+module Prdigest
+  class GitHub
+    SEARCH_CAP = 1_000
+    MAX_ATTEMPTS = 3
+
+    def initialize(token:, client: nil, sleeper: ->(seconds) { sleep(seconds) }, now: -> { Time.now.to_i })
+      @token = token.to_s
+      @client = client || default_client
+      @sleeper = sleeper
+      @now = now
+    end
+
+    def fetch(date:, window:, repositories:, line_stats: false)
+      pulls = repositories.flat_map do |repository|
+        fetch_repository(repository, date, window, line_stats)
+      end
+      DayDigest.build(date: date, repository_order: repositories, pulls: pulls, line_stats: line_stats)
+    end
+
+    def inspect
+      "#<#{self.class} token=[REDACTED]>"
+    end
+
+    alias to_s inspect
+
+    private
+
+    def default_client
+      middleware = Octokit::Default::MIDDLEWARE.dup
+      middleware.handlers.reject! { |handler| retry_middleware?(handler.klass) }
+      Octokit::Client.new(
+        access_token: @token,
+        middleware: middleware,
+        connection_options: { request: { open_timeout: 10, timeout: 30, write_timeout: 30 } }
+      )
+    end
+
+    def retry_middleware?(middleware)
+      %w[Faraday::Request::Retry Faraday::Retry::Middleware].include?(middleware.name)
+    end
+
+    def fetch_repository(repository, date, window, line_stats)
+      return [] if window.zero_length?
+
+      query = build_query(repository, window)
+      page = 1
+      items = []
+      seen_numbers = Set.new
+      total = nil
+      loop do
+        response = request(repository, date) { @client.search_issues(query, per_page: 100, page: page) }
+        incomplete = field(response, :incomplete_results)
+        fail_fetch!(repository, date, "incomplete search results") if incomplete
+        response_total = Integer(field(response, :total_count))
+        fail_fetch!(repository, date, "search result cap exceeded") if response_total > SEARCH_CAP
+        total ||= response_total
+        fail_fetch!(repository, date, "search total changed during pagination") unless total == response_total
+
+        page_items = Array(field(response, :items))
+        page_items.each do |item|
+          number = Integer(field(item, :number))
+          fail_fetch!(repository, date, "pagination repeated a pull request") unless seen_numbers.add?(number)
+        end
+        items.concat(page_items)
+        fail_fetch!(repository, date, "pagination exceeded total") if items.length > total
+        break if items.length == total
+        fail_fetch!(repository, date, "pagination stopped before total") if page_items.empty?
+        page += 1
+      end
+
+      mapped = items.map { |item| map_item(item, repository, date, window) }
+      return mapped unless line_stats
+
+      mapped.map do |pull|
+        detail = request(repository, date) { @client.pull_request(repository, pull.number) }
+        PullRequest.new(
+          **pull.to_h,
+          additions: Integer(field(detail, :additions)),
+          deletions: Integer(field(detail, :deletions)),
+          commits: Integer(field(detail, :commits))
+        )
+      end
+    rescue FetchError
+      raise
+    rescue StandardError => e
+      fail_fetch!(repository, date, "malformed GitHub response (#{e.class})")
+    end
+
+    def build_query(repository, window)
+      finish = window.end_time - 1
+      "repo:#{repository} is:pr is:merged merged:#{timestamp(window.start_time)}..#{timestamp(finish)}"
+    end
+
+    def timestamp(time)
+      time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+    end
+
+    def map_item(item, repository, date, window)
+      actual_repository = repository_name(item)
+      merged_at = Time.iso8601(field(field(item, :pull_request), :merged_at).to_s).utc
+      unless actual_repository.casecmp?(repository) && window.cover?(merged_at)
+        fail_fetch!(repository, date, "result outside requested repository or UTC window")
+      end
+
+      PullRequest.new(
+        repository: repository,
+        number: Integer(field(item, :number)),
+        title: field(item, :title),
+        url: field(item, :html_url),
+        author: field(field(item, :user), :login),
+        merged_at: merged_at
+      )
+    end
+
+    def repository_name(item)
+      repository = optional_field(item, :repository)
+      full_name = optional_field(repository, :full_name) if repository
+      return full_name.to_s unless full_name.to_s.empty?
+
+      url = field(item, :repository_url).to_s
+      match = url.match(%r{/repos/([^/]+/[^/]+)\z})
+      raise KeyError, "repository identity missing" unless match
+      match[1]
+    end
+
+    def field(object, key)
+      value = optional_field(object, key)
+      raise KeyError, key if value.nil?
+      value
+    end
+
+    def optional_field(object, key)
+      if object.respond_to?(:key?)
+        return object[key] if object.key?(key)
+        return object[key.to_s] if object.key?(key.to_s)
+      end
+      return object.public_send(key) if object.respond_to?(key)
+    end
+
+    def request(repository, date)
+      attempts = 0
+      begin
+        attempts += 1
+        yield
+      rescue StandardError => e
+        unless transient?(e) && attempts < MAX_ATTEMPTS
+          fail_fetch!(repository, date, error_kind(e))
+        end
+        delay = retry_delay(e) || attempts
+        fail_fetch!(repository, date, "retry delay exceeds 60 seconds") if delay > 60
+        @sleeper.call(delay)
+        retry
+      end
+    end
+
+    def transient?(error)
+      error.is_a?(Octokit::ServerError) ||
+        rate_limited?(error) ||
+        (defined?(Faraday::ConnectionFailed) && error.is_a?(Faraday::ConnectionFailed)) ||
+        (defined?(Faraday::TimeoutError) && error.is_a?(Faraday::TimeoutError))
+    end
+
+    def rate_limited?(error)
+      error.is_a?(Octokit::TooManyRequests) ||
+        (error.respond_to?(:response_status) && Integer(error.response_status, exception: false) == 429)
+    end
+
+    def retry_delay(error)
+      headers = error.respond_to?(:response_headers) ? error.response_headers : nil
+      retry_after = Integer(response_header(headers, "retry-after"), exception: false)
+      return retry_after if retry_after
+
+      reset_at = Integer(response_header(headers, "x-ratelimit-reset"), exception: false)
+      [reset_at - Integer(@now.call), 0].max if reset_at
+    rescue StandardError
+      nil
+    end
+
+    def response_header(headers, name)
+      return unless headers
+
+      Faraday::Utils::Headers.from(headers)[name]
+    end
+
+    def error_kind(error)
+      transient?(error) ? "GitHub request retries exhausted" : "GitHub request refused"
+    end
+
+    def fail_fetch!(repository, date, reason)
+      raise FetchError.new("GitHub fetch failed for #{repository} on #{date}: #{reason}", kind: "github")
+    end
+  end
+end