rosett-ai 1.3.3 → 1.5.9

data/lib/rosett_ai/dbus/focus_monitor_interface.rb

@@ -15,6 +15,7 @@ module RosettAi
     # Signals:
     #   FocusChanged(app_id: s, title: s)  Emitted on active window change
     class FocusMonitorInterface < ::DBus::Object
+      # @return [String] D-Bus interface name.
       INTERFACE = 'be.neatnerds.rosettai.FocusMonitor'
 
       dbus_interface INTERFACE do

data/lib/rosett_ai/dbus/manager_interface.rb

@@ -23,6 +23,7 @@ module RosettAi
     # - Rate limiting (10 req/s, burst 20) prevents DoS via rapid method calls
     # - Compile operations have stricter limits (2 req/s, burst 5)
     class ManagerInterface < ::DBus::Object
+      # @return [String] D-Bus interface name.
       INTERFACE = 'be.neatnerds.rosettai.Manager'
 
       # Rate limit configurations per operation type

data/lib/rosett_ai/dbus/plugin_manager_interface.rb

@@ -21,8 +21,10 @@ module RosettAi
     # @author hugo
     # @author claude
     class PluginManagerInterface < ::DBus::Object
+      # @return [String] D-Bus interface name.
       INTERFACE = 'be.neatnerds.rosettai.PluginManager'
 
+      # @return [Array] Set of permitted type values.
       VALID_TYPES = ['engine', 'gui', 'mcp'].freeze
 
       dbus_interface INTERFACE do

data/lib/rosett_ai/dbus/rate_limiter.rb

@@ -31,6 +31,7 @@ module RosettAi
 
       # Default limits (requests per second / burst capacity)
       DEFAULT_RATE = 10
+      # @return [Integer] Default burst limit for rate limiting.
       DEFAULT_BURST = 20
 
       # @param rate [Numeric] tokens added per second

data/lib/rosett_ai/dbus/service.rb

@@ -6,6 +6,7 @@
 require 'dbus'
 
 module RosettAi
+  # D-Bus session service for desktop integration.
   module DBus
     # Main D-Bus session service for Rosett-AI.
     #
@@ -16,7 +17,9 @@ module RosettAi
     #
     # The service is designed to gracefully degrade when D-Bus is unavailable.
     class Service
+      # @return [String] D-Bus well-known bus name.
       BUS_NAME = 'be.neatnerds.rosettai'
+      # @return [String] D-Bus object path.
       OBJECT_PATH = '/be/neatnerds/rosett-ai'
 
       attr_reader :bus, :main_loop, :manager, :focus_monitor, :status_notifier

data/lib/rosett_ai/dbus/status_notifier_interface.rb

@@ -15,10 +15,14 @@ module RosettAi
     #
     # Degrades gracefully if no StatusNotifierHost is available.
     class StatusNotifierInterface < ::DBus::Object
+      # @return [String] D-Bus interface name.
       INTERFACE = 'org.kde.StatusNotifierItem'
 
+      # @return [String] StatusNotifierItem category.
       CATEGORY = 'ApplicationStatus'
+      # @return [String] StatusNotifierItem icon name.
       ICON_NAME = 'rosett-ai-symbolic'
+      # @return [String] StatusNotifierItem application identifier.
       APP_ID = 'be.neatnerds.rosettai'
 
       dbus_interface INTERFACE do
@@ -46,10 +50,20 @@ module RosettAi
         @current_status = 'Active'
       end
 
+      # Return the unique identifier.
+      # @return [String]
       def id         = APP_ID
+      # Return the StatusNotifierItem category.
+      # @return [String]
       def category   = CATEGORY
+      # Return the current status.
+      # @return [String]
       def status     = @current_status
+      # Return the display title.
+      # @return [String]
       def title      = "rai #{RosettAi::VERSION}"
+      # Return the icon name for display.
+      # @return [String]
       def icon_name  = ICON_NAME
 
       # ToolTip is a struct: (icon_name, icon_pixmap[], title, body)

data/lib/rosett_ai/desktop/dbus_client.rb

