picatrix 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c1526c5c727bb983c60d9c3240984054c96187de
-  data.tar.gz: 6af84973981466c805aa680fad9ca915353418f8
+  metadata.gz: 28283e340d828d5a22f3152ccd81c502b863eccf
+  data.tar.gz: d5c7a1a4234333f7002f3a6016c325a1fcd6f636
 SHA512:
-  metadata.gz: b3feed7709d09d6b5bd06d3d88cc09de6a054bee63d24dd9cf62c01f80f356fbb0cdb20f6530c9b950f8c2fc8320273020ebeaae6892fbfc2ad7e51362c021d6
-  data.tar.gz: 7f399c285ac1dde603ca580a3fdc2fe2fca415bc17dd24ef3a75f4ea2cfe5cd5b31c56175edc1840817349fc41c51e4ebce3ddbd16559ba09d340a3360ee7b94
+  metadata.gz: c71a9ae39ddf75673c92affe67f2a93e5e61e81aef091596de7a037109ee301cf731439c67b4659cc8393d6de8b61f6910ddde9ba3639f11fbdfe4c36849e9c4
+  data.tar.gz: 4f113d91d4e052728a87cdc347a902c732b2e3df02a33b150d2524fcb183b6a5caa1d6bd2e8d75afd97625a7a45d4594239389fa99822c8e80872195cf686b1d

data/Gemfile.lock

@@ -1,11 +1,13 @@
 PATH
   remote: .
   specs:
-    picatrix (0.1.0)
+    picatrix (0.2.0)
       activesupport
+      faker
       grape
       grape-roar
       parslet
+      protobuf
       require_all
       roar
       ruby-graphviz
@@ -16,7 +18,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.2.4)
+    activesupport (4.2.5)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
@@ -36,6 +38,8 @@ GEM
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.2.5)
     equalizer (0.0.11)
+    faker (1.5.0)
+      i18n (~> 0.5)
     grape (0.13.0)
       activesupport
       builder
@@ -54,11 +58,17 @@ GEM
     ice_nine (0.11.1)
     json (1.8.3)
     method_source (0.8.2)
+    middleware (0.1.0)
     minitest (5.8.2)
     multi_json (1.11.2)
     multi_xml (0.5.5)
     parslet (1.7.1)
       blankslate (>= 2.0, <= 4.0)
+    protobuf (3.5.5)
+      activesupport (>= 3.2)
+      middleware
+      thor
+      thread_safe
     pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)

data/README.md

