yard_example_runner 0.1.0

data/Rakefile

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'rake/clean'
+
+# Load all .rake files from tasks and its subdirectories.
+Dir.glob('rake_tasks/**/*.rake').each { |r| load r }
+
+CLOBBER << '.husky/_'
+CLOBBER << 'node_modules'
+CLOBBER << 'Gemfile.lock'
+CLOBBER << 'package-lock.json'
+
+default_tasks = %i[cucumber markdownlint rubocop yard]
+
+task default: default_tasks
+
+# Prepend a module into Rake::Task to add per-task logging without stomping on
+# other patches that may also wrap execute.
+module Rake
+  # Rake::Task with per-task box logging prepended.
+  class Task
+    prepend(Module.new do
+      def execute(args = nil)
+        # Only output the task name if it wasn't the only top-level task
+        # rake default      # => output task name for each task called by the default task
+        # rake rubocop      # => do not output the task name
+        # rake rubocop yard # => output task name for rubocop and yard
+        top_level_tasks = Rake.application.top_level_tasks
+        box("Rake task: #{name}") unless top_level_tasks.length == 1 && name == top_level_tasks[0]
+        super
+      end
+
+      private
+
+      def box(message)
+        width = message.length + 2
+        puts "┌#{'─' * width}┐"
+        puts "│ #{message} │"
+        puts "└#{'─' * width}┘"
+      end
+    end)
+  end
+
+  # Rake::Application with SUCCESS/FAIL summary appended after the full run.
+  # top_level is used rather than run because the Rakefile is loaded inside
+  # run, so any patch to run is applied too late to affect the current call.
+  class Application
+    prepend(Module.new do
+      def top_level
+        super
+        puts "\nSUCCESS"
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        puts "\n#{e.is_a?(SystemExit) && e.success? ? 'SUCCESS' : 'FAILED'}"
+        raise
+      end
+    end)
+  end
+end

data/bin/setup

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+if [ -x "$(command -v npm)" ]; then
+  npm install
+else
+  echo "npm is not installed"
+  echo "Install npm then re-run this script to enable the conventional commit git hook."
+fi

data/lib/yard/cli/run_examples.rb

