xing-backend-specdoc 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a4fb54b420e096821934f1179eb5c9f274f70deb
+  data.tar.gz: b0624e2586339eb47c2b6e18fc1165cb422dec75
+SHA512:
+  metadata.gz: c70d8ad1026fa80d5d8545dfc76054ba26b530687e6455ee9f098d001c92d5148df66c7fd2f9755585362002a26167349dc7a73d85612e9c4af862e19e87bd0d
+  data.tar.gz: 98efef1c24410242f382363ec918a5b583db04a50aa17aa6584d978cf867848b7272e47938d0d16f3ab066757055c50154da7bee95b3f041f407556e05bce69f

data/lib/xing/specdoc/api-doccer.rb

@@ -0,0 +1,63 @@
+require 'xing/specdoc/patterner'
+require 'xing/specdoc/document'
+
+module Xing
+  module SpecDoc
+    class ApiDoccer
+      def self.patterner
+        @patterner ||= Patterner.new(Rails.application.routes)
+      end
+
+      def initialize(example, request, response, patterner=nil)
+        @example = example
+        @request = request
+        @response = response
+        @patterner = patterner || ApiDoccer.patterner
+      end
+
+      attr_reader :example, :request, :response, :patterner
+
+      def output_path
+        @output_path ||= File::join( SpecDoc.response_target_dir, filename )
+      end
+
+      def base_filename
+        @base_filename ||=
+          begin
+            pattern = patterner.build(request).sub(%r{^/},"").gsub(%{/:},":").gsub(%r{/},"-")
+            File::join(example.metadata[:doc_path],
+                       "#{request.method}+#{response.status}@#{pattern}")
+          end
+      end
+
+      def filename
+        base_filename + ".json"
+      end
+
+      def existing_body
+        JSON.parse(File.read(output_path))
+      end
+
+      def example_passed?
+        example.exception.nil?
+      end
+
+      def document
+        @document ||= Document.new(output_path, response.body)
+      end
+
+      def significant_change?
+        document.different_from?(existing_body)
+      rescue Errno::ENOENT
+        true
+      end
+
+      def store
+        if example_passed?
+          Xing::SpecDoc.store(self)
+        end
+      end
+
+    end
+  end
+end

data/lib/xing/specdoc/doc-family.rb

@@ -0,0 +1,92 @@
+require 'fileutils'
+require 'xing/specdoc/document'
+require 'xing/specdoc/winnower'
+
+module Xing
+  module SpecDoc
+    class DocFamily
+      def initialize(name)
+        @name = name
+        @docs = []
+        @index = 1
+        @out_stream = $stdout
+      end
+
+      attr_reader :name, :docs
+      attr_accessor :out_stream
+
+      def add(doc)
+        @docs << doc
+      end
+
+      def old_doc_glob
+        File::join(Xing::SpecDoc.response_target_dir, name) + "*"
+      end
+
+      def old_doc_paths
+        @old_doc_paths ||= dir_glob(old_doc_glob).find_all do |path|
+          re = /#{Regexp.escape(name)}-\d+\.json$/
+          path =~ re
+        end
+      end
+
+      def old_docs
+        old_doc_paths.map do |path|
+          Document.new(path, File.read(path))
+        end
+      end
+
+      def record
+        ensure_target_dir
+
+        winnower = Winnower.new(docs, old_docs)
+
+        winnower.obsolete_paths.each do |path|
+          kill(path)
+        end
+
+        winnower.kept_new.each do |doc|
+          write(doc)
+        end
+      end
+
+      def next_output_path
+        loop do
+          candidate = File::join(Xing::SpecDoc.response_target_dir, "#{name}-#{@index}.json")
+          if exist?(candidate)
+            @index += 1
+          else
+            return candidate
+          end
+        end
+      end
+
+      def ensure_target_dir
+        FileUtils.mkdir_p(File.dirname(File::join(Xing::SpecDoc.response_target_dir, name)))
+      end
+
+      def kill(path)
+        @out_stream.puts "Removing outdated JSON example at #{path}"
+        FileUtils::rm_f(path)
+      end
+
+      def write(doc)
+        path = next_output_path
+        @out_stream.puts "Writing new JSON example to       #{path}"
+        File.write(path, doc.pretty_body)
+      end
+
+      def dir_glob(pattern)
+        Dir.glob(pattern)
+      end
+
+      def exist?(path)
+        File.exist?(path)
+      end
+
+      def read(path)
+        File.read(path)
+      end
+    end
+  end
+end

