prmd 0.0.1

data/lib/prmd.rb

@@ -0,0 +1,15 @@
+require "diff-lcs"
+require "erubis"
+require "json"
+
+dir = File.dirname(__FILE__)
+require File.join(dir, 'prmd', 'commands', 'combine')
+require File.join(dir, 'prmd', 'commands', 'doc')
+require File.join(dir, 'prmd', 'commands', 'expand')
+require File.join(dir, 'prmd', 'commands', 'init')
+require File.join(dir, 'prmd', 'commands', 'verify')
+require File.join(dir, 'prmd', 'schema')
+require File.join(dir, 'prmd', 'version')
+
+module Prmd
+end

data/lib/prmd/commands/combine.rb

@@ -0,0 +1,5 @@
+module Prmd
+  def self.combine(directory, options={})
+    Prmd::Schema.load(directory, options).to_s
+  end
+end

data/lib/prmd/commands/doc.rb

@@ -0,0 +1,110 @@
+def extract_attributes(schema, properties)
+  attributes = []
+  properties.each do |key, value|
+    # found a reference to another element:
+    value = schema.dereference(value)
+    if value.has_key?('anyOf')
+      descriptions = []
+      examples = []
+
+      # sort anyOf! always show unique identifier first
+      anyof = value['anyOf'].sort_by do |property|
+        property['$ref'].split('/').last.gsub('id', 'a')
+      end
+
+      anyof.each do |ref|
+        nested_field = schema.dereference(ref)
+        descriptions << nested_field['description']
+        examples << nested_field['example']
+      end
+
+      # avoid repetition :}
+      if descriptions.size > 1
+        descriptions.first.gsub!(/ of (this )?.*/, "")
+        descriptions[1..-1].map { |d| d.gsub!(/unique /, "") }
+      end
+      description = descriptions.join(" or ")
+      example = doc_example(*examples)
+      attributes << [key, "string", description, example]
+
+    # found a nested object
+    elsif value['type'] == ['object'] && value['properties']
+      nested = extract_attributes(schema, value['properties'])
+      nested.each do |attribute|
+        attribute[0] = "#{key}:#{attribute[0]}"
+      end
+      attributes.concat(nested)
+    # just a regular attribute
+    else
+      description = value['description']
+      if value['enum']
+        description += '<br/><b>one of:</b>' + doc_example(*value['enum'])
+      end
+      example = doc_example(value['example'])
+      attributes << [key, doc_type(value), description, example]
+    end
+  end
+  return attributes
+end
+
+def doc_type(property)
+  schema_type = property["type"].dup
+  type = "nullable " if schema_type.delete("null")
+  type.to_s + (property["format"] || schema_type.first)
+end
+
+def doc_example(*examples)
+  examples.map { |e| "<code>#{e.to_json}</code>" }.join(" or ")
+end
+
+module Prmd
+  def self.doc(schema, options={})
+    root_url = schema['links'].find{|l| l['rel'] == 'root'}['href'] rescue schema['url']
+
+    doc = (options[:prepend] || []).map do |path|
+      File.open(path, 'r').read + "\n"
+    end
+
+    doc << schema['definitions'].map do |_, definition|
+      next if (definition['links'] || []).empty?
+      resource = definition['id'].split('/').last
+      serialization = {}
+      if definition['definitions'].has_key?('identity')
+        identifiers = if definition['definitions']['identity'].has_key?('anyOf')
+          definition['definitions']['identity']['anyOf']
+        else
+          [definitions['definitions']['identity']]
+        end
+
+        identifiers = identifiers.map {|ref| ref['$ref'].split('/').last }
+      end
+      if definition['properties']
+        definition['properties'].each do |key, value|
+          unless value.has_key?('properties')
+            serialization[key] = schema.dereference(value)['example']
+          else
+            serialization[key] = {}
+            value['properties'].each do |k,v|
+              serialization[key][k] = schema.dereference(v)['example']
+            end
+          end
+        end
+      else
+        serialization.merge!(definition['example'])
+      end
+
+      title = definition['title'].split(' - ', 2).last
+
+      Erubis::Eruby.new(File.read(File.dirname(__FILE__) + "/../views/endpoint.erb")).result({
+        definition:      definition,
+        identifiers:     identifiers,
+        resource:        resource,
+        root_url:        root_url,
+        schema:          schema,
+        serialization:   serialization,
+        title:           title,
+        params_template: File.read(File.dirname(__FILE__) + "/../views/parameters.erb"),
+      }) + "\n"
+    end
+  end
+end

