roast-ai 0.1.0

data/examples/grading/calculate_final_grade.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+class CalculateFinalGrade < Roast::Workflow::BaseStep
+  attr_accessor :llm_analysis
+
+  WEIGHTS = {
+    line_coverage: 0.1,
+    method_coverage: 0.1,
+    branch_coverage: 0.3,
+    test_helpers: 0.1,
+    mocks_and_stubs: 0.1,
+    readability: 0.1,
+    maintainability: 0.1,
+    effectiveness: 0.1,
+  }.freeze
+
+  def call
+    @llm_analysis = workflow.output["generate_grades"].merge(workflow.output["analyze_coverage"])
+    weighted_sum = WEIGHTS.sum do |criterion, weight|
+      score = llm_analysis[criterion.to_s]["score"].to_f / 10.0
+      score * weight
+    end
+
+    {
+      final_score: {
+        weighted_score: weighted_sum,
+        letter_grade: calculate_letter_grade(weighted_sum),
+      },
+      rubric_scores: calculate_rubric_scores,
+    }
+  end
+
+  private
+
+  def calculate_letter_grade(score)
+    case score
+    when 0.9..1.0
+      "A"
+    when 0.8...0.9
+      "B"
+    when 0.7...0.8
+      "C"
+    when 0.6...0.7
+      "D"
+    else
+      "F"
+    end
+  end
+
+  def calculate_rubric_scores
+    scores = {}
+
+    WEIGHTS.each_key do |criterion|
+      raw_score = llm_analysis[criterion.to_s]["score"].to_f
+      normalized_score = raw_score / 10.0
+
+      scores[criterion] = {
+        raw_value: raw_score,
+        score: normalized_score,
+        description: llm_analysis[criterion.to_s]["justification"],
+        weighted_score: normalized_score * WEIGHTS[criterion],
+      }
+    end
+
+    scores
+  end
+end

data/examples/grading/format_result.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class FormatResult < Roast::Workflow::BaseStep
+  RUBRIC = {
+    line_coverage: { description: "Line Coverage", weight: 0.1 },
+    method_coverage: { description: "Method Coverage", weight: 0.1 },
+    branch_coverage: { description: "Branch Coverage", weight: 0.3 },
+    test_helpers: { description: "Test Helpers Usage", weight: 0.1 },
+    mocks_and_stubs: { description: "Mocks and Stubs Usage", weight: 0.1 },
+    readability: { description: "Test Readability", weight: 0.1 },
+    maintainability: { description: "Test Maintainability", weight: 0.1 },
+    effectiveness: { description: "Test Effectiveness", weight: 0.1 },
+  }.freeze
+
+  def call
+    append_to_final_output(<<~OUTPUT)
+      ========== TEST GRADE REPORT ==========
+      Test file: #{workflow.file}
+      Source file: #{workflow.subject_file}
+    OUTPUT
+
+    format_results
+    append_to_final_output("\n\n")
+  end
+
+  private
+
+  def format_results
+    format_grade
+
+    append_to_final_output("RUBRIC SCORES:")
+    workflow.output["calculate_final_grade"][:rubric_scores].each do |category, data|
+      append_to_final_output("  #{RUBRIC[category][:description]} (#{(RUBRIC[category][:weight] * 100).round}% of grade):")
+      append_to_final_output("    Value: #{data[:raw_value]}")
+      append_to_final_output("    Score: #{(data[:score] * 10).round}/10 - \"#{data[:description]}\"")
+    end
+  end
+
+  def format_grade
+    letter_grade = workflow.output["calculate_final_grade"][:final_score][:letter_grade]
+    celebration_emoji = letter_grade == "A" ? "🎉" : ""
+    append_to_final_output(<<~OUTPUT)
+      \nFINAL GRADE:
+        Score: #{(workflow.output["calculate_final_grade"][:final_score][:weighted_score] * 100).round}/100
+        Letter Grade: #{letter_grade} #{celebration_emoji}
+    OUTPUT
+  end
+end