data/lib/xing/specdoc/document.rb

@@ -0,0 +1,73 @@
+require 'hashdiff'
+
+module Xing
+  module SpecDoc
+    class Document
+      def initialize(path, contents)
+        @path = path
+        @contents = contents
+      end
+      attr_reader :path, :contents
+
+      def parsed_body
+        @parsed_body ||= JSON.parse(contents)
+      end
+
+      def pretty_body
+        @pretty_body ||= JSON.pretty_generate(parsed_body)+"\n"
+      end
+
+      def difference_from(other)
+        diff(parsed_body, other)
+      end
+
+      def diff(one, other)
+        diff = HashDiff.diff(one, other)
+
+
+        by_change = diff.group_by {|change| change[0]}
+
+        adds = by_change.delete("+") || []
+        subs = by_change.delete("-") || []
+        mods = by_change.values.inject do |all, a_kind|
+          all + a_kind
+        end || []
+
+        arr_adds, other_adds = adds.partition do |add|
+          add[1] =~ /\[\d+\]$/
+        end
+
+        mods += (other_adds || [])
+
+        arr_adds.each do |add|
+          sub = subs.find{|sub| sub[1] == add[1]}
+          if sub.nil?
+            mods << add
+          else
+            subs.delete(sub)
+            new_diff = diff(add[2], sub[2])
+            mods += new_diff.map do |change|
+              [change[0], [add[1], change[1]].join(".")] + change[2..-1]
+            end
+          end
+        end
+
+        mods += subs
+
+        mods
+      end
+
+      def significant_diff_item?(change)
+        return true if change[0] != "~"
+        return true if change[2].class != change[3].class
+        return false
+      end
+
+      def different_from?(body)
+        difference_from(body).any? do |change|
+          significant_diff_item?(change)
+        end
+      end
+    end
+  end
+end

data/lib/xing/specdoc/module.rb

@@ -0,0 +1,40 @@
+require 'xing/specdoc/api-doccer'
+require 'xing/specdoc/doc-family'
+
+module Xing
+  module SpecDoc
+    class << self
+      def target_dir
+        RSpec.configuration.specdoc_target_directory
+      end
+
+      def response_target_dir
+        File.join(target_dir,  "responses")
+      end
+
+      def request_target_dir
+        File.join(target_dir,  "requests")
+      end
+
+      def doc_hash
+        @doc_hash ||= Hash.new{|h,k| h[k]= DocFamily.new(k)}
+      end
+
+      def store(doc)
+        doc_hash[doc.base_filename].add(doc)
+      end
+
+      def record_docs
+        doc_hash.each_pair do |_, docs|
+          docs.record
+        end
+      end
+
+      def included(group)
+        group.after(:each) do |example|
+          ApiDoccer.new(example, request, response).store
+        end
+      end
+    end
+  end
+end

data/lib/xing/specdoc/patterner.rb

@@ -0,0 +1,41 @@
+module Xing
+  module SpecDoc
+    class Patterner
+      def initialize(rails_routes, route_set=nil)
+        @rails_routes = rails_routes
+        @route_set = route_set
+      end
+      attr_reader :rails_routes
+
+      def route_map
+        @route_map ||=
+          begin
+            ad_routes_array   = rails_routes.routes
+            rack_routes_array = rails_routes.set.instance_eval{ @routes }
+            Hash[ rack_routes_array.zip(ad_routes_array) ]
+          end
+      end
+
+      def route_set
+        @route_set ||= Rails.application.routes.router
+      end
+
+      def build(req)
+        route_set.recognize(req) do |route, matches, params|
+          rails_route = route_map[route]
+
+          path_spec = :unrecognized
+          segment_keys = {}
+
+          if route_map.has_key?(route)
+            rails_route = route_map[route]
+            path_spec = rails_route.path.spec.to_s
+            segment_keys = rails_route.segment_keys
+            return path_spec.sub(/\(\.:format\)/,"")
+          end
+        end
+        return nil
+      end
+    end
+  end
+end

data/lib/xing/specdoc/winnower.rb

