zirconia 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83981e69d14fe2bbfa9a7a0058ddf5422cb987d0693d516fda42defd59795cab
+  data.tar.gz: 4b4fe6bd399d63f2225a205a2da28b3483b459449d7dd89d1133c45faa4fc525
+SHA512:
+  metadata.gz: 45088c025d1e60ce8e57be3e8725e80edaaf7546976bf8c8a36e46f3ba98237885c6295162423249d75450aa94909ad5915599fe3cae47de450b82dea35531d0
+  data.tar.gz: 65b9f8e5797bd0842ad727380d6d0055b6e38487635b61612670d1f1717e55a82c053cf050ee7645ee7e8ed63805694d72bdc6bfd133ee8d8361ae89ad20df2d

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,69 @@
+require:
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  SuggestExtensions: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Layout/ExtraSpacing:
+  AllowForAlignment: true
+Layout/LineLength:
+  Max: 80
+Layout/MultilineMethodCallIndentation:
+  Enabled: false
+
+Lint/AmbiguousBlockAssociation:
+  AllowedMethods:
+    - change
+Lint/ConstantDefinitionInBlock:
+  Exclude:
+    - spec/spec_helper.rb
+Lint/MissingSuper:
+  Enabled: false
+
+Naming/MethodParameterName:
+  AllowedNames:
+    - by
+    - to
+
+Style/CharacterLiteral:
+  Enabled: false
+Style/Documentation:
+  Enabled: false
+Style/ExplicitBlockArgument:
+  Enabled: false
+Style/FormatStringToken:
+  EnforcedStyle: template
+Style/FrozenStringLiteralComment:
+  Enabled: false
+Style/RescueStandardError:
+  EnforcedStyle: implicit
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+RSpec/AnyInstance:
+  Enabled: false
+RSpec/ContextWording:
+  Prefixes:
+    - when
+    - with
+    - without
+    - if
+    - unless
+    - and
+    - but
+RSpec/DescribedClass:
+  SkipBlocks: true
+RSpec/ExpectChange:
+  EnforcedStyle: block
+RSpec/LetSetup:
+  Enabled: false
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/SharedExamples:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.2.0

data/Gemfile

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "rubocop-rspec"
+gem "steep"

data/Gemfile.lock

@@ -0,0 +1,115 @@
+PATH
+  remote: .
+  specs:
+    zirconia (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (7.0.8)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    base64 (0.1.1)
+    concurrent-ruby (1.2.2)
+    csv (3.2.7)
+    diff-lcs (1.5.0)
+    ffi (1.16.2)
+    fileutils (1.7.1)
+    i18n (1.14.1)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    listen (3.8.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.5.3)
+    minitest (5.20.0)
+    parallel (1.23.0)
+    parser (3.2.2.4)
+      ast (~> 2.4.1)
+      racc
+    racc (1.7.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rbs (3.2.2)
+    regexp_parser (2.8.2)
+    rexml (3.2.6)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.6)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.57.1)
+      base64 (~> 0.1.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.4)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.29.0)
+      parser (>= 3.2.1.0)
+    rubocop-capybara (2.19.0)
+      rubocop (~> 1.41)
+    rubocop-factory_bot (2.24.0)
+      rubocop (~> 1.33)
+    rubocop-rspec (2.24.1)
+      rubocop (~> 1.33)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+    ruby-progressbar (1.13.0)
+    securerandom (0.2.2)
+    steep (1.5.3)
+      activesupport (>= 5.1)
+      concurrent-ruby (>= 1.1.10)
+      csv (>= 3.0.9)
+      fileutils (>= 1.1.0)
+      json (>= 2.1.0)
+      language_server-protocol (>= 3.15, < 4.0)
+      listen (~> 3.0)
+      logger (>= 1.3.0)
+      parser (>= 3.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rbs (>= 3.1.0)
+      securerandom (>= 0.1)
+      strscan (>= 1.0.0)
+      terminal-table (>= 2, < 4)
+    strscan (3.0.6)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.5.0)
+
+PLATFORMS
+  arm64-darwin-21
+  x86_64-linux
+
+DEPENDENCIES
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  rubocop-rspec
+  steep
+  zirconia!
+
+BUNDLED WITH
+   2.4.1