data/examples/grading/generate_grades/prompt.md

@@ -0,0 +1,105 @@
+These are the key testing guidelines to consider in your evaluation:
+
+- Tests should serve as specifications that define expected behaviors
+- Tests should have descriptive names that clearly communicate intent
+- Tests should focus on behavior rather than implementation details
+- Excessive mocking/stubbing should be avoided in favor of testing real behavior
+- Tests should be well-structured with minimal setup complexity
+- Tests should be maintainable and not break when implementation details change
+- Tests should cover edge cases and error conditions
+- Tests should follow proper naming conventions and directory structure
+- Tests should not modify the behaviour of the code being tested (e.g. making a private method public in tests)
+
+Now consider the full transcript and evaluate the test being graded based on the following rubrics on a scale of 1-10:
+
+<test_helpers>
+0-1: Extremely poor helper usage - Helpers used incorrectly or inappropriately, making tests harder to understand
+2-3: Poor helper usage - Helpers are poorly designed, tightly coupled to implementation, or used incorrectly
+4-5: Basic helper usage - Helpers work but may be poorly organized or not reusable
+6-7: Good helper usage - Helpers are well-designed and used appropriately
+8-9: Very good helper usage - Helpers are well-factored, reusable, and make tests clearer
+10: Excellent helper usage - Helpers are perfectly designed, highly reusable, and significantly improve test clarity and maintainability. Also give this score to tests that DO NOT use test helpers at all.
+</test_helpers>
+
+<mocks_and_stubs>
+0-1: Extremely poor mocking - Mocks/stubs used incorrectly or excessively, completely hiding real behavior
+2-3: Poor mocking - Heavy reliance on mocks that couple tests to implementation; mocks don't match real behavior
+4-5: Basic mocking - Mocks used appropriately but may be overused or not match implementation exactly
+6-7: Good mocking - Mocks used judiciously where needed; generally match implementation
+8-9: Very good mocking - Minimal mocking focused on external dependencies; accurately reflects real behavior
+10: Excellent mocking - Mocks used only where absolutely necessary (external APIs, etc); perfectly match real implementations; maintain loose coupling
+</mocks_and_stubs>
+
+<readability>
+0-1: Extremely poor readability - Test purpose is impossible to understand; no structure or organization
+2-3: Poor readability - Test names are vague or misleading; structure is confusing with no clear assertions
+4-5: Basic readability - Structure is understandable but not optimized for clarity
+6-7: Good readability - Structure is logical with clear assertions
+8-9: Very readable - Well-organized with explicit, meaningful test names and assertions
+10: Exceptionally readable - Test names serve as perfect specifications; elegant structure with context-providing descriptions; self-documenting with clear setup, execution, and verification phases
+</readability>
+
+<maintenability>
+0-1: Extremely brittle - Tests are completely coupled to implementation details
+2-3: Highly unmaintainable - Will require significant rework when code changes because of heavy coupling to implementation details
+4-5: Somewhat maintainable - Some coupling to implementation details
+6-7: Reasonably maintainable - Tests mostly focus on behavior over implementation; limited coupling to implementation details
+8-9: Highly maintainable - Tests focus on behavior rather than implementation; changes to implementation should rarely break tests
+10: Exceptionally maintainable - Tests purely focus on behavior and public interfaces; implementation can be completely refactored without breaking tests; well-factored test helpers and fixtures
+</maintenability>
+
+<effectiveness>
+0-1: Ineffective - Don't validate actual behavior and could pass even if code is broken
+2-3: Minimally effective - Only the most basic functionality validated. Many incorrect behaviors would not be caught
+4-5: Partially effective - Only catch obvious issues but miss subtle bugs; limited validation of actual outcomes
+6-7: Reasonably effective - Should catch most common bugs
+8-9: Highly effective - Should catch nearly all bugs
+10: Exceptionally effective - Should catch even subtle edge case bugs; validate both positive and negative cases
+</effectiveness>
+
+While grading, consider the following goals as being applicable across all rubrics:
+
+SUBJECTIVE:
+- Well-written: Organized, easy to understand, and follow best practices
+- Real behavior: Validate what the code does rather than implementation details
+- Isolated: Should not depend on external systems, services, or APIs. Note: The use of fixtures such as `shops(:snowdevil)` is expected and should not be penalized. The only exception is when the SUT is being loaded as a fixture unnecessarily when it could be instantiated directly.
+
+OBJECTIVE
+- Idempotent: Should be able to run repeatedly without affecting outcome or side effects.
+- Deterministic: Should produce the same results across all runs and environments.
+- No sleep: Does not include sleep calls or rely on timing for synchronization.
+- Concurrent: Properly handles concurrent execution paths without errors.
+- Timeless: Does not depend on the current date or time. Will not fail due to changes such as daylight savings or leap years. Specifically with regards to handling time, look for anti-patterns like `Time.current + 7.days.to_i`, which fails on DST changes. The correct approach is `7.days.from_now`.
+
+VIOLATING ANY OBJECTIVE GOAL SHOULD RESULT IN AN OVERALL SCORE LESS THAN 5!
+
+Provide a brief justification for each score, using a maximum of 1-3 sentences. (Note that specific recommendations for improvement are not needed at this step.)
+
+You are acting as a stern and relentless striver for excellence in programming, so you must be highly critical. The point of this grading exercise is to facilitate substantial improvement, not just stroking the programmer's ego. Do not hesitate to give a failing overall score (0) for serious violations!
+
+RESPONSE FORMAT: You must respond in JSON format within <json> XML tags.
+
+<json>
+{
+  "test_helpers": {
+    "score": 4,
+    "justification": "Helpers are used incorrectly in several places, reducing test maintainability and clarity. The assert_valid_record helper is being misused with hashes instead of model instances."
+  },
+  "mocks_and_stubs": {
+    "score": 4,
+    "justification": "Several mocks don't match the actual implementation, making tests brittle and potentially hiding production bugs. For example, mocking success: true when the service returns status: 'success'."
+  },
+  "readability": {
+    "score": 8,
+    "justification": "Test names clearly describe behavior being tested."
+  },
+  "maintainability": {
+    "score": 6,
+    "justification": "Tests mostly focus on behavior but have some coupling to implementation."
+  },
+  "effectiveness": {
+    "score": 7,
+    "justification": "Tests validate most expected behaviors and would catch common bugs."
+  }
+}
+</json>

