json-schema-diff 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1aea7e4fe80d247f0391631e587a149d622839d7b78b99443e334eea7c422df1
-  data.tar.gz: 4a9aeceeb2c7d356306cb237c03f8710eb4bd8291d010f583e2d1bb433110046
+  metadata.gz: 114ad725bbe219e05ad01ecbb7f419cf47a9d6e0e0861a3f65259ffe5ba08954
+  data.tar.gz: 34aa2c647ac5e9b6443788328af81dc8b26143641891e34d53b7cd732e711eb2
 SHA512:
-  metadata.gz: 86c942503b94f7ab01c896fabefa07e9def0701daabff6bf17725dbf9e148c49282293a95e52ebb06a9ee941905c767124134a38243533591bab35b1a59a06c0
-  data.tar.gz: 5ef4bbfcf3fc8957ec04800a8ea3ea3c3696553dec7f746050194ef6e241c8b55170cfbc87b0505c6238f0af4c5bccef205fe571b451d22cf9f27dcae0727e79
+  metadata.gz: a26c6bd182618f38904058a803235b897257263fb012074fb609ba5c11b00835809cdf13fe1e0f963a00a5fb555c9a3cbd5eaebe8d41a43cb976deea839eefdf
+  data.tar.gz: c657e645bcbe47ad82a46c527b09a0013838569f807674b66af106c5b94ffebdb4b100b3573c4727354240e2b1b1b430601d77de8308bfec5266cfe69b70c7ca

data/CHANGELOG.md

@@ -7,6 +7,35 @@ 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
+
+- JSON Schema validation capabilities with `json-schema` gem dependency
+- New CLI options for validation control:
+  - `--[no-]validate` for JSON Schema format validation (enabled by default)
+  - `--[no-]validate-json` for JSON content validation against schema (disabled by default)
+- Comprehensive error handling for invalid schemas and JSON validation failures
+- Schema structure validation with clear error messages for malformed schemas
+- Type checking validation ensuring JSON data types match schema expectations
+- Required field validation for object schemas
+- Fallback validation approach for complex schemas with external references
+
+### Changed
+
+- Updated `json-schema` dependency to version ~> 5.0 for improved performance and compatibility
+- Removed `bigdecimal` dependency (no longer needed with json-schema v5)
+- Enhanced error messages with specific validation failure details
+
 ## [0.1.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.
@@ -60,6 +61,19 @@ json-schema-diff --format json schema.json old.json new.json
 json-schema-diff --no-color schema.json old.json new.json
 ```
 
+### Validation Options
+
+```bash
+# Enable JSON validation against schema (helps catch data format errors)
+json-schema-diff --validate-json schema.json old.json new.json
+
+# Disable schema format validation (for malformed schemas)
+json-schema-diff --no-validate schema.json old.json new.json
+
+# Both validation options
+json-schema-diff --validate-json --validate schema.json old.json new.json
+```
+
 ### Ignoring Fields
 
 ```bash
@@ -83,6 +97,8 @@ Options:
   -f, --format FORMAT          Output format (pretty, json)
   -i, --ignore-fields FIELDS   Comma-separated list of field paths to ignore
       --[no-]color             Enable/disable colored output (default: enabled)
+      --[no-]validate          Enable/disable JSON Schema format validation (default: enabled)
+      --[no-]validate-json     Enable/disable JSON validation against schema (default: disabled)
   -h, --help                   Show help message
   -v, --version                Show version
 ```

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)
           
@@ -20,12 +33,18 @@ module Json
           schema_file, old_file, new_file = args
 
           begin
-            schema = SchemaParser.new(schema_file)
+            schema = SchemaParser.new(schema_file, validate_schema: options[:validate])
             comparer = Comparer.new(schema, options[:ignore_fields] || [])
             
             old_json = JSON.parse(File.read(old_file))
             new_json = JSON.parse(File.read(new_file))
             
+            # Validate JSON files against schema if requested
+            if options[:validate_json]
+              schema.validate_json(old_json)
+              schema.validate_json(new_json)
+            end
+            
             diff_result = comparer.compare(old_json, new_json)
             
             formatter = Formatter.new(options[:format], options[:color])
@@ -44,11 +63,18 @@ 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",
             color: true,
-            ignore_fields: []
+            ignore_fields: [],
+            validate: true,
+            validate_json: false
           }
 
           parser = OptionParser.new do |opts|
@@ -77,6 +103,14 @@ module Json
               options[:color] = color
             end
 
+            opts.on("--[no-]validate", "Enable/disable JSON Schema format validation (default: enabled)") do |validate|
+              options[:validate] = validate
+            end
+
+            opts.on("--[no-]validate-json", "Enable/disable JSON validation against schema (default: disabled)") do |validate_json|
+              options[:validate_json] = validate_json
+            end
+
             opts.on("-h", "--help", "Show this help message") do
               puts opts
               exit 0

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,17 +3,67 @@
 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
 
-        def initialize(schema_file)
+        # 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))
+          
+          if validate_schema
+            validate_basic_schema_structure!
+          end
         rescue JSON::ParserError => e
           raise Error, "Invalid JSON schema: #{e.message}"
         rescue Errno::ENOENT => e
           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
+            # Basic check - if schema has type "array", JSON should be array, etc.
+            if @schema["type"] == "array" && !json_data.is_a?(Array)
+              raise Error, "JSON validation failed: Expected array but got #{json_data.class.name.downcase}"
+            elsif @schema["type"] == "object" && !json_data.is_a?(Hash)
+              raise Error, "JSON validation failed: Expected object but got #{json_data.class.name.downcase}"
+            end
+            
+            # If we have required fields in schema, check they exist in JSON
+            if @schema["required"] && json_data.is_a?(Hash)
+              missing_fields = @schema["required"] - json_data.keys
+              unless missing_fields.empty?
+                raise Error, "JSON validation failed: Missing required fields: #{missing_fields.join(', ')}"
+              end
+            end
+            
+            true
+          rescue StandardError => e
+            raise Error, "JSON validation error: #{e.message}"
+          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
@@ -28,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]
@@ -49,6 +107,26 @@ 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)
+            raise Error, "Schema must be a JSON object"
+          end
+          
+          # Check for basic schema structure
+          if @schema["type"].nil? && @schema["properties"].nil? && @schema["items"].nil?
+            raise Error, "Schema appears to be missing basic JSON Schema structure (no type, properties, or items)"
+          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.1.0"
+      VERSION = "0.2.1"
     end
   end
 end

data/lib/json/schema/diff.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "json-schema"
 require "optparse"
 require_relative "diff/version"
 require_relative "diff/cli"
@@ -8,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,14 +1,28 @@
 --- !ruby/object:Gem::Specification
 name: json-schema-diff
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Andrew Nesbitt
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
 description: A Ruby gem that performs semantic diffs between JSON files, using JSON
   Schema to guide and annotate the diff output with type information, field metadata,
   and structured change detection.
@@ -50,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