jsonc-merge 1.0.0

data/lib/jsonc/merge.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+# std libs
+require "set"
+
+# External gems
+# TreeHaver provides a unified cross-Ruby interface to tree-sitter.
+# It handles grammar discovery and backend selection automatically
+# via parser_for(:jsonc). No manual registration needed.
+require "tree_haver"
+require "version_gem"
+
+# Shared merge infrastructure
+require "ast/merge"
+
+# This gem
+require_relative "merge/version"
+
+# Jsonc::Merge provides a generic JSONC file smart merge system using tree-sitter AST analysis.
+# It intelligently merges template and destination JSON/JSONC files by identifying matching
+# keys and resolving differences using structural signatures.
+#
+# JSONC (JSON with Comments) support allows merging configuration files that include
+# comments (like devcontainer.json, tsconfig.json, VS Code settings, etc.).
+#
+# @example Basic usage
+#   template = File.read("template.json")
+#   destination = File.read("destination.json")
+#   merger = Jsonc::Merge::SmartMerger.new(template, destination)
+#   result = merger.merge
+#
+# @example With debug information
+#   merger = Jsonc::Merge::SmartMerger.new(template, destination)
+#   debug_result = merger.merge_with_debug
+#   puts debug_result[:content]
+#   puts debug_result[:statistics]
+module Jsonc
+  # Smart merge system for JSONC files using tree-sitter AST analysis.
+  # Provides intelligent merging by understanding JSON structure
+  # rather than treating files as plain text.
+  #
+  # @see SmartMerger Main entry point for merge operations
+  # @see FileAnalysis Analyzes JSON structure
+  # @see ConflictResolver Resolves content conflicts
+  module Merge
+    # Base error class for Jsonc::Merge
+    # Inherits from Ast::Merge::Error for consistency across merge gems.
+    class Error < Ast::Merge::Error; end
+
+    # Raised when a JSON/JSONC file has parsing errors.
+    # Inherits from Ast::Merge::ParseError for consistency across merge gems.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     analysis = FileAnalysis.new(json_content)
+    #   rescue ParseError => e
+    #     puts "JSON syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error}" }
+    #   end
+    class ParseError < Ast::Merge::ParseError
+      # @param message [String, nil] Error message (auto-generated if nil)
+      # @param content [String, nil] The JSON source that failed to parse
+      # @param errors [Array] Parse errors from tree-sitter
+      def initialize(message = nil, content: nil, errors: [])
+        super(message, errors: errors, content: content)
+      end
+    end
+
+    # Raised when the template file has syntax errors.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class DestinationParseError < ParseError; end
+
+    autoload :CommentTracker, "jsonc/merge/comment_tracker"
+    autoload :DebugLogger, "jsonc/merge/debug_logger"
+    autoload :Emitter, "jsonc/merge/emitter"
+    autoload :FreezeNode, "jsonc/merge/freeze_node"
+    autoload :FileAnalysis, "jsonc/merge/file_analysis"
+    autoload :MergeResult, "jsonc/merge/merge_result"
+    autoload :NodeWrapper, "jsonc/merge/node_wrapper"
+    autoload :ConflictResolver, "jsonc/merge/conflict_resolver"
+    autoload :SmartMerger, "jsonc/merge/smart_merger"
+  end
+end
+
+# Register with ast-merge's MergeGemRegistry for RSpec dependency tags
+# Only register if MergeGemRegistry is loaded (i.e., in test environment)
+if defined?(Ast::Merge::RSpec::MergeGemRegistry)
+  Ast::Merge::RSpec::MergeGemRegistry.register(
+    :jsonc_merge,
+    require_path: "jsonc/merge",
+    merger_class: "Jsonc::Merge::SmartMerger",
+    test_source: "// comment\n{\"key\": \"value\"}",
+    category: :data,
+  )
+end
+
+Jsonc::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/jsonc-merge.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "jsonc/merge"

data/sig/json/merge.rbs