data/lib/prmd/commands/expand.rb

@@ -0,0 +1,113 @@
+original = {
+  'description' => 'A foo is bar.',
+  'id'          => 'schema/foo',
+  'title'       => 'API - Foo',
+
+  'definitions' => {
+    'created-at' => {
+      'description' => 'when foo was created',
+      'format'      => 'date-time'
+    },
+    'email' => {
+      'description' => 'email for foo',
+      'format'      => 'email'
+    },
+    'id' => {
+      'description' => 'unique identifier for foo',
+      'format'      => 'uuid'
+    },
+    'updated-at' => {
+      'description' => 'when foo was created',
+      'format'      => 'date-time',
+      'type'        => ['null', 'string']
+    }
+  }
+}
+expanded = original.dup
+
+expanded = {
+  '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
+  'definitions' => {},
+  'links'       => [],
+  'properties'  => {},
+  'type'        => ['object']
+}.merge!(expanded)
+
+if original['definitions']
+  original['definitions'].each do |key, value|
+    default = case value['format']
+    when 'uuid'
+      {
+        'example'   => '01234567-89ab-cdef-0123-456789abcdef',
+        'readOnly'  => true,
+        'type'      => ['string']
+      }
+    when 'email'
+      {
+        'example'   => 'username@example.com',
+        'readOnly'  => false,
+        'type'      => ['string']
+      }
+    when 'date-time'
+      {
+        'example'   => '2012-01-01T12:00:00Z',
+        'readOnly'  => true,
+        'type'      => ['string']
+      }
+    else
+      {
+        'readOnly'  => false
+      }
+    end
+    expanded['definitions'][key] = default.merge!(value)
+  end
+end
+
+if original['links']
+  original['links'].each do |key, value|
+    default = case value['title']
+    when 'Create'
+      {
+        'method'  => 'POST',
+        'rel'     => 'create'
+      }
+    when 'Delete'
+      {
+        'method'  => 'DELETE',
+        'rel'     => 'delete'
+      }
+    when 'Info'
+      {
+        'method'  => 'GET',
+        'rel'     => 'self'
+      }
+    when 'List'
+      {
+        'method'  => 'GET',
+        'rel'     => 'instances'
+      }
+    when 'Update'
+      {
+        'method'  => 'PATCH',
+        'rel'     => 'update'
+      }
+    end
+    expanded = original['links'][key] = default.merge!(value)
+  end
+end
+
+
+#require 'json'
+#require 'pp'
+
+#puts
+
+#puts original_json = JSON.pretty_generate(original)
+#puts original_json.split("\n").length
+
+#puts
+
+#puts expanded_json = JSON.pretty_generate(expanded)
+#puts expanded_json.split("\n").length
+
+#puts

data/lib/prmd/commands/init.rb

