plover 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c02ad2ecd60c71f6183a2db31ba64dd0f15769cbf7774273913595dfb72ccd93
+  data.tar.gz: c6fb12369964a4aa2238ffde51d4675e5b716eae056e12311193bb3570ec204e
+SHA512:
+  metadata.gz: 15a087dd706ac377d6535956b9f62bb3a94e7811ce15c09e2a1b81ee3e79a2c25b26d495eedf5dd1a561e54b495d6c3867d9342a0d28ebbefc48fed7800c48b8
+  data.tar.gz: 7c8eee52f8818b246f1a57dd01947cb1ee398f12e92d0811559e0c3425ca93e5abfba0ecc2597c0dd091f74a48cf34feb7f159d43257f263c0b1eaab27c3d30b

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Charlton Trezevant
+
+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,201 @@
+# Plover
+
+Plover is a tiny, embeddable Ruby build system designed to provide "Just Enough to Be Comfortable".
+
+Plover is not a Make/Rake clone. It's intended to make it easier to write clean, organized build scripts in plain Ruby.
+
+To help you with that, Plover provides a lightweight DSL for defining build phases, managing configuration flags, and tracking build artifacts, making it easier to manage configuration, state, and shared logic across your build and release processes.
+
+## Features
+
+#### Tiny & Embeddable 
+
+Plover consists of ~200 lines of plain Ruby, with no dependencies outside of the standard library.
+
+Because Plover is built to be embeddable, you can copy/paste `lib/plover.rb` into your project if you'd rather not use the gem. 
+
+#### Phased Build Process
+
+Define your build steps in distinct phases (setup, before_build, build, after_build, teardown) using a clean DSL that doesn't get in your way.
+
+#### Flags
+
+Easily configure your builds using flags passed via environment variables or directly as parameters.
+
+Plover will automatically pick up environment variables prefixed with `PLOVER_FLAG_` and merge them with your build configuration.
+
+#### Artifacts
+
+Track outputs from each build phase and retrieve them for further processing or validation.
+
+#### Extensible
+
+Plover provides a Concern system similar to ActiveSupport::Concern to help you organize and reuse common build functionality.
+
+
+## Installation
+
+You can install Plover as a gem:
+
+```
+gem install plover
+```
+
+Or, add it to your project’s Gemfile:
+
+```
+gem "plover"
+```
+
+Because Plover is built to be embeddable, you can also just copy/paste `lib/plover.rb` into your project if you'd rather not use RubyGems (it's ~200 lines of plain Ruby, with no dependencies outside of the standard library).
+
+## Usage
+
+Plover uses Plover to publish itself, so a real-world example can be found [in this repository](https://github.com/chtzvt/plover/blob/master/.github/workflows/publish.rb).
+
+
+### Basic Example 
+
+```ruby
+require "plover" # or require_relative "path/to/your/plover.rb"
+
+class MyBuilder < Plover::Builder
+  # Require a flag named :my_flag
+  expect_flags(:my_flag)
+
+  # Setup phase: print a message
+  phase(:setup) do
+    puts "Setting up the build..."
+  end
+
+  # Build phase: simulate a build operation
+  phase(:build) do
+    puts "Building the project..."
+    do_a_thing if flag(:my_flag)
+  end
+
+  # Teardown phase: print a cleanup message
+  phase(:teardown) do
+    puts "Cleaning up..."
+  end
+
+  def do_a_thing
+    puts "I did a thing! #{flag(:my_flag)}"
+  end 
+end
+
+# Create an instance with the required flag and run the build phases.
+MyBuilder.new(my_flag: "cool").run
+```
+
+### Shared Concerns
+
+```ruby
+require "plover"
+
+# Define a concern under the Plover::Builder::Common namespace.
+module Plover::Builder::Common::Greeting
+  extend Plover::Concern
+
+  # When this module is included, the `included` block is stored and later evaluated
+  # in the context of the including Builder.
+  included do
+    # Define an instance method.
+    def greet_builder
+      puts "(Concern) Hey there #{flag(:name)}!"
+    end
+
+    # Add a phase step in the setup phase.
+    phase(:setup) do
+      puts "A Builder and a Concern enter:"
+    end
+
+    # Prepend a step to the build phase that calls the class method from the concern.
+    prepend_phase(:build) do
+      self.class.greet_class
+    end
+
+    # Prepend a step to the after_build phase.
+    prepend_phase(:after_build) do
+      greet_builder
+      puts "(Concern) See you later."
+    end
+
+    # Add a step to the teardown phase.
+    phase(:teardown) do
+      puts "fin."
+    end
+  end
+
+  # Define class methods that will be extended onto the including class.
+  class_methods do
+    def greet_class
+      puts "(Concern) Hello! I'm a Concern. We can prepend or append steps to phases, define class or instance methods, and access state."
+    end
+  end
+end
+
+# Define a builder subclass that uses the Greeting concern.
+class MyBuilder < Plover::Builder
+  # Include the concern by specifying its name.
+  common_include "Greeting"
+
+  # Optionally, you could include multiple concerns:
+  #   common_include "Greeting", "SomethingElse"
+  # or include all common modules:
+  #   common_include_all
+
+  # Register a build phase step that calls a builder method.
+  phase(:build) do
+    builder_greeting
+  end
+
+  # Register an after_build phase step.
+  phase(:after_build) do
+    builder_goodbye
+  end
+
+  def builder_greeting
+    # Set a flag that can be used by the concern.
+    set_flag(:name, self.class.name)
+    puts "(Builder) Hi! I'm a Builder named #{flag(:name)}."
+  end
+
+  def builder_goodbye
+    puts "(Builder) Goodbye!"
+  end
+end
+
+# Instantiate and run the builder.
+MyBuilder.new.run
+```
+
+
+## Running Your Build
+
+Plover is typically invoked by running your build script (e.g. ruby path/to/your/Ploverfile.rb). You can pass configuration flags via environment variables:
+
+```
+PLOVER_FLAG_GEM_VERSION="v0.1.0" \
+PLOVER_FLAG_RUBYGEMS_RELEASE_TOKEN="YOUR_TOKEN" \
+PLOVER_FLAG_GITHUB_RELEASE_TOKEN="YOUR_TOKEN" \
+ruby path/to/your/Ploverfile.rb
+```
+
+Environment variables will automatically be configured as Builder flags with a common convention (`PLOVER_FLAG_MY_OPTION` becomes `flag(:my_option)`).
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+Feel free to check issues page.
+
+1.	Fork the repository.
+2.	Create a new branch (`git switch -c feature/my-feature`).
+3.	Make your changes.
+4.	Submit a pull request.
+
+
+## License
+
+This project is licensed under the MIT License. See LICENSE for details.
+

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "rspec/core/rake_task"
+
+require "standard/rake"
+
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.ruby_opts = %w[-w]
+end
+
+task test: %i[spec standard]
+task default: %i[test]

data/lib/plover.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Plover
+  require "shellwords"
+  require "fileutils"
+
+  VERSION = "1.0.0"
+
+  class PloverError < StandardError; end
+
+  module Concern
+    def self.extended(base)
+      base.instance_variable_set(:@_included_blocks, [])
+    end
+
+    def included(base = nil, &block)
+      return unless base.nil?
+
+      @_included_blocks << block if block_given?
+    end
+
+    def class_methods(&block)
+      const_set(:ClassMethods, Module.new(&block))
+    end
+
+    def apply_concern(base)
+      base.extend(const_get(:ClassMethods)) if const_defined?(:ClassMethods)
+      @_included_blocks.each { |blk| base.class_eval(&blk) }
+      base.include(self)
+    end
+  end
+
+  class Builder
+    class FlagError < PloverError; end
+
+    class BuildError < PloverError; end
+
+    class ArtifactError < BuildError; end
+
+    module Common; end
+
+    attr_reader :configuration
+
+    @configuration = {
+      steps: {
+        setup: [],
+        before_build: [],
+        build: [],
+        after_build: [],
+        teardown: []
+      },
+      options: {
+        flags: {},
+        expected_flags: []
+      },
+      include_common: :none,
+      artifacts: {
+        setup: {},
+        before_build: {},
+        build: {},
+        after_build: {},
+        teardown: {}
+      }
+    }
+
+    class << self
+      attr_reader :configuration
+
+      def inherited(subclass)
+        auto_include_common
+        subclass.instance_variable_set(:@configuration, deep_copy(configuration))
+      end
+
+      def set_flag(name, value)
+        configuration[:options][:flags][name.to_sym] = value
+      end
+
+      def expect_flags(*flags)
+        configuration[:options][:expected_flags] = flags.map(&:to_sym)
+      end
+
+      def common_include_all
+        configuration[:options][:common_include] = :all
+      end
+
+      def common_include_none
+        configuration[:options][:common_include] = :none
+      end
+
+      def common_include(*modules)
+        configuration[:options][:common_include] = [] unless configuration[:options][:common_include].is_a?(Array)
+
+        configuration[:options][:common_include].concat(modules)
+      end
+
+      def env_flags
+        ENV.select { |key, _| key.start_with?("PLOVER_FLAG_") }
+          .map { |key, value| [key.sub(/^PLOVER_FLAG_/, "").downcase.to_sym, value] }
+          .to_h
+      end
+
+      def phase(phase, &block)
+        configuration[:steps][phase] << block
+      end
+
+      def prepend_phase(phase, &block)
+        configuration[:steps][phase].unshift(block)
+      end
+
+      def auto_include_common
+        return if configuration[:options][:common_include] == :none
+
+        ObjectSpace.each_object(Module).select { |m| m&.name&.start_with?("Plover::Builder::Common::") }.each do |mod|
+          next if mod.name.to_s.end_with?("::ClassMethods")
+
+          next if configuration[:options][:common_include].is_a?(Array) && !configuration[:options][:common_include].any? { |m| m.end_with?("::#{mod.name}") }
+
+          mod.apply_concern(self) if mod.respond_to?(:apply_concern) && !included_modules.include?(mod)
+        end
+      end
+
+      def deep_copy(obj)
+        case obj
+        when Hash
+          obj.each_with_object({}) { |(k, v), h| h[k] = deep_copy(v) }
+        when Array
+          obj.map { |e| deep_copy(e) }
+        else
+          obj
+        end
+      end
+    end
+
+    def initialize(flags = {})
+      self.class.auto_include_common
+      @configuration = self.class.configuration
+      @configuration[:options][:flags] = @configuration[:options][:flags].merge(flags).merge(self.class.env_flags)
+
+      return unless @configuration[:options][:expected_flags].any?
+
+      missing_flags = @configuration[:options][:expected_flags].reject { |sym| @configuration[:options][:flags].key?(sym) }
+      raise BuildError.new("Missing required flags: #{missing_flags.join(", ")}") if missing_flags.any?
+    end
+
+    def prepend_phase(phase, &block)
+      @configuration[:steps][phase].unshift(block)
+    end
+
+    def append_phase(phase, &block)
+      @configuration[:steps][phase] << block
+    end
+
+    def esc(str)
+      Shellwords.escape(str)
+    end
+
+    def flag(name)
+      @configuration[:options][:flags][name.to_sym]
+    end
+
+    def esc_flag(name)
+      flag(name) ? esc(flag(name)) : nil
+    end
+
+    def set_flag(name, value)
+      @configuration[:options][:flags][name.to_sym] = value
+    end
+
+    def raise_unless_flag(name, message)
+      raise FlagError.new(message) unless flag(name)
+    end
+
+    def push_artifact(name, value)
+      return unless @current_phase
+      @configuration[:artifacts][@current_phase][name] = value
+    end
+
+    def esc_artifact(phase, name)
+      artifact = self.artifact(phase, name)
+      artifact ? esc(artifact) : nil
+    end
+
+    def artifact(phase, name)
+      @configuration[:artifacts][phase][name]
+    end
+
+    def artifacts(phase = nil)
+      phase ? @configuration[:artifacts][phase] : @configuration[:artifacts]
+    end
+
+    def raise_unless_artifact(phase, name, message)
+      raise ArtifactError.new(message) unless artifact(phase, name)
+    end
+
+    def fail_build(message)
+      raise BuildError.new(message)
+    end
+
+    def run_phase(phase)
+      @current_phase = phase
+      @configuration[:steps][phase].each { |block| instance_exec(&block) }
+      @current_phase = nil
+    end
+
+    def run
+      run_phase(:setup)
+      Dir.chdir(flag(:build_root) || ".") do
+        run_phase(:before_build)
+        run_phase(:build)
+        run_phase(:after_build)
+      end
+      run_phase(:teardown)
+    end
+  end
+end

data/sig/plover.rbs

@@ -0,0 +1,4 @@
+module Plover
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: plover
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Charlton Trezevant
+bindir: exe
+cert_chain: []
+date: 2025-03-17 00:00:00.000000000 Z
+dependencies: []
+description: Plover is a tiny, embeddable Ruby build system.
+email:
+- ct@ctis.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/plover.rb
+- sig/plover.rbs
+homepage: https://github.com/chtzvt/plover
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/chtzvt/plover
+  source_code_uri: https://github.com/chtzvt/plover
+  changelog_uri: https://github.com/chtzvt/plover/releases
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Plover is a tiny, embeddable Ruby build system.
+test_files: []