flaky-friend 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d016af0bdc9c0fbadfe3671661682a1cdf85eb96b2f666dec28c1c1d69420757
-  data.tar.gz: 6983cdd0f2763185858bf3774f8ab4df10e503691f1f37480be65f31ea1ef4ae
+  metadata.gz: c996492175a4e470f3ea4c08890a4626c90e4de13e35e33a1d919ef41a5b04b6
+  data.tar.gz: a7a08059d87983af6e0b163177cee5db2f659201f92267a338355e6b6df71024
 SHA512:
-  metadata.gz: 2619613daf34a41ae20f86702e212fd4379fa738dfcc1fcf30e32e16558ad741152612559d8f50ab368c2538a80fd7ce357899962495bfa7d3e05d8bdda2e117
-  data.tar.gz: 32f4ca285cf88f32ff8b80eb082628063dd8c745ce39175ef96f41af5c825df7b0ae3cc8d7501cde240affeaa5c79d46214d21f9fdf6aa154a9380ecf78612ea
+  metadata.gz: 7282d21702ca0d52b80c74c01dc6bf8fce827f4543bd082a45f57d2080b04d9cbc8b866b10aee1352a74ca1f0279cc3ba73d1baed98911b6843428bb5a184662
+  data.tar.gz: 5201e17baf1732b2cd21879c391021ba96d0a38a0a9b59970225c6b8f2cba52aaf4b72697e6ac052d9af17cc67bbb28336eb3685dcbb19e2daa0e1ef721e743b

data/lib/flaky/age_parser.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Flaky
+  module AgeParser
+    # Parses a human-friendly age string ("24h", "7d", "30m") into seconds.
+    # Returns 86400 (24h) for unrecognized formats.
+    def self.to_seconds(age)
+      case age.to_s
+      when /\A(\d+)h\z/ then $1.to_i * 3600
+      when /\A(\d+)d\z/ then $1.to_i * 86400
+      when /\A(\d+)m\z/ then $1.to_i * 60
+      else 86400
+      end
+    end
+  end
+end

data/lib/flaky/commands/fetch.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../database"
+require_relative "../repository"
 require_relative "../log_parser"
 
 module Flaky
@@ -8,67 +8,101 @@ module Flaky
     class Fetch
       def initialize(age: "24h")
         @age = age
-        @db = Database.new
+        @repo = Repository.new
         @parser = LogParser.new
       end
 
       def execute
         provider = Flaky.provider
         branch = Flaky.configuration.branch
-        conn = @db.connection
 
+        print "Fetching #{branch} workflows (last #{@age})... "
+        $stdout.flush
         workflows = provider.fetch_workflows(age: @age)
-        main_workflows = workflows.select { |w| w[:branch] == branch }
+        puts "#{workflows.length} found."
 
-        if main_workflows.empty?
-          puts "No #{branch} workflows found in the last #{@age}."
+        if workflows.empty?
+          puts "Nothing to do."
           return
         end
 
-        new_workflows = 0
-        new_failures = 0
-        total_jobs = 0
+        new_workflows = workflows.reject { |wf| @repo.workflow_fetched?(wf[:id]) }
 
-        main_workflows.each do |wf|
-          # Skip if already fetched
-          existing = conn.get_first_value("SELECT 1 FROM ci_runs WHERE workflow_id = ?", wf[:id])
-          next if existing
-
-          # Determine pipeline result by fetching jobs
-          jobs = provider.fetch_jobs(pipeline_id: wf[:pipeline_id])
-          pipeline_result = jobs.any? { |j| j[:result] == "failed" } ? "failed" : "passed"
-
-          conn.execute(
-            "INSERT INTO ci_runs (workflow_id, pipeline_id, branch, result, created_at) VALUES (?, ?, ?, ?, ?)",
-            [wf[:id], wf[:pipeline_id], wf[:branch], pipeline_result, wf[:created_at]]
-          )
-          new_workflows += 1
-
-          jobs.each do |job|
-            total_jobs += 1
-            log = provider.fetch_log(job_id: job[:id])
-            parsed = @parser.parse(log)
-
-            conn.execute(
-              "INSERT OR IGNORE INTO job_results (job_id, workflow_id, job_name, block_name, result, example_count, failure_count, seed, duration_seconds) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
-              [job[:id], wf[:id], job[:name], job[:block_name], parsed.failure_count.to_i > 0 ? "failed" : "passed",
-               parsed.example_count, parsed.failure_count, parsed.seed, parsed.duration_seconds]
-            )
+        if new_workflows.empty?
+          puts "All #{workflows.length} workflows already in database."
+          return
+        end
 