data/examples/grading/generate_recommendations/output.txt

@@ -0,0 +1,17 @@
+========== TEST RECOMMENDATIONS ==========
+<%- if response["recommendations"].empty? -%>
+No recommendations found.
+<%- else -%>
+<%- response["recommendations"].each_with_index do |rec, index| -%>
+Recommendation #<%= index + 1 %>:
+Description: <%= rec["description"] %>
+Impact: <%= rec["impact"] %>
+Priority: <%= rec["priority"] %>
+
+Code Suggestion:
+
+<%= rec["code_suggestion"] %>
+
+<%- end -%>
+<%- end -%>
+===========================================

data/examples/grading/generate_recommendations/prompt.md

@@ -0,0 +1,60 @@
+Finally, based on the conversation transcript above, go ahead and provide specific, actionable recommendations that would most effectively improve the overall test score.
+
+Focus on recommendations that would:
+
+1. Increase coverage
+2. Add more assertions where needed
+3. Make the tests more maintainable or readable
+4. Ensure tests serve as specifications by having clear, descriptive names
+5. Reduce excessive mocking/stubbing that couples tests to implementation details
+6. Improve test structure to reduce setup complexity
+7. Ensure tests focus on behavior rather than implementation details
+8. Ensure gaps in private methods are tested through public methods
+9. Fix any issues with test helpers that are used incorrectly or unnecessarily
+10. Improve efficiency by combining or deleting tests where appropriate (note that having more than one assertion per test is acceptable)
+11. Fix any violations of the objective criteria (idempotency, determinism, etc.)
+12. Be specific about edge cases that should be covered by tests. Write down in the recommendations which edge cases you are referring to.
+13. Do not recommend the use of RSpec features like `let` for Minispec tests.
+
+IF YOU IDENTIFY EDGE CASES, YOU MUST BE SPECIFIC ABOUT THEM IN THE RECOMMENDATIONS.
+
+RESPONSE FORMAT: You must respond in JSON format inside <json> XML tags without additional commentary.
+
+Example:
+
+<json>
+{
+  "recommendations": [
+    {
+      "description": "Add tests for uncovered method X",
+      "impact": "Would increase method coverage by Y%",
+      "priority": "High",
+      "code_suggestion": "def test_method_x_with_valid_input\n  result = subject.method_x('valid_input')\n  assert_equal expected_result, result\nend"
+    },
+    {
+      "description": "Fix time handling to avoid DST issues",
+      "impact": "Would make tests deterministic across DST changes",
+      "priority": "High",
+      "code_suggestion": "# Replace\nexpiry_time = Time.current + 7.days.to_i\n\n# With\nexpiry_time = 7.days.from_now"
+    },
+    {
+      "description": "Add edge case tests for the show action for when the parameter X is blank",
+      "impact": "Would improve test completeness and effectiveness",
+      "priority": "Medium",
+      "code_suggestion": "..."
+    },  
+    {
+      "description": "Improve test descriptions to better serve as specifications",
+      "impact": "Would make tests more valuable as documentation",
+      "priority": "Medium",
+      "code_suggestion": "# Replace\ndef test_process\n\n# With\ndef test_process_returns_success_with_valid_input"
+    },
+    {
+      "description": "Replace implementation-focused mocks with behavior assertions",
+      "impact": "Would make tests less brittle and more maintainable",
+      "priority": "High",
+      "code_suggestion": "# Replace\nUserNotifier.expects(:notify).with(user, 'welcome')\n\n# With\nassert_sends_notification(user, 'welcome') do\n  subject.process\nend"
+    }
+  ]
+}
+</json>

