stitches 3.5.0 → 3.6.0.RC1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 62009fed84cc0754e785017cc928284f840b63fd
-  data.tar.gz: 4284223ca7d0b02b50de0ec7aed0027a85cd9f20
+SHA256:
+  metadata.gz: 9af000ef971218e036d2b46e0bc508749ed8e834f216e857a57c6fb194928fe5
+  data.tar.gz: b39481868efbe1c8e373c265d9561d09989e1be3230b4716adf14176d5de63af
 SHA512:
-  metadata.gz: b69a8d5c5bc964c70902d0becb072d69af02ed587e9b593ae972bc5df32baa3d9203aadf425791047527f68a9ced87d4f02b0f02eba51871e46604dbf63969fd
-  data.tar.gz: e375f477cf060d106d42ba8a5ff3644e70dd75c515c7840b68c1010e58aaeedcd16ac73089ccf45479abbbc623c6aa64c4b97ddb66247c2234407051b6c8807f
+  metadata.gz: b6eb58de02836b34c9ddda0170c4d0b53f64d4b95e01ca4726213af7ae701978fe772e50d038c46cceb6c78b47de46029f04a9043b08fb4d77e3abe8eb9ba79a
+  data.tar.gz: 553079dcb2c338bff86d978db574634802db678344c30655d1db3c67b0625b576034b2f410dae975e04accd7514681df7aee6c0b5c58be2e1a48cb6a3b877a7c

data/.circleci/config.yml

@@ -0,0 +1,102 @@
+# DO NOT MODIFY - this is managed by Git Reduce in goro
+#
+---
+version: 2
+jobs:
+  ruby-2.5.1-rails-5.2:
+    docker:
+    - image: circleci/ruby:2.5.1
+      environment:
+        BUNDLE_GEMFILE: Gemfile.rails-5.2
+    working_directory: "~/stitches"
+    steps:
+    - checkout
+    - run: bundle install --full-index
+    - run: bundle exec rspec --format RspecJunitFormatter --out /tmp/test-results/rspec.xml
+        --format=doc
+    - run:
+        name: Notify Pager Duty
+        command: bundle exec y-notify eng-platform
+        when: on_fail
+    - store_test_results:
+        path: "/tmp/test-results"
+  ruby-2.4.4-rails-5.2:
+    docker:
+    - image: circleci/ruby:2.4.4
+      environment:
+        BUNDLE_GEMFILE: Gemfile.rails-5.2
+    working_directory: "~/stitches"
+    steps:
+    - checkout
+    - run: bundle install --full-index
+    - run: bundle exec rspec --format RspecJunitFormatter --out /tmp/test-results/rspec.xml
+        --format=doc
+    - run:
+        name: Notify Pager Duty
+        command: bundle exec y-notify eng-platform
+        when: on_fail
+    - store_test_results:
+        path: "/tmp/test-results"
+  ruby-2.5.1-rails-5.1:
+    docker:
+    - image: circleci/ruby:2.5.1
+      environment:
+        BUNDLE_GEMFILE: Gemfile.rails-5.1
+    working_directory: "~/stitches"
+    steps:
+    - checkout
+    - run: bundle install --full-index
+    - run: bundle exec rspec --format RspecJunitFormatter --out /tmp/test-results/rspec.xml
+        --format=doc
+    - run:
+        name: Notify Pager Duty
+        command: bundle exec y-notify eng-platform
+        when: on_fail
+    - store_test_results:
+        path: "/tmp/test-results"
+  ruby-2.4.4-rails-5.1:
+    docker:
+    - image: circleci/ruby:2.4.4
+      environment:
+        BUNDLE_GEMFILE: Gemfile.rails-5.1
+    working_directory: "~/stitches"
+    steps:
+    - checkout
+    - run: bundle install --full-index
+    - run: bundle exec rspec --format RspecJunitFormatter --out /tmp/test-results/rspec.xml
+        --format=doc
+    - run:
+        name: Notify Pager Duty
+        command: bundle exec y-notify eng-platform
+        when: on_fail
+    - store_test_results:
+        path: "/tmp/test-results"
+workflows:
+  version: 2
+  on-commit:
+    jobs:
+    - ruby-2.5.1-rails-5.2:
+        context: org-global
+    - ruby-2.4.4-rails-5.2:
+        context: org-global
+    - ruby-2.5.1-rails-5.1:
+        context: org-global
+    - ruby-2.4.4-rails-5.1:
+        context: org-global
+  scheduled:
+    triggers:
+    - schedule:
+        cron: 53 20 * * 1,2,3,4,5
+        filters:
+          branches:
+            only:
+            - master
+    jobs:
+    - ruby-2.5.1-rails-5.2:
+        context: org-global
+    - ruby-2.4.4-rails-5.2:
+        context: org-global
+    - ruby-2.5.1-rails-5.1:
+        context: org-global
+    - ruby-2.4.4-rails-5.1:
+        context: org-global