-            parsed.failures.each do |failure|
-              conn.execute(
-                "INSERT OR IGNORE INTO test_failures (workflow_id, job_id, job_name, spec_file, line_number, description, seed, branch, failed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
-                [wf[:id], job[:id], job[:name], failure.spec_file, failure.line_number, failure.description,
-                 parsed.seed, wf[:branch], wf[:created_at]]
-              )
-              new_failures += 1
-            end
-          end
+        puts "Processing #{new_workflows.length} new workflow(s)..."
+
+        total_jobs = 0
+        total_failures = 0
+
+        new_workflows.each_with_index do |wf, wi|
+          jobs, failures = process_workflow(provider, wf, wi, new_workflows.length)
+          total_jobs += jobs
+          total_failures += failures
         end
 
-        puts "Fetched #{new_workflows} new workflow(s), #{total_jobs} job(s) parsed, #{new_failures} failure(s) recorded."
+        puts "\nDone: #{new_workflows.length} workflow(s), #{total_jobs} job(s), #{total_failures} failure(s) recorded."
       ensure
-        @db.close
+        @repo.close
+      end
+
+      private
+
+      def process_workflow(provider, wf, index, total)
+        print "  [#{index + 1}/#{total}] #{wf[:created_at]} — fetching jobs... "
+        $stdout.flush
+
+        jobs = provider.fetch_jobs(pipeline_id: wf[:pipeline_id])
+        pipeline_result = jobs.any? { |j| j[:result] == "failed" } ? "failed" : "passed"
+
+        @repo.insert_ci_run(
+          workflow_id: wf[:id], pipeline_id: wf[:pipeline_id],
+          branch: wf[:branch], result: pipeline_result, created_at: wf[:created_at],
+          commit_sha: wf[:commit_sha]
+        )
+
+        puts "#{jobs.length} test jobs (#{pipeline_result})"
+
+        failures = 0
+        jobs.each_with_index do |job, ji|
+          failures += process_job(provider, job, wf, ji, jobs.length)
+        end
+
+        [jobs.length, failures]
+      end
+
+      def process_job(provider, job, wf, index, total)
+        print "    [#{index + 1}/#{total}] #{job[:name]}... "
+        $stdout.flush
+
+        log = provider.fetch_log(job_id: job[:id])
+        parsed = @parser.parse(log)
+
+        @repo.insert_job_result(
+          job_id: job[:id], workflow_id: wf[:id], job_name: job[:name],
+          block_name: job[:block_name], result: parsed.failure_count.to_i > 0 ? "failed" : "passed",
+          example_count: parsed.example_count, failure_count: parsed.failure_count,
+          seed: parsed.seed, duration_seconds: parsed.duration_seconds
+        )
+
+        if parsed.failures.any?
+          parsed.failures.each do |failure|
+            @repo.insert_test_failure(
+              workflow_id: wf[:id], job_id: job[:id], job_name: job[:name],
+              spec_file: failure.spec_file, line_number: failure.line_number,
+              description: failure.description, seed: parsed.seed,
+              branch: wf[:branch], failed_at: wf[:created_at]
+            )
+          end
+          puts "\e[31m#{parsed.failures.length} failure(s)\e[0m"
+          parsed.failures.length
+        else
+          puts "\e[32mok\e[0m (#{parsed.example_count} examples)"
+          0
+        end
       end
     end
   end

data/lib/flaky/commands/history.rb

@@ -1,43 +1,18 @@
 # frozen_string_literal: true
 
-require_relative "../database"
+require_relative "../repository"
 
 module Flaky
   module Commands
     class History
       def initialize(spec_location:)
         @spec_location = spec_location
-        @db = Database.new
+        @repo = Repository.new
       end
 
       def execute
-        conn = @db.connection
-
         file, line = parse_location(@spec_location)
-
-        conditions = ["tf.spec_file LIKE ?"]
-        params = ["%#{file}%"]
-
-        if line
-          conditions << "tf.line_number = ?"
-          params << line
-        end
-
-        rows = conn.execute(<<~SQL, params)
-          SELECT
-            tf.spec_file,
-            tf.line_number,
-            tf.description,
-            tf.seed,
-            tf.job_name,
-            tf.branch,
-            tf.failed_at,
-            cr.workflow_id
-          FROM test_failures tf
-          JOIN ci_runs cr ON cr.workflow_id = tf.workflow_id
-          WHERE #{conditions.join(" AND ")}
-          ORDER BY tf.failed_at DESC
-        SQL
+        rows = @repo.failure_history(file: file, line: line)
 
         if rows.empty?
           puts "No failures found matching '#{@spec_location}'."
@@ -47,20 +22,21 @@ module Flaky
         first = rows.first
         puts "Failure history for #{first['spec_file']}:#{first['line_number']}"
         puts "  #{first['description']}\n\n"
-        puts format("%-20s %-8s %-30s %s", "Date", "Seed", "Job", "Workflow")
-        puts "-" * 100
+        puts format("%-20s %-8s %-10s %-30s %s", "Date", "Seed", "Commit", "Job", "Workflow")
+        puts "-" * 110
 
         rows.each do |row|
