Merge branch 'kpaulisse-release-1-0-doc' into kpaulisse-script-integration

Author: Kevin Paulisse

.version

@@ -1 +1 @@
-0.6.1
+0.99.rc1

README.md

@@ -8,7 +8,7 @@ At GitHub, we manage thousands of nodes with a Puppet code base containing 500,0
 
 `octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
 
-It is under active development at this time. We suspect that with the initial release, some people who try it out could be using configurations of Puppet that we haven't experienced within our environment. We are eager to identify and fix as many of these as we can to expand the compatibility of this tool as much as possible.
+We consider the 1.x release of `octocatalog-diff` to be stable and production-quality. We continue to maintain and enhance `octocatalog-diff` to meet our own internal needs and to incorporate suggestions from the community. Please consult the [change log](/doc/CHANGELOG.md) for details.
 
 ## How?
 

doc/CHANGELOG.md

@@ -8,6 +8,22 @@
 </tr>
 </thead><tbody>
 <tr valign=top>
+<td>0.99.0rc1</td>
+<td>2017-xx-xx</td>
+<td>
+This is a release candidate for `octocatalog-diff` version 1.0. Please use caution before using this in a production environment. Report any problems to us as <a href="https://github.com/github/octocatalog-diff/issues/new">in a new issue</a>.
+
+<h4>New Features</h4>
+
+The most significant change in version 1.0 is the addition of the <a href="./dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should also improve the reliability and allow faster development cycles.
+
+<h4>Breaking Changes</h4>
+
+The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> if anyone depends upon the output in the old format.
+
+</td>
+</tr>
+<tr valign=top>
 <td>0.6.1</td>
 <td>2017-01-07</td>
 <td>

doc/dev/api.md

@@ -2,4 +2,4 @@
 
 The octocatalog-diff API allows developers to construct and work with certain octocatalog-diff internals in their own projects.
 
-The current API version is [API v1](/doc/dev/api/v1.md), which is available as of octocatalog-diff version 0.7.
+The current API version is [API v1](/doc/dev/api/v1.md), which is available as of octocatalog-diff version 1.0.

doc/dev/api/v1/objects/diff.md

@@ -44,6 +44,10 @@ Note that this is a pass-through of information provided in the Puppet catalog,
 
 Note also that if the diff represents removal of a resource, this will return `nil`, because the resource does not exist in the new catalog.
 
+#### `#new_location` (Hash)
+
+Returns a hash containing `:file` (equal to `#new_file`) and `:line` (equal to `#new_line`) when either is defined. Returns `nil` if both are undefined.
+
 #### `#new_value` (Object)
 
 Returns the value of the resource from the new catalog.
@@ -111,6 +115,10 @@ Note that this is a pass-through of information provided in the Puppet catalog,
 
 Note also that if the diff represents addition of a resource, this will return `nil`, because the resource does not exist in the old catalog.
 
+#### `#old_location` (Hash)
+
+Returns a hash containing `:file` (equal to `#old_file`) and `:line` (equal to `#old_line`) when either is defined. Returns `nil` if both are undefined.
+
 #### `#old_value` (Object)
 
 Returns the value of the resource from the old catalog.
@@ -249,4 +257,5 @@ These methods are available for debugging or development purposes but are not gu
 - `#inspect` (String): Returns inspection of object
 - `#raw` (Array): Returns internal array data structure of the "diff"
 - `#to_h` (Hash): Returns object as a hash, where keys are above described methods
+- `#to_h_with_string_keys` (Hash): Returns object as a hash, where keys are above described methods; keys are strings, not symbols
 - `#[]` (Object): Retrieve indexed array elements from raw internal array object

doc/optionsref.md

@@ -27,7 +27,7 @@ Usage: octocatalog-diff [command line options]
         --bootstrap-then-exit        Bootstrap from-dir and/or to-dir and then exit
         --[no-]color                 Enable/disable colors in output
     -o, --output-file FILENAME       Output results into FILENAME
-        --output-format FORMAT       Output format: text,json
+        --output-format FORMAT       Output format: text,json,legacy_json
     -d, --[no-]debug                 Print debugging messages to STDERR
     -q, --[no-]quiet                 Quiet (no status messages except errors)
         --ignore "Type1[Title1],Type2[Title2],..."
@@ -708,10 +708,12 @@ to ignore any changes for any defined type where this tag is set. (<a href="../l
       <pre><code>--output-format FORMAT</code></pre>
     </td>
     <td valign=top>
-      Output format: text,json
+      Output format: text,json,legacy_json
     </td>
     <td valign=top>
-      Output format option (<a href="../lib/octocatalog-diff/cli/options/output_format.rb">output_format.rb</a>)
+      Output format option. 'text' is human readable text, 'json' is an array of differences
+identified by human readable keys (the preferred octocatalog-diff 1.x format), and 'legacy_json' is an
+array of differences, where each difference is an array (the octocatalog-diff 0.x format). (<a href="../lib/octocatalog-diff/cli/options/output_format.rb">output_format.rb</a>)
     </td>
   </tr>
 

lib/octocatalog-diff/api/v1/diff.rb

@@ -22,8 +22,13 @@ class Diff
         # Constructor: Accepts a diff in the traditional array format and stores it.
         # @param raw [Array] Diff in the traditional format
         def initialize(raw)
+          if raw.is_a?(OctocatalogDiff::API::V1::Diff)
+            @raw = raw.raw
+            return
+          end
+
           unless raw.is_a?(Array)
-            raise ArgumentError, 'OctocatalogDiff::API::V1::Diff#initialize expects Array argument'
+            raise ArgumentError, "OctocatalogDiff::API::V1::Diff#initialize expects Array argument (got #{raw.class})"
           end
           @raw = raw
         end
@@ -119,6 +124,22 @@ def new_line
           x.nil? ? nil : x['line']
         end
 
+        # Public: Get the "old" location, i.e. location in the "from" catalog
+        # @return [Hash] <file:, line:> of resource
+        def old_location
+          return nil if addition?
+          return @raw[3] if removal?
+          @raw[4]
+        end
+
+        # Public: Get the "new" location, i.e. location in the "to" catalog
+        # @return [Hash] <file:, line:> of resource
+        def new_location
+          return @raw[3] if addition?
+          return nil if removal?
+          @raw[5]
+        end
+
         # Public: Convert this object to a hash
         # @return [Hash] Hash with keys set by these methods
         def to_h
@@ -132,10 +153,20 @@ def to_h
             old_file: old_file,
             old_line: old_line,
             new_file: new_file,
-            new_line: new_line
+            new_line: new_line,
+            old_location: old_location,
+            new_location: new_location
           }
         end
 
