yard_example_runner 0.1.0

data/lib/yard_example_runner/rake.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rake/tasklib'
+
+module YardExampleRunner
+  # Rake task for running YARD @example tags as tests.
+  #
+  # @example Define the task with defaults
+  #   YardExampleRunner::RakeTask.new
+  #
+  # @example Define the task with custom options
+  #   YardExampleRunner::RakeTask.new do |task|
+  #     task.run_examples_opts = %w[-v]
+  #     task.pattern = 'app/**/*.rb'
+  #   end
+  #
+  # @api public
+  #
+  class RakeTask < ::Rake::TaskLib
+    # The name of the Rake task
+    #
+    # @example
+    #   task = YardExampleRunner::RakeTask.new
+    #   task.name #=> 'yard:run-examples'
+    #
+    # @return [String] the task name
+    #
+    attr_accessor :name
+
+    # Options passed to the +yard run-examples+ command
+    #
+    # @example
+    #   task = YardExampleRunner::RakeTask.new
+    #   task.run_examples_opts = %w[-v]
+    #   task.run_examples_opts #=> ['-v']
+    #
+    # @return [Array<String>] the command-line options
+    #
+    attr_accessor :run_examples_opts
+
+    # Glob pattern for files to pass to +yard run-examples+
+    #
+    # @example
+    #   task = YardExampleRunner::RakeTask.new
+    #   task.pattern = 'app/**/*.rb'
+    #   task.pattern #=> 'app/**/*.rb'
+    #
+    # @return [String] the glob pattern, or an empty string to use the default
+    #
+    attr_accessor :pattern
+
+    # Creates and registers the Rake task
+    #
+    # @example
+    #   YardExampleRunner::RakeTask.new do |task|
+    #     task.run_examples_opts = %w[-v]
+    #     task.pattern = 'app/**/*.rb'
+    #   end
+    #
+    # @param name [String] the Rake task name
+    #
+    # @yield [self] gives the task instance to the block for configuration
+    #
+    # @return [void]
+    #
+    def initialize(name = 'yard:run-examples')
+      super()
+      @name = name
+      @run_examples_opts = []
+      @pattern = ''
+      yield self if block_given?
+      define
+    end
+
+    protected
+
+    # Defines the Rake task
+    #
+    # @return [void]
+    #
+    # @api private
+    #
+    def define
+      desc 'Run YARD @example tags as tests'
+      task(name) do
+        args = run_examples_opts + (pattern.empty? ? [] : [pattern])
+        abort unless system('yard', 'run-examples', *args)
+      end
+    end
+  end
+end

data/lib/yard_example_runner/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module YardExampleRunner
+  # The current gem version
+  # @return [String] the current gem version.
+  VERSION = '0.1.0'
+end