@@ -0,0 +1,66 @@
+
+module Xing
+  module SpecDoc
+    class Winnower
+      def initialize(incoming_docs, existing_docs)
+        @incoming_docs = incoming_docs
+        @existing_docs = existing_docs
+
+        reset
+      end
+
+      def kept_new
+        if @keepable.nil?
+          resolve
+        end
+        @keepable
+      end
+
+      def obsolete_paths
+        if @keepable.nil?
+          resolve
+        end
+        @obsolete_paths
+      end
+
+      def reset
+        @obsolete_paths = []
+        @keepable = nil
+      end
+
+      def resolve
+        new_docs = significant_docs
+
+        @existing_docs.each do |doc|
+          new_docs = resolve_against_existing(doc, new_docs)
+        end
+
+        @keepable = new_docs
+      end
+
+      def significant_docs
+        @incoming_docs.reduce([]) do |list, doc|
+          if list.any?{|kept| not kept.different_from?(doc.parsed_body)}
+            list
+          else
+            list + [doc]
+          end
+        end
+      end
+
+      def resolve_against_existing(doc, list)
+        old_doc = JSON.parse(doc.contents)
+
+        keep, trash = list.partition do |doc|
+          doc.different_from?(old_doc)
+        end
+
+        if trash.length == 0
+          @obsolete_paths << doc.path
+        end
+
+        return keep
+      end
+    end
+  end
+end

data/lib/xing/specdoc.rb

@@ -0,0 +1,11 @@
+require 'xing/specdoc/module'
+
+RSpec.configure do |config|
+  config.add_setting :specdoc_target_directory, :default => "../spec_api"
+
+  config.include(Xing::SpecDoc, :doc_path => proc{|value| !!value})
+
+  config.after(:suite) do
+    Xing::SpecDoc.record_docs
+  end
+end

data/spec/document_spec.rb

@@ -0,0 +1,125 @@
+require 'xing/specdoc/document'
+
+describe Xing::SpecDoc::Document do
+  let :path do
+    "whatever_path"
+  end
+
+  subject :doccer do
+    Xing::SpecDoc::Document.new(path, response_json)
+  end
+
+  let :our_hash do
+    {
+      "number" => 127,
+      "string" => "a string",
+      "string_list" => [
+        "a", "b", "c"
+      ],
+      "number_list" => [
+        1, 2, 3
+      ],
+      "object" => {
+        "number" => 127,
+        "string" => "a string",
+        "string_list" => [
+          "a", "b", "c"
+        ],
+        "number_list" => [
+          1, 2, 3
+        ]
+      }
+    }
+  end
+
+  let :other_hash do
+    our_hash.dup
+  end
+
+  let :response_json do
+    our_hash.to_json
+  end
+
+  context "should not register difference" do
+    let :is_diff do
+      false
+    end
+
+    it "from an identical JSON" do
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "from changed number values" do
+      other_hash["number"] = 321
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "from changed string values" do
+      other_hash["string"] = "another string"
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "from changed list values" do
+      other_hash["string_list"] = [ "z","y","x" ]
+      other_hash["number_list"] = [ 4,5,6 ]
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+  end
+
+  context "should register differences" do
+    let :is_diff do
+      true
+    end
+
+    it "when string changes to number" do
+      other_hash["string"] = 1234
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when number changes to string" do
+      other_hash["number"] = "tuesday"
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a field is removed" do
+      other_hash.delete("string")
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a field is added" do
+      other_hash["new_string"] = "hello"
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a list shortens" do
+      other_hash["string_list"] = our_hash["string_list"][0..-2]
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a list lengthens" do
+      other_hash["number_list"] = our_hash["number_list"] + [5]
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a member of list changes from number to string" do
+      other_hash["number_list"] = our_hash["number_list"][0..-2] + ["string"]
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+
+    it "when a member of list changes from string to number" do
+      other_hash["string_list"] = our_hash["string_list"][0..-2] + [37]
+
+      expect(doccer.different_from?(other_hash)).to eq(is_diff)
+    end
+  end
+end

data/spec/winnower_spec.rb