-          puts format("%-20s %-8d %-30s %s", row["failed_at"], row["seed"], row["job_name"], row["workflow_id"])
+          sha = row["commit_sha"] ? row["commit_sha"][0..6] : "       "
+          puts format("%-20s %-8d %-10s %-30s %s", row["failed_at"], row["seed"], sha, row["job_name"], row["workflow_id"])
         end
 
         puts "\nTotal failures: #{rows.length}"
 
         seeds = rows.map { |r| r["seed"] }.uniq
         puts "Unique seeds: #{seeds.join(', ')}"
-        puts "\nTo reproduce: rake flaky:stress[#{first['spec_file']}:#{first['line_number']},10,#{seeds.first},true]"
+        puts "\nTo reproduce: SPEC=#{first['spec_file']}:#{first['line_number']} SEED=#{seeds.first} CI=true bin/rails flaky:stress"
       ensure
-        @db.close
+        @repo.close
       end
 
       private

data/lib/flaky/commands/rank.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../database"
+require_relative "../repository"
 
 module Flaky
   module Commands
@@ -8,39 +8,20 @@ module Flaky
       def initialize(since_days: 30, min_failures: 1)
         @since_days = since_days
         @min_failures = min_failures
-        @db = Database.new
+        @repo = Repository.new
       end
 
       def execute
-        conn = @db.connection
         branch = Flaky.configuration.branch
 
-        rows = conn.execute(<<~SQL, [branch, "-#{@since_days} days", @min_failures])
-          SELECT
-            tf.spec_file,
-            tf.line_number,
-            tf.description,
-            COUNT(*) as failure_count,
-            MAX(tf.failed_at) as last_failure,
-            GROUP_CONCAT(DISTINCT tf.seed) as seeds
-          FROM test_failures tf
-          JOIN ci_runs cr ON cr.workflow_id = tf.workflow_id
-          WHERE cr.branch = ?
-            AND cr.created_at >= datetime('now', ?)
-          GROUP BY tf.spec_file, tf.line_number
-          HAVING COUNT(*) >= ?
-          ORDER BY failure_count DESC, last_failure DESC
-        SQL
+        rows = @repo.rank_failures(branch: branch, since_days: @since_days, min_failures: @min_failures)
 
         if rows.empty?
           puts "No flaky tests found in the last #{@since_days} days."
           return
         end
 
-        total_runs = conn.get_first_value(
-          "SELECT COUNT(DISTINCT workflow_id) FROM ci_runs WHERE branch = ? AND created_at >= datetime('now', ?)",
-          [branch, "-#{@since_days} days"]
-        ).to_i
+        total_runs = @repo.total_runs_count(branch: branch, since_days: @since_days)
 
         puts "Flaky tests on #{branch} (last #{@since_days} days, #{total_runs} CI runs):\n\n"
         puts format("%-6s %-50s %s", "Fails", "Location", "Last Failure")
@@ -55,11 +36,12 @@ module Flaky
             puts "\n  \e[33m▶ Next to investigate:\e[0m #{location}"
             puts "    #{row['description']}"
             puts "    Seeds: #{row['seeds']}"
+            puts "    Commits: #{row['commit_shas']}" if row["commit_shas"]
             puts ""
           end
         end
       ensure
-        @db.close
+        @repo.close
       end
     end
   end

data/lib/flaky/commands/report.rb

@@ -1,66 +1,40 @@
 # frozen_string_literal: true
 
-require_relative "../database"
+require_relative "../repository"
 
 module Flaky
   module Commands
     class Report
       def initialize
-        @db = Database.new
+        @repo = Repository.new
       end
 
       def execute
-        conn = @db.connection
         branch = Flaky.configuration.branch
-
-        total_runs = conn.get_first_value("SELECT COUNT(*) FROM ci_runs WHERE branch = ?", branch).to_i
-        failed_runs = conn.get_first_value("SELECT COUNT(*) FROM ci_runs WHERE branch = ? AND result = 'failed'", branch).to_i
-        total_failures = conn.get_first_value("SELECT COUNT(*) FROM test_failures WHERE branch = ?", branch).to_i
-        unique_specs = conn.get_first_value("SELECT COUNT(DISTINCT spec_file || ':' || line_number) FROM test_failures WHERE branch = ?", branch).to_i
-        last_fetch = conn.get_first_value("SELECT MAX(fetched_at) FROM ci_runs")
+        stats = @repo.run_stats(branch: branch)
+        trend = @repo.failure_trend(branch: branch)
 
         puts "=== Flaky Test Report (#{branch}) ==="
         puts ""
