spill 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e3fbd52dab7cb94bc936122dce281e3f08a854df2814ae8dd136cd7ceb05cc55
+  data.tar.gz: d6b2c9fe0a68bae6a2295f84a82c60b16075f142632f3f4362e7a2ad1a8a0bec
+SHA512:
+  metadata.gz: 7c7d6bfe3c753170d59d469f79ac94bfd8655a72fa41141d3808a73cae96ab5ed048c7af2ef7092a06910ae8520630d2d8df6c5065490d064bf254ed05064b16
+  data.tar.gz: a9327e2dc50834fc63c7e9afbab1b05954347c98dfa2e96e4908c3c9e91d7d8e07d9509ca24fec7f84edc4e8ce6bb3458d424718d0a5ec8cb8ed3dd58eb21870

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-04
+
+- Initial release: Done/Doing standup report from local git and GitHub (`gh`).

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tugcem Yalcin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,50 @@
+# spill 🍵
+
+Your standup, spilled. `spill` scans a folder of git repos and prints what you
+**did** and what you're **doing** — synthesized from local git and (optionally)
+your GitHub activity via the `gh` CLI. Not a commit dump: merged PRs, reviews
+you gave, branches in flight, uncommitted work.
+
+    $ cd ~/code && spill
+
+    spill · Fri Jul 4 · today + yesterday
+
+    DONE
+      icebreaker-bingo · main · 7 commits
+        Scaffold Rails 8.1 app on Ruby 4.0.4
+        Add QR code page
+      GitHub
+        merged PR #12 (acme/website) — Fix nav
+        reviewed PR #87 (acme/dashboard) — Payout calc
+
+    DOING
+      icebreaker-bingo · feed-page: 3 unpushed commits
+      website: uncommitted changes (4 files)
+      PR #14 open (acme/website) — Live feed
+
+    3 quiet repos skipped
+
+## Install
+
+    gem install spill
+
+Requires Ruby ≥ 3.2 and `git`. The GitHub section lights up automatically if
+the [gh CLI](https://cli.github.com) is installed and authenticated — no
+tokens, no config. No `gh`? Local git still works; the section is skipped.
+
+## Usage
+
+    spill                      # scan the current directory (repos up to 2 levels down)
+    spill ~/code               # scan somewhere else
+    spill --since "3 days ago" # wider window ("yesterday", "2 weeks ago", "2026-07-01")
+    spill --author me@work.com # override the git author
+    spill --no-github          # local git only
+
+## Roadmap
+
+Deployment detection, a NEXT section from issue trackers, and an LLM narrator —
+see [docs/specs](docs/specs/) for the layered design.
+
+## License
+
+MIT

data/exe/spill

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "spill"
+
+exit Spill::CLI.run(ARGV)

data/lib/spill/cli.rb

@@ -0,0 +1,45 @@
+require "optparse"
+
+module Spill
+  class CLI
+    def self.run(argv, stdout: $stdout)
+      options = { github: true }
+      early_exit = false
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: spill [ROOT] [options]"
+        opts.on("--since EXPR", 'Window start: "yesterday", "3 days ago", "2026-07-01"') { |v| options[:since] = v }
+        opts.on("--author EMAIL", "Override the commit author for all repos") { |v| options[:author] = v }
+        opts.on("--no-github", "Skip the GitHub layer") { options[:github] = false }
+        opts.on("--version", "Print version") do
+          stdout.puts Spill::VERSION
+          early_exit = true
+        end
+        opts.on("-h", "--help", "Show this help") do
+          stdout.puts opts
+          early_exit = true
+        end
+      end
+
+      args = parser.parse(argv)
+      return 0 if early_exit
+
+      report = build_report(args, options)
+      color = stdout.respond_to?(:tty?) && stdout.tty? && ENV["NO_COLOR"].nil?
+      stdout.puts Renderer.render(report, color: color)
+      0
+    rescue OptionParser::ParseError, ArgumentError => e
+      stdout.puts "spill: #{e.message}"
+      0
+    end
+
+    def self.build_report(args, options)
+      window = options[:since] ? Window.parse(options[:since]) : Window.default
+      repo_paths = RepoFinder.find(args.first || Dir.pwd)
+      local = Collectors::LocalGit.new(repo_paths: repo_paths, author: options[:author])
+                                  .collect(window: window)
+      github = options[:github] ? Collectors::Github.new.collect(window: window) : []
+      Report.build(local: local, github: github,
+                   repos: repo_paths.map { |path| File.basename(path) }, window: window)
+    end
+  end
+end

data/lib/spill/collectors/github.rb

@@ -0,0 +1,129 @@
+require "json"
+require "open3"
+require "time"
+
+module Spill
+  module Collectors
+    class Github
+      MAX_PAGES = 3
+      PAGE_SIZE = 100
+
+      DEFAULT_RUNNER = lambda do |args|
+        out, _err, status = Open3.capture3("gh", *args)
+        [ out, status.success? ]
+      rescue Errno::ENOENT
+        [ "", false ]
+      end
+
+      def initialize(runner: DEFAULT_RUNNER)
+        @runner = runner
+      end
+
+      def collect(window:)
+        login = fetch_login
+        return nil if login.nil?
+
+        raw = fetch_raw_events(login)
+        return nil if raw.nil?
+
+        events = raw.filter_map { |item| map_event(item) }
+                    .select { |event| event.timestamp >= window.since }
+        open_prs = open_pr_events(login)
+        return nil if open_prs.nil?
+
+        events.concat(open_prs)
+        events << truncation_event(raw) if truncated?(raw, window)
+        events
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      def fetch_login
+        out, ok = @runner.call([ "api", "user" ])
+        return nil unless ok
+
+        JSON.parse(out)["login"]
+      rescue JSON::ParserError
+        nil
+      end
+
+      def fetch_raw_events(login)
+        raw = []
+        (1..MAX_PAGES).each do |page|
+          out, ok = @runner.call([ "api", "users/#{login}/events?per_page=#{PAGE_SIZE}&page=#{page}" ])
+          return nil unless ok
+
+          batch = JSON.parse(out)
+          raw.concat(batch)
+          break if batch.size < PAGE_SIZE
+        end
+        raw
+      rescue JSON::ParserError
+        nil
+      end
+
+      def map_event(item)
+        repo = item.dig("repo", "name")
+        created = item["created_at"]
+        return nil if created.nil?
+
+        time = Time.parse(created).localtime
+        case item["type"]
+        when "PullRequestEvent" then map_pull_request(item, repo, time)
+        when "PullRequestReviewEvent" then build(:review, item.dig("payload", "pull_request"), repo, time)
+        when "IssuesEvent"
+          build(:issue_closed, item.dig("payload", "issue"), repo, time) if item.dig("payload", "action") == "closed"
+        end
+      end
+
+      def map_pull_request(item, repo, time)
+        pull = item.dig("payload", "pull_request")
+        return nil if pull.nil?
+
+        case item.dig("payload", "action")
+        when "opened" then build(:pr_opened, pull, repo, time)
+        when "closed" then build(:pr_merged, pull, repo, time) if pull["merged"]
+        end
+      end
+
+      def build(kind, subject, repo, time)
+        return nil if subject.nil?
+
+        Event.new(source: :github, kind: kind, repo: repo, title: subject["title"],
+                  ref: "##{subject["number"]}", timestamp: time)
+      end
+
+      def open_pr_events(login)
+        query = "search/issues?q=is:pr+is:open+author:#{login}&per_page=50&advanced_search=true"
+        out, ok = @runner.call([ "api", query ])
+        return nil unless ok
+
+        JSON.parse(out).fetch("items", []).map do |item|
+          Event.new(source: :github, kind: :pr_open,
+                    repo: item["repository_url"].to_s.split("/repos/").last,
+                    title: item["title"], ref: "##{item["number"]}",
+                    timestamp: Time.parse(item["updated_at"]).localtime)
+        end
+      rescue JSON::ParserError
+        nil
+      end
+
+      def truncated?(raw, window)
+        return false if raw.size < MAX_PAGES * PAGE_SIZE
+
+        oldest_time(raw) > window.since
+      end
+
+      def truncation_event(raw)
+        Event.new(source: :github, kind: :github_truncated, repo: nil,
+                  extra: { oldest: oldest_time(raw) })
+      end
+
+      def oldest_time(raw)
+        raw.map { |item| Time.parse(item["created_at"]) }.min.localtime
+      end
+    end
+  end
+end

data/lib/spill/collectors/local_git.rb

@@ -0,0 +1,94 @@
+require "open3"
+require "time"
+
+module Spill
+  module Collectors
+    class LocalGit
+      SEP = "\x1f"
+
+      def initialize(repo_paths:, author: nil)
+        @repo_paths = repo_paths
+        @author = author
+      end
+
+      def collect(window:)
+        @repo_paths.flat_map { |path| repo_events(path, window) }
+      end
+
+      private
+
+      def repo_events(path, window)
+        name = File.basename(path)
+        events = []
+        email = @author || git(path, "config", "user.email")&.strip
+        events.concat(commit_events(path, name, email, window)) unless email.nil? || email.empty?
+        events.concat(state_events(path, name))
+        events
+      end
+
+      def commit_events(path, name, email, window)
+        seen = {}
+        ordered_branches(path).flat_map do |branch|
+          log = git(path, "log", branch, "--no-merges", "--author=#{email}",
+                    "--since=#{window.since.iso8601}", "--date=iso-strict",
+                    "--pretty=format:%H#{SEP}%ad#{SEP}%s")
+          next [] if log.nil?
+
+          log.each_line(chomp: true).filter_map do |line|
+            sha, date, subject = line.split(SEP, 3)
+            next if sha.nil? || seen[sha]
+
+            seen[sha] = true
+            Event.new(source: :local_git, kind: :commit, repo: name, title: subject,
+                      ref: branch, timestamp: Time.parse(date), extra: { sha: sha })
+          end
+        end
+      end
+
+      def state_events(path, name)
+        events = []
+        dirty = (git(path, "status", "--porcelain") || "").lines.count
+        if dirty.positive?
+          events << Event.new(source: :local_git, kind: :dirty_tree, repo: name,
+                              extra: { files: dirty })
+        end
+        events.concat(unpushed_events(path, name))
+        events
+      end
+
+      def unpushed_events(path, name)
+        return [] if (git(path, "remote") || "").strip.empty?
+
+        refs = git(path, "for-each-ref", "refs/heads",
+                   "--format=%(refname:short)#{SEP}%(upstream:short)#{SEP}%(upstream:track)")
+        (refs || "").each_line(chomp: true).filter_map do |line|
+          branch, upstream, track = line.split(SEP, 3)
+          if upstream.nil? || upstream.empty?
+            count = git(path, "rev-list", "--count", branch, "--not", "--remotes").to_i
+            next unless count.positive?
+
+            Event.new(source: :local_git, kind: :branch_wip, repo: name, ref: branch,
+                      extra: { unpushed: count, no_upstream: true })
+          elsif track =~ /ahead (\d+)/
+            Event.new(source: :local_git, kind: :branch_wip, repo: name, ref: branch,
+                      extra: { ahead: Regexp.last_match(1).to_i })
+          end
+        end
+      end
+
+      def ordered_branches(path)
+        head = git(path, "symbolic-ref", "--short", "HEAD")&.strip
+        all = (git(path, "for-each-ref", "refs/heads", "--format=%(refname:short)") || "")
+              .each_line(chomp: true).to_a
+        ([ head ] + (all - [ head ]).sort).compact.uniq
+      end
+
+      def git(path, *args)
+        out, _err, status = Open3.capture3("git", "-C", path, *args)
+        status.success? ? out : nil
+      rescue Errno::ENOENT
+        nil
+      end
+    end
+  end
+end

data/lib/spill/event.rb

@@ -0,0 +1,7 @@
+module Spill
+  Event = Data.define(:source, :kind, :repo, :title, :ref, :timestamp, :extra) do
+    def initialize(source:, kind:, repo:, title: nil, ref: nil, timestamp: nil, extra: {})
+      super
+    end
+  end
+end

data/lib/spill/renderer.rb

@@ -0,0 +1,90 @@
+module Spill
+  module Renderer
+    module_function
+
+    def render(report, color: false, now: Time.now)
+      lines = [ "#{style("spill", :bold, color)} · #{now.strftime("%a %b %-d")} · #{report.window.label}" ]
+      if empty?(report)
+        lines << "" << "Nothing to spill. 🍵"
+      else
+        lines.concat(done_lines(report, color))
+        lines.concat(doing_lines(report, color))
+        lines.concat(quiet_lines(report, color))
+      end
+      report.notes.each { |note| lines << "" << style(note, :dim, color) }
+      lines.join("\n") << "\n"
+    end
+
+    def empty?(report)
+      report.done.empty? && report.github_done.empty? && report.doing.empty?
+    end
+
+    def done_lines(report, color)
+      return [] if report.done.empty? && report.github_done.empty?
+
+      lines = [ "", style("DONE", :bold, color) ]
+      report.done.each do |entry|
+        entry[:branches].each do |branch|
+          count = branch[:commits].size
+          lines << "  #{entry[:repo]} · #{branch[:name]} · #{pluralize(count, "commit")}"
+          branch[:commits].each { |commit| lines << "    #{commit.title}" }
+        end
+      end
+      if report.github_done.any?
+        lines << "  GitHub"
+        report.github_done.each { |event| lines << "    #{github_line(event)}" }
+      end
+      lines
+    end
+
+    def doing_lines(report, color)
+      return [] if report.doing.empty?
+
+      [ "", style("DOING", :bold, color) ] +
+        report.doing.map { |event| "  #{doing_line(event)}" }
+    end
+
+    def quiet_lines(report, color)
+      return [] if report.quiet.empty?
+
+      count = report.quiet.size
+      [ "", style("#{count} quiet #{count == 1 ? "repo" : "repos"} skipped", :dim, color) ]
+    end
+
+    def github_line(event)
+      verb = { pr_merged: "merged PR", pr_opened: "opened PR",
+               review: "reviewed PR", issue_closed: "closed issue" }.fetch(event.kind)
+      "#{verb} #{event.ref} (#{event.repo})#{title_suffix(event.title)}"
+    end
+
+    def title_suffix(title)
+      title.to_s.empty? ? "" : " — #{title}"
+    end
+
+    def doing_line(event)
+      case event.kind
+      when :dirty_tree
+        "#{event.repo}: uncommitted changes (#{pluralize(event.extra[:files], "file")})"
+      when :branch_wip
+        if event.extra[:no_upstream]
+          "#{event.repo} · #{event.ref}: not pushed yet (#{pluralize(event.extra[:unpushed], "commit")})"
+        else
+          "#{event.repo} · #{event.ref}: #{event.extra[:ahead]} unpushed #{event.extra[:ahead] == 1 ? "commit" : "commits"}"
+        end
+      when :pr_open
+        "PR #{event.ref.delete_prefix("#").prepend("#")} open (#{event.repo})#{title_suffix(event.title)}"
+      end
+    end
+
+    def pluralize(count, noun)
+      "#{count} #{count == 1 ? noun : "#{noun}s"}"
+    end
+
+    def style(text, kind, color)
+      return text unless color
+
+      code = kind == :bold ? 1 : 2
+      "\e[#{code}m#{text}\e[0m"
+    end
+  end
+end

data/lib/spill/repo_finder.rb

@@ -0,0 +1,9 @@
+module Spill
+  module RepoFinder
+    def self.find(root)
+      root = File.expand_path(root)
+      candidates = [ root ] + Dir.glob(File.join(root, "*")) + Dir.glob(File.join(root, "*", "*"))
+      candidates.select { |dir| File.directory?(File.join(dir, ".git")) }.sort
+    end
+  end
+end

data/lib/spill/report.rb

@@ -0,0 +1,45 @@
+module Spill
+  Report = Data.define(:window, :done, :github_done, :doing, :quiet, :notes) do
+    GITHUB_DONE_KINDS = %i[ pr_opened pr_merged review issue_closed ].freeze
+    LOCAL_STATE_KINDS = %i[ branch_wip dirty_tree ].freeze
+
+    def self.build(local:, github:, repos:, window:)
+      local ||= []
+      github_events = github || []
+      commits = local.select { |event| event.kind == :commit }
+      state = local.select { |event| LOCAL_STATE_KINDS.include?(event.kind) }
+
+      new(
+        window: window,
+        done: build_done(commits),
+        github_done: github_events.select { |e| GITHUB_DONE_KINDS.include?(e.kind) }.sort_by(&:timestamp),
+        doing: build_doing(state, github_events),
+        quiet: repos - (commits.map(&:repo) + state.map(&:repo)).uniq,
+        notes: build_notes(github, github_events)
+      )
+    end
+
+    def self.build_done(commits)
+      commits.group_by(&:repo).map do |repo, events|
+        branches = events.group_by(&:ref).map do |branch, list|
+          { name: branch, commits: list.sort_by(&:timestamp) }
+        end
+        { repo: repo, branches: branches, last: events.map(&:timestamp).max }
+      end.sort_by { |entry| entry[:last] }.reverse
+    end
+
+    def self.build_doing(state, github_events)
+      open_prs = github_events.select { |e| e.kind == :pr_open }
+                              .sort_by(&:timestamp).reverse
+      state.sort_by { |e| [ e.repo, e.kind.to_s ] } + open_prs
+    end
+
+    def self.build_notes(github, github_events)
+      notes = []
+      notes << "GitHub: skipped (gh not available)" if github.nil?
+      truncated = github_events.find { |e| e.kind == :github_truncated }
+      notes << "GitHub: may be incomplete before #{truncated.extra[:oldest].strftime("%b %-d")}" if truncated
+      notes
+    end
+  end
+end

data/lib/spill/version.rb

@@ -0,0 +1,3 @@
+module Spill
+  VERSION = "0.1.0"
+end

data/lib/spill/window.rb

@@ -0,0 +1,27 @@
+require "time"
+
+module Spill
+  Window = Data.define(:since, :label) do
+    def self.default(now: Time.now)
+      new(since: midnight(now) - 86_400, label: "today + yesterday")
+    end
+
+    def self.parse(expr, now: Time.now)
+      text = expr.strip
+      since =
+        case text
+        when "today" then midnight(now)
+        when "yesterday" then midnight(now) - 86_400
+        when /\A(\d+)\s+hours?\s+ago\z/ then now - ($1.to_i * 3_600)
+        when /\A(\d+)\s+days?\s+ago\z/ then now - ($1.to_i * 86_400)
+        when /\A(\d+)\s+weeks?\s+ago\z/ then now - ($1.to_i * 7 * 86_400)
+        else Time.parse(text)
+        end
+      new(since: since, label: text)
+    end
+
+    def self.midnight(time)
+      Time.new(time.year, time.month, time.day)
+    end
+  end
+end

data/lib/spill.rb

@@ -0,0 +1,13 @@
+require_relative "spill/version"
+require_relative "spill/event"
+require_relative "spill/window"
+require_relative "spill/repo_finder"
+require_relative "spill/collectors/local_git"
+require_relative "spill/collectors/github"
+require_relative "spill/report"
+require_relative "spill/renderer"
+require_relative "spill/cli"
+
+module Spill
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: spill
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tugcem Yalcin
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: spill scans a folder of git repos and prints a standup report — commits,
+  PRs merged, reviews given, and work still in flight — synthesized from local git
+  and (optionally) the GitHub CLI.
+email:
+- tugcemyalcin@gmail.com
+executables:
+- spill
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/spill
+- lib/spill.rb
+- lib/spill/cli.rb
+- lib/spill/collectors/github.rb
+- lib/spill/collectors/local_git.rb
+- lib/spill/event.rb
+- lib/spill/renderer.rb
+- lib/spill/repo_finder.rb
+- lib/spill/report.rb
+- lib/spill/version.rb
+- lib/spill/window.rb
+homepage: https://github.com/tugcem/spill
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/tugcem/spill
+  changelog_uri: https://github.com/tugcem/spill/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: 'Your standup, spilled: a Done/Doing report from local git and GitHub.'
+test_files: []