data/examples/grading/run_coverage.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "open3"
+
+class RunCoverage < Roast::Workflow::BaseStep
+  def call
+    # Run the test with coverage analysis
+    run_test_with_coverage
+  end
+
+  private
+
+  def run_test_with_coverage
+    subject_file = workflow.output["read_dependencies"]
+    subject_file = subject_file.match(%r{<sut>(.*?)</sut>})&.[](1) || subject_file
+    test_file = workflow.file
+    extension = File.extname(test_file).gsub(".", "")
+
+    # Handle JS/TS test files
+    extension = "js" if ["js", "jsx", "ts", "tsx"].include?(extension)
+
+    # Get the absolute path to the test_runner executable
+    test_runner_path = File.expand_path("../../bin/#{extension}_test_runner", __dir__)
+
+    # Make sure the test_runner executable exists
+    unless File.exist?(test_runner_path)
+      Roast::Helpers::Logger.error("Test runner executable not found: #{test_runner_path}")
+      exit(1)
+    end
+
+    # Resolve paths to prevent issues when pwd differs from project root
+    resolved_subject_file = Roast::Helpers::PathResolver.resolve(subject_file)
+    resolved_test_file = Roast::Helpers::PathResolver.resolve(test_file)
+
+    # Run the test_runner using shadowenv for environment consistency
+    command = "shadowenv exec --dir . -- #{test_runner_path} #{resolved_subject_file} #{resolved_test_file}"
+    output, status = Open3.capture2(command)
+
+    unless status.success?
+      Roast::Helpers::Logger.error("Test runner exited with non-zero status: #{status.exitstatus}")
+      Roast::Helpers::Logger.error(output)
+      exit(status.exitstatus)
+    end
+
+    output
+  end
+end