-        puts "CI Runs tracked:     #{total_runs}"
-        puts "Failed runs:         #{failed_runs} (#{total_runs > 0 ? (failed_runs.to_f / total_runs * 100).round(1) : 0}%)"
-        puts "Total test failures: #{total_failures}"
-        puts "Unique flaky specs:  #{unique_specs}"
-        puts "Last fetch:          #{last_fetch || 'never'}"
-
-        # Recent trend
-        recent = conn.get_first_value(
-          "SELECT COUNT(*) FROM test_failures WHERE branch = ? AND failed_at >= datetime('now', '-7 days')", branch
-        ).to_i
-        prior = conn.get_first_value(
-          "SELECT COUNT(*) FROM test_failures WHERE branch = ? AND failed_at >= datetime('now', '-14 days') AND failed_at < datetime('now', '-7 days')", branch
-        ).to_i
+        puts "CI Runs tracked:     #{stats[:total_runs]}"
+        failure_pct = stats[:total_runs] > 0 ? (stats[:failed_runs].to_f / stats[:total_runs] * 100).round(1) : 0
+        puts "Failed runs:         #{stats[:failed_runs]} (#{failure_pct}%)"
+        puts "Total test failures: #{stats[:total_failures]}"
+        puts "Unique flaky specs:  #{stats[:unique_specs]}"
+        puts "Last fetch:          #{stats[:last_fetch] || 'never'}"
 
         puts ""
-        puts "7-day trend:         #{recent} failures (prior 7 days: #{prior})"
+        puts "7-day trend:         #{trend[:recent]} failures (prior 7 days: #{trend[:prior]})"
 
-        if recent > prior
+        if trend[:recent] > trend[:prior]
           puts "                     \e[31m▲ Trending worse\e[0m"
-        elsif recent < prior
+        elsif trend[:recent] < trend[:prior]
           puts "                     \e[32m▼ Trending better\e[0m"
         else
           puts "                     → Stable"
         end
 
-        # Top 5 flaky tests
-        top = conn.execute(<<~SQL, [branch])
-          SELECT
-            spec_file,
-            line_number,
-            description,
-            COUNT(*) as failure_count,
-            MAX(failed_at) as last_failure
-          FROM test_failures
-          WHERE branch = ?
-          GROUP BY spec_file, line_number
-          ORDER BY failure_count DESC
-          LIMIT 5
-        SQL
-
+        top = @repo.top_flaky(branch: branch)
         if top.any?
           puts "\nTop 5 flaky tests:"
           puts "-" * 80
@@ -70,8 +44,7 @@ module Flaky
           end
         end
 
-        # Recent stress runs
-        stress = conn.execute("SELECT * FROM stress_runs ORDER BY created_at DESC LIMIT 3")
+        stress = @repo.recent_stress_runs
         if stress.any?
           puts "\nRecent stress runs:"
           puts "-" * 80
@@ -83,7 +56,7 @@ module Flaky
           end
         end
       ensure
-        @db.close
+        @repo.close
       end
     end
   end

data/lib/flaky/commands/stress.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "../database"
+require_relative "../repository"
 
 module Flaky
   module Commands
@@ -11,7 +11,7 @@ module Flaky
         @seed = seed
         @ci_simulate = ci_simulate
         @timeout = timeout
-        @db = Database.new
+        @repo = Repository.new
       end
 
       def execute
@@ -67,16 +67,14 @@ module Flaky
           puts "  FLAKY_CI_SIMULATE=#{@ci_simulate ? '1' : '0'} bundle exec rspec #{@spec_location} --seed #{failed_seeds.first}"
         end
 