@@ -18,14 +18,20 @@ module RosettAi
     # Ruby Rosett-AI modules directly. This ensures the D-Bus service is
     # the single source of truth.
     class DbusClient
+      # @return [String] D-Bus well-known bus name.
       BUS_NAME = 'be.neatnerds.rosettai'
+      # @return [String] D-Bus object path.
       OBJECT_PATH = '/be/neatnerds/rosett-ai'
+      # @return [String] Manager iface constant.
       MANAGER_IFACE = 'be.neatnerds.rosettai.Manager'
+      # @return [String] Focus iface constant.
       FOCUS_IFACE = 'be.neatnerds.rosettai.FocusMonitor'
 
       # Default safe return values
       SAFE_STATUS = { 'error' => 'Service not available', 'version' => 'unknown' }.freeze
+      # @return [Array] Safe focus constant.
       SAFE_FOCUS = ['', ''].freeze
+      # @return [String] Safe compile result constant.
       SAFE_COMPILE_RESULT = 'Error: D-Bus service not available'
 
       attr_reader :bus, :last_error

data/lib/rosett_ai/desktop/gtk4_app.rb

@@ -6,6 +6,7 @@
 require_relative 'gui_logger'
 
 module RosettAi
+  # Desktop GUI application and D-Bus client.
   module Desktop
     # Main GTK4/Adwaita application for rai desktop integration.
     #
@@ -22,7 +23,9 @@ module RosettAi
     # Follows GNOME HIG: single-window, instant-apply preferences,
     # headerbar with title and buttons.
     class Gtk4App
+      # @return [String] GTK application identifier.
       APPLICATION_ID = 'be.neatnerds.rosettai'
+      # @return [String] Error message when the UI backend is not available.
       UNAVAILABLE_MESSAGE = 'GTK4 app requires the adwaita gem. Install: gem install adwaita'
 
       attr_reader :application, :dbus_client

data/lib/rosett_ai/desktop/gtk4_preferences.rb

@@ -66,6 +66,7 @@ module RosettAi
         log_error('Failed to present preferences dialog', e)
       end
 
