wicked-pipeline 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 315fc6476825e5f4e336eb28b3951fdc6851902919916547c0a3f046da73c353
-  data.tar.gz: 1af17136066174c31e7bed32aa43e477f1b1bbdc1c1e0775a6eb4d256806ac37
+  metadata.gz: c59b79336370d4dff4c11d14e81248c309a7621abffec1b4e07252047db97312
+  data.tar.gz: 11bb3cbed87f59db523471ccaf24669b375b7122e46a2bbe2b7e91c1fd0c306d
 SHA512:
-  metadata.gz: bd19625bc5ee76db912dc057f8f2425c23e423ca9775253701a45884f3a4c734fc013e8dac350cd40df4a000c9c96f3bf3399991f68975cfada8a277a5b23c4f
-  data.tar.gz: b925b48b9a027cc8cc18b346fe92be23e036c85e44252082768248771daad59b2b98a384eeab631c42d90e598ae31fb1884dca9d38b21cc42e895f9b100aa8ae
+  metadata.gz: 5416bd3edb4ecb54735249a6546cce437468c4cc33b925be995236bee843bb4ed054f639e592fdc01acba1f720a4c380a2ce2b16d23aa31d0970c40a65b59a3a
+  data.tar.gz: daa012c32f06118c45c8983ad8a08fe12cc9f44f39e9437b46c43264f3524310d12dbc589512e7e004ae527ba2cec9c58395eac3dbadc2328ea48a10d4425501

data/.standard.yml

@@ -1,6 +1,6 @@
 ruby_version: 2.6
 parallel: true
-format: progress
+format: "progress"
 
 ignore:
   - "spec/rails_app/db/schema.rb"

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 [Unreleased]
 ------------
 
+[0.1.1] - 2022-04-17
+--------------------
+
+- Add pipeline and step generators
+
 [0.1.0] - 2022-04-15
 --------------------
 

data/README.md

@@ -1,30 +1,34 @@
 Wicked::Pipeline
 ================
 