@@ -0,0 +1,259 @@
+# Type signatures for json-merge gem
+# Smart merge for JSON/JSONC files using tree-sitter AST analysis
+
+module Json
+  module Merge
+    VERSION: String
+
+    # Base error class for json-merge errors
+    class Error < StandardError
+    end
+
+    # Error raised when template JSON file has syntax errors
+    class TemplateParseError < Error
+      attr_reader errors: Array[untyped]
+      attr_reader content: String?
+
+      def initialize: (?String? message, ?errors: Array[untyped], ?content: String?) -> void
+    end
+
+    # Error raised when destination JSON file has syntax errors
+    class DestinationParseError < Error
+      attr_reader errors: Array[untyped]
+      attr_reader content: String?
+
+      def initialize: (?String? message, ?errors: Array[untyped], ?content: String?) -> void
+    end
+
+    # Debug logging utility for Json::Merge
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      def self.env_var_name: () -> String
+      def self.env_var_name=: (String name) -> String
+      def self.log_prefix: () -> String
+      def self.log_prefix=: (String prefix) -> String
+      def self.enabled?: () -> bool
+      def self.debug: (String message, ?Hash[Symbol, untyped] context) -> void
+      def self.info: (String message) -> void
+      def self.warning: (String message) -> void
+      def self.time: [T] (String operation) { () -> T } -> T
+      def self.extract_node_info: (untyped node) -> Hash[Symbol, untyped]
+    end
+
+    # Freeze block node for JSON/JSONC files
+    class FreezeNode < Ast::Merge::FreezeNode
+      InvalidStructureError: singleton(Ast::Merge::FreezeNode::InvalidStructureError)
+      Location: singleton(Ast::Merge::FreezeNode::Location)
+
+      attr_reader lines: Array[String]
+
+      def initialize: (
+        start_line: Integer,
+        end_line: Integer,
+        lines: Array[String],
+        ?start_marker: String?,
+        ?end_marker: String?,
+        ?pattern_type: Symbol
+      ) -> void
+
+      def signature: () -> Array[Symbol | String]
+      def object?: () -> bool
+      def array?: () -> bool
+      def pair?: () -> bool
+      def slice: () -> String?
+      def inspect: () -> String
+
+      private
+
+      def validate_structure!: () -> void
+    end
+
+    # Wrapper for tree-sitter JSON nodes
+    class NodeWrapper
+      attr_reader node: untyped
+      attr_reader start_line: Integer
+      attr_reader end_line: Integer
+      attr_reader analysis: FileAnalysis?
+
+      def initialize: (
+        untyped node,
+        String source,
+        ?analysis: FileAnalysis?
+      ) -> void
+
+      def location: () -> Ast::Merge::FreezeNode::Location
+      def signature: () -> Array[untyped]
+      def freeze_node?: () -> bool
+      def object?: () -> bool
+      def array?: () -> bool
+      def pair?: () -> bool
+      def key: () -> String?
+      def value: () -> untyped
+      def slice: () -> String?
+      def text: () -> String
+      def inspect: () -> String
+    end
+
+    # Comment tracker for JSONC files
+    class CommentTracker
+      attr_reader comments: Array[Hash[Symbol, untyped]]
+      attr_reader source: String
+      attr_reader lines: Array[String]
+
+      def initialize: (String source) -> void
+
+      def extract_comments: () -> Array[Hash[Symbol, untyped]]
+      def comments_for_line: (Integer line) -> Array[Hash[Symbol, untyped]]
+      def leading_comments_for: (Integer line) -> Array[Hash[Symbol, untyped]]
+      def trailing_comment_for: (Integer line) -> Hash[Symbol, untyped]?
+      def line_comment?: (String line) -> bool
+      def block_comment?: (String line) -> bool
+    end
+
+    # File analysis for JSON/JSONC files
+    class FileAnalysis
+      include Ast::Merge::FileAnalysisBase
+
+      DEFAULT_FREEZE_TOKEN: String
+      PARSER_SEARCH_PATHS: Array[String]
+
+      attr_reader source: String
+      attr_reader lines: Array[String]
+      attr_reader ast: untyped
+      attr_reader statements: Array[NodeWrapper | FreezeNode]
+      attr_reader freeze_blocks: Array[FreezeNode]
+      attr_reader freeze_token: String
+      attr_reader signature_generator: (^(untyped) -> Array[untyped]?)?
+      attr_reader comment_tracker: CommentTracker
+      attr_reader errors: Array[untyped]
+
+      def self.find_parser_path: () -> String?
+
+      def initialize: (
+        String source,
+        ?freeze_token: String,
+        ?signature_generator: (^(untyped) -> Array[untyped]?)?,
+        ?parser_path: String?
+      ) -> void
+
+      def valid?: () -> bool
+      def nodes: () -> Array[NodeWrapper | FreezeNode]
+      def line_at: (Integer line_num) -> String?
+      def normalized_line: (Integer line_num) -> String?
+      def in_freeze_block?: (Integer line_num) -> bool
+      def freeze_block_at: (Integer line_num) -> FreezeNode?
+      def signature_at: (Integer index) -> Array[untyped]?
+      def generate_signature: (untyped node) -> Array[untyped]?
+      def compute_node_signature: (untyped node) -> Array[untyped]?
+
+      private
+
+      def parse_json: () -> void
+      def extract_nodes: (untyped tree_node) -> Array[NodeWrapper]
+      def extract_freeze_blocks: () -> Array[FreezeNode]
+      def integrate_nodes_and_freeze_blocks: () -> Array[NodeWrapper | FreezeNode]
+    end
+
+    # Result of a JSON merge operation
+    class MergeResult < Ast::Merge::MergeResult
+      DECISION_KEPT_TEMPLATE: Symbol
+      DECISION_KEPT_DEST: Symbol
+      DECISION_MERGED: Symbol
+      DECISION_ADDED: Symbol
+      DECISION_FREEZE_BLOCK: Symbol
+
+      attr_reader lines: Array[Hash[Symbol, untyped]]
+      attr_reader decisions: Array[Hash[Symbol, untyped]]
+      attr_reader statistics: Hash[Symbol, Integer]
+
+      def initialize: (
+        ?template_analysis: FileAnalysis?,
+        ?dest_analysis: FileAnalysis?,
+        ?conflicts: Array[Hash[Symbol, untyped]],
+        ?frozen_blocks: Array[FreezeNode],
+        ?stats: Hash[Symbol, untyped]
+      ) -> void
+
+      def add_line: (
+        String line,
+        decision: Symbol,
+        source: Symbol,
+        ?original_line: Integer?
+      ) -> void
+
+      def add_lines: (
+        Array[String] lines,
+        decision: Symbol,
+        source: Symbol,
+        ?start_line: Integer?
+      ) -> void
+
+      def add_blank_line: (?decision: Symbol, ?source: Symbol) -> void
+      def add_freeze_block: (FreezeNode freeze_node) -> void
+      def to_json: () -> String
+      def content: () -> Array[Hash[Symbol, untyped]]
+      def content_string: () -> String
+      def empty?: () -> bool
+
+      private
+
+      def track_statistics: (Symbol decision, Symbol source) -> void
+    end
+
+    # Smart merger for JSON/JSONC files
+    class SmartMerger
+      include Ast::Merge::MergerConfig
+
+      attr_reader template_analysis: FileAnalysis
+      attr_reader dest_analysis: FileAnalysis
+      attr_reader signature_match_preference: (Symbol | Hash[Symbol, Symbol])
+      attr_reader add_template_only_nodes: bool
+
+      def initialize: (
+        String template_content,
+        String dest_content,
+        ?signature_match_preference: (Symbol | Hash[Symbol, Symbol]),
+        ?add_template_only_nodes: bool,
+        ?freeze_token: String,
+        ?signature_generator: (^(untyped) -> Array[untyped]?)?,
+        ?node_splitter: Hash[Symbol, untyped]?,
+        ?parser_path: String?
+      ) -> void
+
+      def merge: () -> MergeResult
+
+      private
+
+      def perform_merge: () -> MergeResult
+      def merge_nodes: (MergeResult result) -> void
+    end
+
+    # Conflict resolver for JSON merges
+    class ConflictResolver
+      attr_reader template_analysis: FileAnalysis
+      attr_reader dest_analysis: FileAnalysis
+      attr_reader signature_match_preference: (Symbol | Hash[Symbol, Symbol])
+      attr_reader add_template_only_nodes: bool
+
+      def initialize: (
+        FileAnalysis template_analysis,
+        FileAnalysis dest_analysis,
+        ?signature_match_preference: (Symbol | Hash[Symbol, Symbol]),
+        ?add_template_only_nodes: bool
+      ) -> void
+
+      def resolve: (untyped boundary, MergeResult result) -> void
+    end
+
+    # Emitter for reconstructing JSON output
+    class Emitter
+      attr_reader result: MergeResult
+      attr_reader indent: Integer
+
+      def initialize: (MergeResult result, ?indent: Integer) -> void
+
+      def emit: () -> String
+    end
+  end
+end

data.tar.gz.sig

@@ -0,0 +1 @@
+��~���bV(4F���]'�4LKa�U bI1��Z��P���m�d���9�� B�n%�U!Ը�oL&=ivH5E92��jZ��g������c�>���/�c��~S2�T