+        # Public: Convert this object to a hash with string keys
+        # @return [Hash] Hash with keys set by these methods, with string keys
+        def to_h_with_string_keys
+          result = {}
+          to_h.each { |key, val| result[key.to_s] = val }
+          result
+        end
+
         # Public: String inspection
         # @return [String] String for inspection
         def inspect
@@ -147,24 +178,6 @@ def inspect
         def to_s
           raw.inspect
         end
-
-        private
-
-        # Private: Get the "old" location, i.e. location in the "from" catalog
-        # @return [Hash] <file:, line:> of resource
-        def old_location
-          return nil if addition?
-          return @raw[3] if removal?
-          @raw[4]
-        end
-
-        # Private: Get the "new" location, i.e. location in the "to" catalog
-        # @return [Hash] <file:, line:> of resource
-        def new_location
-          return @raw[3] if addition?
-          return nil if removal?
-          @raw[5]
-        end
       end
     end
   end

lib/octocatalog-diff/catalog-diff/display.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require_relative '../api/v1/diff'
 require_relative 'differ'
 require_relative 'display/json'
+require_relative 'display/legacy_json'
 require_relative 'display/text'
 
 module OctocatalogDiff
@@ -21,8 +23,9 @@ class Display
       # @param logger [Logger] Logger object
       # @return [String] Text output for provided diff
       def self.output(diff_in, options = {}, logger = nil)
-        diff = diff_in.is_a?(OctocatalogDiff::CatalogDiff::Differ) ? diff_in.diff : diff_in
-        raise ArgumentError, "text_output requires Array<Diff results>; passed in #{diff_in.class}" unless diff.is_a?(Array)
+        diff_x = diff_in.is_a?(OctocatalogDiff::CatalogDiff::Differ) ? diff_in.diff : diff_in
+        raise ArgumentError, "text_output requires Array<Diff results>; passed in #{diff_in.class}" unless diff_x.is_a?(Array)
+        diff = diff_x.map { |x| OctocatalogDiff::API::V1::Diff.new(x) }
 
         # req_format means 'requested format' because 'format' has a built-in meaning to Ruby
         req_format = options.fetch(:format, :color_text)
@@ -41,6 +44,9 @@ def self.output(diff_in, options = {}, logger = nil)
         when :json
           logger.debug 'Generating JSON output' if logger
           OctocatalogDiff::CatalogDiff::Display::Json.generate(diff, opts, logger)
+        when :legacy_json
+          logger.debug 'Generating Legacy JSON output' if logger
+          OctocatalogDiff::CatalogDiff::Display::LegacyJson.generate(diff, opts, logger)
         when :text
           logger.debug 'Generating non-colored text output' if logger
           OctocatalogDiff::CatalogDiff::Display::Text.generate(diff, opts.merge(color: false), logger)

lib/octocatalog-diff/catalog-diff/display/json.rb

@@ -7,7 +7,8 @@
 module OctocatalogDiff
   module CatalogDiff
     class Display
-      # Display the output from a diff in JSON format.
+      # Display the output from a diff in JSON format. This is the new format, used in octocatalog-diff
+      # 1.x, where each diff is represented by an hash with named keys.
       class Json < OctocatalogDiff::CatalogDiff::Display
         # Generate JSON representation of the 'diff' suitable for further analysis.
         # @param diff [Array<Diff results>] The diff which *must* be in this format
@@ -16,7 +17,7 @@ class Json < OctocatalogDiff::CatalogDiff::Display
         # @param _logger [Logger] Not used here
         def self.generate(diff, options = {}, _logger = nil)
           result = {
-            'diff' => diff
+            'diff' => diff.map(&:to_h_with_string_keys)
           }
           result['header'] = options[:header] unless options[:header].nil?
           result.to_json

lib/octocatalog-diff/catalog-diff/display/legacy_json.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative '../display'
+
+require 'json'
+
+module OctocatalogDiff
+  module CatalogDiff
+    class Display
+      # Display the output from a diff in JSON format. This is the legacy format, used in octocatalog-diff
+      # 0.x, where each diff is represented by an array.
+      class LegacyJson < OctocatalogDiff::CatalogDiff::Display
+        # Generate JSON representation of the 'diff' suitable for further analysis.
+        # @param diff [Array<Diff results>] The diff which *must* be in this format
+        # @param options [Hash] Options which are:
+        #           - :header => [String] Header to print; no header is printed if not specified
+        # @param _logger [Logger] Not used here
+        def self.generate(diff, options = {}, _logger = nil)
+          result = {
+            'diff' => diff.map(&:raw)
+          }
+          result['header'] = options[:header] unless options[:header].nil?
+          result.to_json
+        end
+      end
+    end
+  end
+end