-        # Record to database
-        conn = @db.connection
-        conn.execute(
-          "INSERT INTO stress_runs (spec_location, seed, iterations, passes, failures, ci_simulation) VALUES (?, ?, ?, ?, ?, ?)",
-          [@spec_location, @seed, @iterations, passes, failures, @ci_simulate ? 1 : 0]
+        @repo.insert_stress_run(
+          spec_location: @spec_location, seed: @seed, iterations: @iterations,
+          passes: passes, failures: failures, ci_simulation: @ci_simulate ? 1 : 0
         )
 
         exit(failures > 0 ? 1 : 0)
       ensure
-        @db.close
+        @repo.close
       end
     end
   end

data/lib/flaky/configuration.rb

@@ -4,13 +4,14 @@ module Flaky
   class Configuration
     PROVIDERS = {}
 
-    attr_accessor :project, :branch, :db_path
+    attr_accessor :project, :branch, :db_path, :test_blocks
 
     def initialize
       @provider_name = nil
       @project = nil
       @branch = "main"
       @db_path = nil # resolved lazily
+      @test_blocks = ["Unit Tests", "System Tests"]
     end
 
     def provider=(name)
@@ -18,6 +19,7 @@ module Flaky
     end
 
     def provider_instance
+      validate!
       klass = PROVIDERS[@provider_name] || raise(Error, "Unknown provider: #{@provider_name}. Registered: #{PROVIDERS.keys.join(', ')}")
       klass.new(self)
     end
@@ -26,6 +28,15 @@ module Flaky
       @db_path || (defined?(Rails) ? Rails.root.join("tmp", "flaky.db").to_s : "tmp/flaky.db")
     end
 
+    def validate!
+      unless @provider_name
+        raise Error, "Flaky: provider not configured. Add `Flaky.configure { |c| c.provider = :semaphore }` to your initializer."
+      end
+      unless @project
+        raise Error, "Flaky: project not configured. Add `Flaky.configure { |c| c.project = 'your-project' }` to your initializer."
+      end
+    end
+
     def self.register_provider(name, klass)
       PROVIDERS[name.to_sym] = klass
     end

data/lib/flaky/database.rb

@@ -4,7 +4,7 @@ require "sqlite3"
 
 module Flaky
   class Database
-    SCHEMA_VERSION = 1
+    SCHEMA_VERSION = 2
 
     def initialize(path = nil)
       @path = path || Flaky.configuration.resolved_db_path
@@ -87,9 +87,14 @@ module Flaky
           CREATE INDEX IF NOT EXISTS idx_ci_runs_branch ON ci_runs(branch);
           CREATE INDEX IF NOT EXISTS idx_job_results_workflow ON job_results(workflow_id);
 
-          PRAGMA user_version = 1;
+          PRAGMA user_version = 2;
         SQL
       end
+
+      if version < 2
+        db.execute("ALTER TABLE ci_runs ADD COLUMN commit_sha TEXT")
+        db.execute("PRAGMA user_version = 2")
+      end
     end
   end
 end

data/lib/flaky/providers/base.rb

@@ -10,7 +10,7 @@ module Flaky
       end
 
       # Returns Array of Hashes:
-      #   { id:, pipeline_id:, branch:, result:, created_at: }
+      #   { id:, pipeline_id:, branch:, commit_sha:, created_at: }
       def fetch_workflows(age: "24h")
         raise NotImplementedError
       end

data/lib/flaky/providers/github_actions.rb

@@ -2,15 +2,15 @@
 
 require "json"
 require_relative "base"
+require_relative "../age_parser"
 
 module Flaky
   module Providers
     class GithubActions < Base
       def fetch_workflows(age: "24h")
-        hours = parse_age_to_hours(age)
-        cutoff = Time.now - (hours * 3600)
+        cutoff = Time.now - AgeParser.to_seconds(age)
 
-        output = run_cmd("gh run list --branch #{config.branch} --limit 100 --json databaseId,conclusion,createdAt,headBranch,workflowName")
+        output = run_cmd("gh run list --branch #{config.branch} --limit 100 --json databaseId,conclusion,createdAt,headBranch,headSha,workflowName")
         runs = JSON.parse(output)
 
         runs.filter_map do |run|
@@ -21,6 +21,7 @@ module Flaky
             id: run["databaseId"].to_s,
             pipeline_id: run["databaseId"].to_s,
             branch: run["headBranch"],
+            commit_sha: run["headSha"],
             result: map_conclusion(run["conclusion"]),
             created_at: run["createdAt"]
           }
@@ -56,14 +57,6 @@ module Flaky
         output
       end
 
-      def parse_age_to_hours(age)
-        case age
-        when /(\d+)h/ then $1.to_i
-        when /(\d+)d/ then $1.to_i * 24
-        else 24
-        end
-      end
-
       def map_conclusion(conclusion)
         case conclusion
         when "success" then "passed"

data/lib/flaky/providers/semaphore.rb

@@ -5,14 +5,13 @@ require "net/http"
 require "uri"
 require "yaml"
 require_relative "base"
+require_relative "../age_parser"
 
 module Flaky
   module Providers
     class Semaphore < Base
-      TEST_BLOCKS = ["Unit Tests", "System Tests"].freeze
-
       def fetch_workflows(age: "24h")
-        cutoff = Time.now - parse_age_seconds(age)
+        cutoff = Time.now - AgeParser.to_seconds(age)
         project_id = resolve_project_id
         branch = config.branch
         workflows = []
@@ -34,6 +33,7 @@ module Flaky
               id: wf["wf_id"],
               pipeline_id: wf["initial_ppl_id"],
               branch: wf["branch_name"],
+              commit_sha: wf["commit_sha"],
               created_at: created_at.strftime("%Y-%m-%d %H:%M:%S")
             }
           end
@@ -51,10 +51,11 @@ module Flaky
       def fetch_jobs(pipeline_id:)
         data = api_get("pipelines/#{pipeline_id}", detailed: true)
         blocks = data["blocks"] || []
+        test_blocks = config.test_blocks
 
         blocks.flat_map do |block|
           block_name = block["name"]