data/LICENSE.txt

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

data/README.md

@@ -0,0 +1,131 @@
+# Zirconia: A Ruby Gem Synthesiser for RSpec
+
+Zirconia is a lightweight testing utility that is capable of generating\ temporary Ruby Gem applications from within the test suite. 
+
+Zirconia offers an intuitive interface around the synthetic gem allowing them to be configured and coded from within the test environment.
+
+Use cases include:
+- Testing frameworks written in Ruby
+- Testing autoloaders
+- Testing gem-gem interaction
+- Testing metaprogramming-heavy modules and classes
+
+Currently, only `RSpec` is supported.
+
+
+## Quick Start
+
+- Add `zirconia` to your Gemfile:
+
+```ruby
+source "https://rubygems.org"
+
+gem "zirconia"
+```
+
+- Require `zirconia/rspec` in your spec_helper:
+```ruby
+require "zirconia/rspec"
+```
+
+- Instantiate a Zirconia Gem in your spec using the `with_gem: gem_name` metadata:
+```rspec
+require 'spec_helper'
+
+RSpec.describe "Some Gem", with_gem: :some_gem do
+  it "instantiates a Zirconia Gem" do
+    expect(gem).to be_a(Zirconia::Application)
+  end
+end
+```
+
+That's it! You can now interact with your newly spun up gem (through `gem`) in `before`/`after` hooks or in the tests themselves.
+
+Note that calling `:with_gem` without a name argument is valid as well. In this case the gem name will be set to the default (`SomeGem`).
+
+
+## Overview
+
+Interaction, configuration and coding of your fake gem is executed through the `gem` variable set by Zirconia when the `with_gem` RSpec metadata is specified.
+
+Gems are created using the `bundle gem` command within your system's temp directory. As gem creation is delegated to `bundler`, your local system `bundler` configuration will be respected. Gems are removed and Gem modules unsourced around each test.
+
+Adding code to the fake gem is achieved by writing files to their respective path before loading the gem into memory. The `gem` object (an instance of `Zirconia::Application`) defines several instance methods that return `Pathname` objects at canonical locations in the gem filetree. Conventionally these are:
+
+```
+|-+temp_dir/            gem.dir
+  |-+ some_gem/         gem.gem_path
+    |-+ lib/            gem.lib_path
+      |-- some_gem.rb   gem.main_file
+      |-+ some_gem/     gem.path
+        |-- foobar.rb   gem.path("foobar")
+```
+
+### Path Methods
+
+These path methods are return a `Pathname` objects. `Pathname` is a Ruby standard library, and offers a simple interface for paths in a filetree. Of importance may be:
+- `write(string)`: Writes `string` to the file at path
+- `read`: Reads the contents of the file at path
+- `exist?`: Returns whether a file 
+- `mkdir`: Make (non recursive) a directory at the current path
+
+The `_path` methods can be called with a variable amount of string path fragments and an optional extension. String fragments will be joined into the path, whilst the extension will be appended to the path
+
+
+### Methods
+
+#### dir
+- The (temporary) directory that contains the gem
+
+#### gem_path
+- Returns `Pathname` objects for paths in the root gem directory
+- In a conventional Ruby gem filetree this is `some_gem/*.ext`
+
+#### lib_path
+- Returns `Pathname` objects for paths in the gem lib directory
+- In a conventional Ruby gem filetree this is `some_gem/lib/*.ext`
+
+#### path
+- Returns `Pathname` objects for paths in the gem named lib directory
+- In a conventional Ruby gem filetree this is `some_gem/lib/some_gem/*.ext`
+
+#### main_file
+- Returns a `Pathname` object
+- This is the entrypoint to the gem application:
+- In a conventional Ruby gem filetree this is `some_gem/lib/some_gem.rb`
+
+#### load!
+- This method requires the fake gem into your current Ruby scope.
+- Note that this process is not idempotent as gems will not be reloaded.
+
+
+## Example
+
+Say we are creating a fancy new testing framework `spectacular`, and we want to test how it behaves when included in target Ruby gem applications. `spectacular` defines an `Initialiser` class that is run when the gem is included into its target gem.
+
+With `zirconia`, we can spin up a target Gem, write some Ruby code to be injected into the Gem entrypoint, and then test how it behaves when run. This could look something like:
+
+```ruby
+RSpec.describe Spectacular::Initialiser, :with_gem do
+  before do
+    gem.main_file.write(<<~RUBY)
+      require "spectacular"
+
+      module SomeGem
+        extend Spectacular::Initialiser
+      end
+    RUBY
+  end
+
+  describe "requiring Spectacular" do
+    subject(:require_spectacular) { gem.load! }
+
+    it "loads the gem" do
+      expect { require_spectacular }
+        .to change { Object.const_defined?(:SomeGem) }
+        .from(false)
+        .to(true)
+    end
+  end
+end
+```

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/Steepfile