@@ -0,0 +1,101 @@
+module Prmd
+  def self.init(resource, options={})
+    data = {
+      '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
+      'title'       => 'FIXME',
+      'type'        => ['object'],
+      'definitions' => {},
+      'links'       => [],
+      'properties'  => {}
+    }
+
+    if options[:meta] && File.exists?(options[:meta])
+      data.merge!(JSON.parse(File.read(options[:meta])))
+    end
+
+    schema = Prmd::Schema.new(data)
+
+    if resource
+      schema['id']    = "schema/#{resource}"
+      schema['title'] = "#{schema['title']} - #{resource[0...1].upcase}#{resource[1..-1]}"
+      schema['definitions'] = {
+        "created_at" => {
+          "description" => "when #{resource} was created",
+          "example"     => "2012-01-01T12:00:00Z",
+          "format"      => "date-time",
+          "readOnly"    => true,
+          "type"        => ["string"]
+        },
+        "id" => {
+          "description" => "unique identifier of #{resource}",
+          "example"     => "01234567-89ab-cdef-0123-456789abcdef",
+          "format"      => "uuid",
+          "readOnly"    => true,
+          "type"        => ["string"]
+        },
+        "identity" => {
+          "$ref" => "/schema/#{resource}#/definitions/id"
+        },
+        "updated_at" => {
+          "description" => "when #{resource} was updated",
+          "example"     => "2012-01-01T12:00:00Z",
+          "format"      => "date-time",
+          "readOnly"    => true,
+          "type"        => ["string"]
+        }
+      }
+      schema['links'] = [
+        {
+          "description" => "Create a new #{resource}.",
+          "href"        => "/#{resource}s",
+          "method"      => "POST",
+          "rel"         => "create",
+          "schema"      => {
+            "properties"  => {},
+            "type"        => ["object"]
+          },
+          "title"       => "Create"
+        },
+        {
+          "description" => "Delete an existing #{resource}.",
+          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"      => "DELETE",
+          "rel"         => "destroy",
+          "title"       => "Delete"
+        },
+        {
+          "description"  => "Info for existing #{resource}.",
+          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"       => "GET",
+          "rel"          => "self",
+          "title"        => "Info"
+        },
+        {
+          "description"  => "List existing #{resource}.",
+          "href"        => "/#{resource}s",
+          "method"       => "GET",
+          "rel"          => "instances",
+          "title"        => "List"
+        },
+        {
+          "description"  => "Update an existing #{resource}.",
+          "href"        => "/#{resource}s/{(%2Fschema%2F#{resource}%23%2Fdefinitions%2Fidentity)}",
+          "method"       => "PATCH",
+          "rel"          => "update",
+          "schema"      => {
+            "properties"  => {},
+            "type"        => ["object"]
+          },
+          "title"        => "Update"
+        }
+      ]
+      schema['properties'] = {
+        "created_at"  => { "$ref" => "/schema/#{resource}#/definitions/created_at" },
+        "id"          => { "$ref" => "/schema/#{resource}#/definitions/id" },
+        "updated_at"  => { "$ref" => "/schema/#{resource}#/definitions/updated_at" }
+      }
+    end
+
+    schema.to_s
+  end
+end

data/lib/prmd/commands/verify.rb

@@ -0,0 +1,66 @@
+module Prmd
+  def self.verify(schema)
+    errors = []
+
+    id = schema['id']
+
+    missing_requirements = []
+    %w{description id $schema title type definitions links properties}.each do |requirement|
+      unless schema.has_key?(requirement)
+        missing_requirements << requirement
+      end
+    end
+    missing_requirements.each do |missing_requirement|
+      errors << "Missing `#{id}#/#{missing_requirement}`"
+    end
+
+    if schema['definitions']
+      unless schema['definitions'].has_key?('identity')
+        errors << "Missing `#{id}#/definitions/identity`"
+      end
+      schema['definitions'].each do |key, value|
+        missing_requirements = []
+        unless key == 'identity'
+          %w{description readOnly type}.each do |requirement|
+            unless schema['definitions'][key].has_key?(requirement)
+              missing_requirements << requirement
+            end
+          end
+        end
+        # check for example, unless they are nested in array/object
+        type = schema['definitions'][key]['type']
+        unless type.nil? || type.include?('array') || type.include?('object')
+          unless schema['definitions'][key].has_key?('example')
+            missing_requirements << 'example'
+          end
+        end
+        missing_requirements.each do |missing_requirement|
+          errors << "Missing `#{id}#/definitions/#{key}/#{missing_requirement}`"
+        end
+      end
+    end
+
+    if schema['links']
+      schema['links'].each do |link|
+        missing_requirements = []
+        %w{description href method rel title}.each do |requirement|
+          unless link.has_key?(requirement)
+            missing_requirements << requirement
+          end
+        end
+        if link.has_key?('schema')
+          %w{properties type}.each do |requirement|
+            unless link['schema'].has_key?(requirement)
+              missing_requirements << "schema/#{requirement}"
+            end
+          end
+        end
+        missing_requirements.each do |missing_requirement|
+          errors << "Missing #{missing_requirement} in `#{link}` link for `#{id}`"
+        end
+      end
+    end
+
+    errors
+  end
+end