data/examples/grading/verify_mocks_and_stubs/prompt.md

@@ -0,0 +1,12 @@
+Find places in the provided test code where stubbing and mocking are used. Search for the corresponding implementation source code of those dependencies elsewhere in the codebase to validate that the stub or mock matches the implementation that it is doubling. Use the tool functions provided to find and read the dependencies.
+
+Once you've found the dependencies, verify that any mocks and stubs accurately reflect the real implementation. If there are discrepancies, list them out alphabetically with:
+
+1. The name of the mocked/stubbed method
+2. What the mock/stub expects in terms of arguments and/or return values
+3. What the actual implementation actually takes as arguments and returns
+4. Suggestions for fixing the discrepancy
+
+Note: If there are no discrepancies, do not summarize those that accurately reflect their real implementations in the codebase, just respond "All mocks and stubs verified."
+
+IMPORTANT: There's absolutely no need for you to waste time grepping for methods/functions that you know belong to testing libraries such as Mocha's `expects` and `stubs`. Only search for the implementation of things that are stubbed and/or mocked in the test to verify whether the test code matches the implementation code.

data/examples/grading/verify_test_helpers/prompt.md

@@ -0,0 +1,53 @@
+Now identify custom test helpers used in this test for the following purpose:
+
+1. Analyzing if they are used correctly
+2. Understanding test code that has had significant chunks of implementation abstracted away into helpers
+3. Fully understanding custom assertions that are not included by default in Ruby on Rails or part of your base knowledge
+
+Your grep tool function is vital for this work. It provides 4 lines of context before and after the matching line.
+
+For example, if you call `grep(string: "def assert_sql")`, the output will include:
+
+```
+.test/support/helpers/sql_assertions.rb-101-    end
+.test/support/helpers/sql_assertions.rb-102-    result
+.test/support/helpers/sql_assertions.rb-103-  end
+.test/support/helpers/sql_assertions.rb-104-
+.test/support/helpers/sql_assertions.rb:105:  def assert_sql(*patterns_to_match, **kwargs, &block)
+.test/support/helpers/sql_assertions.rb-106-    mysql_only_test!
+.test/support/helpers/sql_assertions.rb-107-
+.test/support/helpers/sql_assertions.rb-108-    result = T.let(nil, T.nilable(T::Boolean))
+.test/support/helpers/sql_assertions.rb-109-    counter = ActiveRecord::SQLCounter.new(**kwargs)
+```
+
+Unfortunately, many test helper methods are undocumented. In those cases (like the example above) the pre-context will be junk. However, there are a number of helper methods that do have very specific and narrow use cases, and those do tend to be well-documented. In those cases, you should use `read_file` to be able to read the full documentation.
+
+For example, here is the result of calling `grep(string: "def assert_sql_events")`
+
+```
+.test/support/helpers/externals_helper.rb-93-  # @example Logs events in the list that did not occur
+.test/support/helpers/externals_helper.rb-94-  #   expected_queries = { "Shop Load" => 1, "User Load" => 1 }
+.test/support/helpers/externals_helper.rb-95-  #   # Fails and reports that User Load occured 0 times instead of expected 1
+.test/support/helpers/externals_helper.rb-96-  #   assert_sql_events(expected_queries) { Shop.current_or_find(shop.id) }
+.test/support/helpers/externals_helper.rb:97:  def assert_sql_events(expected_events, &block)
+.test/support/helpers/externals_helper.rb-98-    mysql_only_test!
+.test/support/helpers/externals_helper.rb-99-
+.test/support/helpers/externals_helper.rb-100-    mysql_events = ExternalsCollector.new(&block).events
+.test/support/helpers/externals_helper.rb-101-      .select { |e| e.first == :mysql }
+```
+
+Notice that the documentation for the `assert_sql_events` method is cutoff. Use your `read_file` tool function to get the whole test helper source code and gain better understanding of how it is intended to be used, with the side benefit of also being able to see how it is implemented.
+
+Note: You will undoubtedly already be familiar with some of Minitest and RSpec's built-in helpers. There is no need to search for those, since they are packaged as gems you won't find them anyway.
+
+DO NOT FORGET TO PREPEND `def` TO YOUR QUERY TO FIND A METHOD DEFINITION INSTEAD OF USAGES, otherwise you may bring back a very large and useless result set!!!
+
+Once you are done understanding the custom test helpers used in the test file, analyze and report on whether it seems like any of the helpers are:
+
+1. Used incorrectly
+2. Used unnecessarily
+3. Any other problem related to the use of helper methods
+
+Where possible, use your best judgment to make recommendations for how to fix problems that you find, but ONLY related to test helpers.
+
+Note: You are only being used to help find problems so it is not necessary to report on correct usage of helpers or to make positive comments.

