appmap_swagger 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a33cef0212a7370171c60f0fc5729a7e5a68c7051647ff0abede311c6532a448
-  data.tar.gz: fb9b3b10b5cd1faa4128367174336682e328e87b7d6e5326081ff6c67bb336c2
+  metadata.gz: 87efac78c319723b4cd01a2682c5980a06030b1dde8c70f5ee5fadfeea534d8d
+  data.tar.gz: ddb457dbee27c3520a2e277436e591423966419ac3d68579e1a235c699520e9a
 SHA512:
-  metadata.gz: 41e31f98cde40c9cc6d0b7f7385d715aa7b5af0f24ecfca9ed22fce3bc62aad18395ab9cb3460745b376ea1b27323847c8b9fbf3026452214cdd02923ada29cd
-  data.tar.gz: e61e353925c1b5e1dc4d923133707335f4ccc94d49a7df83cf45e1637c657bae71fd11e5831e7cfb3c6f648d5e01c531879bbb1d5c78824eddf0bed38c88735a
+  metadata.gz: 5ca916e54814cc605b3f47c0b98e47c8cac5753057f6046a4c213ef18171749f7abb078572ea4292b17b3280f0872f4ddef7532ce2b3ecd51de1cad962d35ecb
+  data.tar.gz: 7c0c5a9aa40124e6774e810e03b3aad9674cb6e58523ba08a0af914939b2dab5fa0c33d72b660edb2d3e0d614ab7cc1418e99febd68c4548186f61db653515a0

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+# v0.2.0
+
+* Add `swagger:diff` task.
+
 # v0.1.2
 
 * Fix `verbose` behavior, and respect the `rake -v` flag. 

data/README.md