data/lib/prmd/schema.rb

@@ -0,0 +1,107 @@
+module Prmd
+  class Schema
+
+    def [](key)
+      @data[key]
+    end
+
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    def self.load(path, options={})
+      unless File.directory?(path)
+        data = JSON.parse(File.read(path))
+      else
+        data = {
+          '$schema'     => 'http://json-schema.org/draft-04/hyper-schema',
+          'definitions' => {},
+          'properties'  => {},
+          'type'        => ['object']
+        }
+
+        if options[:meta] && File.exists?(options[:meta])
+          data.merge!(JSON.parse(File.read(options[:meta])))
+        end
+
+        Dir.glob(File.join(path, '**', '*.json')).each do |schema|
+          schema_data = JSON.parse(File.read(schema))
+          id = if schema_data['id']
+            schema_data['id'].gsub('schema/', '')
+          end
+          next if id.nil? || id[0..0] == '_' # FIXME: remove this exception?
+
+          data['definitions'][id] = schema_data
+          reference_localizer = lambda do |datum|
+            case datum
+            when Array
+              datum.map {|element| reference_localizer.call(element)}
+            when Hash
+              if datum.has_key?('$ref')
+                datum['$ref'] = datum['$ref'].gsub(%r{/schema/([^#]*)#}, '#/definitions/\1')
+              end
+              if datum.has_key?('href')
+                datum['href'] = datum['href'].gsub(%r{%2Fschema%2F([^%]*)%23%2F}, '%23%2Fdefinitions%2F\1%2F')
+              end
+              datum.each { |k,v| datum[k] = reference_localizer.call(v) }
+            else
+              datum
+            end
+          end
+          reference_localizer.call(data['definitions'][id])
+
+          data['properties'][id] = { '$ref' => "#/definitions/#{id}" }
+        end
+      end
+
+      self.new(data)
+    end
+
+    def initialize(new_data = {})
+      convert_type_to_array = lambda do |datum|
+        case datum
+        when Array
+          datum.map { |element| convert_type_to_array.call(element) }
+        when Hash
+          if datum.has_key?('type')
+            datum['type'] = [*datum['type']]
+          end
+          datum.each { |k,v| datum[k] = convert_type_to_array.call(v) }
+        else
+          datum
+        end
+      end
+      @data = convert_type_to_array.call(new_data)
+    end
+
+    def dereference(reference)
+      if reference.is_a?(Hash)
+        if reference.has_key?('$ref')
+          key = reference['$ref']
+        else
+          return reference # no dereference needed
+        end
+      else
+        key = reference
+      end
+      begin
+        datum = @data
+        key.gsub(%r{[^#]*#/}, '').split('/').each do |fragment|
+          datum = datum[fragment]
+        end
+        datum
+      rescue => error
+        $stderr.puts("Failed to dereference `#{key}`")
+        raise(error)
+      end
+    end
+
+    def to_s
+      new_json = JSON.pretty_generate(@data)
+      # nuke empty lines
+      new_json = new_json.split("\n").delete_if {|line| line.empty?}.join("\n") + "\n"
+      new_json
+    end
+
+  end
+end