data/examples/grading/workflow.md

@@ -0,0 +1,8 @@
+As a senior software engineer and testing expert, evaluate the quality of this test file based on guidelines that will be subsequently provided.
+
+Next I will now provide the source code of the test that we will be analyzing, and then step you through a series of analysis activities, before finally asking you to provided a final report.
+
+<test>
+# <%= file %>
+<%= File.read(file) %>
+</test>

data/examples/grading/workflow.rb.md

@@ -0,0 +1,6 @@
+As a senior Ruby engineer and testing expert, evaluate the quality of this Ruby test file. Next I will now provide the source code of the test that we will be analyzing, and then step you through a series of analysis activities, before finally asking you to provided a final report.
+
+<test>
+# <%= file %>
+<%= File.read(file) %>
+</test>

data/examples/grading/workflow.ts+tsx.md

@@ -0,0 +1,6 @@
+As a senior front-end engineer and testing expert, evaluate the quality of this test file. Next I will now provide the source code of the test that we will be analyzing, and then step you through a series of analysis activities, before finally asking you to provided a final report.
+
+<test>
+# <%= file %>
+<%= File.read(file) %>
+</test>

data/examples/grading/workflow.yml

@@ -0,0 +1,46 @@
+name: Grading current test changes
+
+tools:
+  - Roast::Tools::Grep
+  - Roast::Tools::ReadFile
+  - Roast::Tools::SearchFile
+
+each: '% cd $(git rev-parse --show-toplevel) && git status --porcelain | grep "_test\.rb" | cut -c4- | xargs realpath'
+
+steps:
+  - read_dependencies
+  - run_coverage
+  -
+    - analyze_coverage
+    - verify_test_helpers
+    - verify_mocks_and_stubs
+  - generate_grades
+  - calculate_final_grade
+  - format_result
+  - generate_recommendations
+  - annotate_pr_with_comments
+
+# set non-default attributes for steps below
+analyze_coverage:
+  model: gpt-4.1-mini
+  loop: false
+  json: true
+  
+generate_grades:
+  model: o3
+  json: true
+
+generate_recommendations:
+  model: o3
+  loop: false
+  json: true
+  params:
+    max_completion_tokens: 5_000
+
+annotate_pr_with_comments:
+  tools:
+    - Roast::Tools::Github::Annotator
+  model: o3
+  params:
+    max_completion_tokens: 5_000
+  if: "workflow.pr? && output.recommendations.any?"

data/exe/roast

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+Encoding.default_external = Encoding::UTF_8
+Encoding.default_internal = Encoding::UTF_8
+
+unshift_path = ->(path) {
+  p = File.expand_path("../../#{path}", __FILE__)
+  $LOAD_PATH.unshift(p) unless $LOAD_PATH.include?(p)
+}
+unshift_path.call("lib")
+
+require "bundler/setup"
+require "roast"
+
+puts "🔥🔥🔥 Everyone loves a good roast 🔥🔥🔥\n\n"
+Roast::CLI.start(ARGV)