-A step by step pipeline is comprised of multiple "blocks" that will be described here:
+[![RSpec](https://github.com/RobertAudi/wicked-pipeline/actions/workflows/rspec.yml/badge.svg)](https://github.com/RobertAudi/wicked-pipeline/actions/workflows/rspec.yml)
+[![Standard](https://github.com/RobertAudi/wicked-pipeline/actions/workflows/standard.yml/badge.svg)](https://github.com/RobertAudi/wicked-pipeline/actions/workflows/standard.yml)
 
-- Step objects for each step
-- A step pipeline class that encapsulates all the steps in a pipeline
-- A step controller
+A step by step pipeline system built on top of [Wicked](https://github.com/zombocom/wicked).
 
 Table of Contents
 -----------------
 
+- [Table of Contents](#table-of-contents)
 - [Installation](#installation)
-- [Step objects](#step-objects)
-  - [Attributes](#attributes)
-  - [Validations](#validations)
-  - [Blocking](#blocking)
-    * [Blocking reason](#blocking-reason)
-- [Step pipelines](#step-pipelines)
-- [Steps controllers](#steps-controllers)
-  - [Routes](#routes)
-  - [Nested routes](#nested-routes)
-  - [Actions](#actions)
-  - [Flash messages](#flash-messages)
-  - [Views](#views)
-  - [Forms](#forms)
-  - [Breadcrumbs](#breadcrumbs)
+- [Usage](#usage)
+  - [Step objects](#step-objects)
+    - [Attributes](#attributes)
+    - [Validations](#validations)
+    - [Blocking](#blocking)
+    - [Blocking reason](#blocking-reason)
+  - [Step pipelines](#step-pipelines)
+  - [Steps controllers](#steps-controllers)
+    - [Routes](#routes)
+    - [Nested routes](#nested-routes)
+    - [Actions](#actions)
+    - [Flash messages](#flash-messages)
+    - [Views](#views)
+    - [Forms](#forms)
+    - [Breadcrumbs](#breadcrumbs)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 Installation
 ------------
@@ -41,8 +45,26 @@ If bundler is not being used to manage dependencies, install the gem by executin
 $ gem install wicked-pipeline
 ```
 
-Step objects
-------------
+Usage
+-----
+
+You can generate a pipeline using the dedicated generator:
+
+```console
+$ rails generate wicked:pipeline Registration identification profile preferences
+```
+
+This will geneate the `RegistrationPipeline`, `IdentificationStep`, `ProfileStep`, and `PreferencesStep` classes under `app/steps`. It will also generate test files under `spec/steps` if RSpec is installed.
+
+You can also generate individual steps:
+
+```console
+$ rails generate wicked:pipeline:step identification email subscribe_to_newsletter:boolean interests:array
+```
+
+This will generate the `IdentificationStep` with the `email`, `subscribe_to_newsletter` and `interests` attributes. It will also generate a test file under `spec/steps` if RSpec is installed.
+
+### Step objects
 
 A step object is very similar to a form object. It takes a "resource" (the `ActiveRecord` model) and optional params as arguments and will contain attribute definitions, validations for the step, a list of permitted params and a `#save` method. The validations are specific to the step but the resource will also be validated before being saved.
 
@@ -50,10 +72,10 @@ Step objects are subclasses of the `BaseStep` class, and they live in the `app/s
 
 - The name of a step class must end with `Step`
 - Attributes must be defined using the `ActiveModel::Attributes` API (more on that later)
-  * Nested attributes must **not** be defined as attributes in the step object.
+  - Nested attributes must **not** be defined as attributes in the step object.
 - The class must implement the `permitted_params` method which returns an array of attributes.
 - If the `#save` method is overridden, `super` must be called and its value must be used.
-  * The `#save` method **must** return a boolean value.
+  - The `#save` method **must** return a boolean value.
 
 The only method that needs to be implemented is the `permitted_params` private method, everything else is optional. Here is the most basic step object that can exist:
 
@@ -77,7 +99,7 @@ As mentioned before, step objects require a resource:
 Users::ProfileStep.new(User.last)
 ```
 
-### Attributes
+#### Attributes
 
 The attributes of a step object are defined using the `.attribute` method. The first argument is the name of the attribute, and the second argument is the type of the attribute. The type argument is optional but it **must** be specified for boolean attributes.
 
@@ -103,7 +125,7 @@ end
 
 The attributes **must** be in the list of permitted parameters!
 
-### Validations
+#### Validations
 
 Validations are used the same way as in `ActiveRecord` models. One exception is the uniqueness validation which is **not** available in step objects.
 
@@ -133,7 +155,7 @@ end
 
 Custom validation errors must be added to the step object **not** the resource itself, they will be merged into the resource's errors automatically.
 
-### Blocking
+#### Blocking
 
 A blocking step will short-circuit a pipeline. In other words, all step following a blocking step will be inaccessible.
 
@@ -185,8 +207,7 @@ module Users
 end
 ```
 
-Step pipelines
---------------
+### Step pipelines
 
 A step pipeline class is a subclass of the `BasePipeline` class and live in `app/steps`. At the most basic level should contain a list of step classes.
 
@@ -225,8 +246,7 @@ Finally, pipelines are also used to check if all steps are valid for a given res
 UserAccountPipeline.valid?(User.last)
 ```
 
-Steps controllers
------------------
+### Steps controllers
 
 A steps controller is a subclass of `BaseStepsController`, it can have any name and can be placed anywhere under the `app/controllers` directory. Unlike a regular controller, the `:id` parameter references the current step **not** the ID of a resource. For this reason, the name of the resource ID parameter must be specified using the `#resource_param_name` private method.
 
@@ -262,7 +282,7 @@ end
 - The `#find_resource` method must only retrieve the record associated with the resource ID (`#includes` is allowed), **not** a collection of records.
 - The `#find_resource` method must return the record.
 
-### Routes
+#### Routes
 
 The `param` option must be specified when defining resource routes:
 
@@ -272,7 +292,7 @@ resources :users, only: [:show, :update], param: :user_id
 
 **DO NOT** use nested routes with the step routes.
 
-### Nested routes
+#### Nested routes
 
 When the controller has an `index` action, nested routes can be defined in the following way:
 
@@ -294,7 +314,7 @@ scope path: "users/:user_id" do
 end
 ```
 
-### Actions
+#### Actions
 
 A step controller has the `show` and `update` actions. **It cannot have the `new`, `edit` and `create` actions!** The `index` and `destroy` actions can be implemented but they will be independent of the pipeline.
 
@@ -336,7 +356,7 @@ end
   - `@next_step`
   - `@previous_step`
 
-### Flash messages
+#### Flash messages
 
 Flash messages can be set manually **after** calling `super`. Step objects have a `#saved?` method which can be used to verify that it was successfully saved. The method should be used before setting a flash messages:
 
@@ -359,7 +379,7 @@ class UsersController < BaseStepsController
 end
 ```
 
-### Views
+#### Views
 
 There must be a view for each step, **not** a partial, it must have the name of the step and it should live in the root directory of the controller's view directory:
 
@@ -377,7 +397,7 @@ app
 - **DO NOT** create a view for the `show` action.
 - **DO NOT** create views named `new` or `edit`.
 
-### Forms
+#### Forms
 
 The form in step view must be declared in the following way:
 
@@ -400,7 +420,7 @@ The form in step view must be declared in the following way:
 - The resource object must be passed to `form_for`, **not** the step processor
 - The form's method must be either `:put` or `:patch`
 
-### Breadcrumbs
+#### Breadcrumbs
 
 Step controllers provide a extended version of their pipeline's steps metadata with the following added info:
 
@@ -443,6 +463,8 @@ Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/RobertAudi/wicked-pipeline.
 
+The code is linted using [Standard](https://github.com/testdouble/standard). To lint the code run `bundle exec rake standard` or `bundle exec rake standard:fix` to autocorrect offenses.
+
 License
 -------
 

data/lib/generators/rspec/wicked/pipeline/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Generates a spec file for a Pipeline. Pass the pipeline name, either CamelCased
+    or under_scored.
+
+    To create a pipeline within a module, specify the pipeline name as a
+    path like "parent_module/pipeline_name".
+
+Example:
+    `bin/rails generate rspec:wicked:pipeline Registration
+
+    Registration spec.
+        RSpec:     spec/steps/registration_pipeline_spec.rb

data/lib/generators/rspec/wicked/pipeline/pipeline_generator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Rspec
+  module Wicked
+    class PipelineGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_spec_file
+        template "pipeline_spec.rb", File.join("spec/steps", class_path, "#{file_name}_pipeline_spec.rb")
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= remove_possible_suffix(super)
+      end
+
+      def remove_possible_suffix(name)
+        name.sub(/_?pipeline\z/i, "")
+      end
+    end
+  end
+end

data/lib/generators/rspec/wicked/pipeline/step/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Generates a spec file for a Step. Pass the step name, either CamelCased
+    or under_scored.
+
+    To create a step within a module, specify the step name as a
+    path like "parent_module/step_name".
+
+Example:
+    `bin/rails generate rspec:wicked:pipeline:step UserIdendification
+
+    UserIdentificationStep spec.
+        RSpec:     spec/steps/user_identification_step_spec.rb

data/lib/generators/rspec/wicked/pipeline/step/step_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Rspec
+  module Wicked
+    module Pipeline
+      class StepGenerator < Rails::Generators::NamedBase
+        source_root File.expand_path("templates", __dir__)
+
+        def create_spec_file
+          template "step_spec.rb", File.join("spec/steps", class_path, "#{file_name}_step_spec.rb")
+        end
+
+        private
+
+        def file_name
+          @_file_name ||= remove_possible_suffix(super)
+        end
+
+        def remove_possible_suffix(name)
+          name.sub(/_?step\z/i, "")
+        end
+      end
+    end
+  end
+end

data/lib/generators/rspec/wicked/pipeline/step/templates/step_spec.rb.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Step do
+  subject { described_clas.new(spy) }
+
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/generators/rspec/wicked/pipeline/templates/pipeline_spec.rb.tt

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Pipeline do
+  pending "add some examples to (or delete) #{__FILE__}"
+end

data/lib/generators/wicked/pipeline/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Generates a new pipeline. Pass the pipeline name, either CamelCased or
+    under_scored, and an optional list of steps.
+
+    To create a pipeline within a module, specify the pipeline name as a
+    path like "parent_module/pipeline_name".
+
+Example:
+    `bin/rails generate wicked:pipeline Registration identification profile preferences
+
+    RegistrationPipeline.
+        Pipeline:     app/steps/registration_pipeline.rb
+        Step:         app/steps/identification_step.rb
+        Step:         app/steps/profile_step.rb
+        Step:         app/steps/preferences_step.rb

data/lib/generators/wicked/pipeline/pipeline_generator.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Wicked
+  class PipelineGenerator < Rails::Generators::NamedBase
+    check_class_collision suffix: "Pipeline"
+
+    source_root File.expand_path("templates", __dir__)
+
+    argument :steps, type: :array, default: [], banner: "step_name step_name"
+
+    def create_pipeline_file
+      template "pipeline.rb", File.join("app/steps", class_path, "#{file_name}_pipeline.rb")
+    end
+
+    hook_for :test_framework, as: "wicked:pipeline"
+
+    def create_step_files
+      step_classes.each do |step_class|
+        Rails::Generators.invoke "wicked:pipeline:step", [step_class, *options_as_switches], behavior: behavior
+      end
+    end
+
+    private
+
+    def file_name
+      @_file_name ||= remove_possible_suffix(super)
+    end
+
+    def remove_possible_suffix(name)
+      name.sub(/_?pipeline\z/i, "")
+    end
+
+    def step_classes
+      @step_classes ||= steps.map do |step_name|
+        if step_name.match?(/\/|::/)
+          String.new(step_name.sub(/_?step\z/i, "").camelize) << "Step"
+        else
+          String.new((class_path + [step_name.sub(/_?step\z/i, "")]).map!(&:camelize).join("::")) << "Step"
+        end
+      end
+    end
+
+    def options_as_switches
+      @options_as_switches ||= options.compact_blank.each_with_object([]) do |(option, value), obj|
+        next unless value
+
+        obj << "--#{option.to_s.dasherize}"
+        obj << value.presence unless value == true
+      end
+    end
+  end
+end

data/lib/generators/wicked/pipeline/step/USAGE

@@ -0,0 +1,15 @@
+Description:
+    Generates a new step. Pass the step name, either CamelCased or
+    under_scored, and an optional list of attribute pairs as arguments.
+
+    Attribute pairs are name:type arguments specifying the
+    step's attributes.
+
+    To create a step within a module, specify the step name as a
+    path like "parent_module/step_name".
+
+Example:
+    `bin/rails generate wicked:pipeline:step UserIdendification name is_active:boolean hobbies:array`
+
+    UserIdentificationStep.
+        Step:     app/steps/user_identification_step.rb

data/lib/generators/wicked/pipeline/step/step_generator.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Wicked
+  module Pipeline
+    class StepGenerator < Rails::Generators::NamedBase
+      check_class_collision suffix: "Step"
+
+      source_root File.expand_path("templates", __dir__)
+
+      argument :attributes, type: :array, default: [], banner: "attribute[:type] attribute[:type]"
+
+      def create_step_file
+        template "step.rb", File.join("app/steps", class_path, "#{file_name}_step.rb")
+      end
+
+      hook_for :test_framework, as: "wicked:pipeline:step"
+
+      private
+
+      def file_name
+        @_file_name ||= remove_possible_suffix(super)
+      end
+
+      def remove_possible_suffix(name)
+        name.sub(/_?step\z/i, "")
+      end
+
+      def array_attributes
+        @array_attributes ||= attributes.select { |attribute| attribute.type == :array }
+      end
+
+      def boolean_attributes
+        @boolean_attributes ||= attributes.select { |attribute| attribute.type == :boolean }
+      end
+    end
+  end
+end

data/lib/generators/wicked/pipeline/step/templates/step.rb.tt

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name %>Step < Wicked::Pipeline::BaseStep
+  # -------------------------------------------- #
+  #                  Attributes                  #
+  # -------------------------------------------- #
+
+<% if attributes.present? -%>
+<% attributes.each do |attribute| -%>
+<% if attribute.type == :array -%>
+  attribute :<%= attribute.name %>, array: true
+<% elsif attribute.type != :string -%>
+  attribute :<%= attribute.name %>, :<%= attribute.type %>
+<% else -%>
+  attribute :<%= attribute.name %>
+<% end -%>
+<% end -%>
+<% else -%>
+  # ...
+<% end -%>
+
+  # -------------------------------------------- #
+  #                  Validations                 #
+  # -------------------------------------------- #
+
+<% if boolean_attributes.present? -%>
+<% boolean_attributes.each do |attribute| -%>
+  validates :<%= attribute.name %>, inclusion: {in: [true, false]}
+<% end -%>
+
+  # ...
+<% else -%>
+  # ...
+<% end -%>
+
+  # -------------------------------------------- #
+
+<% array_attributes.each do |attribute| -%>
+  def <%= attribute.name %>=(value)
+    super(Array(value).compact_blank)
+  end
+
+<% end -%>
+  # def blocking?
+  #   false
+  # end
+
+  private
+
+  def permitted_params
+<% if attributes.present? -%>
+    [
+<% attributes.each_with_index do |attribute, index| -%>
+<% next if attribute.type == :array -%>
+      :<%= attribute.name %><%= "," if index < attributes.size - 1 %>
+<% end -%>
+<% array_attributes.each_with_index do |attribute, index| -%>
+      <%= attribute.name %>: []<%= "," if index < array_attributes.size - 1 %>
+<% end -%>
+    ]
+<% else -%>
+    []
+<% end -%>
+  end
+
+  # def regenerate_blocking_reasons!
+  #   super
+  # end
+
+  # def stale_attributes
+  #   stale_attributes = []
+  #
+  #   # ...
+  #
+  #   stale_attributes
+  # end
+end
+<% end -%>

data/lib/generators/wicked/pipeline/templates/pipeline.rb.tt

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+<% module_namespacing do -%>
+class <%= class_name %>Pipeline < Wicked::Pipeline::BasePipeline
+  def steps
+<% if step_classes.present? -%>
+    [
+<% step_classes.each_with_index do |step_class, index| -%>
+      <%= step_class %><%= "," if index < step_classes.size - 1 %>
+<% end -%>
+    ]
+<% else -%>
+    []
+<% end -%>
+  end
+end
+<% end -%>

data/lib/wicked/pipeline/version.rb

@@ -2,6 +2,6 @@
 
 module Wicked
   module Pipeline
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/wicked-pipeline.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |spec|
   spec.authors = ["Robert Audi"]
   spec.email = ["robert@robertaudi.com"]
 
-  spec.summary = "Multi-step forms with step objects using Wicked"
+  spec.summary = "A step by step pipeline system built on top of Wicked"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 2.6.0"
 
@@ -23,7 +23,6 @@ Gem::Specification.new do |spec|
     end
   end
 
-  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_dependency "railties", ">= 6.1", "< 7"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wicked-pipeline
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Robert Audi
@@ -120,13 +120,24 @@ files:
 - README.md
 - Rakefile
 - app/controllers/wicked/pipeline/base_steps_controller.rb
+- lib/generators/rspec/wicked/pipeline/USAGE
+- lib/generators/rspec/wicked/pipeline/pipeline_generator.rb
+- lib/generators/rspec/wicked/pipeline/step/USAGE
+- lib/generators/rspec/wicked/pipeline/step/step_generator.rb
+- lib/generators/rspec/wicked/pipeline/step/templates/step_spec.rb.tt
+- lib/generators/rspec/wicked/pipeline/templates/pipeline_spec.rb.tt
+- lib/generators/wicked/pipeline/USAGE
+- lib/generators/wicked/pipeline/pipeline_generator.rb
+- lib/generators/wicked/pipeline/step/USAGE
+- lib/generators/wicked/pipeline/step/step_generator.rb
+- lib/generators/wicked/pipeline/step/templates/step.rb.tt
+- lib/generators/wicked/pipeline/templates/pipeline.rb.tt
 - lib/wicked/pipeline.rb
 - lib/wicked/pipeline/base_pipeline.rb
 - lib/wicked/pipeline/base_step.rb
 - lib/wicked/pipeline/engine.rb
 - lib/wicked/pipeline/readonly_step.rb
 - lib/wicked/pipeline/version.rb
-- sig/wicked/pipeline.rbs
 - wicked-pipeline.gemspec
 homepage: https://github.com/RobertAudi/wicked-pipeline
 licenses:
@@ -153,5 +164,5 @@ requirements: []
 rubygems_version: 3.3.11
 signing_key:
 specification_version: 4
-summary: Multi-step forms with step objects using Wicked
+summary: A step by step pipeline system built on top of Wicked
 test_files: []

data/sig/wicked/pipeline.rbs

@@ -1,5 +0,0 @@
-module Wicked
-  module Pipeline
-    VERSION: String
-  end
-end