data/lib/yard_example_runner.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'yard'
+require 'minitest'
+require 'minitest/spec'
+
+require_relative 'yard/cli/run_examples'
+require_relative 'yard_example_runner/example'
+require_relative 'yard_example_runner/expectation'
+require_relative 'yard_example_runner/version'
+
+# Provides configuration and hooks for running YARD @example tags as tests.
+#
+# @api public
+#
+module YardExampleRunner
+  # Configures YardExampleRunner
+  #
+  # @example
+  #   YardExampleRunner.configure do |runner|
+  #     runner.before { @value = 1 }
+  #     runner.after { puts 'done' }
+  #   end
+  #
+  # @yield [self] gives the module itself to the block for configuration
+  #
+  # @return [void]
+  #
+  # @api public
+  #
+  def self.configure
+    yield self
+  end
+
+  # Registers a block to be called before each example, or before a specific test
+  #
+  # The block is evaluated in the same context as the example.
+  #
+  # @example Register a global before hook
+  #   YardExampleRunner.before { @value = 1 }
+  #
+  # @example Register a hook for a specific test
+  #   YardExampleRunner.before('#my_method') { @value = 42 }
+  #
+  # @param test [String, nil] the test name to match, or +nil+ for all tests
+  #
+  # @param blk [Proc] the block to call before the matched example(s)
+  #
+  # @return [void]
+  #
+  # @api public
+  #
+  def self.before(test = nil, &blk)
+    hooks[:before] << { test: test, block: blk }
+  end
+
+  # Registers a block to be called after each example, or after a specific test
+  #
+  # The block is evaluated in the same context as the example.
+  #
+  # @example Register a global after hook
+  #   YardExampleRunner.after { puts 'done' }
+  #
+  # @example Register a hook for a specific test
+  #   YardExampleRunner.after('#my_method') { puts 'my_method done' }
+  #
+  # @param test [String, nil] the test name to match, or +nil+ for all tests
+  #
+  # @param blk [Proc] the block to call after the matched example(s)
+  #
+  # @return [void]
+  #
+  # @api public
+  #
+  def self.after(test = nil, &blk)
+    hooks[:after] << { test: test, block: blk }
+  end
+
+  # Registers a block to be called after all examples have run
+  #
+  # The block is evaluated in a different context from the examples. Delegates
+  # to +Minitest.after_run+.
+  #
+  # @example
+  #   YardExampleRunner.after_run { puts 'All examples finished' }
+  #
+  # @return [void]
+  #
+  # @api public
+  #
+  def self.after_run(&)
+    Minitest.after_run(&)
+  end
+
+  # Registers a test definition to be skipped
+  #
+  # @example
+  #   YardExampleRunner.skip '#my_method'
+  #
+  # @param test [String] the test name or definition path to skip
+  #
+  # @return [void]
+  #
+  # @api public
+  #
+  def self.skip(test)
+    skips << test
+  end
+
+  # Returns the array of test definitions registered to be skipped
+  #
+  # @return [Array<String>] the registered skip patterns
+  #
+  # @api private
+  #
+  def self.skips
+    @skips ||= []
+  end
+
+  # Returns the hash of registered before/after hooks
+  #
+  # @return [Hash{Symbol => Array<Hash>}] the registered hooks grouped by type
+  #
+  # @api private
+  #
+  def self.hooks
+    @hooks ||= {}.tap do |hash|
+      hash[:before] = []
+      hash[:after] = []
+    end
+  end
+end
+
+YARD::CLI::CommandParser.commands[:'run-examples'] = YARD::CLI::RunExamples

data/package.json

@@ -0,0 +1,12 @@
+{
+  "devDependencies": {
+    "@commitlint/cli": "^19.8.0",
+    "@commitlint/config-conventional": "^19.8.0",
+    "husky": "^9.1.7",
+    "markdownlint-cli": "^0.47.0"
+  },
+  "scripts": {
+    "lint:md": "markdownlint '**/*.md' --ignore node_modules --ignore vendor",
+    "prepare": "husky"
+  }
+}

data/rake_tasks/cucumber.rake

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'cucumber/rake/task'
+
+Cucumber::Rake::Task.new do |task|
+  task.cucumber_opts = %w[-f progress features --publish-quiet]
+end
+
+CLEAN << 'tmp'

data/rake_tasks/gem_tasks.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+
+# Make it so that calling `rake release` just calls `rake release:rubygem_push` to
+# avoid creating and pushing a new tag.
+
+Rake::Task['release'].clear
+desc 'Customized release task to avoid creating a new tag'
+task release: 'release:rubygem_push'
+
+CLOBBER << 'Gemfile.lock'

data/rake_tasks/markdownlint.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+desc 'Run markdownlint on all Markdown files'
+task :markdownlint do
+  sh 'npm run lint:md'
+end

data/rake_tasks/rubocop.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new

data/rake_tasks/yard.rake

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# YARD documentation for this project can NOT be built with JRuby or TruffleRuby.
+# This project uses the redcarpet gem which can not be installed on JRuby.
+#
+unless RUBY_PLATFORM == 'java' || RUBY_ENGINE == 'truffleruby'
+  # yard:build
+
+  require 'yard'
+
+  YARD::Rake::YardocTask.new('yard:build') do |t|
+    t.files = %w[lib/**/*.rb]
+    t.stats_options = ['--list-undoc']
+  end
+
+  CLEAN << '.yardoc'
+  CLEAN << 'doc'
+
+  # yard:audit
+
+  desc 'Run yardstick to show missing YARD doc elements'
+  task :'yard:audit' do
+    sh "yardstick 'lib/**/*.rb'"
+  end
+
+  # yard:coverage
+
+  require 'yardstick/rake/verify'
+
+  Yardstick::Rake::Verify.new(:'yard:coverage') do |verify|
+    verify.threshold = 100
+    verify.require_exact_threshold = false
+  end
+
+  # yard
+
+  desc 'Run YARD documentation tasks (build, coverage)'
+  task yard: %i[yard:build yard:audit yard:coverage]
+end