@@ -0,0 +1,15 @@
+target :lib do
+  signature "sig"
+
+  check "lib"
+
+  # Too much RSpec interfacing to type.
+  ignore "lib/zirconia/rspec.rb"
+
+  configure_code_diagnostics do |hash|
+    hash[Steep::Diagnostic::Ruby::FallbackAny] = nil
+    hash[Steep::Diagnostic::Ruby::UnknownConstant] = :error
+    hash[Steep::Diagnostic::Ruby::MethodDefinitionMissing] = nil
+    hash[Steep::Diagnostic::Ruby::UnsupportedSyntax] = :hint
+  end
+end

data/lib/zirconia/application.rb

@@ -0,0 +1,57 @@
+module Zirconia
+  class Application
+    attr_reader :dir, :name
+
+    def initialize(dir:, name:)
+      @dir  = Pathname.new(dir).join(name)
+      @name = name
+    end
+
+    def create!
+      `bundle gem #{dir}`
+    end
+
+    def load!
+      require main_file.to_s
+    end
+
+    def gem_path(*, ext: nil)
+      build_path(*, dir:, ext:)
+    end
+
+    def lib_path(*, ext: :rb)
+      build_path(*, dir: lib_dir, ext:)
+    end
+
+    def path(*, ext: :rb)
+      build_path(*, dir: gem_dir, ext:)
+    end
+
+    def main_file
+      @main_file ||= lib_path(name, ext: :rb)
+    end
+
+    def to_sym
+      name.split("_").map(&:capitalize).join.to_sym
+    end
+
+    private
+
+    def lib_dir
+      @lib_dir ||= dir.join("lib")
+    end
+
+    def gem_dir
+      @gem_dir ||= lib_dir.join(name)
+    end
+
+    def build_path(*fragments, dir:, ext:)
+      return dir if fragments.empty?
+
+      file = fragments.pop || raise
+      file = "#{file}.#{ext}" if ext
+
+      dir.join(*fragments, file)
+    end
+  end
+end

data/lib/zirconia/rspec.rb

@@ -0,0 +1,29 @@
+require "tmpdir"
+
+module Zirconia
+  module RSpec
+    require "zirconia/application"
+
+    DEFAULT_NAME = "some_gem".freeze
+
+    ::RSpec.configure do |config|
+      config.around(with_gem: true) do |spec|
+        self.class.class_eval { attr_reader :gem }
+
+        name = ::RSpec.current_example.metadata[:with_gem]
+        name = DEFAULT_NAME if name == true
+        name = name.to_s
+
+        Dir.mktmpdir do |dir|
+          @gem = Zirconia::Application.new(dir:, name:).tap(&:create!)
+
+          spec.run
+
+          if Object.const_defined?(gem.to_sym)
+            Object.send(:remove_const, gem.to_sym)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zirconia/version.rb