@@ -5,27 +5,23 @@
        '. (___.'_/
         ((-((-''mrf
 
-# Picatrix
+# picatrix
 
-An opinionated hypermedia API generator.
+An opinionated hypermedia API generator. :grin:
 
-Requires:
-- valid `.dot` file with the following additional style guidelines
-  - edge style defaults to `arrowhead="odiamond"` to signify default requests are `GET`
-  - the first node listed should be the root, and is signified by `xlabel=` and `shape=point`
-  - collection nodes should be given `shape=folder` and pluralized
-  - the item node belonging to the collection node should be its singularized version and `shape=rectangle`
-  - forms (often called templates in the code, because they are a template for a valid request to the server) are given a `_template` suffix and `shape=note`
-  - `style=dotted` means the related object will be represented inline (embedded)
-  - `style=bold` and `arrowhead=normal` means `POST`
-  - `arrowhead=normal` alone means `PATCH`
-  - `color=red fontcolor=red` means `DELETE`
+## Requires:
+
+- valid `.dot` file with [additional style guidelines](#dot-file-styles)
+- Protobuf [definitions of inputs/outputs](#protobuf-definitions-of-representations) for all state transitions, by node
 
-Outputs:
-- Sinatra style routes
-- `application/vnd.mason+json` assets
-  - serializers
-  - templates (think forms, not views)
+
+## Outputs:
+
+- basic Sinatra app and mock objects fitting your schema
+  - protobuf generated representation objects (you dont edit these)
+  - fixture interface to map to your persistance layer, is generated with fake data generators (you do edit these)
+- `application/vnd.mason+json`
+  - controls
 - state diagram image ([see below](https://github.com/mooreniemi/picatrix#sample-image-output))
 
 ## About
@@ -36,6 +32,12 @@ The ideal way to use Picatrix is to do an exercise in designing your API "outsid
 
 ## Installation
 
+Install system dependencies (Mac OS sample):
+
+```bash
+$ brew install graphviz
+$ brew install protobuf
+```
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -50,6 +52,25 @@ Or install it yourself as:
 
     $ gem install picatrix
 
+## getting ready
+
+### .dot file styles
+
+  - edge style defaults to `arrowhead=odiamond` to signify default requests are `GET`
+  - the first node listed should be the root, and is signified by `xlabel=` and `shape=point`, you should never need to change this (unless you are knitting together workflows - future thing)
+  - collection nodes should be given `shape=folder` and pluralized
+  - the item node belonging to the collection node should be its singularized version and `shape=rectangle`
+  - `style=bold` and `arrowhead=normal` means `POST`
+  - `arrowhead=normal` alone means `PATCH`
+  - `color=red fontcolor=red` means `DELETE`
+
+### protobuf definitions of representations
+
+  - must match the node names (each node signifies a representation)
+  - consider
+    - from the perspective of the client at any request, what does it need to make the request and have the server fufill its contract?
+    - from the perspective of the server, what might the client want in response for it to make any interesting subsequent requests from this node in the workflow?
+    - inputs will map onto controls, and outputs will map on to representations (dereferenced content)
 ## Usage
 
 In its final state, the intent is to use it as a CLI:
@@ -70,8 +91,6 @@ $ bin/picapica dg_api.dot app_name
 
 Nodes and edges translate roughly into application and/or resource states, and state transitions.
 
-Dotted lines represent inlined relations. So, `View submissions` inlines `View submission` by `:item_id` (in this example a number).
-
 Labels on edges are link relations. Confusingly the actual _URL_ of the state transition (moving to the next state) is still the target node (essentially, think of the state transition name as the same as the name of the ideal output) _and_ its link relation to its source. So, `A (make_B_do_x)-> B` is `B/make_B_do_x`. This is still (obviously) sketchy.
 
 ## Development
@@ -81,16 +100,13 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ### TODO
-- generate sinatra routes from app & resource edges
-  - initially make mason stubs myself
-  - usage will be to iteratively make the necessary templates until routes are filled out
-- with all mason stubs established, make generators for them from
-  - RAML?
-  - json
-  - yml?
-
-#### done
-- parse dot file in Ruby
+
+process goes: .dot file + `prep` (1)-> proto file from nodes + user input into .proto + `proto` (2)-> ruby representation classes + user input to fixturize (3)-> `g` (4)-> `rackup lib/picatrix/generated/app.rb`
+
+1. outside in design process produced a diagram, which is written into a .dot file
+2. all nodes are representations of resources, and thus get proto objects generated for them, here is where the inputs/outputs are formed into a schema
+3. representation nodes now have ruby classes that reflect the information that will be sent back and forth in messages so we generate the app
+4. boot up the app
 
 ## Contributing
 

data/Rakefile

@@ -1,5 +1,6 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+load 'protobuf/tasks/compile.rake'
 
 RSpec::Core::RakeTask.new(:spec)
 

data/bin/console

@@ -3,5 +3,11 @@
 require "bundler/setup"
 require "picatrix"
 
+# generate ruby classes
+`protoc -I ./definitions --ruby_out ./lib/picatrix/generated definitions/*.proto`
+
+require './lib/picatrix/generated/mason.pb.rb'
+require './lib/picatrix/generated/app.pb.rb'
+
 require "pry"
-pry.start
+Pry.start

data/definitions/app.proto

@@ -0,0 +1,47 @@
+import "mason.proto";
+
+// objects
+message ViewSubmission {
+  optional int32 id = 1;
+  optional string category = 2;
+  optional string photo = 3;
+
+  // items probably want a minimal representation
+  // of available controls when in collection view
+  message Controls {
+    optional mason.Self self = 2;
+  }
+
+  message Attachment {
+    optional int32 id = 1;
+  }
+
+  optional Controls controls = 4;
+  repeated Attachment attachments = 5;
+}
+
+message ViewSubmissions {
+  repeated ViewSubmission collection = 1;
+}
+
+// controls
+message EditViewSubmission {
+  // someday gen this from schema?
+  optional mason.Edit form = 3;
+  message Template {
+    optional string category = 1;
+    optional string has_photo = 2;
+  }
+  optional Template template = 4;
+}
+
+message CreateViewSubmission {
+  // someday gen this from schema?
+  optional mason.Create form = 3;
+  message Template {
+    optional string category = 1;
+    optional string has_photo = 2;
+  }
+  optional Template template = 4;
+}
+

data/definitions/mason.proto

@@ -0,0 +1,63 @@
+package mason;
+
+enum HTTPVerb {
+  GET = 1;
+  PUT = 2;
+  PATCH = 3;
+  DELETE = 4;
+  POST = 5;
+}
+
+message Self {
+  optional string href = 1;
+  optional string title = 2;
+}
+
+message Up {
+  optional string href = 1;
+  optional string title = 2;
+}
+
+// Filter should be broken out into custom Picatrix stuff
+// as it's not really part of the Mason spec
+message Filter {
+  enum HrefTemplate {
+    TRUE = 0;
+    FALSE = 1;
+  }
+
+  optional string href = 1;
+  optional HTTPVerb method = 2 [default = GET];
+  optional HrefTemplate isHrefTemplate = 3 [default = TRUE];
+}
+
+message Create {
+  optional string href = 1;
+  optional HTTPVerb method = 2 [default = POST];
+  optional string title = 3;
+  optional string encoding = 4;
+}
+
+message Edit {
+  optional string href = 1;
+  optional HTTPVerb method = 2 [default = PATCH];
+  optional string title = 3;
+  optional string encoding = 4;
+}
+
+message Remove {
+  optional string href = 1;
+  optional HTTPVerb method = 2 [default = DELETE];
+  optional string title = 3;
+}
+
+// when viewing an item directly, you see
+// all available controls for it
+message Controls {
+  optional Self self = 2;
+  optional Up up = 3;
+  optional Edit edit = 4;
+  optional Remove remove = 5;
+  optional Create create = 6;
+  optional Filter filter = 7;
+}

data/lib/picatrix/buffy.rb

@@ -0,0 +1,56 @@
+require 'protobuf'
+require 'faker'
+
+module Picatrix
+  class Buffy
+    include Thor::Base
+    include Thor::Actions
+
+    attr_accessor :destination_stack, :options,
+      :resources, :id
+
+    source_root File.dirname(__FILE__)
+
+    PROTOBUF_FIXTURES = {
+      Protobuf::Field::Int32Field => "Faker::Number.number(6)",
+      Protobuf::Field::StringField => "Faker::Lorem.word"
+    }
+
+    def initialize(nodes, options = {})
+      # thor related
+      @options = options
+      @destination_stack = [self.class.source_root]
+
+      @resources = nodes.keys.select {|n| n if n.pluralize == n}
+      resources.each do |resource|
+        @resource_name = resource.camelize
+        @fields = @resource_name.singularize.
+          constantize.fields.inject({}) do |memo, field|
+
+          field_value =
+            if PROTOBUF_FIXTURES[field.type_class]
+              # TODO this is too general need some way to signal
+              # primary key which is addressable
+              if field.name.to_s.include?("id")
+                "id = #{PROTOBUF_FIXTURES[field.type_class]}"
+              else
+                PROTOBUF_FIXTURES[field.type_class]
+              end
+            elsif field.type_class.to_s.demodulize == "Controls"
+              "#{field.type_class}.new(minimal_controls_for(item_id))"
+            else
+              # TODO recursively gen these relations
+              "[#{field.type_class}.new(params = {})]"
+            end
+
+          memo[field.name] = field_value
+          memo
+        end
+        template(
+          'templates/type.rb',
+          File.join("generated/#{resource}.rb")
+        )
+      end
+    end
+  end
+end

data/lib/picatrix/cruddy.rb

@@ -0,0 +1,45 @@
+module Picatrix
+  class Cruddy
+    attr_accessor :controls
+
+    def initialize(edges)
+      @controls = edges.inject({}) do |memo, edge|
+        source = edge.keys.first
+        target = edge[source][:target]
+
+        next memo if source.upcase == "ROOT"
+
+        memo[target] = appropriate_controls_for(target)
+        memo
+      end
+    end
+
+    private
+    def appropriate_controls_for(source)
+      #TODO unless these become more diff again, should combine
+      if source.pluralize == source # collection?
+        {
+          source => template_map(:collection)
+        }
+      else
+        {
+          source => template_map(:item)
+        }
+      end
+    end
+    def template_map(type)
+      {
+        item: {
+          get: :mason_self,
+          patch: :edit,
+          put: :edit,
+          delete: :remove
+        },
+        collection: {
+          post: :create,
+          get: :filter
+        }
+      }[type]
+    end
+  end
+end

data/lib/picatrix/digraph_parser.rb

@@ -10,7 +10,14 @@ module Picatrix
       (newline.absent? >> any).repeat(1) >>
       newline
     end
+    rule(:graph_setting) do
+      indent >>
+      (str(";").absent? >> any).repeat(0) >>
+      str(";") >>
+      newline
+    end
     rule(:default_definitions) do
+      graph_setting.repeat(0) >>
       indent >>
       str("edge [") >>
       (str("]").absent? >> any).repeat(0) >>

data/lib/picatrix/fixtures/view_submission.rb

@@ -0,0 +1,19 @@
+class ViewSubmissionFixture
+  # real object has more properties
+  def self.attributes
+    {
+      category: random_category,
+      photo: random_photo,
+      secret_data: "that won't be shared",
+      pci_data: "really won't appear"
+    }
+  end
+
+  def self.random_category
+    %w{ cats }.sample
+  end
+
+  def self.random_photo
+    %w{ http://imgur.com/r/cats/myEqIZx }.sample
+  end
+end

data/lib/picatrix/generated/app.pb.rb

@@ -0,0 +1,79 @@
+# encoding: utf-8
+
+##
+# This file is auto-generated. DO NOT EDIT!
+#
+require 'protobuf/message'
+
+
+##
+# Imports
+#
+require_relative 'mason.pb.rb'
+
+
+##
+# Message Classes
+#
+class ViewSubmission < ::Protobuf::Message
+  class Controls < ::Protobuf::Message; end
+  class Attachment < ::Protobuf::Message; end
+
+end
+
+class ViewSubmissions < ::Protobuf::Message; end
+class EditViewSubmission < ::Protobuf::Message
+  class Template < ::Protobuf::Message; end
+
+end
+
+class CreateViewSubmission < ::Protobuf::Message
+  class Template < ::Protobuf::Message; end
+
+end
+
+
+
+##
+# Message Fields
+#
+class ViewSubmission
+  class Controls
+    optional ::Mason::Self, :self, 2
+  end
+
+  class Attachment
+    optional :int32, :id, 1
+  end
+
+  optional :int32, :id, 1
+  optional :string, :category, 2
+  optional :string, :photo, 3
+  optional ::ViewSubmission::Controls, :controls, 4
+  repeated ::ViewSubmission::Attachment, :attachments, 5
+end
+
+class ViewSubmissions
+  repeated ::ViewSubmission, :collection, 1
+end
+
+class EditViewSubmission
+  class Template
+    optional :string, :category, 1
+    optional :string, :has_photo, 2
+  end
+
+  optional ::Mason::Edit, :form, 3
+  optional ::EditViewSubmission::Template, :template, 4
+end
+
+class CreateViewSubmission
+  class Template
+    optional :string, :category, 1
+    optional :string, :has_photo, 2
+  end
+
+  optional ::Mason::Create, :form, 3
+  optional ::CreateViewSubmission::Template, :template, 4
+end
+