json-schema-diff 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 05eac26b2e1df57105bd4adddc22d72062db1450b442a393a3af227393ec47d6
-  data.tar.gz: 6accbbf59486d9ed5ee7b4a725dfb751e3d71038885eefddb5f12bf3071fb8e4
+  metadata.gz: 114ad725bbe219e05ad01ecbb7f419cf47a9d6e0e0861a3f65259ffe5ba08954
+  data.tar.gz: 34aa2c647ac5e9b6443788328af81dc8b26143641891e34d53b7cd732e711eb2
 SHA512:
-  metadata.gz: 2bfaabdb040888fe7e908a7a52fdf66f6904b506df445c634ec5e14870799c0d80657c1dde023ecdb6d249286926627531152b5d7ef51efa0da6a38e23589f4d
-  data.tar.gz: 43356130be48c1566844f3af16a66bb4247ffc053073c3eacc51526949cceeb19fc9e2539df200f6dae5bc8be2d4a478254a47f87014273f464a0effcc644e49
+  metadata.gz: a26c6bd182618f38904058a803235b897257263fb012074fb609ba5c11b00835809cdf13fe1e0f963a00a5fb555c9a3cbd5eaebe8d41a43cb976deea839eefdf
+  data.tar.gz: c657e645bcbe47ad82a46c527b09a0013838569f807674b66af106c5b94ffebdb4b100b3573c4727354240e2b1b1b430601d77de8308bfec5266cfe69b70c7ca

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-01-26
+
+### Added
+
+- Comprehensive RDoc documentation for all classes and methods
+- API documentation with @param and @return annotations
+- Documentation URI in gemspec pointing to rubydoc.info
+- Documentation badge in README
+
 ## [0.2.0] - 2025-01-26
 
 ### Added

data/README.md