@@ -0,0 +1,297 @@
+# frozen_string_literal: true
+
+module YARD
+  module CLI
+    # Implements the +yard run-examples+ command
+    #
+    # Registered with YARD's command dispatcher so that running
+    # +yard run-examples [paths...] [options]+ invokes {#run}. The full
+    # pipeline is:
+    #
+    # 1. {#parse_files} — expand the given paths/globs into +.rb+ file paths,
+    #    defaulting to +app/+ and +lib/+ when none are given.
+    # 2. {#parse_examples} — YARD-parse those files and collect every
+    #    +@example+ tag from the registry.
+    # 3. {#add_pwd_to_path} — ensure the current working directory is on
+    #    +$LOAD_PATH+ so that +require+ calls inside examples resolve correctly.
+    # 4. {#generate_tests} — convert each tag into a {YardExampleRunner::Example}
+    #    and register it as a +Minitest::Spec+.
+    # 5. {#run_tests} — schedule the specs to run via +Minitest.autorun+ when
+    #    the process exits.
+    #
+    # @see YardExampleRunner::Example
+    #
+    # @see YardExampleRunner::Expectation
+    #
+    # @api private
+    #
+    class RunExamples < Command
+      # Returns the one-line description of the command shown in +yard help+
+      #
+      # @return [String] the description string
+      def description
+        'Run @example tags as tests'
+      end
+
+      # Runs the command line, parsing arguments and generating tests
+      #
+      # @param [Array<String>] args Switches are passed to minitest, everything else
+      #   is treated as the list of directories/files or glob
+      #
+      # @return [void]
+      #
+      def run(*args)
+        files = parse_files(args.grep_v(/^-/))
+        examples = parse_examples(files)
+        add_pwd_to_path
+        generate_tests(examples)
+        run_tests
+      end
+
+      private
+
+      # Expands a list of glob patterns or directory names into Ruby source file paths
+      #
+      # Each entry in +globs+ is treated as follows:
+      # - If it is an existing directory, +/**/*.rb+ is appended before
+      #   expansion, recursively matching all Ruby files under that directory.
+      # - Otherwise, it is passed directly to +Dir[]+ as-is, allowing explicit
+      #   file paths or glob patterns.
+      #
+      # If +globs+ is empty, it defaults to +['app', 'lib']+.
+      #
+      # @param globs [Array<String>] file paths, directory names, or glob
+      #   patterns to expand; defaults to +['app', 'lib']+ when empty
+      #
+      # @return [Array<String>] the flat list of +.rb+ file paths matched
+      #   by expanding all globs; an empty array if no files are matched
+      #
+      def parse_files(globs)
+        globs = %w[app lib] if globs.empty?
+
+        files = globs.map do |glob|
+          glob = "#{glob}/**/*.rb" if File.directory?(glob)
+
+          Dir[glob]
+        end
+
+        files.flatten
+      end
+
+      # Parses the given Ruby source files and returns all +@example+ tags found
+      #
+      # Instructs YARD to parse +files+, excluding any files matched by the
+      # patterns returned from {#excluded_files}. Once parsed, the full YARD
+      # registry is loaded and every code object is inspected for +@example+
+      # tags. The resulting tags from all objects are collected and flattened
+      # into a single array.
+      #
+      # Note: YARD silently swallows parse-level errors (syntax errors,
+      # +ArgumentError+, +NotImplementedError+) and logs warnings rather than
+      # raising. Only OS-level I/O errors propagate.
+      #
+      # @param files [Array<String>] absolute or relative paths to the Ruby
+      #   source files to parse
+      #
+      # @return [Array<YARD::Tags::Tag>] all +@example+ tags found across every
+      #   documented code object in the parsed files, in registry order
+      #
+      # @raise [Errno::EACCES] if a file in +files+ exists but cannot be read
+      #   due to insufficient permissions
+      #
+      # @raise [Errno::ENOENT] if a file in +files+ is deleted between directory
+      #   expansion and the point at which YARD reads it
+      #
+      def parse_examples(files)
+        YARD.parse(files, excluded_files)
+        registry = YARD::Registry.load_all
+        registry.all.map { |object| object.tags(:example) }.flatten
+      end
+
+      # Returns the list of file patterns to exclude from YARD parsing
+      #
+      # Reads the combined arguments from the command line and the +.yardopts+
+      # file (via {YARD::Config.with_yardopts}) and extracts the values of any
+      # +--exclude+ options. These patterns are passed directly to {YARD.parse}
+      # which treats them as case-insensitive regular expressions.
+      #
+      # If +--exclude+ appears without a following value (e.g. as the last
+      # argument), it is silently ignored.
+      #
+      # @return [Array<String>] the exclusion patterns, one per +--exclude+
+      #   argument found; empty if none are present
+      #
+      def excluded_files
+        excluded = []
+        args = YARD::Config.with_yardopts { YARD::Config.arguments.dup }
+        args.each_with_index do |arg, i|
+          next unless arg == '--exclude'
+          next if args[i + 1].nil?
+
+          excluded << args[i + 1]
+        end
+
+        excluded
+      end
+
+      # Generates an in-memory Minitest spec for each +@example+ tag
+      #
+      # Calls {#build_spec} to construct a {YardExampleRunner::Example} for
+      # each tag, then calls +generate+ on it, which dynamically defines and
+      # registers an anonymous +Minitest::Spec+ subclass. The registered specs
+      # are held in memory by Minitest and executed when {#run_tests} triggers
+      # the test run.
+      #
+      # @param examples [Array<YARD::Tags::Tag>] the +@example+ tags to convert
+      #   into Minitest specs, as returned by {#parse_examples}
+      #
+      # @return [void]
+      #
+      def generate_tests(examples)
+        examples.each do |example|
+          build_spec(example).generate
+        end
+      end
+
+      # Builds a {YardExampleRunner::Example} from a YARD +@example+ tag
+      #
+      # Constructs a new {YardExampleRunner::Example} and populates it with
+      # the metadata needed to generate and run a Minitest spec:
+      #
+      # - +name+ — the title from the +@example+ tag (e.g. +"Adding two numbers"+),
+      #   or an empty string if the tag has no title
+      # - +definition+ — the YARD path of the owning code object
+      #   (e.g. +"MyClass#my_method"+), used as the spec description
+      # - +filepath+ — the absolute path and line number of the code object's
+      #   definition (e.g. +"/project/lib/my_class.rb:10"+), used to enrich
+      #   failure backtraces
+      # - +expectations+ — the list of expectations parsed from the example body
+      #   by {#extract_expectations}
+      #
+      # @param example [YARD::Tags::Tag] a single +@example+ tag whose +object+,
+      #   +name+, and +text+ attributes will be used to populate the spec
+      #
+      # @return [YardExampleRunner::Example] the populated example object, ready
+      #   to have +generate+ called on it
+      #
+      def build_spec(example)
+        YardExampleRunner::Example.new(example.name).tap do |spec|
+          spec.definition = example.object.path
+          spec.filepath = "#{Dir.pwd}/#{example.object.files.first.join(':')}"
+          spec.expectations = extract_expectations(example)
+        end
+      end
+
+      # Parses the body of a YARD +@example+ tag into expectations
+      #
+      # Parses the body of a YARD +@example+ tag into a list of
+      # {YardExampleRunner::Expectation} objects
+      #
+      # The example body is first normalized by {#normalize_example_lines}, which
+      # puts each +#=>+ annotation on its own line and strips whitespace. The
+      # resulting lines are then consumed in chunks:
+      #
+      # 1. All lines up to (but not including) the next +#=>+ line are joined as the
+      #    +actual+ Ruby expression.
+      # 2. The +#=>+ line that follows (if any) is stripped of its prefix and
+      #    whitespace to form the +expected+ value string.
+      # 3. An {YardExampleRunner::Expectation} is appended to the result array and
+      #    the process repeats.
+      #
+      # If a chunk of code lines has no following +#=>+ line, +expected+ is set to
+      # +nil+, which signals to the test runner that the expression should be
+      # evaluated but not asserted against a specific value.
+      #
+      # @example Parsing a single expectation tag.text = "sum(1, 2) #=> 3"
+      #   extract_expectations(tag) #=> [Expectation[actual: "sum(1, 2)", expected:
+      #   "3"]]
+      #
+      # @example Parsing multiple expectations with shared setup tag.text = "a =
+      #   1\nsum(a, 2) #=> 3\nsum(a, 3) #=> 4" extract_expectations(tag) #=>
+      #   [Expectation[actual: "a = 1\nsum(a, 2)", expected: "3"],
+      #   #    Expectation[actual: "sum(a, 3)", expected: "4"]]
+      #
+      # @param example [YARD::Tags::Tag] the +@example+ tag whose +text+ body will be
+      #   parsed into expectations
+      #
+      # @return [Array<YardExampleRunner::Expectation>] one +Expectation+ per +#=>+
+      #   annotation found in the example body; each holds:
+      #   - +actual+ [String] — one or more lines of Ruby code to evaluate
+      #   - +expected+ [String, nil] — the expected return value, or +nil+ if the
+      #     expression should be evaluated without asserting a result
+      #
+      def extract_expectations(example)
+        lines = normalize_example_lines(example.text)
+        [].tap do |arr|
+          until lines.empty?
+            actual = lines.take_while { |l| l !~ /^#=>/ }
+            expected = lines[actual.size]&.sub('#=>', '')&.strip
+            lines.slice! 0..actual.size
+            arr << YardExampleRunner::Expectation.new(actual: actual.join("\n"), expected: expected)
+          end
+        end
+      end
+
+      # Normalizes the raw text of a +@example+ tag into a flat array of lines
+      #
+      # Performs three transformations in order:
+      #
+      # 1. Normalizes the +# =>+ annotation style (with a space) to +#=>+
+      #    (without a space), so both forms are treated identically.
+      # 2. Ensures each +#=>+ annotation is on its own line by inserting a
+      #    newline before every occurrence. This handles inline annotations
+      #    such as +sum(1, 2) #=> 3+, splitting them into two lines.
+      # 3. Splits on newlines, strips leading and trailing whitespace from
+      #    each line, and discards any blank lines.
+      #
+      # The resulting array is consumed by {#extract_expectations} to identify
+      # code lines and their corresponding +#=>+ assertion lines.
+      #
+      # @param text [String] the raw body text of a +@example+ tag
+      #
+      # @return [Array<String>] the normalized, non-empty lines of the example;
+      #   +#=>+ lines are always separate entries, never inline with code
+      #
+      def normalize_example_lines(text)
+        text = text.gsub('# =>', '#=>')
+        text = text.gsub('#=>', "\n#=>")
+        text.split("\n").map(&:strip).reject(&:empty?)
+      end
+
+      # Schedules the generated Minitest specs to run when the process exits
+      #
+      # Calls +Minitest.autorun+, which registers an +at_exit+ hook. That hook
+      # calls +Minitest.run+ and then fires any callbacks registered via
+      # +Minitest.after_run+ (including {YardExampleRunner.after_run} blocks).
+      #
+      # +Minitest.autorun+ is used rather than calling +Minitest.run+ directly
+      # because +Minitest.after_run+ callbacks are only invoked inside
+      # +autorun+'s +at_exit+ handler — a bare +Minitest.run+ call does not
+      # trigger them.
+      #
+      # @return [void]
+      #
+      def run_tests
+        Minitest.autorun
+      end
+
+      # Adds the current working directory to Ruby's load path if not present
+      #
+      # Example code in +@example+ tags is evaluated in the same Ruby process
+      # as +yard run-examples+. That code commonly uses +require+ to load the
+      # project's own files (e.g. +require 'lib/my_class'+), but Ruby's default
+      # +$LOAD_PATH+ does not include the current working directory. Without
+      # this, those +require+ calls would raise +LoadError+.
+      #
+      # This method must be called before {#generate_tests} so that any
+      # +require+ statements executed during example evaluation can resolve
+      # paths relative to the project root.
+      #
+      # @return [void]
+      #
+      def add_pwd_to_path
+        $LOAD_PATH.unshift(Dir.pwd) unless $LOAD_PATH.include?(Dir.pwd)
+      end
+    end
+  end
+end

data/lib/yard_example_runner/example/comparison.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+module YardExampleRunner
+  class Example < ::Minitest::Spec
+    # Comparison and matcher logic for verifying example expectations
+    #
+    # This module is included into {Example} so that its methods have direct
+    # access to Minitest assertions (+assert+, +assert_equal+, +assert_nil+,
+    # +diff+) inherited from +Minitest::Spec+. It also delegates to the
+    # {Evaluator} (via {Example#evaluator}) for expression evaluation.
+    #
+    # The module handles three verification strategies:
+    #
+    # 1. **Block matchers** — matchers that implement +supports_block_expectations?+
+    #    (e.g. RSpec's +raise_error+, +change+, +output+). The actual expression
+    #    is wrapped in a +Proc+ and passed unevaluated.
+    # 2. **Value matchers** — matchers that implement +matches?+ (e.g. +eq+,
+    #    +be_a+, +be_within+). The actual expression is evaluated and the
+    #    resulting value is passed.
+    # 3. **Bare values** — compared via {#compare_values} using error handling,
+    #    +nil+ checks, and +===+ case equality.
+    #
+    module Comparison
+      protected
+
+      # Evaluates both the actual and expected expressions and compares their results
+      #
+      # The expected expression is always evaluated first via
+      # {Evaluator#evaluate_with_assertion} (which captures any +StandardError+
+      # as a value). The result determines which of two branches is taken:
+      #
+      # 1. **Matcher** ({#matcher?}) — delegates to {#assert_matcher}, which
+      #    handles both block matchers (e.g. +raise_error+) and value matchers
+      #    (e.g. +eq+, +be_a+, +be_within+).
+      # 2. **Bare value** — +actual+ is also evaluated via
+      #    {Evaluator#evaluate_with_assertion} and the pair is compared via
+      #    {#compare_values}, which handles error-vs-error, single-error,
+      #    +nil+, and +===+ cases.
+      #
+      # On failure the backtrace is decorated with the example's source location
+      # via {Example#add_filepath_to_backtrace}.
+      #
+      # @param example [Example] the owning example, used to decorate failure backtraces
+      #
+      # @param expected [String] the Ruby expression representing the expected value
+      #
+      # @param actual [String] the Ruby expression representing the actual value
+      #
+      # @param bind [Class, nil] the class scope to evaluate +actual+ in; +expected+
+      #   is always evaluated in a +nil+ binding (top-level context)
+      #
+      # @return [void]
+      #
+      # @raise [Minitest::Assertion] re-raises any assertion failure with the
+      #   example's filepath prepended to the backtrace
+      #
+      # @example
+      #   verify_actual(example, '42', 'answer', nil)
+      #
+      # @api private
+      #
+      def verify_actual(example, expected, actual, bind)
+        expected = evaluator.evaluate_with_assertion(expected, nil)
+
+        if matcher?(expected)
+          assert_matcher(expected, actual, bind)
+        else
+          actual = evaluator.evaluate_with_assertion(actual, bind)
+          compare_values(expected, actual)
+        end
+      rescue Minitest::Assertion => e
+        add_filepath_to_backtrace(e, example.filepath)
+        raise e
+      end
+
+      # Evaluates +actual+ and asserts a matcher against it
+      #
+      # When the matcher is a {#block_matcher?}, the actual expression is wrapped
+      # in a +Proc+ and passed unevaluated so the matcher can invoke it (e.g.
+      # +raise_error+). Otherwise the actual expression is evaluated via
+      # {Evaluator#evaluate} and the resulting value is matched. If evaluation
+      # raises, the error propagates — use a block matcher like +raise_error+
+      # to assert on exceptions.
+      #
+      # @param expected [#matches?] a matcher object
+      # @param actual [String] the Ruby expression representing the actual value
+      # @param bind [Class, nil] the class scope for evaluation
+      #
+      # @return [void]
+      #
+      # @example
+      #   assert_matcher(eq(42), 'answer', nil)
+      #
+      # @api private
+      #
+      def assert_matcher(expected, actual, bind)
+        subject = if block_matcher?(expected)
+                    -> { evaluator.evaluate(actual, bind) }
+                  else
+                    evaluator.evaluate(actual, bind)
+                  end
+        assert expected.matches?(subject), failure_message_for(expected)
+      end
+
+      # Compares two already-evaluated values and raises on mismatch
+      #
+      # Handles four cases in priority order:
+      #
+      # 1. **Both are errors** — compares their string representations
+      #    (++"#<ClassName: message>"+++) with +assert_equal+, so mismatched error
+      #    types or messages produce a readable diff.
+      # 2. **Only one is an error** — raises that error directly, surfacing an
+      #    unexpected exception as a test failure.
+      # 3. **Expected is +nil+** — uses +assert_nil+ so Minitest's nil-specific
+      #    failure message is produced.
+      # 4. **Otherwise** — uses +assert+ with +===+ (case equality), which allows
+      #    +expected+ to be a +Regexp+, a +Range+, a +Proc+, or any other object
+      #    that implements a meaningful +===+.
+      #
+      # @param expected [Object] the already-evaluated expected value (or a
+      #   +StandardError+ if evaluation raised)
+      #
+      # @param actual [Object] the already-evaluated actual value (or a
+      #   +StandardError+ if evaluation raised)
+      #
+      # @return [void]
+      #
+      # @raise [Minitest::Assertion] if the values do not match under the applicable rule
+      #
+      # @raise [StandardError] if exactly one of the values is an error
+      #
+      # @example
+      #   compare_values(42, 42)
+      #
+      # @api private
+      #
+      def compare_values(expected, actual)
+        if both_are_errors?(expected, actual)
+          assert_equal("#<#{expected.class}: #{expected}>", "#<#{actual.class}: #{actual}>")
+        elsif (error = only_one_is_error?(expected, actual))
+          raise error
+        elsif expected.nil?
+          assert_nil(actual)
+        else
+          assert expected === actual, diff(expected, actual) # rubocop:disable Style/CaseEquality
+        end
+      end
+
+      # Returns +true+ if +obj+ implements the matcher protocol
+      #
+      # Checks for the presence of a +matches?+ method, which is the standard
+      # interface for both RSpec matchers and +minitest-matchers+.
+      #
+      # @param obj [Object] the object to test
+      #
+      # @return [Boolean]
+      #
+      # @example
+      #   matcher?(eq(42)) # => true
+      #
+      # @api private
+      #
+      def matcher?(obj)
+        obj.respond_to?(:matches?)
+      end
+
+      # Returns +true+ if +obj+ is a block-style matcher
+      #
+      # A block matcher is a {#matcher?} that also responds to
+      # +supports_block_expectations?+ and returns +true+ from it. RSpec's
+      # +raise_error+, +change+, and +output+ matchers follow this protocol.
+      #
+      # @param obj [Object] the object to test
+      #
+      # @return [Boolean]
+      #
+      # @example
+      #   block_matcher?(raise_error(RuntimeError)) # => true
+      #
+      # @api private
+      #
+      def block_matcher?(obj)
+        matcher?(obj) &&
+          obj.respond_to?(:supports_block_expectations?) &&
+          obj.supports_block_expectations?
+      end
+
+      # Returns the failure message from a matcher, with legacy fallback
+      #
+      # Tries +failure_message+ first (RSpec 3.x / modern minitest-matchers),
+      # then falls back to +failure_message_for_should+ (RSpec 2.x / older
+      # minitest-matchers).
+      #
+      # @param a_matcher [#failure_message, #failure_message_for_should] the matcher
+      #
+      # @return [String, nil] the failure message, or +nil+ if neither method exists
+      #
+      # @example
+      #   failure_message_for(eq(42))
+      #
+      # @api private
+      #
+      def failure_message_for(a_matcher)
+        if a_matcher.respond_to?(:failure_message)
+          a_matcher.failure_message
+        elsif a_matcher.respond_to?(:failure_message_for_should)
+          a_matcher.failure_message_for_should
+        end
+      end
+
+      private
+
+      # Returns +true+ if both values are +StandardError+ instances
+      #
+      # @param expected [Object] the expected value
+      # @param actual [Object] the actual value
+      #
+      # @return [Boolean]
+      #
+      # @example
+      #   both_are_errors?(RuntimeError.new, ArgumentError.new) # => true
+      #
+      # @api private
+      #
+      def both_are_errors?(expected, actual)
+        expected.is_a?(StandardError) && actual.is_a?(StandardError)
+      end
+
+      # Returns the error if exactly one value is a +StandardError+, otherwise +nil+
+      #
+      # @param expected [Object] the expected value
+      # @param actual [Object] the actual value
+      #
+      # @return [StandardError, nil]
+      #
+      # @example
+      #   only_one_is_error?(RuntimeError.new, 42) # => RuntimeError
+      #
+      # @api private
+      #
+      def only_one_is_error?(expected, actual)
+        if expected.is_a?(StandardError) && !actual.is_a?(StandardError)
+          expected
+        elsif !expected.is_a?(StandardError) && actual.is_a?(StandardError)
+          actual
+        end
+      end
+    end
+  end
+end