katapult 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddcf0832f9fb8d7597253465296fe0726761e1bd2d3088d741e4bedf51e05cf7
-  data.tar.gz: 293a4ba645e9710e1392707ae59df834e9d14cbd841920e919d02d3d0db02e73
+  metadata.gz: f4099dfe92529880417ce7c3ac5204b70fc115b33a6b60b0027d75c6f7e001e3
+  data.tar.gz: 688a93e927f9240fc0d6e67caceeaae882438c9f5114618f051fda4c5063495f
 SHA512:
-  metadata.gz: 2ead2ca1d7f9bbee69ad9bdac6e5043c513e23deffa6f73119b3b4145206d56f7cf3537067d7116b39d04b0e7c07f795eb839600dedd14f9e22d6bc501e8f33e
-  data.tar.gz: cd2336671a2317373433ff47a3568e35073757c21ff2972d1a8d3004830c764adcc7c422e55b34966255952516760eee329a0468687159adf78c5aa2c46551f3
+  metadata.gz: 5a2a28034878af36af8c5251550c87b257091d4ddadc0e923a7845ea4ace323660040c50de547f7460153fac5df88520bbe10558870a6ec6de9f22153300c5e4
+  data.tar.gz: 405ae1ffbdd3172e78f5e2aced6bf4096e400b5ca30d86aaa6f23b8ed10e0875c6de048d5da11e333f20709644e4fb21c6941a8e68b5e7c83eb1590ff4256f41

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 0.4.0 on 2018-01-15
+
+### Features
+- Support for has_many/belongs_to associations
+- Create a project README
+- New CHANGELOG
+
+### Fixes
+- Models now inherit from `ApplicationRecord`
+
+
+## 0.3.0 on 2018-01-11
+
+### Features
+- Generating a Rails 5.1.4 app on Ruby 2.5.0
+- Dropped asset pipeline in favor of Webpacker
+- The generated application now has a sleek, simple design based on Bootstrap
+- Employing [Unpoly](https://unpoly.com)
+- New DSL command `crud` for creating Model plus WebUI
+- The generated application model is now a transformable example of katapult's features
+
+### Development improvements
+- Add katapult update script
+- Speed up tests (now running in about 9 min)
+- Improve development workflow (see README)
+- No bundler issues in tests any more
+
+See [all changes](https://github.com/makandra/katapult/compare/v0.2.0...v0.3.0).

data/README.md

@@ -99,15 +99,18 @@ has the following syntax, taking a name, options, and a block:
 
 
 ### Model
-Takes a name and a block:
+Takes a name and a block. Generates a Rails model, a migration, and a spec.
 
     model 'Customer' do |customer|
       # customer.attr :name etc, see Attribute element
+      # customer.belongs_to :group, see Association element
     end
 
 
 #### Attribute
-Defined on Model. Takes a name and options:
+Defined on Model; takes a name and options. Adds a database field in the model
+migration, form fields in a WebUI, and configuration code in the model as
+needed.
 
     # Default type :string
     model.attr :name
@@ -136,8 +139,21 @@ Defined on Model. Takes a name and options:
     model.attr :avoid, type: :plain_json # PostgreSQL "json"
 
 
+### Association
+Defined on Model; takes the name of another model just like you called it in the
+model. Adds a foreign key attribute to the model and `belongs_to`/`has_many`
+calls to the respective models.
+
+    model 'Customer' do |customer|
+      customer.belongs_to 'Group'
+    end
+
+    model 'Group'
+
+
 ### WebUI
-Takes a name, options and a block:
+Takes a name, options and a block. Generates controller, routes, views, and a
+passing Cucumber feature.
 
     web_ui 'Customer', model: 'User' do |web_ui|
       web_ui.crud # Create all the standard rails actions
@@ -150,7 +166,8 @@ Takes a name, options and a block:
 
 
 #### Action
-Defined on WebUI. Takes a name and options:
+Defined on WebUI; takes a name and options. Adds an action to the controller,
+and a route as needed.
 
     # Select single Rails actions
     web_ui.action :index
@@ -164,7 +181,7 @@ Defined on WebUI. Takes a name and options:
     web_ui.action :other_action, method: :get, scope: :collection
     
 ### Crud
-This is a shortcut for creating a model together with a WebUI with CRUD actions.
+Shortcut for creating a model together with a WebUI with CRUD actions.
 
     crud 'Customer' do |customer|
       customer.attr :name
@@ -172,8 +189,7 @@ This is a shortcut for creating a model together with a WebUI with CRUD actions.
 
 
 ### Navigation
-No arguments, will generate a main menu with links to the index pages of all
-WebUIs.
+Generates a main menu with links to the index pages of all WebUIs.
 
     navigation
 
@@ -184,8 +200,8 @@ email address. Generates authentication with [Clearance](https://github.com/thou
 
     authenticate 'User', system_email: 'system@example.com'
 
-The email address will be the sender for Clearance mails like password reset
-requests.
+The given email address will be configured as the sender for all mails sent by
+Rails, including Clearance mails like password reset requests.
 
 
 ## Development
@@ -204,6 +220,31 @@ Create a dedicated account on your local PostgreSQL server:
 Whenever you start working on `katapult`, you should run `script/update`, which
 will guide you through a quick update process.
 
+### Architecture
+`katapult` is roughly split into three parts: the `katapult` binary in bin/,
+the model in lib/katapult/ and the generators in lib/generators. Also, there
+is a script/ directory that holds some scripts to ease development. It is not
+part of the `katapult` gem, however.
+
+The generators of `katapult` base on the `rails/generators` you probably know
+from generating migration files or scaffolds; however, it lifts their usage on a
+new level by invoking generators programmatically with a "model object". Instead
+of plain text input, the `katapult` generators can explore the whole application
+model. They are all to be run from within a Rails application.
+
+There are three base generators that can be considered the next-lower level API
+of `katapult`:
+
+- `basics` generator: Enhances a pristine Rails app with all of the basic
+  configuration `katapult` brings.
+- `app_model` generator: Installs a boilerplate application model that serves as
+  a starting point for modeling your own application.
+- `transform` generator: Parses the application model into an internal
+  representation, which will be turned into code by all the other generators.
+
+Note that the `katapult` binary is the only Rails-independent part of Katapult;
+everything else runs in the context of the Rails appplication.
+
 ### Suggested workflow
 When adding a feature to `katapult`, it will usually take you some time to
 figure out how exactly the generated code should look like. You'll be switching
@@ -225,6 +266,13 @@ Here's a the suggested process:
 7) Remove the @no-clobber tag and run the scenario normally to see if it's still
    green. Remember to stop the development server first.
 
+### Guidelines
+Please respect the following guidelines during development:
+
+- The application model should be order-agnostic. There is a #prepare_render
+  method in `ApplicationModel` for things that need to happen between parsing
+  and rendering the application model.
+
 ### Debugging
 Add the `@announce-output` tag to `katapult` features in order to have any output
 logged to your terminal. Note that each step will print all output to date, so

data/bin/katapult

@@ -6,7 +6,7 @@
 usage = 'Usage: katapult new APP_NAME | fire [path/to/model] | version'
 
 require_relative '../lib/katapult/version'
-require_relative '../lib/katapult/binary_util'
+require_relative '../lib/katapult/support/binary_util'
 util = Katapult::BinaryUtil
 
 require 'optparse'
@@ -74,8 +74,12 @@ when 'new'
   util.pink <<-INSTRUCTIONS
 Application initialization done.
 
-Next step: Model your application in lib/katapult/application_model.rb and
-transform it into code by running `katapult fire`.
+Next steps:
+
+- Model your application in lib/katapult/application_model.rb and transform it
+  into code by running `katapult fire`
+- Configure public/robots.txt
+- Write a README
   INSTRUCTIONS
 
 when 'fire'

data/features/application_model.feature

@@ -1,5 +1,5 @@
 #@announce-output
-Feature: The application model prepared by Katapult
+Feature: The default application model prepared by Katapult
 
   Scenario: Generating the application model template
     Given a new Rails application with Katapult basics installed
@@ -19,6 +19,9 @@ Feature: The application model prepared by Katapult
       product.attr :mode, assignable_values: %w[public private]
       product.attr :provider, type: :url
       product.attr :import_data, type: :json
+
+      # Reference other models just like you called them
+      product.belongs_to 'user'
     end
 
     # Define a model

data/features/authenticate.feature

@@ -170,24 +170,7 @@ Feature: Add authentication to an application
         config.middleware.use Clearance::BackDoor
 
       """
-    And the file "config/initializers/clearance.rb" should contain exactly:
-      """
-      Clearance.configure do |config|
-        config.allow_sign_up = false
-        # config.cookie_domain = '.example.com'
-        # config.cookie_expiration = lambda { |cookies| 1.year.from_now.utc }
-        # config.cookie_name = 'remember_token'
-        # config.cookie_path = '/'
-        config.routes = false
-        # config.httponly = true
-        config.mailer_sender = 'system@example.com'
-        # config.password_strategy = Clearance::PasswordStrategies::BCrypt
-        # config.redirect_url = '/'
-        # config.secure_cookie = true
-        # config.sign_in_guards = []
-        # config.user_model = User
-      end
-      """
+    And the file "config/initializers/clearance.rb" should contain "  config.mailer_sender = 'system@example.com'"
     And a file named "config/locales/clearance.en.yml" should exist
     And the file "config/routes.rb" should contain:
       """

data/features/basics.feature

@@ -10,6 +10,7 @@ Feature: Preparation of a new Rails app (basics generator)
     Then the ruby-version file should be up-to-date
 
     And the file ".gitignore" should contain "config/database.yml"
+    And the file "README.md" should contain "# Katapult Test App"
     And the file ".bundle/config" should match /NOKOGIRI.*--use-system-libraries/
     And the file "Guardfile" should contain:
       """

data/features/binary.feature

@@ -44,13 +44,11 @@ Feature: Katapult binary `katapult`
       And the output should contain "Installing katapult"
       And the output should contain "Generating katapult basics"
       And the output should contain the configured Rails version
-      And the output should contain:
-    """
-    Application initialization done.
 
-    Next step: Model your application in lib/katapult/application_model.rb and
-    transform it into code by running `katapult fire`.
-    """
+      And the output should contain "Application initialization done."
+      And the output should contain "Model your application in lib/katapult/application_model.rb"
+      And the output should contain "Configure public/robots.txt"
+      And the output should contain "Write a README"
 
     When I cd to "binary_test"
     Then the file "Gemfile" should contain "gem 'katapult'"
@@ -69,7 +67,7 @@ Feature: Katapult binary `katapult`
       And the output should contain "Author: katapult <katapult@makandra.com>"
 
 
-  Scenario: Transform the application model
+  Scenario: Transform the default application model
     Given a new Rails application with Katapult basics installed
       And the default aruba exit timeout is 45 seconds
 

data/features/model.feature

@@ -1,4 +1,5 @@
 #@announce-output
+#@announce-stderr
 Feature: Generate Models
 
   Background:
@@ -13,11 +14,13 @@ Feature: Generate Models
     And I successfully transform the application model
     Then the file "app/models/car.rb" should contain exactly:
       """
-      class Car < ActiveRecord::Base
+      class Car < ApplicationRecord
+
 
         def to_s
           "Car##{id}"
         end
+
       end
 
       """
@@ -47,6 +50,10 @@ Feature: Generate Models
       end
 
       """
+    And the file "spec/factories/factories.rb" should contain:
+      """
+        factory :car
+      """
 
 
   Scenario: Generate ActiveRecord Model with attributes
@@ -72,13 +79,16 @@ Feature: Generate Models
     And I successfully transform the application model including migrations
     Then the file "app/models/person.rb" should contain exactly:
       """
-      class Person < ActiveRecord::Base
+      class Person < ApplicationRecord
+
         include DoesFlag[:locked, default: false]
+
         has_defaults({:homepage=>"http://www.makandra.de"})
 
         def to_s
           age.to_s
         end
+
       end
 
       """
@@ -148,6 +158,31 @@ Feature: Generate Models
     Then the output should contain "Katapult::Attribute does not support option :invalid_option. (Katapult::Element::UnknownOptionError)"
 
 
+  Scenario: Specify model associations
+    When I write to "lib/katapult/application_model.rb" with:
+      """
+      model('Company') { |c| c.attr :name }
+      model 'User' do |user|
+        user.belongs_to 'Company'
+      end
+      """
+    And I successfully transform the application model including migrations
+    Then the file "app/models/company.rb" should contain "has_many :users"
+    And the file "app/models/user.rb" should contain "belongs_to :company"
+    And the file "app/models/user.rb" should contain:
+      """
+        assignable_values_for :company, {:allow_blank=>true} do
+          Company.all.to_a
+        end
+      """
+
+    And there should be a migration with:
+      """
+          create_table :users do |t|
+            t.integer :company_id
+      """
+
+
   Scenario: Specify assignable values
     When I write to "lib/katapult/application_model.rb" with:
       """
@@ -159,10 +194,13 @@ Feature: Generate Models
     And I successfully transform the application model including migrations
     Then the file "app/models/person.rb" should contain exactly:
       """
-      class Person < ActiveRecord::Base
+      class Person < ApplicationRecord
+
+
         assignable_values_for :age, {} do
           9..99
         end
+
         assignable_values_for :hobby, {:allow_blank=>true, :default=>"soccer"} do
           ["soccer", "baseball"]
         end
@@ -170,6 +208,7 @@ Feature: Generate Models
         def to_s
           age.to_s
         end
+
       end
 
       """

data/features/step_definitions/rails_steps.rb

@@ -1,4 +1,4 @@
-require 'katapult/binary_util'
+require 'katapult/support/binary_util'
 
 module RailsHelper
 

data/features/web_ui.feature

@@ -9,7 +9,7 @@ Feature: Web User Interface
   Scenario: Generate a Web User Interface
     When I write to "lib/katapult/application_model.rb" with:
       """
-      model 'customer' do |customer|
+      crud 'customer' do |customer|
         customer.attr :name
         customer.attr :age, type: :integer
 
@@ -22,11 +22,11 @@ Feature: Web User Interface
         customer.attr :first_visit, type: :datetime
         customer.attr :indexable_data, type: :json
         customer.attr :plain_data, type: :plain_json
-      end
 
-      web_ui 'customer', model: 'customer' do |web_ui|
-        web_ui.crud
+        customer.belongs_to 'project'
       end
+
+      model('project') { |p| p.attr :title }
       """
     And I successfully transform the application model including migrations
     Then the file "app/controllers/customers_controller.rb" should contain exactly:
@@ -107,6 +107,7 @@ Feature: Web User Interface
             :first_visit,
             :indexable_data,
             :plain_data,
+            :project_id,
           )
         end
 
@@ -195,6 +196,10 @@ Feature: Web User Interface
           = Customer.human_attribute_name(:first_visit)
         %dd
           = l(@customer.first_visit.to_date) if @customer.first_visit
+        %dt
+          = Customer.human_attribute_name(:project_id)
+        %dd
+          = @customer.project
 
       """
     And the file "app/views/customers/new.html.haml" should contain exactly:
@@ -250,6 +255,10 @@ Feature: Web User Interface
         .form-group
           = form.label :first_visit
           = form.date_field :first_visit, class: 'form-control'
+        .form-group
+          = form.label :project_id
+          = form.collection_select :project_id, form.object.assignable_projects,
+            :id, :title, { include_blank: true }, class: 'form-control'
 
         .action-bar
           - cancel_path = @customer.new_record? ? customers_path : customer_path(@customer)
@@ -272,6 +281,7 @@ Feature: Web User Interface
 
         Scenario: CRUD customers
           Given I am on the list of customers
+            And there is a project with the title "title-string"
 
           # create
           When I follow "Add customer"
@@ -284,6 +294,7 @@ Feature: Web User Interface
             And I check "Locked"
             And I fill in "Notes" with "notes-text"
             And I fill in "First visit" with "2022-03-25"
+            And I select "title-string" from "Project"
             And I press "Save"
 
           # read
@@ -296,6 +307,7 @@ Feature: Web User Interface
             And I should see "Locked Yes"
             And I should see "notes-text"
             And I should see "2022-03-25"
+            And I should see "title-string"
 
           # update
           When I follow "Edit"
@@ -308,6 +320,7 @@ Feature: Web User Interface
             And the "Locked" checkbox should be checked
             And the "Notes" field should contain "notes-text"
             And the "First visit" field should contain "2022-03-25"
+            And "title-string" should be selected for "Project"
 
           # destroy
           When I go to the list of customers
@@ -318,7 +331,6 @@ Feature: Web User Interface
           But I should not see "name-string"
 
       """
-
     When I run cucumber
     Then the features should pass
 

data/lib/generators/katapult/app_model/templates/lib/katapult/application_model.rb

@@ -13,6 +13,9 @@ crud 'product' do |product|
   product.attr :mode, assignable_values: %w[public private]
   product.attr :provider, type: :url
   product.attr :import_data, type: :json
+
+  # Reference other models just like you called them
+  product.belongs_to 'user'
 end
 
 # Define a model

data/lib/generators/katapult/basics/basics_generator.rb

@@ -1,6 +1,6 @@
 # Generates model-independent application basics (see method names).
 
-require 'katapult/generator_goodies'
+require 'katapult/support/generator_goodies'
 require 'katapult/version' # For writing .ruby-version
 
 module Katapult
@@ -26,16 +26,11 @@ module Katapult
       class_option :db_password, type: :string, default: '',
         description: 'The password to set in config/database.yml'
 
-      def write_ruby_version
+      def add_basic_files
         template '.ruby-version'
-      end
-
-      def add_gitignore
         template '.gitignore', force: true
-      end
-
-      def add_robots_txt
         template 'public/robots.txt', force: true
+        template 'README.md', force: true
       end
 
       # Gems ###################################################################

data/lib/generators/katapult/basics/templates/README.md.tt

@@ -0,0 +1,33 @@
+# <%= app_name(:human) %>
+
+Describe the whole project in a few sentences to a few paragraphs, just as you
+would explain it to your fellow developer. What is it actually, what was it
+built for, who is using it, etc
+
+See <https://makandracards.com/makandra/48339>.
+
+
+## Architecture and models
+
+Give a quick overview of the few core models and how they interact. Do not go
+into detail – class documentation should be written atop the class file. Just
+impart the very basics to grasp the application model, so a new developer knows
+where to dive in.
+
+
+## Development
+
+Describe how to get started with the project. Document employed 3rd party
+services and how to use them, how to start a development server – just about
+anything that a new developer needs to know.
+
+
+## Peculiarity X
+
+Add a section for each special concept in the application, e.g. a CDN and what
+it is used for, that icons are rendered from a custom icon font and how to update
+it, that all posts are created from an importer, that there's a web UI *and* a
+JSON API *and* an embeddable component.
+
+Make the reader aware of a peculiarity, but remember to keep it short. Details
+should be documented in the respective area.

data/lib/generators/katapult/basics/templates/features/support/paths.rb

@@ -15,7 +15,7 @@ module NavigationHelpers
       action_prose, model_prose = $1, $2
       route = "#{action_prose == 'form' ? 'edit_' : ''}#{model_prose_to_route_segment(model_prose)}_path"
       model = model_prose_to_class(model_prose)
-      send(route, model.last)
+      send(route, model.reorder(:id).last!)
 
     when /^the (page|form) for the (.*?) "(.*?)"$/
       action_prose, model_prose, identifier = $1, $2, $3

data/lib/generators/katapult/clearance/clearance_generator.rb

@@ -19,7 +19,7 @@ module Katapult
 
       def install_clearance
         insert_into_file 'Gemfile', <<-GEM, before: "gem 'katapult'"
-gem 'clearance', '< 1.14.0' # Has broken InstallGenerator :(
+gem 'clearance'
 
         GEM
         run 'bundle install --quiet'
@@ -122,8 +122,12 @@ resources :users do
       end
 
       def add_user_factory
-        inject_into_file 'spec/factories/factories.rb', <<-'CONTENT', after: 'FactoryBot.define do'
+        factories_file = 'spec/factories/factories.rb'
 
+        # Remove empty factory, if it exists
+        gsub_file factories_file, "  factory :user\n\n", ''
+
+        inject_into_file factories_file, <<-'CONTENT', before: /end\n\z/
   factory :user do
     sequence(:email) { |i| "user-#{ i }@example.com" }
     password 'password'

data/lib/generators/katapult/clearance/templates/config/initializers/clearance.rb

@@ -12,4 +12,5 @@ Clearance.configure do |config|
   # config.secure_cookie = true
   # config.sign_in_guards = []
   # config.user_model = User
+  config.rotate_csrf_on_sign_in = true
 end

data/lib/generators/katapult/cucumber_features/cucumber_features_generator.rb

@@ -12,12 +12,22 @@ module Katapult
         template 'feature.feature', "features/#{model.name(:variables)}.feature"
       end
 
+      no_tasks do
+        def belongs_tos
+          app_model.get_belongs_tos_for model.name
+        end
+      end
+
       private
 
       def model
         @element
       end
 
+      def app_model
+        model.application_model
+      end
+
     end
   end
 end

data/lib/generators/katapult/cucumber_features/templates/feature.feature

@@ -2,6 +2,9 @@ Feature: <%= model.name(:humans).titleize %>
 
   Scenario: CRUD <%= model.name(:humans) %>
     Given I am on the list of <%= model.name(:variables) %>
+<% belongs_tos.each do |model| -%>
+      And there is a <%= model.name(:human) %> with the <%= model.label_attr.name(:human) %> "<%= model.label_attr.test_value %>"
+<% end -%>
 
     # create
     When I follow "Add <%= model.name(:human) %>"
@@ -25,7 +28,7 @@ Feature: <%= model.name(:humans).titleize %>
     Then I should be on the page for the <%= model.name(:variable) %> above
 <% model.attrs.each do |attr| -%>
   <%- case attr.type -%>
-    <%- when :string, :email, :url, :integer, :money, :text -%>
+    <%- when :string, :email, :url, :integer, :money, :text, :foreign_key -%>
       And I should see "<%= attr.test_value %>"
   <%- when :flag -%>
       And I should see "<%= attr.name.humanize %> Yes"
@@ -52,7 +55,6 @@ Feature: <%= model.name(:humans).titleize %>
   <%- end -%>
 <% end -%>
 
-<% if model.label_attr -%>
     # destroy
     When I go to the list of <%= model.name(:variables) %>
     Then I should see "<%= model.label_attr.test_value %>"
@@ -60,4 +62,3 @@ Feature: <%= model.name(:humans).titleize %>
     When I follow "Destroy <%= model.label_attr.test_value %>"
     Then I should be on the list of <%= model.name(:variables) %>
     But I should not see "<%= model.label_attr.test_value %>"
-<% end -%>

data/lib/generators/katapult/model/model_generator.rb

@@ -30,11 +30,26 @@ module Katapult
         template 'app/models/shared/does_flag.rb' if flag_attrs.any?
       end
 
+      def write_factory
+        insert_into_file 'spec/factories/factories.rb', <<-FACTORY, before: /end\n\z/
+  factory #{ model.name(:symbol) }
+
+        FACTORY
+      end
+
       def generate_unit_tests
         Generators::ModelSpecsGenerator.new(model).invoke_all
       end
 
       no_commands do
+        def belongs_tos
+          model.application_model.get_belongs_tos_for model.name
+        end
+
+        def has_manys
+          model.application_model.get_has_manys_for model.name
+        end
+
         def flag_attrs
           model.attrs.select(&:flag?)
         end