@@ -2,7 +2,14 @@
 
 This gem provides a Rake task called `swagger` that generates [Swagger 3](https://swagger.io/specification/) (aka OpenAPI) YAML from [AppMap](https://github.com/applandinc/appmap-ruby) data.
 
-It depends on an NPM package called [@appland/appmap-swagger](https://www.npmjs.com/package/@appland/appmap-swagger), which does most of the heavy lifting of converting AppMaps to Swagger. This gem adds the Rake task and some niceties such as Rails integration.
+It depends on an NPM package called [@appland/appmap-swagger](https://www.npmjs.com/package/@appland/appmap-swagger), which does most of the heavy lifting of converting AppMaps to Swagger.
+
+To the NPM package, this gem adds:
+
+* A Rake task - Normally configured as `appmap:swagger`.
+* Rails integration - For example, default configuration of the application name.
+* Swagger "diff" - Smart comparison of the current revision Swagger YAML to a base revision.
+
 
 # How it works
 
@@ -18,6 +25,12 @@ The Rake task `swagger`:
 
 `openapi_stable.yaml` is ideal for use in code reviews, to see if (and how) web services have been changed.
 
+The Rake task `swagger:diff`:
+
+1. Computes a smart "diff" between the current revision Swagger and base revision.
+2. Prints this diff in a user-friendly format, suitable for inclusion in a pull request or issue comment.
+
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -50,10 +63,42 @@ namespace :appmap do
       # You may not have a VERSION file. Do what works best for you.
       task.project_version = "v#{File.read(File.join(Rails.root, 'VERSION')).strip}"
     end
+
+    AppMap::Swagger::RakeDiffTask.new(:'swagger:diff', [ :base, :swagger_file ]).tap do |task|
+      # Default base; can be overridden by the :base task argument
+      task.base = 'remotes/origin/main'
+      # Default swagger file; can be overridden by the :swagger_file task argument
+      task.swagger_file = 'swagger/openapi_stable.yaml'
+    end
   end
 end
 ```
 
+## Example
+
+```sh-session
+$ ./bin/rake appmap:swagger:diff
+changed       @ info.version
+old value     : v0.22.0
+new value     : v0.22.1
+
+added         @ paths."/api/api_keys".delete.responses
+added key     : 200
+added value   : {"content"=>{"application/json"=>{}}}
+
+removed       @ paths."/scenarios/{id}".put.requestBody.content."application/json".schema.properties.scenario.properties
+removed key   : mapset
+removed value : {"type"=>"string"}
+
+removed       @ paths."/scenarios/{scenario_id}/save_as".post.requestBody.content."application/json".schema.properties.save_as.properties
+removed key   : feature
+removed value : {"type"=>"string"}
+
+removed       @ paths."/scenarios/{scenario_id}/save_as".post.requestBody.content."application/json".schema.properties.save_as.properties
+removed key   : feature_group
+removed value : {"type"=>"string"}
+```
+
 ## Incorporating the Swagger API and UI
 
 Two other gems work great with `appmap:swagger`: `rswag-api` and `rswag-ui` from [rswag](https://github.com/rswag/rswag).

data/appmap_swagger.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'rdoc'
   spec.add_dependency 'reverse_markdown'
   spec.add_dependency 'activesupport'
+  spec.add_dependency 'hashdiff'
 
   spec.add_development_dependency 'minitest'
 end

data/lib/appmap/swagger/rake_diff_task.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'rake'
+require 'rake/tasklib'
+require 'hashdiff'
+
+module AppMap
+  module Swagger
+    class RakeDiffTask < ::Rake::TaskLib
+      DEFAULT_BASE         = 'remotes/origin/main'
+      DEFAULT_GIT          = 'git'
+      DEFAULT_SWAGGER_FILE = 'swagger/openapi_stable.yaml'
+
+      attr_accessor :name, :git_command, :base, :swagger_file
+
+      Command = Struct.new(:git_command, :base, :swagger_file) do
+        def verbose
+          Rake.verbose == true
+        end
+  
+        def perform
+          do_fail = lambda do |msg|
+            warn msg
+            exit $?.exitstatus || 1
+          end
+  
+          return do_fail.(%Q('#{git_command}' not found; please install git)) unless system('git --version 2>&1 > /dev/null')
+
+          fetch_command = 'git fetch'
+          warn fetch_command if verbose
+          do_fail.(%Q(#{fetch_command} failed)) unless system(fetch_command)
+
+          show_command = %Q(git show #{base}:#{swagger_file})
+          warn show_command if verbose
+          base_content = `#{show_command}`
+          do_fail.(%Q(#{show_command} failed)) unless $?.exitstatus == 0
+
+          base_content = YAML.load(base_content)
+          head_content = YAML.load(File.read(swagger_file))
+
+          format_path = lambda do |tokens|
+            tokens.map do |token|
+              if token =~ /^[a-zA-Z0-9_-]+$/
+                token
+              else
+                %Q("#{token}")
+              end
+            end.join('.')
+          end
+
+          format_change = lambda do |entry|
+            path, old_v, new_v = entry
+            [
+              "changed       @ #{format_path.call path.split('.')}",
+              "old value     : #{old_v}",
+              "new value     : #{new_v}" 
+            ].join("\n")
+          end
+
+          format_deletion = lambda do |entry|
+            path, old_v = entry
+            path_tokens = path.split('.')
+            removed_key = path_tokens.pop
+            [
+              "removed       @ #{format_path.call path_tokens}",
+              "removed key   : #{removed_key}",
+              "removed value : #{old_v}" 
+            ].join("\n")
+          end
+
+          format_addition = lambda do |entry|
+            path, new_v = entry
+            path_tokens = path.split('.')
+            added_key = path_tokens.pop
+            [
+              "added         @ #{format_path.call path_tokens}",
+              "added key     : #{added_key}",
+              "added value   : #{new_v}" 
+            ].join("\n")
+          end
+
+          formatters = {
+            '~' => format_change,
+            '-' => format_deletion,
+            '+' => format_addition,
+          }
+
+          diff = Hashdiff.diff(base_content, head_content)
+          diff.each_with_index do |entry, index|
+            puts unless index == 0
+            warn YAML.dump(entry) if verbose
+            puts formatters[entry[0]].(entry[1..-1])
+          end
+        end
+      end
+
+      def initialize(*args, &task_block)
+        @name         = args.shift || :'swagger:diff'
+        @git_command  = DEFAULT_GIT
+        @base         = DEFAULT_BASE
+        @swagger_file = DEFAULT_SWAGGER_FILE
+
+        define(args, &task_block)
+      end
+
+      private
+
+      # This bit of black magic - https://github.com/rspec/rspec-core/blob/main/lib/rspec/core/rake_task.rb#L110
+      def define(args, &task_block)
+        desc "Generate Swagger from AppMaps" unless ::Rake.application.last_description
+
+        task(name, *args) do |_, task_args|
+          RakeFileUtils.__send__(:verbose, Rake.verbose == true) do
+            task_block.call(*[self, task_args].slice(0, task_block.arity)) if task_block
+            Command.new(:git_command).tap do |cmd|
+              cmd.base = task_args[:base] || self.base
+              cmd.swagger_file = task_args[:swagger_file] || self.swagger_file
+            end.perform
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appmap/swagger/rake_task.rb

@@ -43,12 +43,12 @@ module AppMap
         FileUtils.mkdir_p output_dir
 
         do_fail = lambda do |msg|
-          warn msg if verbose
+          warn msg
           exit $?.exitstatus || 1
         end
 
         return do_fail.(%Q('node' not found; please install NodeJS)) unless system('node --version 2>&1 > /dev/null')
-        return do_fail.(%Q('#{swaggergen}' not found; please install appmap-swagger from NPM)) unless File.exists?(swaggergen)
+        return do_fail.(%Q('#{swaggergen}' not found; please install @appland/appmap-swagger from NPM)) unless File.exists?(swaggergen)
 
         warn swagger_command.join(' ') if verbose
 

data/lib/appmap/swagger/version.rb

@@ -1,5 +1,5 @@
 module AppMap
   module Swagger
-    VERSION = "0.1.2"
+    VERSION = "0.2.0"
   end
 end

data/lib/appmap_swagger.rb

@@ -1,2 +1,3 @@
 require 'appmap/swagger/version'
 require 'appmap/swagger/rake_task'
+require 'appmap/swagger/rake_diff_task'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appmap_swagger
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Kevin Gilpin
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-04-02 00:00:00.000000000 Z
+date: 2021-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: hashdiff
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -98,6 +112,7 @@ files:
 - bin/console
 - bin/setup
 - lib/appmap/swagger/markdown_descriptions.rb
+- lib/appmap/swagger/rake_diff_task.rb
 - lib/appmap/swagger/rake_task.rb
 - lib/appmap/swagger/stable.rb
 - lib/appmap/swagger/version.rb