@@ -0,0 +1,112 @@
+require 'xing/specdoc/document'
+require 'xing/specdoc/winnower'
+
+describe Xing::SpecDoc::Winnower do
+  subject :winnower do
+    Xing::SpecDoc::Winnower.new(new_docs, old_docs)
+  end
+
+  let :first_content do
+    { "a" => "a" }.to_json
+  end
+
+  let :second_content do
+    { "something" => "else" }.to_json
+  end
+
+  let :third_content do
+    { "something_completely" => "else" }.to_json
+  end
+
+  let :new_docs do
+    new_contents.each_with_index.map do |content, index|
+      Xing::SpecDoc::Document.new("new_path_#{index}", content)
+    end
+  end
+
+  let :old_docs do
+    old_contents.each_with_index.map do |content, index|
+      Xing::SpecDoc::Document.new("old_path_#{index}", content)
+    end
+  end
+
+  let :old_paths do
+    old_docs.map(&:path)
+  end
+
+  let :new_contents do
+    []
+  end
+
+  let :old_contents do
+    []
+  end
+
+  context "should reduce extraneous new docs" do
+    let :new_contents do
+      [ first_content, first_content, first_content ]
+    end
+
+    it "should strip the extras" do
+      expect(winnower.kept_new.length).to eq(1)
+    end
+
+    it "should not invent obsoletes" do
+      expect(winnower.obsolete_paths.length).to eq(0)
+    end
+  end
+
+  context "should prefer existing docs" do
+    let :new_contents do
+      [ first_content ]
+    end
+
+    let :old_contents do
+      [ first_content ]
+    end
+
+    it "should strip the duplicate new docs" do
+      expect(winnower.kept_new.length).to eq(0)
+    end
+
+    it "should not consider incumbents obsolete" do
+      expect(winnower.obsolete_paths.length).to eq(0)
+    end
+  end
+
+  context "should consider old docs without support obsolete" do
+    let :new_contents do
+      [ first_content ]
+    end
+
+    let :old_contents do
+      [ second_content ]
+    end
+
+    it "should strip the duplicate new docs" do
+      expect(winnower.kept_new.length).to eq(1)
+    end
+
+    it "should not consider incumbents obsolete" do
+      expect(winnower.obsolete_paths.length).to eq(1)
+    end
+  end
+
+  context "whole set up" do
+    let :new_contents do
+      [ first_content, second_content ]
+    end
+
+    let :old_contents do
+      [ second_content, third_content ]
+    end
+
+    it "should strip the duplicate new docs" do
+      expect(winnower.kept_new.length).to eq(1)
+    end
+
+    it "should not consider incumbents obsolete" do
+      expect(winnower.obsolete_paths.length).to eq(1)
+    end
+  end
+end

data/spec_help/file-sandbox.rb