@@ -0,0 +1,3 @@
+module Zirconia
+  VERSION = "0.1.0".freeze
+end

data/lib/zirconia.rb

@@ -0,0 +1,7 @@
+require_relative "zirconia/version"
+
+require "tmpdir"
+require "zirconia/application"
+
+module Zirconia
+end

data/sig/dir.rbs

@@ -0,0 +1,3 @@
+class Dir
+  def self.mktmpdir: { (String) -> untyped } -> untyped
+end

data/sig/pathname.rbs

@@ -0,0 +1,17 @@
+class Pathname
+  def initialize: (String path) -> void
+
+  def read: -> String
+
+  def write: (String contents) -> void
+
+  def basename: (?String) -> Pathname
+
+  def dirname: -> Pathname
+
+  def exist?: -> bool
+
+  def join: (*String) -> Pathname
+
+  def to_s: -> String
+end

data/sig/rspec.rbs

@@ -0,0 +1,3 @@
+module RSpec
+  def self.configure: { (untyped) -> untyped } -> void
+end

data/sig/zirconia/application.rbs

@@ -0,0 +1,29 @@
+module Zirconia
+  class Application
+    attr_reader dir: Pathname
+    attr_reader name: String
+
+    def initialize: (dir: String, name: String) -> void
+
+    def create!: -> void
+
+    def load!: -> void
+
+    def gem_path: (*String, ?ext: Symbol?) -> Pathname
+
+    def lib_path: (*String, ?ext: Symbol?) -> Pathname
+
+    def path: (*String, ?ext: Symbol?) -> Pathname
+
+    def to_sym: -> Symbol
+
+    attr_reader main_file: Pathname
+
+    private
+    
+    attr_reader lib_dir: Pathname
+    attr_reader gem_dir: Pathname
+
+    def build_path: (*String, dir: Pathname, ext: Symbol?) -> Pathname
+  end
+end

data/sig/zirconia.rbs

@@ -0,0 +1,3 @@
+module Zirconia
+  VERSION: String
+end

data/zirconia.gemspec

@@ -0,0 +1,33 @@
+require_relative "lib/zirconia/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "zirconia"
+  spec.version = Zirconia::VERSION
+  spec.authors = ["Chris Welham"]
+  spec.email = ["71787007+apexatoll@users.noreply.github.com"]
+
+  spec.summary = "Lightweight testing utility for synthesising Ruby gems"
+
+  spec.description = <<~DESCRIPTION
+    Zirconia is a lightweight testing utility that is capable of generating\
+    temporary Ruby Gem applications from within the test suite.
+
+    Zirconia offers an intuitive interface around the synthetic gem allowing
+    them to be configured and coded from within the test environment.
+  DESCRIPTION
+
+  spec.homepage = "https://github.com/apexatoll/zirconia"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|spec)/|\.(?:git))})
+    end
+  end
+
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: zirconia
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Chris Welham
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-10-16 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Zirconia is a lightweight testing utility that is capable of generatingtemporary Ruby Gem applications from within the test suite.
+
+  Zirconia offers an intuitive interface around the synthetic gem allowing
+  them to be configured and coded from within the test environment.
+email:
+- 71787007+apexatoll@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- Steepfile
+- lib/zirconia.rb
+- lib/zirconia/application.rb
+- lib/zirconia/rspec.rb
+- lib/zirconia/version.rb
+- sig/dir.rbs
+- sig/pathname.rbs
+- sig/rspec.rbs
+- sig/zirconia.rbs
+- sig/zirconia/application.rbs
+- zirconia.gemspec
+homepage: https://github.com/apexatoll/zirconia
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/apexatoll/zirconia
+  source_code_uri: https://github.com/apexatoll/zirconia
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.1
+signing_key:
+specification_version: 4
+summary: Lightweight testing utility for synthesising Ruby gems
+test_files: []