@@ -4,6 +4,7 @@ A Ruby gem that performs semantic diffs between JSON files, using JSON Schema to
 
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org/)
 [![Gem Version](https://badge.fury.io/rb/json-schema-diff.svg)](https://rubygems.org/gems/json-schema-diff)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/json-schema-diff)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 Perfect for comparing structured CLI output from security tools like zizmor and capslock across versions to highlight when security issues have been introduced or resolved.

data/lib/json/schema/diff/cli.rb

@@ -3,11 +3,24 @@
 module Json
   module Schema
     module Diff
+      # Command-line interface for json-schema-diff
+      #
+      # Provides a comprehensive CLI for comparing JSON files using JSON Schema guidance.
+      # Supports multiple output formats, validation options, and field filtering.
       class CLI
+        # Entry point for the CLI application
+        #
+        # @param args [Array<String>] Command-line arguments
+        # @return [void]
         def self.start(args)
           new.run(args)
         end
 
+        # Runs the CLI with the provided arguments
+        #
+        # @param args [Array<String>] Command-line arguments including schema, old JSON, and new JSON files
+        # @return [void]
+        # @raise [SystemExit] Exits with status 1 on errors
         def run(args)
           options = parse_options(args)
           
@@ -50,6 +63,11 @@ module Json
 
         private
 
+        # Parses command-line options and arguments
+        #
+        # @param args [Array<String>] Command-line arguments to parse
+        # @return [Hash] Parsed options hash
+        # @raise [SystemExit] Exits on invalid options or help/version requests
         def parse_options(args)
           options = {
             format: "pretty",

data/lib/json/schema/diff/comparer.rb

@@ -3,12 +3,25 @@
 module Json
   module Schema
     module Diff
+      # Compares two JSON objects using schema guidance to detect changes
+      #
+      # This class performs recursive comparison of JSON structures, using schema
+      # information to provide context and handle special cases like read-only fields.
       class Comparer
+        # Initialize a new Comparer
+        #
+        # @param schema_parser [SchemaParser] Parser for the JSON Schema
+        # @param ignore_fields [Array<String>] List of field paths to ignore during comparison
         def initialize(schema_parser, ignore_fields = [])
           @schema_parser = schema_parser
           @ignore_fields = ignore_fields.map(&:to_s)
         end
 
+        # Compares two JSON objects and returns a list of changes
+        #
+        # @param old_json [Object] The original JSON data
+        # @param new_json [Object] The new JSON data to compare against
+        # @return [Array<Hash>] Array of change objects with metadata
         def compare(old_json, new_json)
           changes = []
           compare_recursive(old_json, new_json, "", changes)

data/lib/json/schema/diff/formatter.rb

@@ -3,7 +3,12 @@
 module Json
   module Schema
     module Diff
+      # Formats diff results into human-readable or machine-readable output
+      #
+      # Supports both pretty-printed colorized output for humans and JSON output for machines.
+      # Handles ANSI color codes and provides structured formatting of change information.
       class Formatter
+        # ANSI color codes for terminal output
         COLORS = {
           red: "\e[31m",
           green: "\e[32m",
@@ -14,11 +19,19 @@ module Json
           reset: "\e[0m"
         }.freeze
 
+        # Initialize a new Formatter
+        #
+        # @param format [String] Output format - "pretty" or "json" (default: "pretty")
+        # @param use_color [Boolean] Whether to use ANSI color codes (default: true)
         def initialize(format = "pretty", use_color = true)
           @format = format
           @use_color = use_color
         end
 
+        # Formats an array of changes into the specified output format
+        #
+        # @param changes [Array<Hash>] Array of change objects from Comparer
+        # @return [String] Formatted output string
         def format(changes)
           case @format
           when "json"

data/lib/json/schema/diff/schema_parser.rb

@@ -3,9 +3,19 @@
 module Json
   module Schema
     module Diff
+      # Parses and validates JSON Schema files, extracting field metadata for diff guidance
+      #
+      # This class handles loading JSON Schema files, validating their structure,
+      # and providing methods to extract field information and detect noisy fields.
       class SchemaParser
+        # @return [Hash] The parsed JSON Schema
         attr_reader :schema
 
+        # Initialize a new SchemaParser with a JSON Schema file
+        #
+        # @param schema_file [String] Path to the JSON Schema file
+        # @param validate_schema [Boolean] Whether to validate the schema structure (default: true)
+        # @raise [Error] If the schema file is invalid or not found
         def initialize(schema_file, validate_schema: true)
           @schema = JSON.parse(File.read(schema_file))
           
@@ -18,6 +28,14 @@ module Json
           raise Error, "Schema file not found: #{e.message}"
         end
 
+        # Validates JSON data against the schema
+        #
+        # Performs basic structural validation to ensure JSON data types match schema expectations
+        # and required fields are present.
+        #
+        # @param json_data [Object] The JSON data to validate
+        # @return [Boolean] True if validation passes
+        # @raise [Error] If validation fails
         def validate_json(json_data)
           # Simple structural validation - check if JSON structure roughly matches schema expectations
           begin
@@ -42,6 +60,10 @@ module Json
           end
         end
 
+        # Gets field information from the schema for a given path
+        #
+        # @param path [String] Dot-separated path to the field (e.g., "user.profile.name")
+        # @return [Hash] Field information including type, title, description, format, enum, and read_only
         def get_field_info(path)
           field_schema = traverse_schema(path.split('.'))
           return {} unless field_schema
@@ -56,6 +78,14 @@ module Json
           }
         end
 
+        # Determines if a field is considered "noisy" and should potentially be ignored
+        #
+        # Noisy fields are those that change frequently but aren't meaningful for comparison,
+        # such as timestamps, UUIDs, or fields marked as readOnly in the schema.
+        #
+        # @param path [String] Dot-separated path to the field
+        # @param value [Object] The field value
+        # @return [Boolean] True if the field is considered noisy
         def is_noisy_field?(path, value)
           field_info = get_field_info(path)
           format = field_info[:format]
@@ -77,6 +107,10 @@ module Json
 
         private
 
+        # Validates that the schema has basic JSON Schema structure
+        #
+        # @return [void]
+        # @raise [Error] If the schema is missing basic structure
         def validate_basic_schema_structure!
           # Basic structural validation for schema
           unless @schema.is_a?(Hash)
@@ -89,6 +123,10 @@ module Json
           end
         end
 
+        # Traverses the schema following a path to find field-specific schema information
+        #
+        # @param path_parts [Array<String>] Array of path components
+        # @return [Hash, nil] Schema for the field at the path, or nil if not found
         def traverse_schema(path_parts)
           current = @schema
           

data/lib/json/schema/diff/version.rb

@@ -3,7 +3,7 @@
 module Json
   module Schema
     module Diff
-      VERSION = "0.2.0"
+      VERSION = "0.2.1"
     end
   end
 end

data/lib/json/schema/diff.rb

@@ -9,9 +9,25 @@ require_relative "diff/schema_parser"
 require_relative "diff/comparer"
 require_relative "diff/formatter"
 
+# JSON Schema Diff provides semantic diffing capabilities for JSON files using JSON Schema metadata.
+#
+# This gem allows you to compare two JSON files and get a rich diff output that is guided by
+# a JSON Schema, providing type information, field metadata, and structured change detection.
+#
+# @example Basic usage
+#   Json::Schema::Diff::CLI.start(['schema.json', 'old.json', 'new.json'])
+#
+# @example Programmatic usage
+#   schema = Json::Schema::Diff::SchemaParser.new('schema.json')
+#   comparer = Json::Schema::Diff::Comparer.new(schema)
+#   diff = comparer.compare(old_data, new_data)
+#   formatter = Json::Schema::Diff::Formatter.new('pretty')
+#   puts formatter.format(diff)
 module Json
   module Schema
+    # The Diff module contains all functionality for JSON Schema-guided diffing
     module Diff
+      # Base error class for all JSON Schema Diff errors
       class Error < StandardError; end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json-schema-diff
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Nesbitt
@@ -64,6 +64,7 @@ metadata:
   homepage_uri: https://github.com/andrew/json-schema-diff
   source_code_uri: https://github.com/andrew/json-schema-diff
   changelog_uri: https://github.com/andrew/json-schema-diff/blob/main/CHANGELOG.md
+  documentation_uri: https://rubydoc.info/gems/json-schema-diff
 rdoc_options: []
 require_paths:
 - lib