@@ -0,0 +1,164 @@
+#require 'ftools'
+require 'fileutils'
+
+module FileSandbox
+  def self.included(spec)
+    return unless spec.respond_to? :before
+
+    spec.before do
+      setup_sandbox
+    end
+
+    spec.after do
+      teardown_sandbox
+    end
+  end
+
+  class HaveContents
+    def initialize(contents)
+      @contents = contents
+    end
+
+    def matches?(target)
+      case @contents
+      when Regexp
+	@contents =~ target.contents
+      when String
+	@contents == target.contents
+      end
+    end
+  end
+
+  def have_contents(expected)
+    HaveContents.new(expected)
+  end
+
+  attr_reader :sandbox
+
+  def in_sandbox(&block)
+    raise "I expected to create a sandbox as you passed in a block to me" if !block_given?
+
+    setup_sandbox
+    original_error = nil
+
+    begin
+      yield @sandbox
+    rescue => e
+      original_error = e
+      raise
+    ensure
+      begin
+        teardown_sandbox
+      rescue
+        if original_error
+          STDERR.puts "ALERT: a test raised an error and failed to release some lock(s) in the sandbox directory"
+          raise(original_error)
+        else
+          raise
+        end
+      end
+    end
+  end
+
+  def setup_sandbox(path = '__sandbox')
+    unless @sandbox
+      @sandbox = Sandbox.new(path)
+      @__old_path_for_sandbox = Dir.pwd
+      Dir.chdir(@sandbox.root)
+    end
+  end
+
+  def teardown_sandbox
+    if @sandbox
+      Dir.chdir(@__old_path_for_sandbox)
+      @sandbox.clean_up
+      @sandbox = nil
+    end
+  end
+
+  class Sandbox
+    attr_reader :root
+
+    def initialize(path = '__sandbox')
+      @root = File.expand_path(path)
+      clean_up
+      FileUtils.mkdir_p @root
+    end
+
+    def [](name)
+      SandboxFile.new(File.join(@root, name), name)
+    end
+
+    # usage new :file=>'my file.rb', :with_contents=>'some stuff'
+    def new(options)
+      if options.has_key? :directory
+        dir = self[options.delete(:directory)]
+        FileUtils.mkdir_p dir.path
+      else
+        file = self[options.delete(:file)]
+        if (binary_content = options.delete(:with_binary_content) || options.delete(:with_binary_contents))
+          file.binary_content = binary_content
+        else
+          file.content = (options.delete(:with_content) || options.delete(:with_contents) || '')
+        end
+      end
+
+      raise "unexpected keys '#{options.keys.join(', ')}'" unless options.empty?
+
+      dir || file
+    end
+
+    def remove(options)
+      name = File.join(@root, options[:file])
+      FileUtils.remove_file name
+    end
+
+    def clean_up
+      FileUtils.rm_rf @root
+      if File.exists? @root
+        raise "Could not remove directory #{@root.inspect}, something is probably still holding a lock on it"
+      end
+    end
+  end
+
+
+  class SandboxFile
+    attr_reader :path
+
+    def initialize(path, sandbox_path)
+      @path = path
+      @sandbox_path = sandbox_path
+    end
+
+    def inspect
+      "SandboxFile: #@sandbox_path"
+    end
+
+    def exist?
+      File.exist? path
+    end
+
+    def content
+      File.read path
+    end
+
+    def content=(content)
+      FileUtils.mkdir_p File.dirname(@path)
+      File.open(@path, "w") {|f| f << content}
+    end
+
+    def binary_content=(content)
+      FileUtils.mkdir_p File.dirname(@path)
+      File.open(@path, "wb") {|f| f << content}
+    end
+
+    def create
+      self.content = ''
+    end
+
+    alias exists? exist?
+    alias contents content
+    alias contents= content=
+    alias binary_contents= binary_content=
+  end
+end

data/spec_help/gem_test_suite.rb

@@ -0,0 +1,17 @@
+puts Dir::pwd
+require 'test/unit'
+begin
+  require 'spec'
+rescue LoadError
+  false
+end
+
+class RSpecTest < Test::Unit::TestCase
+  def test_that_rspec_is_available
+    assert_nothing_raised("\n\n *  RSpec isn't available - please run: gem install rspec  *\n\n"){ ::Spec }
+  end
+
+  def test_that_specs_pass
+    assert(system(*%w{spec -f e -p **/*.rb spec}),"\n\n *  Specs failed  *\n\n")
+  end
+end

data/spec_help/spec_helper.rb

@@ -0,0 +1,10 @@
+require 'rspec'
+require 'rspec/core/formatters/base_formatter'
+require 'file-sandbox'
+require 'cadre/rspec3'
+
+RSpec.configure do |config|
+  config.run_all_when_everything_filtered = true
+  config.add_formatter(Cadre::RSpec3::NotifyOnCompleteFormatter)
+  config.add_formatter(Cadre::RSpec3::QuickfixFormatter)
+end

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: xing-backend-specdoc
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Judson Lester
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-12-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashdiff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: ''
+email:
+- nyarly@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/xing/specdoc.rb
+- lib/xing/specdoc/api-doccer.rb
+- lib/xing/specdoc/doc-family.rb
+- lib/xing/specdoc/document.rb
+- lib/xing/specdoc/module.rb
+- lib/xing/specdoc/patterner.rb
+- lib/xing/specdoc/winnower.rb
+- spec/document_spec.rb
+- spec/winnower_spec.rb
+- spec_help/file-sandbox.rb
+- spec_help/gem_test_suite.rb
+- spec_help/spec_helper.rb
+homepage: http://nyarly.github.com/xing-backend-specdoc
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options:
+- "--inline-source"
+- "--main"
+- doc/README
+- "--title"
+- xing-backend-specdoc-0.0.1 Documentation
+require_paths:
+- lib/
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: xing-backend-specdoc
+rubygems_version: 2.4.8
+signing_key: 
+specification_version: 4
+summary: ''
+test_files:
+- spec_help/gem_test_suite.rb