data/yard_example_runner.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+version = File.read(File.expand_path('lib/yard_example_runner/version.rb', __dir__)).match(/VERSION = ['"](.*?)['"]/)[1]
+
+Gem::Specification.new do |spec|
+  spec.name         = 'yard_example_runner'
+  spec.summary      = 'A YARD plugin that executes @example tag code as tests'
+  spec.description  = 'yard_example_runner parses @example tags from YARD documentation and ' \
+                      'executes them as tests, ensuring code examples remain accurate ' \
+                      'and serve as a living, executable specification.'
+  spec.author       = 'James Couball'
+  spec.email        = 'jcouball@yahoo.com'
+  spec.homepage     = 'https://github.com/main-branch/yard_example_runner'
+  spec.license      = 'MIT'
+  spec.version      = version
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}/file/CHANGELOG.md"
+  spec.metadata['documentation_uri'] = "https://rubydoc.info/gems/#{spec.name}/#{spec.version}"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.3.0'
+
+  spec.add_dependency 'minitest', '~> 6.0'
+  spec.add_dependency 'yard', '~> 0.9'
+
+  spec.add_development_dependency 'aruba', '~> 2.3'
+  spec.add_development_dependency 'main_branch_shared_rubocop_config', '~> 0.1'
+  spec.add_development_dependency 'minitest-matchers_vaccine', '~> 1.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'redcarpet', '~> 3.6'
+  spec.add_development_dependency 'rspec-expectations', '~> 3.13'
+  spec.add_development_dependency 'rubocop', '~> 1.84'
+  spec.add_development_dependency 'ruby-lsp', '~> 0.26'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'yardstick', '~> 0.9'
+end

metadata

@@ -0,0 +1,251 @@
+--- !ruby/object:Gem::Specification
+name: yard_example_runner
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- James Couball
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: main_branch_shared_rubocop_config
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: minitest-matchers_vaccine
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.84'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.84'
+- !ruby/object:Gem::Dependency
+  name: ruby-lsp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.26'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: yardstick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: yard_example_runner parses @example tags from YARD documentation and
+  executes them as tests, ensuring code examples remain accurate and serve as a living,
+  executable specification.
+email: jcouball@yahoo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".commitlintrc.yml"
+- ".github/workflows/continuous-integration.yml"
+- ".github/workflows/enforce_conventional_commits.yml"
+- ".github/workflows/release.yml"
+- ".gitignore"
+- ".husky/commit-msg"
+- ".markdownlint.yml"
+- ".release-please-config.json"
+- ".release-please-manifest.json"
+- ".rubocop.yml"
+- AI_POLICY.md
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- GOVERNANCE.md
+- Gemfile
+- LICENSE.txt
+- MAINTAINERS.md
+- README.md
+- Rakefile
+- bin/setup
+- lib/yard/cli/run_examples.rb
+- lib/yard_example_runner.rb
+- lib/yard_example_runner/example.rb
+- lib/yard_example_runner/example/comparison.rb
+- lib/yard_example_runner/example/constant_sandbox.rb
+- lib/yard_example_runner/example/evaluator.rb
+- lib/yard_example_runner/expectation.rb
+- lib/yard_example_runner/rake.rb
+- lib/yard_example_runner/version.rb
+- package.json
+- rake_tasks/cucumber.rake
+- rake_tasks/gem_tasks.rake
+- rake_tasks/markdownlint.rake
+- rake_tasks/rubocop.rake
+- rake_tasks/yard.rake
+- yard_example_runner.gemspec
+homepage: https://github.com/main-branch/yard_example_runner
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-branch/yard_example_runner
+  source_code_uri: https://github.com/main-branch/yard_example_runner
+  changelog_uri: https://rubydoc.info/gems/yard_example_runner/0.1.0/file/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/yard_example_runner/0.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A YARD plugin that executes @example tag code as tests
+test_files: []