data/lib/roast/helpers/function_caching_interceptor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "active_support/cache"
+require "active_support/notifications"
+require_relative "logger"
+
+module Roast
+  module Helpers
+    # Intercepts function dispatching to add caching capabilities
+    # This module wraps around Raix::FunctionDispatch to provide caching for tool functions
+    module FunctionCachingInterceptor
+      def dispatch_tool_function(function_name, params)
+        # legacy workflows don't have a configuration
+        return super(function_name, params) if configuration.blank?
+
+        function_config = configuration.function_config(function_name)
+        if function_config&.dig("cache", "enabled")
+          # Call the original function and pass in the cache
+          super(function_name, params, cache: Roast::Tools::CACHE)
+        else
+          Roast::Helpers::Logger.debug("⚠️ Caching not enabled for #{function_name}")
+          super(function_name, params)
+        end
+      end
+    end
+  end
+end

data/lib/roast/helpers/logger.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "logger"
+require "forwardable"
+
+module Roast
+  module Helpers
+    # Central logger for the Roast application
+    class Logger
+      extend Forwardable
+      VALID_LOG_LEVELS = ["DEBUG", "INFO", "WARN", "ERROR", "FATAL"].freeze
+
+      attr_reader :logger, :log_level
+
+      # Delegate info and warn methods to the underlying logger
+      def_delegators :logger, :info, :warn
+
+      # Create a specialized debug method that ensures proper functionality
+      def debug(message)
+        logger.debug(message)
+      end
+
+      def error(message)
+        # Add any custom error handling logic here
+        logger.error(message)
+      end
+
+      def fatal(message)
+        # Add any custom fatal error handling logic here
+        logger.fatal(message)
+      end
+
+      def initialize(stdout: $stdout, log_level: ENV["ROAST_LOG_LEVEL"] || "INFO")
+        @log_level = validate_log_level(log_level)
+        @logger = create_logger(stdout)
+      end
+
+      def log_level=(level)
+        @log_level = validate_log_level(level)
+        logger.level = ::Logger.const_get(@log_level)
+      end
+
+      class << self
+        extend Forwardable
+
+        def instance
+          @instance ||= new
+        end
+
+        # Delegate logging methods to the singleton instance
+        def_delegators :instance, :debug, :info, :warn, :error, :fatal
+
+        # For testing purposes
+        def reset
+          @instance = nil
+        end
+      end
+
+      private
+
+      def validate_log_level(level)
+        level_str = level.to_s.upcase
+        unless VALID_LOG_LEVELS.include?(level_str)
+          raise ArgumentError, "Invalid log level: #{level}. Valid levels are: #{VALID_LOG_LEVELS.join(", ")}"
+        end
+
+        level_str
+      end
+
+      def create_logger(stdout)
+        ::Logger.new(stdout).tap do |logger|
+          logger.level = ::Logger.const_get(@log_level)
+          logger.formatter = proc do |severity, datetime, _progname, msg|
+            msg_string = format_message(msg)
+
+            if severity == "INFO" && !msg_string.start_with?("[")
+              msg_string
+            else
+              "[#{datetime.strftime("%Y-%m-%d %H:%M:%S")}] #{severity}: #{msg_string.gsub(/^\[|\]$/, "").strip}\n"
+            end
+          end
+        end
+      end
+
+      # Ensures that the message is a string, and if it's an array, it's formatted correctly for the console
+      def format_message(msg)
+        case msg
+        when String
+          msg
+        when Array
+          if msg.first.is_a?(String) && msg.length == 1
+            msg.first
+          else
+            msg.map { |item| item.is_a?(String) ? item : item.inspect.gsub(/^\[|\]$/, "").strip }.join("\n")
+          end
+        when NilClass
+          ""
+        else
+          msg.to_s
+        end
+      end
+    end
+  end
+end