data/.gitignore

@@ -8,3 +8,5 @@ config/database.yml
 .DS_Store
 .jhw-cache
 **.orig
+Gemfile.lock
+.projections.json

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.5.1

data/Gemfile.rails-4.2

@@ -0,0 +1,8 @@
+# DO NOT MODIFY - this is managed by Git Reduce in goro
+#
+source 'https://gem.fury.io/me/'
+source 'https://www.rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 4.2.0'

data/Gemfile.rails-5.0

@@ -0,0 +1,8 @@
+# DO NOT MODIFY - this is managed by Git Reduce in goro
+#
+source 'https://gem.fury.io/me/'
+source 'https://www.rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 5.0.0'

data/Gemfile.rails-5.1

@@ -0,0 +1,8 @@
+# DO NOT MODIFY - this is managed by Git Reduce in goro
+#
+source 'https://gem.fury.io/me/'
+source 'https://www.rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 5.1.0'

data/Gemfile.rails-5.2

@@ -0,0 +1,8 @@
+# DO NOT MODIFY - this is managed by Git Reduce in goro
+#
+source 'https://gem.fury.io/me/'
+source 'https://www.rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 5.2.0'

data/README.md

@@ -35,6 +35,21 @@ Then, set it up:
 > bundle exec rake db:migrate
 ```
 
+### Upgrading from an older version
+
+* If you have a version lower than 3.3.0, you need to run two generators, one of which creates a new database migration on your
+`api_clients` table:
+
+  ```
+  > bin/rails generate stitches:add_enabled_to_api_clients
+  > bin/rails generate stitches:add_deprecation
+  ```
+* If you have a version lower than 3.6.0, you need to run one generator:
+
+  ```
+  > bin/rails generate stitches:add_deprecation
+  ```
+
 ## Example Microservice Endpoint
 
 Suppose we wish to allow our consumers to create Widgets
@@ -47,7 +62,7 @@ class Api::V1::WidgetsController < ApiController
       head 201
     else
       render json: { 
-        errors: Stitches::Errors.from_active_record(widget) 
+        errors: Stitches::Errors.from_active_record_object(widget) 
       }, status: 422
     end
   end
@@ -82,6 +97,7 @@ See [the wiki](https://github.com/stitchfix/stitches/wiki/Setup) for how to setu
   - Versioned requests via HTTP content types
   - Structured Errors
   - ISO 8601-formatted dates
+  - Deprecation using the `Sunset` header
 * The [Generator](https://github.com/stitchfix/stitches/wiki/Generator) sets up some code in your app, so you can start writing
 APIs using vanilla Rails idioms:
   - a "ping" controller that can vaidate your app is working
@@ -95,6 +111,10 @@ APIs using vanilla Rails idioms:
 
 Although `Stitches.configuration` is global, do not depend directly on that in your logic.  Instead, allow all classes to receive a configuration object in their constructor.  This makes the classes easier to deal with and change, without incurring much of a real cost to development.  Global symbols suck, but are convienient.  This is how you make the most of it.
 
+Also, the integration test does a lot of "testing the implementation", but since Rails generators are notorious for silently
+failing with a successful result, we have to make sure that the various `inject_into_file` calls are actually working.  Do not do
+any fancy refactors here, just keep it up to date.
+
 ---
 
 Provided with love by your friends at [Stitch Fix Engineering](http://technology.stitchfix.com)

data/build-matrix.json

@@ -0,0 +1,4 @@
+{
+  "build_matrix": {
+  }
+}

data/lib/stitches.rb

@@ -1,3 +1,4 @@
 require 'stitches_norailtie'
 require 'stitches/railtie'
-require 'apitome'
+# Add new stitches ruby files to the stitches_norailtie file instead of here
+require 'apitome'

data/lib/stitches/add_deprecation_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators'
+
+module Stitches
+  class AddDeprecationGenerator < Rails::Generators::Base
+    source_root(File.expand_path(File.join(File.dirname(__FILE__),"generator_files")))
+
+    desc "Adds deprecation support to an app creates with an older version of stitches"
+    def add_deprecation
+      inject_into_file "app/controllers/api/api_controller.rb", after: /^class.*$/ do<<-CODE
+  include Stitches::Deprecation
+      CODE
+      end
+    end
+  end
+end

data/lib/stitches/api_generator.rb

@@ -12,10 +12,12 @@ module Stitches
 
     desc "Bootstraps your API service with a basic ping controller and spec to ensure everything is setup properly"
     def bootstrap_api
-      inject_into_file "Gemfile", after: /^gem ["']pg['"].*$/ do<<-GEM
+      inject_into_file "Gemfile", after: /^gem ['"]rails['"].*$/ do<<-GEM
 
 gem "apitome"
 gem "responders"
+gem "rspec_api_documentation", group: [ :development, :test ]
+gem "capybara", group: [ :development, :test ]
       GEM
       end
       inject_into_file "config/routes.rb", before: /^end/ do<<-ROUTES
@@ -51,12 +53,6 @@ mount api_docs, at: "docs"
       template "spec/features/api_spec.rb.erb", "spec/features/api_spec.rb"
       copy_file "spec/acceptance/ping_v1_spec.rb", "spec/acceptance/ping_v1_spec.rb"
 
-      inject_into_file "Gemfile", after: /^group :test, :development do.*$/ do<<-GEM
-
-  gem "rspec_api_documentation"
-  gem "capybara"
-      GEM
-      end
       run 'bundle install'
 
       migration_template "db/migrate/enable_uuid_ossp_extension.rb", "db/migrate/enable_uuid_ossp_extension.rb"

data/lib/stitches/deprecation.rb

@@ -0,0 +1,26 @@
+module Stitches
+  module Deprecation
+    # Indicate that a previously-deprecated endpoint is now gone
+    def gone!
+      head 410
+    end
+
+    # Indicate that this endpoint is deprecated and will go away on the given date.
+    #
+    # gon_on: - date, as a string, when this endpoint will go away
+    # block - the contents of the endpoint
+    #
+    # Example:
+    #
+    #     def show
+    #       deprecated gone_on: "2019-04-09" do
+    #         render widgets: { Widget.find(params[:id]) }
+    #       end
+    #     end
+    def deprecated(gone_on:,&block)
+      response.set_header("Sunset",Date.parse(gone_on).in_time_zone("GMT").midnight.strftime("%a, %e %b %Y %H:%M:%S %Z"))
+      Rails.logger.info("Deprecated endpoint #{request.method} #{request.fullpath} requested by #{current_user.id}")
+      block.()
+    end
+  end
+end

data/lib/stitches/generator_files/app/controllers/api/api_controller.rb

@@ -1,4 +1,5 @@
 class Api::ApiController < ActionController::Base
+  include Stitches::Deprecation
   rescue_from ActiveRecord::RecordNotFound do |exception|
     respond_to do |type|
       type.json { render json: { errors: Stitches::Errors.new([ Stitches::Error.new(code: "not_found", message: exception.message) ]) }, status: 404 }

data/lib/stitches/spec.rb

@@ -2,3 +2,5 @@ require 'stitches/spec/be_iso_8601_utc_encoded'
 require 'stitches/spec/have_api_error'
 require 'stitches/spec/api_clients'
 require 'stitches/spec/test_headers'
+require 'stitches/spec/be_gone'
+require 'stitches/spec/show_deprecation'

data/lib/stitches/spec/be_gone.rb

@@ -0,0 +1,19 @@
+# Use this to test that an HTTP response is properly "410/Gone"
+#
+# The object you expect on is generally `self`, because this is the object on which
+# rspec_api_documentation allows you to call `status`
+#
+# get "/api/widgets" do
+#   it "has been removed" do
+#     expect(self).to be_gone
+#   end
+# end
+RSpec::Matchers.define :be_gone do
+  match do |rspec_api_documentation_context|
+    rspec_api_documentation_context.status == 410
+  end
+  failure_message do |rspec_api_documentation_context|
+    "Expected HTTP status to be 410/Gone, but it was #{rspec_api_documentation_context.status}"
+  end
+end
+

data/lib/stitches/spec/show_deprecation.rb

@@ -0,0 +1,46 @@
+class DeprecationAnalysis
+  attr_reader :expected_sunset_value, :status, :sunset_value
+  def initialize(rspec_api_documentation_context, gone_on)
+    gone_on_date = Date.parse(gone_on)
+    if gone_on_date > Date.today
+      @expecting_sunset      = true
+      @expected_sunset_value = gone_on_date.in_time_zone("GMT").midnight.strftime("%a, %e %b %Y %H:%M:%S %Z")
+      @sunset_header_set     = rspec_api_documentation_context.response_headers["Sunset"].present?
+      @sunset_value          = rspec_api_documentation_context.response_headers["Sunset"]
+      @sunset_header_match   = @expected_sunset_value == @sunset_value
+    else
+      @expecting_gone = true
+      @status         = rspec_api_documentation_context.status
+      @gone           = @status == 410
+    end
+  end
+
+  def expecting_sunset?;    !!@expecting_sunset;    end
+  def sunset_header_set?;   !!@sunset_header_set;   end
+  def sunset_header_match?; !!@sunset_header_match; end
+  def gone?;                !!@gone;                end
+end
+
+RSpec::Matchers.define :show_deprecation do |gone_on:|
+  match do |rspec_api_documentation_context|
+    analysis = DeprecationAnalysis.new(rspec_api_documentation_context,gone_on)
+    if analysis.expecting_sunset?
+      analysis.sunset_header_match?
+    else
+      analysis.gone?
+    end
+  end
+  failure_message do |rspec_api_documentation_context|
+    analysis = DeprecationAnalysis.new(rspec_api_documentation_context,gone_on)
+    if analysis.expecting_sunset?
+      if analysis.sunset_header_set?
+        "Expected the Sunset header to be #{analysis.expected_sunset_value}, but was '#{analysis.sunset_value}'"
+      else
+        "No Sunset header was set.  Use the deprecation method from Stitches::Deprecation in the controller method to deprecate this action"
+      end
+    else
+      "Since the deprecation date has passed, expected HTTP status to be 410/Gone, but it was #{analysis.status}.  Re-implement the endpoint using `gone!` and then change the test to expect it to `be_gone`"
+    end
+  end
+end
+

data/lib/stitches/version.rb

@@ -1,3 +1,3 @@
 module Stitches
-  VERSION = '3.5.0'
+  VERSION = '3.6.0.RC1'
 end

data/lib/stitches_norailtie.rb

@@ -12,7 +12,9 @@ require 'stitches/render_timestamps_in_iso8601_in_json'
 require 'stitches/error'
 require 'stitches/errors'
 require 'stitches/api_generator'
+require 'stitches/add_deprecation_generator'
 require 'stitches/add_enabled_to_api_clients_generator'
 require 'stitches/api_version_constraint'
 require 'stitches/api_key'
+require 'stitches/deprecation'
 require 'stitches/valid_mime_type'

data/owners.json

@@ -0,0 +1,7 @@
+{
+  "owners": [
+    {
+      "team": "platform"
+    }
+  ]
+}

data/spec/deprecation_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper.rb'
+
+describe Stitches::Deprecation do
+  let(:response) {
+    double("response").tap { |r|
+      allow(r).to receive(:set_header)
+    }
+  }
+  let(:request) { double("request", method: "PUT", fullpath: "/foo/bar?blah") }
+  let(:api_client) { double("ApiClient", id: 99) }
+  let(:fake_controller) {
+    double("Controller", response: response, request: request, current_user: api_client).extend(described_class).tap { |controller|
+      allow(controller).to receive(:head)
+    }
+  }
+  describe "#gone" do
+    it "sends an HTTP 410" do
+      fake_controller.gone!
+      expect(fake_controller).to have_received(:head).with(410)
+    end
+  end
+
+  describe "#deprecated" do
+    let(:logger) { double("logger") }
+    before do
+      allow(Rails).to receive(:logger).and_return(logger)
+      allow(logger).to receive(:info)
+    end
+    it "sets the Sunset header to the date given in GMT" do
+      fake_controller.deprecated(gone_on: "2018-01-01") {}
+      expect(response).to have_received(:set_header).with("Sunset","Mon,  1 Jan 2018 00:00:00 GMT")
+    end
+    it "logs about the request and current API key id" do
+      fake_controller.deprecated(gone_on: "2018-01-01") {}
+      expect(logger).to have_received(:info).with(/deprecated.*#{Regexp.escape(request.method)}.*#{Regexp.escape(request.fullpath)}.*#{Regexp.escape(api_client.id.to_s)}/i)
+    end
+    it "executes and returns the block" do
+      block_executed = false
+      result = fake_controller.deprecated(gone_on: "2018-01-01") do
+        block_executed = true
+        42
+      end
+      aggregate_failures do
+        expect(result).to eq(42)
+        expect(block_executed).to eq(true)
+      end
+    end
+  end
+end

data/spec/integration/add_to_rails_app_spec.rb

@@ -0,0 +1,200 @@
+require "spec_helper"
+require "fileutils"
+require "open3"
+
+RSpec.describe "Adding Stitches to a New Rails App" do
+  let(:work_dir) { Dir.mktmpdir }
+  let(:rails_app_name) { "swamp-thing" }
+
+  def run(command)
+    stdout, stderr, stat = Open3.capture3(command)
+    success = stat.success? && stdout !~ /Could not find generator/im
+
+    if ENV["DEBUG"] == 'true' || !success
+      $stdout.puts stdout
+      $stderr.puts stderr
+    end
+    unless success
+      raise "'#{command}' failed"
+    end
+  end
+
+  around(:each) do |example|
+    rails_new = [
+      "rails new #{rails_app_name}",
+      "--skip-yarn",
+      "--skip-git",
+      "--skip-keeps",
+      "--skip-action-mailer",
+      "--skip-active-storage",
+      "--skip-action-cable",
+      "--skip-spring",
+      "--skip-listen",
+      "--skip-coffee",
+      "--skip-javascript",
+      "--skip-turbolinks",
+      "--skip-bootsnap",
+      "--no-rc",
+      "--skip-bundle",
+    ].join(" ")
+    FileUtils.chdir work_dir do
+      run rails_new
+      FileUtils.chdir rails_app_name do
+        example.run
+      end
+    end
+  end
+
+  it "works as described in the README" do
+    run "bin/rails generate rspec:install"
+    run "bin/rails generate apitome:install"
+    run "bin/rails generate stitches:api"
+
+    rails_root = Pathname(work_dir) / rails_app_name
+
+    # Yuck!  So much duplication!  BUT: Rails app templates have a notoriously silent failure mode, so mostly
+    # what this is doing is ensuring that the generator inserted stuff when asked and that the very basics of what happens 
+    # during generation are there.  It's gross, and I'm sorry.
+    #
+    # It's also in one big block because making a new rails app and running the generator multiple times seems bad.
+    aggregate_failures do
+      expect(File.exist?(rails_root / "app" / "controllers" / "api" / "api_controller.rb")).to eq(true)
+      expect(rails_root / "Gemfile").to contain_gem("apitome")
+      expect(rails_root / "Gemfile").to contain_gem("responders")
+      expect(rails_root / "Gemfile").to contain_gem("rspec_api_documentation")
+      expect(rails_root / "Gemfile").to contain_gem("capybara")
+      expect(rails_root / "config" / "routes.rb").to have_route(namespace: :api, module_scope: :v1, resource: 'ping')
+      expect(rails_root / "config" / "routes.rb").to have_route(namespace: :api, module_scope: :v2, resource: 'ping')
+      expect(rails_root / "config" / "routes.rb").to have_mounted_engine("Apitome::Engine")
+      migrations = Dir["#{rails_root}/db/migrate/*.rb"].sort
+      expect(migrations.size).to eq(2)
+      expect(migrations[0]).to match(/\/\d+_enable_uuid_ossp_extension.rb/)
+      expect(migrations[1]).to match(/\/\d+_create_api_clients.rb/)
+      expect(File.read(rails_root / "spec" / "rails_helper.rb")).to include("config.include RSpec::Rails::RequestExampleGroup, type: :feature")
+      expect(File.read(rails_root / "spec" / "rails_helper.rb")).to include("require 'stitches/spec'")
+      expect(File.read(rails_root / "spec" / "rails_helper.rb")).to include("require 'rspec_api_documentation'")
+      expect(File.read(rails_root / "config" / "initializers" / "apitome.rb")).to include("config.mount_at = nil")
+      expect(File.read(rails_root / "config" / "initializers" / "apitome.rb")).to include("config.title = 'Service Documentation'")
+    end
+  end
+
+  it "inserts the deprecation module into ApiController" do
+    run "bin/rails generate rspec:install"
+    run "bin/rails generate apitome:install"
+    run "bin/rails generate stitches:api"
+
+    rails_root = Pathname(work_dir) / rails_app_name
+    api_controller = rails_root / "app" / "controllers" / "api" / "api_controller.rb"
+
+    api_controller_contents = File.read(api_controller).split(/\n/)
+    File.open(api_controller,"w") do |file|
+      api_controller_contents.each do |line|
+        file.puts line unless line =~ /Stitches::Deprecation/
+      end
+    end
+
+    run "bin/rails generate stitches:add_deprecation"
+
+    aggregate_failures do
+      expect(File.read(api_controller)).to include("include Stitches::Deprecation")
+    end
+  end
+
+  class RoutesFileAnalysis
+    attr_reader :routes_file
+    def initialize(routes_file, namespace: nil, module_scope: nil, resource: nil, mounted_engine: nil)
+      @routes_file = File.read(routes_file).split(/\n/)
+      @found_namespace = false
+      @found_module = false
+      @found_resource = false
+      @found_engine = false
+      @engine_mounted = false
+
+      @routes_file.each do |line|
+        if line =~ /namespace :#{namespace} do/
+          @found_namespace = true
+        end
+        if @found_namespace && line =~ /^\s*scope module: :#{module_scope}, constraints: Stitches::ApiVersionConstraint/
+          @found_module = true
+        end
+        if @found_module && line =~ /^\s*resource\s+['"]#{resource}["']/
+          @found_resource = true
+        end
+        if line =~ /api_docs = Rack::Auth::Basic.new\(#{mounted_engine}/
+          @found_engine = true
+        end
+        if @found_engine && line =~ /mount api_docs/
+          @engine_mounted = true
+        end
+      end
+    end
+
+    def found_namespace?
+      @found_namespace
+    end
+
+    def found_module?
+      @found_module
+    end
+
+    def found_resource?
+      @found_resource
+    end
+
+    def found_engine?
+      @found_engine
+    end
+
+    def engine_mounted?
+      @engine_mounted
+    end
+  end
+
+  RSpec::Matchers.define :have_mounted_engine do |engine_name|
+    match do |routes_file|
+      analysis = RoutesFileAnalysis.new(routes_file, mounted_engine: engine_name)
+      analysis.engine_mounted?
+    end
+    failure_message do |routes_file|
+      analysis = RoutesFileAnalysis.new(routes_file, mounted_engine: engine_name)
+      error = if analysis.found_engine?
+                "Found engine #{engine_name}, but it's not mounted"
+              else
+                "Didn't find engine #{engine_name}"
+              end
+
+      error + "\n#{File.read(analysis.routes_file.join("\n"))}"
+    end
+  end
+
+  RSpec::Matchers.define :have_route do |namespace:, module_scope:, resource:|
+    match do |routes_file|
+      analysis = RoutesFileAnalysis.new(routes_file, namespace: namespace, module_scope: module_scope, resource: resource)
+      analysis.found_resource? && analysis.found_module? && analysis.found_namespace?
+    end
+
+    failure_message do |routes_file|
+      analysis = RoutesFileAnalysis.new(routes_file, namespace: namespace, module_scope: module_scope, resource: resource)
+      error = if analysis.found_namespace?
+                if analysis.found_module?
+                  "Could not find resource '#{resource}'"
+                else
+                  "Could not find module '#{scope_module}'"
+                end
+              else
+                "Could not find namespace '#{namespace}'"
+              end
+      error + "\n#{File.read(analysis.routes_file.join("\n"))}"
+    end
+  end
+  RSpec::Matchers.define :contain_gem do |gem_name|
+    match do |gemfile|
+      File.read(gemfile).split(/\n/).any? { |line|
+        line =~ /^\s*gem [\"\']#{gem_name}[\"\']/
+      }
+    end
+    failure_message do |gemfile|
+      "#{gem_name} not found in #{gemfile}:\n#{File.read(gemfile)}"
+    end
+  end
+end

data/spec/spec/be_gone_spec.rb

@@ -0,0 +1,18 @@
+require 'spec_helper.rb'
+require 'stitches/spec'
+
+describe "be_gone" do
+  it "passes the test if the http status was 410" do
+    rspec_api_documentation_context = double("a test using rspec_api_documentation", status: 410)
+    expect(rspec_api_documentation_context).to be_gone
+  end
+  it "fails the test if the http status was not 401" do
+    rspec_api_documentation_context = double("a test using rspec_api_documentation", status: 200)
+    begin
+      expect(rspec_api_documentation_context).to be_gone
+      fail "Expected the matcher to fail"
+    rescue RSpec::Expectations::ExpectationNotMetError => e
+      expect(e.message).to match(/expected http status.*410.*200/i)
+    end
+  end
+end

data/spec/spec/show_deprecation_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper.rb'
+require 'stitches/spec'
+
+describe "show_deprecation" do
+  context "when the expiration date is in the future" do
+    it "passes if the sunset header is set properly" do
+      rspec_api_documentation_context = double(
+        "a test using rspec_api_documentation",
+        status: 200,
+        response_headers: { "Sunset" => "Mon, 13 Dec 2038 00:00:00 GMT" }
+      )
+
+      expect(rspec_api_documentation_context).to show_deprecation(gone_on: "2038-12-13")
+    end
+    it "fails if the sunset header is not set" do
+      begin
+        rspec_api_documentation_context = double( "a test using rspec_api_documentation", status: 200, response_headers: {})
+        expect(rspec_api_documentation_context).to show_deprecation(gone_on: "2038-12-13")
+        fail "Expected matcher to fail"
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to match(/No Sunset header was set/i)
+      end
+    end
+    it "fails if the sunset header is the wrong date" do
+      begin
+        rspec_api_documentation_context = double(
+          "a test using rspec_api_documentation",
+          status: 200,
+          response_headers: { "Sunset" => "Tuesday, 14 Dec 2038 00:00:00 GMT" }
+        )
+        expect(rspec_api_documentation_context).to show_deprecation(gone_on: "2038-12-13")
+        fail "Expected matcher to fail"
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to match(/Expected the Sunset header to be Mon, 13 Dec 2038 00:00:00 GMT, but was 'Tuesday, 14 Dec 2038 00:00:00 GMT/i)
+      end
+    end
+  end
+  context "when the expiration date is in the past" do
+    it "passes if the http status is 410/gone" do
+      rspec_api_documentation_context = double("a test using rspec_api_documentation", status: 410)
+      expect(rspec_api_documentation_context).to show_deprecation(gone_on: "2011-01-01")
+    end
+
+    it "fails if the status is not 410/gone" do
+      rspec_api_documentation_context = double("a test using rspec_api_documentation", status: 200)
+      begin
+        expect(rspec_api_documentation_context).to show_deprecation(gone_on: "2011-01-01")
+        fail "Expected matcher to fail"
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        expect(e.message).to match(/deprecation date has passed.*410.*using `gone\!`/i)
+      end
+    end
+  end
+end

data/stitches.gemspec

@@ -17,10 +17,13 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- exe/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
+
   s.add_runtime_dependency("rails")
   s.add_runtime_dependency("pg")
-  s.add_development_dependency("rake")
   s.add_runtime_dependency("rspec", ">= 3")
   s.add_runtime_dependency("rspec-rails", "~> 3")
   s.add_runtime_dependency("apitome")
+
+  s.add_development_dependency("rake")
+  s.add_development_dependency("rspec_junit_formatter")
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stitches
 version: !ruby/object:Gem::Version
-  version: 3.5.0
+  version: 3.6.0.RC1
 platform: ruby
 authors:
 - Stitch Fix Engineering
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-08-24 00:00:00.000000000 Z
+date: 2018-06-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -41,20 +41,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -97,6 +83,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec_junit_formatter
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: You'll be in stitches at how easy it is to create a service at Stitch
   Fix
 email:
@@ -108,6 +122,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".circleci/config.yml"
 - ".gitignore"
 - ".ruby-gemset"
 - ".ruby-version"
@@ -115,16 +130,22 @@ files:
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile
-- Gemfile.lock
+- Gemfile.rails-4.2
+- Gemfile.rails-5.0
+- Gemfile.rails-5.1
+- Gemfile.rails-5.2
 - LICENSE.txt
 - README.md
 - Rakefile
+- build-matrix.json
 - lib/stitches.rb
+- lib/stitches/add_deprecation_generator.rb
 - lib/stitches/add_enabled_to_api_clients_generator.rb
 - lib/stitches/api_generator.rb
 - lib/stitches/api_key.rb
 - lib/stitches/api_version_constraint.rb
 - lib/stitches/configuration.rb
+- lib/stitches/deprecation.rb
 - lib/stitches/error.rb
 - lib/stitches/errors.rb
 - lib/stitches/generator_files/app/controllers/api.rb
@@ -145,19 +166,26 @@ files:
 - lib/stitches/render_timestamps_in_iso8601_in_json.rb
 - lib/stitches/spec.rb
 - lib/stitches/spec/api_clients.rb
+- lib/stitches/spec/be_gone.rb
 - lib/stitches/spec/be_iso_8601_utc_encoded.rb
 - lib/stitches/spec/have_api_error.rb
+- lib/stitches/spec/show_deprecation.rb
 - lib/stitches/spec/test_headers.rb
 - lib/stitches/valid_mime_type.rb
 - lib/stitches/version.rb
 - lib/stitches/whitelisting_middleware.rb
 - lib/stitches_norailtie.rb
+- owners.json
 - spec/api_key_spec.rb
 - spec/api_version_constraint_spec.rb
 - spec/configuration_spec.rb
+- spec/deprecation_spec.rb
 - spec/error_spec.rb
 - spec/errors_spec.rb
+- spec/integration/add_to_rails_app_spec.rb
+- spec/spec/be_gone_spec.rb
 - spec/spec/have_api_error_spec.rb
+- spec/spec/show_deprecation_spec.rb
 - spec/spec_helper.rb
 - spec/valid_mime_type_spec.rb
 - stitches.gemspec
@@ -176,12 +204,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: You'll be in stitches at how easy it is to create a service at Stitch Fix
@@ -189,8 +217,12 @@ test_files:
 - spec/api_key_spec.rb
 - spec/api_version_constraint_spec.rb
 - spec/configuration_spec.rb
+- spec/deprecation_spec.rb
 - spec/error_spec.rb
 - spec/errors_spec.rb
+- spec/integration/add_to_rails_app_spec.rb
+- spec/spec/be_gone_spec.rb
 - spec/spec/have_api_error_spec.rb
+- spec/spec/show_deprecation_spec.rb
 - spec/spec_helper.rb
 - spec/valid_mime_type_spec.rb

data/Gemfile.lock

@@ -1,154 +0,0 @@
-PATH
-  remote: .
-  specs:
-    stitches (3.5.0)
-      apitome
-      pg
-      rails
-      rspec (>= 3)
-      rspec-rails (~> 3)
-
-GEM
-  remote: https://www.rubygems.org/
-  specs:
-    actioncable (5.1.3)
-      actionpack (= 5.1.3)
-      nio4r (~> 2.0)
-      websocket-driver (~> 0.6.1)
-    actionmailer (5.1.3)
-      actionpack (= 5.1.3)
-      actionview (= 5.1.3)
-      activejob (= 5.1.3)
-      mail (~> 2.5, >= 2.5.4)
-      rails-dom-testing (~> 2.0)
-    actionpack (5.1.3)
-      actionview (= 5.1.3)
-      activesupport (= 5.1.3)
-      rack (~> 2.0)
-      rack-test (~> 0.6.3)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.1.3)
-      activesupport (= 5.1.3)
-      builder (~> 3.1)
-      erubi (~> 1.4)
-      rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activejob (5.1.3)
-      activesupport (= 5.1.3)
-      globalid (>= 0.3.6)
-    activemodel (5.1.3)
-      activesupport (= 5.1.3)
-    activerecord (5.1.3)
-      activemodel (= 5.1.3)
-      activesupport (= 5.1.3)
-      arel (~> 8.0)
-    activesupport (5.1.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (~> 0.7)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-    apitome (0.1.0)
-      kramdown
-      railties
-      rspec_api_documentation
-    arel (8.0.0)
-    builder (3.2.3)
-    concurrent-ruby (1.0.5)
-    diff-lcs (1.3)
-    erubi (1.6.1)
-    globalid (0.4.0)
-      activesupport (>= 4.2.0)
-    i18n (0.8.6)
-    kramdown (1.14.0)
-    loofah (2.0.3)
-      nokogiri (>= 1.5.9)
-    mail (2.6.6)
-      mime-types (>= 1.16, < 4)
-    method_source (0.8.2)
-    mime-types (3.1)
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2016.0521)
-    mini_portile2 (2.2.0)
-    minitest (5.10.3)
-    mustache (1.0.5)
-    nio4r (2.1.0)
-    nokogiri (1.8.0)
-      mini_portile2 (~> 2.2.0)
-    pg (0.21.0)
-    rack (2.0.3)
-    rack-test (0.6.3)
-      rack (>= 1.0)
-    rails (5.1.3)
-      actioncable (= 5.1.3)
-      actionmailer (= 5.1.3)
-      actionpack (= 5.1.3)
-      actionview (= 5.1.3)
-      activejob (= 5.1.3)
-      activemodel (= 5.1.3)
-      activerecord (= 5.1.3)
-      activesupport (= 5.1.3)
-      bundler (>= 1.3.0)
-      railties (= 5.1.3)
-      sprockets-rails (>= 2.0.0)
-    rails-dom-testing (2.0.3)
-      activesupport (>= 4.2.0)
-      nokogiri (>= 1.6)
-    rails-html-sanitizer (1.0.3)
-      loofah (~> 2.0)
-    railties (5.1.3)
-      actionpack (= 5.1.3)
-      activesupport (= 5.1.3)
-      method_source
-      rake (>= 0.8.7)
-      thor (>= 0.18.1, < 2.0)
-    rake (12.0.0)
-    rspec (3.6.0)
-      rspec-core (~> 3.6.0)
-      rspec-expectations (~> 3.6.0)
-      rspec-mocks (~> 3.6.0)
-    rspec-core (3.6.0)
-      rspec-support (~> 3.6.0)
-    rspec-expectations (3.6.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.6.0)
-    rspec-mocks (3.6.0)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.6.0)
-    rspec-rails (3.6.0)
-      actionpack (>= 3.0)
-      activesupport (>= 3.0)
-      railties (>= 3.0)
-      rspec-core (~> 3.6.0)
-      rspec-expectations (~> 3.6.0)
-      rspec-mocks (~> 3.6.0)
-      rspec-support (~> 3.6.0)
-    rspec-support (3.6.0)
-    rspec_api_documentation (5.0.0)
-      activesupport (>= 3.0.0)
-      mustache (~> 1.0, >= 0.99.4)
-      rspec (~> 3.0)
-    sprockets (3.7.1)
-      concurrent-ruby (~> 1.0)
-      rack (> 1, < 3)
-    sprockets-rails (3.2.0)
-      actionpack (>= 4.0)
-      activesupport (>= 4.0)
-      sprockets (>= 3.0.0)
-    thor (0.20.0)
-    thread_safe (0.3.6)
-    tzinfo (1.2.3)
-      thread_safe (~> 0.1)
-    websocket-driver (0.6.5)
-      websocket-extensions (>= 0.1.0)
-    websocket-extensions (0.1.2)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  rake
-  stitches!
-
-BUNDLED WITH
-   1.15.3