+      # @return [Array] Engine names used when detection fails.
       FALLBACK_ENGINES = [
         { name: 'claude', display_name: 'Claude' },
         { name: 'generic', display_name: 'Generic' },

data/lib/rosett_ai/desktop/gui_logger.rb

@@ -30,7 +30,9 @@ module RosettAi
     #   RAI_GUI_LOG=1 RAI_GUI_LOG_FILE=/tmp/rosett-ai-gui.log bin/raictl desktop gtk4
     #
     class GuiLogger
+      # @return [Hash] Supported level values.
       LEVELS = { debug: 0, info: 1, warn: 2, error: 3 }.freeze
+      # @return [Symbol] Default log level.
       DEFAULT_LEVEL = :info
 
       class << self

data/lib/rosett_ai/doctor/check.rb

@@ -36,7 +36,7 @@ module RosettAi
       end
 
       # Register this check class with the Doctor module.
-      # @param check_name [String] unique check identifier
+      # @param base [Module] the including module or class
       def self.included(base)
         base.extend(ClassMethods)
       end

data/lib/rosett_ai/doctor/checks/cache_health_check.rb

@@ -5,6 +5,7 @@
 
 module RosettAi
   module Doctor
+    # Individual diagnostic check implementations.
     module Checks
       # Verifies the cache directory exists and is writable.
       #

data/lib/rosett_ai/doctor.rb

@@ -14,6 +14,7 @@ module RosettAi
   # @author claude
   # @see conf/design/doctor.yml
   module Doctor
+    # @return [Array] Supported doctor check status values.
     STATUSES = ['pass', 'warn', 'fail'].freeze
 
     @checks = []

data/lib/rosett_ai/documentation/reference_compiler.rb

@@ -16,8 +16,11 @@ module RosettAi
     #
     # Design reference: conf/design/documentation.yml
     class ReferenceCompiler
+      # @return [Array] External tools required for documentation compilation.
       REQUIRED_TOOLS = ['pdflatex', 'biber', 'makeindex'].freeze
+      # @return [String] Filename for compiled reference documentation.
       OUTPUT_NAME = 'rosett-ai-technical-reference.pdf'
+      # @return [Array] Files produced during reference documentation build.
       BUILD_ARTIFACTS = ['aux', 'bbl', 'bcf', 'blg', 'idx', 'ilg', 'ind',
                          'lof', 'log', 'lot', 'out', 'ptc', 'run.xml', 'toc'].freeze
 
@@ -29,6 +32,8 @@ module RosettAi
         REQUIRED_TOOLS.all? { |tool| tool_on_path?(tool) }
       end
 
+      # Return external tools required but not installed.
+      # @return [Array<String>]
       def missing_tools
         REQUIRED_TOOLS.reject { |tool| tool_on_path?(tool) }
       end
@@ -56,10 +61,14 @@ module RosettAi
         clean_artifacts!
       end
 
+      # Return the compiled documentation output path.
+      # @return [Pathname]
       def output_path
         @root.join('doc', 'reference', OUTPUT_NAME)
       end
 
+      # Return the man page source directory.
+      # @return [Pathname]
       def source_dir
         @root.join('doc', 'reference', 'src')
       end

data/lib/rosett_ai/documentation/translator.rb

@@ -6,18 +6,26 @@
 require 'fileutils'
 
 module RosettAi
+  # Reference documentation compilation and translation.
   module Documentation
     # Produces draft translations of documentation files using the Claude API.
     #
     # Reads source documentation, sends to API with a translation prompt,
     # and writes the result to doc/locales/{locale}/.
     class Translator
+      # @return [String] AI model used for documentation translation.
       MODEL = 'claude-sonnet-4-20250514'
 
       def initialize(doc_dir: nil)
         @doc_dir = doc_dir || RosettAi.root.join('doc')
       end
 
+      # Translate documentation to the target locale.
+      #
+      # @param source_file [Object] the source file
+      # @param from [Object] the from
+      # @param to [Object] the to
+      # @return [void]
       def translate(source_file, from:, to:)
         content = File.read(source_file)
         basename = File.basename(source_file)

data/lib/rosett_ai/engines/base_config_compiler.rb

@@ -15,6 +15,10 @@ module RosettAi
     # file discovery, YAML loading, schema validation, checksum diffing,
     # action determination, and result writing.
     #
+    # By default, compiling a scope MERGES with the existing target file,
+    # preserving entries not covered by any source YAML. Pass strict: true
+    # to get the old replace-all behaviour.
+    #
     # Subclasses must implement:
     #   - #config_dir       → Pathname to scope YAML directory
     #   - #schema_path      → Pathname to JSON Schema file
@@ -22,11 +26,16 @@ module RosettAi
     #   - #transform(data, scope) → [json_data, warnings]
     #   - #output_format    → Symbol (:json, :yaml)
     class BaseConfigCompiler
+      # @return [Array] YAML header keys preserved in compiled output.
       HEADER_KEYS = ['name', 'scope', 'version', 'status', 'compatibility',
                      'author', 'created_at', 'modified_at', 'modified_by'].freeze
 
-      def initialize(simulate: false, secret_resolver: nil)
+      # @param simulate [Boolean] dry-run — compute diffs but do not write
+      # @param secret_resolver [#resolve_all] resolves secret placeholders
+      # @param strict [Boolean] replace target entirely (skip merge pass)
+      def initialize(simulate: false, secret_resolver: nil, strict: false)
         @simulate = simulate
+        @strict = strict
         @secret_resolver = secret_resolver || RosettAi::Config::SecretResolver.new
         @schema = load_schema
       end
@@ -50,6 +59,9 @@ module RosettAi
         json_data = @secret_resolver.resolve_all(json_data)
 
         target = scope_router.target_path(scope)
+        json_data, merge_warnings = merge_pass(target, json_data)
+        warnings.concat(merge_warnings)
+
         action, diff = determine_action(target, json_data)
 
         RosettAi::Config::CompileResult.new(
@@ -115,6 +127,24 @@ module RosettAi
         []
       end
 
+      # Merge compiled JSON with the existing target file, preserving entries
+      # not produced by any source YAML scope. In strict mode, returns compiled
+      # data unchanged.
+      #
+      # @param target_path [Pathname, nil] path to existing settings file
+      # @param json_data [Hash] compiled output from transform + secret resolution
+      # @return [Array(Hash, Array<String>)] [merged_data, preserve_warnings]
+      def merge_pass(target_path, json_data)
+        return [json_data, []] if @strict
+        return [json_data, []] unless target_path&.exist?
+
+        existing = JSON.parse(File.read(target_path))
+        result = deep_merge_preserve(json_data, existing)
+        [result[:data], result[:warnings]]
+      rescue Errno::ENOENT, JSON::ParserError
+        [json_data, []]
+      end
+
       private
 
       def load_schema
@@ -198,6 +228,46 @@ module RosettAi
       def extract_scope_from_path(path)
         File.basename(path, '.yml')
       end
+
+      # Recursively merge compiled data with existing, preserving keys/elements
+      # that are absent from compiled. Array merging appends existing-only elements.
+      #
+      # @param compiled [Hash] compiled json_data (source of truth for what was set)
+      # @param existing [Hash] parsed existing settings file
+      # @param path_prefix [String] dot-path prefix for warning messages
+      # @return [Hash] with keys :data (merged Hash) and :warnings (Array<String>)
+      def deep_merge_preserve(compiled, existing, path_prefix: '')
+        warnings = []
+        merged = compiled.dup
+        existing.each do |key, existing_val|
+          entry_path = path_prefix.empty? ? key.to_s : "#{path_prefix}.#{key}"
+          warnings.concat(merge_existing_entry(merged, compiled, key, existing_val, entry_path))
+        end
+        { data: merged, warnings: warnings }
+      end
+
+      def merge_existing_entry(merged, compiled, key, existing_val, entry_path)
+        unless compiled.key?(key)
+          merged[key] = existing_val
+          return [preserved_warning("#{entry_path}: #{existing_val.inspect}")]
+        end
+        compiled_val = compiled[key]
+        if compiled_val.is_a?(Array) && existing_val.is_a?(Array)
+          extra = existing_val - compiled_val
+          merged[key] = compiled_val + extra
+          return extra.map { |e| preserved_warning(e.inspect) }
+        elsif compiled_val.is_a?(Hash) && existing_val.is_a?(Hash)
+          sub = deep_merge_preserve(compiled_val, existing_val, path_prefix: entry_path)
+          merged[key] = sub[:data]
+          return sub[:warnings]
+        end
+        [] # scalar: compiled wins silently (merged already has compiled[key] from dup)
+      end
+
+      def preserved_warning(entry_label)
+        'Preserved entry from settings.json not in source scopes: ' \
+          "#{entry_label}. Consider running `raictl backfill-user-yml` to capture in source."
+      end
     end
   end
 end

data/lib/rosett_ai/engines/detector.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Engine plugin discovery, detection, and registry.
   module Engines
     # Base engine detector that reads manifest detection rules and probes the system.
     #
@@ -17,6 +18,8 @@ module RosettAi
         @manifest = Registry.manifest(@engine_name)
       end
 
+      # Detect available engines on the system.
+      # @return [Array<Hash>]
       def detect
         checks = []
         detection = @manifest['detection'] || {}
@@ -35,6 +38,8 @@ module RosettAi
 
       protected
 
+      # Return custom engine detection check results.
+      # @return [Array<Hash>]
       def custom_checks
         []
       end

data/lib/rosett_ai/engines/registry.rb

@@ -12,10 +12,17 @@ module RosettAi
     # register.rb files, discovered by Gem.find_files.
     class Registry
       class << self
+        # List all available engine plugins.
+        #
+        # @return [Array<Hash>]
         def available
           RosettAi::Plugins::Registry.available(:engine)
         end
 
+        # Return the Ruby module for the given engine name.
+        #
+        # @param name [String, Symbol] the engine name
+        # @return [Module, nil]
         def engine_module(name)
           RosettAi::Plugins::Registry.plugin_module(:engine, name.to_s)
         end

data/lib/rosett_ai/exit_codes.rb

@@ -17,11 +17,17 @@ module RosettAi
   # @author hugo
   # @author claude
   module ExitCodes
+    # @return [Integer] Success constant.
     SUCCESS      = 0
+    # @return [Integer] General constant.
     GENERAL      = 1
+    # @return [Integer] Validation constant.
     VALIDATION   = 2
+    # @return [Integer] Config constant.
     CONFIG       = 3
+    # @return [Integer] Permission constant.
     PERMISSION   = 4
+    # @return [Integer] Dependency constant.
     DEPENDENCY   = 5
 
     # Maps each RosettAi error class to its exit code.

data/lib/rosett_ai/formatting.rb

@@ -7,6 +7,7 @@ module RosettAi
   # Human-readable formatting for byte sizes and durations.
   # Include in any class that needs to display file sizes or elapsed times.
   module Formatting
+    # @return [Array] Human-readable byte size unit labels.
     SIZE_UNITS = ['B', 'KB', 'MB', 'GB'].freeze
 
     # Formats a byte count as a human-readable string (e.g. "2.0 KB").

data/lib/rosett_ai/gem_consistency_checker.rb

@@ -13,11 +13,15 @@ module RosettAi
   # against gemspec constraints, and scans project files for stale gem version
   # references.
   class GemConsistencyChecker
+    # @return [Array] Directory names excluded from consistency checking.
     EXCLUDED_DIRS = ['vendor', 'tmp', 'coverage', '.git', '.bundle'].freeze
+    # @return [Array] Filenames excluded from consistency checking.
     EXCLUDED_FILES = ['Gemfile.lock', 'Gemfile', 'rosett_ai.gemspec',
                       'spec/rosett_ai/gem_consistency_checker_spec.rb',
                       'spec/examples.txt'].freeze
+    # @return [Array] Filename prefixes excluded from consistency checking.
     EXCLUDED_PREFIXES = ['doc/changes/', 'doc/claude-sessions/', 'conf/design/'].freeze
+    # @return [Array] File extensions excluded from consistency checking.
     EXCLUDED_EXTENSIONS = ['.aux', '.toc', '.out', '.ptc', '.log', '.idx', '.ind',
                            '.ilg', '.bbl', '.blg', '.bcf', '.fls', '.json'].freeze
 
@@ -28,6 +32,8 @@ module RosettAi
       @results = { gems: [], stale_references: [], consistent: true }
     end
 
+    # Run the check and return results.
+    # @return [Hash]
     def check
       constraints = parse_gemspec_constraints
       locked = parse_lockfile_versions

data/lib/rosett_ai/git_hooks/chain_detector.rb

@@ -13,6 +13,7 @@ module RosettAi
     # @author hugo
     # @author claude
     class ChainDetector
+      # @return [Hash] Recognized git hook manager names.
       KNOWN_MANAGERS = {
         'overcommit' => { marker: /overcommit/i, config: '.overcommit.yml' },
         'husky' => { marker: /husky/i, config: '.husky' },

data/lib/rosett_ai/git_hooks/installer.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Git hook installation, generation, and chain detection.
   module GitHooks
     # Installs and uninstalls rosett-ai-managed git hooks in .git/hooks/.
     #
@@ -14,9 +15,12 @@ module RosettAi
     # @author hugo
     # @author claude
     class Installer
+      # @return [String] Marker identifying rai-managed hook scripts.
       RAI_MARKER = '# rosett-ai-managed hook'
+      # @return [String] File extension appended to backup copies.
       BACKUP_SUFFIX = '.rosett-ai-backup'
 
+      # @return [Array] Git hook types supported for installation.
       SUPPORTED_HOOKS = [
         'pre-commit', 'post-commit', 'post-checkout', 'post-merge', 'pre-push'
       ].freeze

data/lib/rosett_ai/git_hooks/script_generator.rb

@@ -15,7 +15,9 @@ module RosettAi
     # @author hugo
     # @author claude
     module ScriptGenerator
+      # @return [String] File extension appended to backup copies.
       BACKUP_SUFFIX = '.rosett-ai-backup'
+      # @return [Integer] Default timeout in seconds.
       DEFAULT_TIMEOUT = 30
 
       # Pattern matching shell metacharacters that indicate potential injection.

data/lib/rosett_ai/gitlab/validators/supplementary_gitlab_ci_yaml_validator.rb

@@ -7,7 +7,9 @@ require 'yaml'
 require 'pathname'
 
 module RosettAi
+  # GitLab CI integration and validation.
   module Gitlab
+    # GitLab CI YAML validation implementations.
     module Validators
       # Validates GitLab CI YAML files for syntax correctness.
       #
@@ -17,7 +19,9 @@ module RosettAi
       # (e.g. double-quoted strings misinterpreted as YAML scalars) while
       # remaining compatible with GitLab-specific extensions.
       class SupplementaryGitlabCiYamlValidator
+        # @return [String] Root CI configuration filename.
         CI_ROOT_FILE = '.gitlab-ci.yml'
+        # @return [String] Directory for supplementary CI YAML files.
         CI_FILES_DIR = '.gitlab-ci-files'
 
         attr_reader :results
@@ -27,6 +31,8 @@ module RosettAi
           @results = { valid: [], invalid: [] }
         end
 
+        # Validate the input and return any errors.
+        # @return [Array<Hash>]
         def validate
           @results = { valid: [], invalid: [] }
 

data/lib/rosett_ai/i18n/utf8_checker.rb

@@ -4,6 +4,7 @@
 # Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
 
 module RosettAi
+  # Internationalization utilities (UTF-8, locale handling).
   module I18n
     # Validates that the runtime environment supports UTF-8 encoding.
     #

data/lib/rosett_ai/init/config_file_writer.rb

@@ -8,6 +8,10 @@ module RosettAi
     # Writes the default rai config file at ~/.config/rosett-ai/config.yml
     # if it does not already exist.
     class ConfigFileWriter
+      # Write the default configuration file to disk.
+      #
+      # @param config_dir [Object] the config dir
+      # @return [void]
       def self.write_default(config_dir: nil)
         dir = config_dir || RosettAi.paths.rai_config_dir
         path = dir.join('config.yml')

data/lib/rosett_ai/init/directory_builder.rb

@@ -9,20 +9,35 @@ module RosettAi
   module Init
     # Helper module for creating directories during initialization
     module DirectoryBuilder
+      # @return [Array] Directory structure for global initialization.
       GLOBAL_DIRS = ['rules', 'locales', 'conf', 'conf/behaviour', 'conf/schemas', 'doc', 'bin', 'lib',
                      'lib/rosett-ai'].freeze
+      # @return [Array] Directory structure for local initialization.
       LOCAL_DIRS = ['rules', 'conf', 'conf/behaviour', 'conf/schemas'].freeze
 
       module_function
 
+      # Create the global ~/.claude/ directory structure.
+      #
+      # @param base_dir [String] the base directory path
+      # @return [Array<String>] list of created directories
       def create_global_structure(base_dir)
         create_directories(base_dir, GLOBAL_DIRS)
       end
 
+      # Create the project-local .claude/ directory structure.
+      #
+      # @param base_dir [String] the base directory path
+      # @return [Array<String>] list of created directories
       def create_local_structure(base_dir)
         create_directories(base_dir, LOCAL_DIRS)
       end
 
+      # Create the specified subdirectories under the base directory.
+      #
+      # @param base_dir [String] the base directory path
+      # @param subdirs [Array<String>] subdirectory names to create
+      # @return [Array<String>] list of newly created directories
       def create_directories(base_dir, subdirs)
         created = []
         ([base_dir] + subdirs.map { |subdir| File.join(base_dir, subdir) }).each do |dir|