-          next [] unless TEST_BLOCKS.include?(block_name)
+          next [] unless test_blocks.include?(block_name)
 
           (block["jobs"] || []).map do |job|
             {
@@ -94,22 +95,41 @@ module Flaky
         raise Error, "Semaphore API error (#{response.code}): #{response.body[0..200]}" unless response.is_a?(Net::HTTPSuccess)
 
         JSON.parse(response.body)
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        raise Error, "Semaphore API timeout: #{e.message}"
+      rescue SocketError => e
+        raise Error, "Cannot reach Semaphore API: #{e.message}"
+      rescue Errno::ECONNREFUSED => e
+        raise Error, "Connection refused to Semaphore API: #{e.message}"
+      rescue JSON::ParserError => e
+        raise Error, "Invalid JSON from Semaphore API: #{e.message}"
+      end
+
+      def sem_config
+        @sem_config ||= begin
+          path = File.expand_path("~/.sem.yaml")
+          unless File.exist?(path)
+            raise Error, "Semaphore config not found at #{path}. Run `sem connect` to authenticate."
+          end
+          YAML.safe_load_file(path)
+        end
       end
 
       def api_host
         @api_host ||= begin
-          sem_config = YAML.load_file(File.expand_path("~/.sem.yaml"))
           context_name = sem_config["active-context"]
           host = sem_config.dig("contexts", context_name, "host")
+          raise Error, "No host found in ~/.sem.yaml for context '#{context_name}'" unless host
           "https://#{host}"
         end
       end
 
       def api_token
         @api_token ||= begin
-          sem_config = YAML.load_file(File.expand_path("~/.sem.yaml"))
           context_name = sem_config["active-context"]
-          sem_config.dig("contexts", context_name, "auth", "token")
+          token = sem_config.dig("contexts", context_name, "auth", "token")
+          raise Error, "No auth token found in ~/.sem.yaml for context '#{context_name}'" unless token
+          token
         end
       end
 
@@ -121,15 +141,6 @@ module Flaky
           project.dig("metadata", "id")
         end
       end
-
-      def parse_age_seconds(age)
-        case age.to_s
-        when /\A(\d+)h\z/ then $1.to_i * 3600
-        when /\A(\d+)d\z/ then $1.to_i * 86400
-        when /\A(\d+)m\z/ then $1.to_i * 60
-        else 86400 # default 24h
-        end
-      end
     end
 
     Configuration.register_provider(:semaphore, Semaphore)

data/lib/flaky/repository.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require_relative "database"
+
+module Flaky
+  class Repository
+    def initialize(path = nil)
+      @db = Database.new(path)
+    end
+
+    def close
+      @db.close
+    end
+
+    # --- CI Runs ---
+
+    def workflow_fetched?(workflow_id)
+      !!connection.get_first_value("SELECT 1 FROM ci_runs WHERE workflow_id = ?", workflow_id)
+    end
+
+    def insert_ci_run(workflow_id:, pipeline_id:, branch:, result:, created_at:, commit_sha: nil)
+      connection.execute(
+        "INSERT INTO ci_runs (workflow_id, pipeline_id, branch, result, created_at, commit_sha) VALUES (?, ?, ?, ?, ?, ?)",
+        [workflow_id, pipeline_id, branch, result, created_at, commit_sha]
+      )
+    end
+
+    # --- Job Results ---
+
+    def insert_job_result(job_id:, workflow_id:, job_name:, block_name:, result:, example_count:, failure_count:, seed:, duration_seconds:)
+      connection.execute(
+        "INSERT OR IGNORE INTO job_results (job_id, workflow_id, job_name, block_name, result, example_count, failure_count, seed, duration_seconds) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        [job_id, workflow_id, job_name, block_name, result, example_count, failure_count, seed, duration_seconds]
+      )
+    end
+
+    # --- Test Failures ---
+
+    def insert_test_failure(workflow_id:, job_id:, job_name:, spec_file:, line_number:, description:, seed:, branch:, failed_at:)
+      connection.execute(
+        "INSERT OR IGNORE INTO test_failures (workflow_id, job_id, job_name, spec_file, line_number, description, seed, branch, failed_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+        [workflow_id, job_id, job_name, spec_file, line_number, description, seed, branch, failed_at]
+      )
+    end
+
+    # --- Ranking ---
+
+    def rank_failures(branch:, since_days:, min_failures: 1)
+      connection.execute(<<~SQL, [branch, "-#{since_days} days", min_failures])
+        SELECT
+          tf.spec_file,
+          tf.line_number,
+          tf.description,
+          COUNT(*) as failure_count,
+          MAX(tf.failed_at) as last_failure,
+          GROUP_CONCAT(DISTINCT tf.seed) as seeds,
+          GROUP_CONCAT(DISTINCT cr.commit_sha) as commit_shas
+        FROM test_failures tf
+        JOIN ci_runs cr ON cr.workflow_id = tf.workflow_id
+        WHERE cr.branch = ?
+          AND cr.created_at >= datetime('now', ?)
+        GROUP BY tf.spec_file, tf.line_number
+        HAVING COUNT(*) >= ?
+        ORDER BY failure_count DESC, last_failure DESC
+      SQL
+    end
+
+    def total_runs_count(branch:, since_days:)
+      connection.get_first_value(
+        "SELECT COUNT(DISTINCT workflow_id) FROM ci_runs WHERE branch = ? AND created_at >= datetime('now', ?)",
+        [branch, "-#{since_days} days"]
+      ).to_i
+    end
+
+    # --- History ---
+
+    def failure_history(file:, line: nil)
+      conditions = ["tf.spec_file LIKE ?"]
+      params = ["%#{file}%"]
+
+      if line
+        conditions << "tf.line_number = ?"
+        params << line
+      end
+
+      connection.execute(<<~SQL, params)
+        SELECT
+          tf.spec_file,
+          tf.line_number,
+          tf.description,
+          tf.seed,
+          tf.job_name,
+          tf.branch,
+          tf.failed_at,
+          cr.workflow_id,
+          cr.commit_sha
+        FROM test_failures tf
+        JOIN ci_runs cr ON cr.workflow_id = tf.workflow_id
+        WHERE #{conditions.join(" AND ")}
+        ORDER BY tf.failed_at DESC
+      SQL
+    end
+
+    # --- Report ---
+
+    def run_stats(branch:)
+      {
+        total_runs: connection.get_first_value("SELECT COUNT(*) FROM ci_runs WHERE branch = ?", branch).to_i,
+        failed_runs: connection.get_first_value("SELECT COUNT(*) FROM ci_runs WHERE branch = ? AND result = 'failed'", branch).to_i,
+        total_failures: connection.get_first_value("SELECT COUNT(*) FROM test_failures WHERE branch = ?", branch).to_i,
+        unique_specs: connection.get_first_value("SELECT COUNT(DISTINCT spec_file || ':' || line_number) FROM test_failures WHERE branch = ?", branch).to_i,
+        last_fetch: connection.get_first_value("SELECT MAX(fetched_at) FROM ci_runs")
+      }
+    end
+
+    def failure_trend(branch:, period_days: 7)
+      recent = connection.get_first_value(
+        "SELECT COUNT(*) FROM test_failures WHERE branch = ? AND failed_at >= datetime('now', ?)",
+        [branch, "-#{period_days} days"]
+      ).to_i
+
+      prior = connection.get_first_value(
+        "SELECT COUNT(*) FROM test_failures WHERE branch = ? AND failed_at >= datetime('now', ?) AND failed_at < datetime('now', ?)",
+        [branch, "-#{period_days * 2} days", "-#{period_days} days"]
+      ).to_i
+
+      { recent: recent, prior: prior }
+    end
+
+    def top_flaky(branch:, limit: 5)
+      connection.execute(<<~SQL, [branch, limit])
+        SELECT
+          spec_file,
+          line_number,
+          description,
+          COUNT(*) as failure_count,
+          MAX(failed_at) as last_failure
+        FROM test_failures
+        WHERE branch = ?
+        GROUP BY spec_file, line_number
+        ORDER BY failure_count DESC
+        LIMIT ?
+      SQL
+    end
+
+    def recent_stress_runs(limit: 3)
+      connection.execute("SELECT * FROM stress_runs ORDER BY created_at DESC LIMIT ?", limit)
+    end
+
+    # --- Stress ---
+
+    def insert_stress_run(spec_location:, seed:, iterations:, passes:, failures:, ci_simulation:)
+      connection.execute(
+        "INSERT INTO stress_runs (spec_location, seed, iterations, passes, failures, ci_simulation) VALUES (?, ?, ?, ?, ?, ?)",
+        [spec_location, seed, iterations, passes, failures, ci_simulation]
+      )
+    end
+
+    private
+
+    def connection
+      @db.connection
+    end
+  end
+end

data/lib/flaky/tasks/flaky.rake

@@ -1,36 +1,89 @@
 # frozen_string_literal: true
 
+# All tasks use environment variables instead of rake arguments
+# to avoid zsh bracket escaping issues.
+#
+#   bin/rails flaky:fetch DURATION=28d
+#   bin/rails flaky:rank SINCE=7
+#   bin/rails flaky:history SPEC=path/to/spec.rb:42
+#   bin/rails flaky:stress SPEC=path/to/spec.rb:42 N=20 SEED=12345 CI=true TIMEOUT=600
+#   bin/rails flaky:report
+
+FLAKY_HELP = <<~HELP
+  \e[1mflaky-friend v#{Flaky::VERSION}\e[0m — Track, rank, and reproduce flaky CI test failures
+
+  \e[1mUsage:\e[0m
+    bin/rails flaky:<command> [ENV_VARS]
+
+  \e[1mCommands:\e[0m
+    flaky:fetch    Fetch recent CI results into the local database
+    flaky:rank     Rank flaky tests by failure frequency
+    flaky:history  Show failure history for a specific spec
+    flaky:stress   Stress-test a spec to reproduce/prove a fix
+    flaky:report   Summary dashboard of flaky test status
+
+  \e[1mExamples:\e[0m
+    bin/rails flaky:fetch                          # last 24 hours (default)
+    bin/rails flaky:fetch DURATION=28d             # last 28 days
+    bin/rails flaky:rank                           # last 30 days (default)
+    bin/rails flaky:rank SINCE=7                   # last 7 days
+    bin/rails flaky:history SPEC=spec/foo_spec.rb:42
+    bin/rails flaky:stress SPEC=spec/foo_spec.rb:42 N=20 SEED=12345 CI=true
+    bin/rails flaky:report
+
+  \e[1mEnvironment variables:\e[0m
+    DURATION   Age window for fetch (e.g. 24h, 7d, 30m)          [default: 24h]
+    SINCE      Number of days to look back for rank               [default: 30]
+    SPEC       Spec file location (path/to/spec.rb or path:line)
+    N          Number of stress test iterations                   [default: 20]
+    SEED       RSpec seed for deterministic ordering
+    CI         Set to "true" to enable CI simulation (latency + reduced threads)
+    TIMEOUT    Stress test timeout in seconds                     [default: 600]
+
+HELP
+
+desc "Show flaky-friend help"
+task :flaky do
+  puts FLAKY_HELP
+end
+
 namespace :flaky do
-  desc "Fetch recent CI results (age: duration, default 24h)"
-  task :fetch, [:age] => :environment do |_t, args|
+  desc "Show flaky-friend help"
+  task help: :environment do
+    puts FLAKY_HELP
+  end
+
+  desc "Fetch recent CI results (DURATION=24h)"
+  task fetch: :environment do
     require "flaky/commands/fetch"
-    age = args[:age] || "24h"
-    Flaky::Commands::Fetch.new(age: age).execute
+    duration = ENV.fetch("DURATION", "24h")
+    Flaky::Commands::Fetch.new(age: duration).execute
   end
 
-  desc "Rank flaky tests by failure frequency (since: days, default 30)"
-  task :rank, [:since] => :environment do |_t, args|
+  desc "Rank flaky tests by failure frequency (SINCE=30)"
+  task rank: :environment do
     require "flaky/commands/rank"
-    since = (args[:since] || 30).to_i
+    since = ENV.fetch("SINCE", "30").to_i
     Flaky::Commands::Rank.new(since_days: since).execute
   end
 
-  desc "Show failure history for a spec (spec_location: file:line)"
-  task :history, [:spec_location] => :environment do |_t, args|
+  desc "Show failure history for a spec (SPEC=path/to/spec.rb:42)"
+  task history: :environment do
     require "flaky/commands/history"
-    raise "Usage: rake flaky:history[path/to/spec.rb:42]" unless args[:spec_location]
-    Flaky::Commands::History.new(spec_location: args[:spec_location]).execute
+    spec = ENV["SPEC"] || abort("Usage: bin/rails flaky:history SPEC=path/to/spec.rb:42")
+    Flaky::Commands::History.new(spec_location: spec).execute
   end
 
-  desc "Stress test a spec (spec, iterations, seed, ci)"
-  task :stress, [:spec, :iterations, :seed, :ci] => :environment do |_t, args|
+  desc "Stress test a spec (SPEC=... N=20 SEED=12345 CI=true TIMEOUT=600)"
+  task stress: :environment do
     require "flaky/commands/stress"
-    raise "Usage: rake flaky:stress[path/to/spec.rb:42,20,12345,true]" unless args[:spec]
+    spec = ENV["SPEC"] || abort("Usage: bin/rails flaky:stress SPEC=path/to/spec.rb:42")
     Flaky::Commands::Stress.new(
-      spec_location: args[:spec],
-      iterations: (args[:iterations] || 20).to_i,
-      seed: args[:seed]&.to_i,
-      ci_simulate: args[:ci] == "true"
+      spec_location: spec,
+      iterations: ENV.fetch("N", "20").to_i,
+      seed: ENV["SEED"]&.to_i,
+      ci_simulate: ENV["CI"] == "true",
+      timeout: ENV.fetch("TIMEOUT", "600").to_i
     ).execute
   end
 

data/lib/flaky/version.rb

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

data/lib/flaky-friend.rb

@@ -2,6 +2,7 @@
 
 require_relative "flaky/version"
 require_relative "flaky/configuration"
+require_relative "flaky/age_parser"
 require_relative "flaky/providers/semaphore"
 require_relative "flaky/providers/github_actions"
 require_relative "flaky/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: flaky-friend
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Flytedesk
@@ -74,6 +74,7 @@ files:
 - LICENSE
 - README.md
 - lib/flaky-friend.rb
+- lib/flaky/age_parser.rb
 - lib/flaky/commands/fetch.rb
 - lib/flaky/commands/history.rb
 - lib/flaky/commands/rank.rb
@@ -87,6 +88,7 @@ files:
 - lib/flaky/providers/github_actions.rb
 - lib/flaky/providers/semaphore.rb
 - lib/flaky/railtie.rb
+- lib/flaky/repository.rb
 - lib/flaky/tasks/flaky.rake
 - lib/flaky/version.rb
 homepage: https://github.com/Flytedesk/flaky