chiridion 0.3.4

data/lib/chiridion/engine/generated_rbs_loader.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Comprehensive loader for RBS::Inline-generated .rbs files.
+    #
+    # Unlike the simpler RbsLoader, this extracts ALL available information
+    # from generated RBS files:
+    #
+    # - Method signatures with parameter types and return types
+    # - Instance variable declarations (@name: Type)
+    # - Attribute declarations (attr_reader name: Type)
+    # - Type aliases (type name = definition)
+    # - Class/module structure with comments
+    #
+    # The generated RBS files are authoritative - they've been properly parsed
+    # by rbs-inline from the source annotations. We just need to read them.
+    #
+    # @example
+    #   loader = GeneratedRbsLoader.new(verbose: true, logger: logger)
+    #   data = loader.load("sig/generated")
+    #   # => { signatures: {...}, ivars: {...}, attrs: {...}, type_aliases: {...} }
+    #
+    class GeneratedRbsLoader
+      # Result structure from loading.
+      Result = Data.define(
+        :signatures,    # Hash[class_path => Hash[method_name => signature_data]]
+        :ivars,         # Hash[class_path => Hash[ivar_name => { type:, desc: }]]
+        :attrs,         # Hash[class_path => Hash[attr_name => { type:, desc: }]]
+        :type_aliases,  # Hash[namespace => Array[{ name:, definition:, description: }]]
+        :overloads      # Hash[class_path => Hash[method_name => Array[signature_strings]]]
+      )
+
+      def initialize(verbose: false, logger: nil)
+        @verbose = verbose
+        @logger  = logger
+      end
+
+      # Load all data from generated RBS directory.
+      #
+      # @param rbs_dir [String] Path to generated RBS directory (e.g., "sig/generated")
+      # @return [Result] All extracted data
+      def load(rbs_dir)
+        signatures   = {}
+        ivars        = {}
+        attrs        = {}
+        type_aliases = {}
+        overloads    = {}
+
+        return empty_result unless rbs_dir && Dir.exist?(rbs_dir)
+
+        rbs_files = Dir.glob(File.join(rbs_dir, "**/*.rbs"))
+        rbs_files.each do |file|
+          parse_file(file, signatures, ivars, attrs, type_aliases, overloads)
+        end
+
+        log_stats(signatures, ivars, attrs, type_aliases) if @verbose
+
+        Result.new(
+          signatures:   signatures,
+          ivars:        ivars,
+          attrs:        attrs,
+          type_aliases: type_aliases,
+          overloads:    overloads
+        )
+      end
+
+      private
+
+      def empty_result
+        Result.new(
+          signatures:   {},
+          ivars:        {},
+          attrs:        {},
+          type_aliases: {},
+          overloads:    {}
+        )
+      end
+
+      def log_stats(signatures, ivars, attrs, type_aliases)
+        method_count = signatures.values.sum { |m| m.size }
+        ivar_count   = ivars.values.sum { |i| i.size }
+        attr_count   = attrs.values.sum { |a| a.size }
+        type_count   = type_aliases.values.sum { |t| t.size }
+
+        @logger&.info "Loaded from generated RBS: #{method_count} methods, " \
+                      "#{ivar_count} ivars, #{attr_count} attrs, #{type_count} type aliases"
+      end
+
+      def parse_file(file, signatures, ivars, attrs, type_aliases, overloads)
+        content = File.read(file)
+        lines   = content.lines
+
+        namespace_stack = []
+        pending_comment = nil
+        pending_method  = nil  # For collecting method overloads
+
+        lines.each_with_index do |line, _idx|
+          stripped = line.strip
+
+          # Track module/class context
+          if stripped =~ /^(?:class|module)\s+([\w:]+)/
+            name            = Regexp.last_match(1)
+            namespace_stack.push(name)
+            pending_comment = nil
+            next
+          end
+
+          # Track end statements
+          if stripped == "end"
+            namespace_stack.pop if namespace_stack.any?
+            pending_comment = nil
+            pending_method  = nil
+            next
+          end
+
+          # Collect comments (may be description for next declaration)
+          if stripped.start_with?("#")
+            comment_text    = stripped.sub(/^#\s*/, "")
+            pending_comment = pending_comment ? "#{pending_comment}\n#{comment_text}" : comment_text
+            next
+          end
+
+          # Skip blank lines but preserve pending_comment
+          next if stripped.empty?
+
+          current_namespace = namespace_stack.join("::")
+          next if current_namespace.empty?
+
+          # Parse instance variable declarations: @name: Type
+          if stripped =~ /^@(\w+):\s*(.+)$/
+            ivar_name = Regexp.last_match(1)
+            ivar_type = Regexp.last_match(2).strip
+
+            ivars[current_namespace]          ||= {}
+            ivars[current_namespace][ivar_name] = {
+              type: ivar_type,
+              desc: extract_first_line_desc(pending_comment)
+            }
+            pending_comment                     = nil
+            next
+          end
+
+          # Parse attr_reader/attr_accessor: attr_reader name: Type
+          if stripped =~ /^attr_(?:reader|accessor|writer)\s+(\w+):\s*(.+)$/
+            attr_name = Regexp.last_match(1)
+            attr_type = Regexp.last_match(2).strip
+
+            attrs[current_namespace]          ||= {}
+            attrs[current_namespace][attr_name] = {
+              type: attr_type,
+              desc: extract_first_line_desc(pending_comment)
+            }
+            pending_comment                     = nil
+            next
+          end
+
+          # Parse type aliases: type name = definition
+          if stripped =~ /^type\s+(\w+)\s*=\s*(.+)$/
+            type_name = Regexp.last_match(1)
+            type_def  = Regexp.last_match(2)
+
+            type_aliases[current_namespace] ||= []
+            type_aliases[current_namespace] << {
+              name:        type_name,
+              definition:  type_def,
+              description: pending_comment
+            }
+            pending_comment                   = nil
+            next
+          end
+
+          # Parse method signatures: def method_name: signature
+          # Also handles: def self.method_name: signature
+          if stripped =~ /^def\s+(?:self\.)?(\w+[?!=]?|\[\]=?):\s*(.+)$/
+            method_name = Regexp.last_match(1)
+            full_sig    = Regexp.last_match(2).strip
+
+            signatures[current_namespace] ||= {}
+
+            # Check if this is a continuation (overload) of previous method
+            if pending_method == method_name
+              overloads[current_namespace]              ||= {}
+              overloads[current_namespace][method_name] ||= []
+              overloads[current_namespace][method_name] << full_sig
+            else
+              # New method - parse signature and store
+              signatures[current_namespace][method_name] = parse_signature(full_sig, pending_comment)
+              pending_method                             = method_name
+            end
+
+            pending_comment = nil
+            next
+          end
+
+          # Check for method overload continuation (line starting with |)
+          if stripped.start_with?("|") && pending_method
+            overload_sig = stripped.sub(/^\|\s*/, "").strip
+
+            overloads[current_namespace]                 ||= {}
+            overloads[current_namespace][pending_method] ||= []
+            overloads[current_namespace][pending_method] << overload_sig
+            next
+          end
+
+          # Any other non-blank line resets pending state
+          pending_comment = nil
+          pending_method  = nil
+        end
+      end
+
+      def extract_first_line_desc(comment)
+        return nil if comment.nil? || comment.empty?
+
+        # Get first line, skip @rbs annotations
+        lines = comment.lines.map(&:strip)
+        lines.reject { |l| l.start_with?("@rbs") }.first
+      end
+
+      # Parse RBS signature into structured data.
+      #
+      # Handles formats like:
+      #   () -> void
+      #   (String name, ?Integer age) -> User
+      #   [T] (T item) -> Array[T]
+      #
+      # @param sig [String] Full RBS signature
+      # @param comment [String, nil] Preceding comment (may contain @rbs descriptions)
+      # @return [Hash] Structured signature data
+      def parse_signature(sig, comment = nil)
+        result = {
+          full:    sig,
+          params:  {},
+          returns: nil
+        }
+
+        # Extract descriptions from comment's @rbs annotations
+        param_descs  = {}
+        return_desc  = nil
+        raises_type  = nil
+
+        if comment
+          comment.lines.each do |line|
+            line = line.strip
+
+            # @rbs param_name: Type -- description
+            if line =~ /@rbs\s+(\w+):\s*\S+\s+--\s+(.+)$/
+              param_descs[Regexp.last_match(1)] = capitalize_first(Regexp.last_match(2))
+            end
+
+            # @rbs return: Type -- description
+            return_desc = capitalize_first(Regexp.last_match(1)) if line =~ /@rbs\s+return:\s*\S+\s+--\s+(.+)$/
+
+            # @rbs raises: Type
+            raises_type = Regexp.last_match(1).strip if line =~ /@rbs\s+raises:\s*(.+)$/
+          end
+        end
+
+        # Parse the signature itself
+        # Handle type parameters: [T] (...)
+        sig_without_type_params = sig.sub(/^\[[^\]]+\]\s*/, "")
+
+        if sig_without_type_params =~ /\A\(([^)]*)\)\s*->\s*(.+)\z/
+          params_str       = Regexp.last_match(1)
+          result[:returns] = { type: Regexp.last_match(2).strip, desc: return_desc }
+          parse_params(params_str, result[:params], param_descs)
+        elsif sig_without_type_params =~ /\A\(\)\s*->\s*(.+)\z/
+          result[:returns] = { type: Regexp.last_match(1).strip, desc: return_desc }
+        end
+
+        result[:raises] = raises_type if raises_type
+        result
+      end
+
+      def parse_params(params_str, result, descriptions)
+        return if params_str.strip.empty?
+
+        params = split_respecting_brackets(params_str)
+
+        params.each do |param|
+          param = param.strip
+          next if param.empty?
+
+          parse_single_param(param, result, descriptions)
+        end
+      end
+
+      def parse_single_param(param, result, descriptions)
+        # Keyword arg: `?name: Type` or `name: Type`
+        if param =~ /\A\??(\w+):\s*(.+)\z/
+          name         = Regexp.last_match(1)
+          type         = Regexp.last_match(2).strip
+          result[name] = { type: type, desc: descriptions[name] }
+        # Block param: `?{ (Type) -> Type }` or `^(Type) -> Type`
+        elsif param =~ /\A\??[{^]/
+          # Store as special block param
+          result["&block"] = { type: param, desc: descriptions["block"] }
+        # Positional: `?Type name` or `Type name`
+        elsif param =~ /\A\??(.+?)\s+(\w+)\z/
+          type         = Regexp.last_match(1).strip
+          name         = Regexp.last_match(2)
+          result[name] = { type: type, desc: descriptions[name] }
+        end
+      end
+
+      def capitalize_first(str)
+        return nil if str.nil? || str.strip.empty?
+
+        s = str.strip
+        s[0].upcase + s[1..]
+      end
+
+      # Split string by commas while respecting nested brackets [], {}, ().
+      def split_respecting_brackets(str)
+        result  = []
+        current = +""
+        depth   = 0
+
+        str.each_char do |c|
+          case c
+          when "[", "{", "("
+            depth += 1
+            current << c
+          when "]", "}", ")"
+            depth -= 1
+            current << c
+          when ","
+            if depth.zero?
+              result << current
+              current = +""
+            else
+              current << c
+            end
+          else
+            current << c
+          end
+        end
+
+        result << current unless current.empty?
+        result
+      end
+    end
+  end
+end

data/lib/chiridion/engine/github_linker.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Generates GitHub source links from file paths and line numbers.
+    #
+    # Parses git remote URL to extract org/repo, then constructs blob URLs
+    # with line references for linking documentation back to source.
+    class GithubLinker
+      # @return [String, nil] GitHub base URL (e.g., "https://github.com/org/repo")
+      attr_reader :base_url
+
+      # @return [String] Git branch for source links
+      attr_reader :branch
+
+      # @param repo [String, nil] Explicit GitHub repo (e.g., "org/repo")
+      # @param branch [String] Git branch for links
+      # @param root [String] Project root for detecting git remote
+      def initialize(repo: nil, branch: "main", root: Dir.pwd)
+        @branch   = branch
+        @base_url = repo ? "https://github.com/#{repo}" : extract_github_base_url(root)
+      end
+
+      # Generate a markdown link to a source location on GitHub.
+      #
+      # @param path [String] Project-relative file path
+      # @param start_line [Integer] Starting line number
+      # @param end_line [Integer, nil] Ending line number (optional)
+      # @return [String] Markdown link or plain text if no GitHub remote
+      def link(path, start_line, end_line = nil)
+        text = format_text(path, start_line, end_line)
+        return "`#{text}`" unless @base_url
+
+        url = format_url(path, start_line, end_line)
+        "[#{text}](#{url})"
+      end
+
+      # Generate just the URL (for frontmatter).
+      #
+      # @param path [String] Project-relative file path
+      # @param start_line [Integer] Starting line number
+      # @param end_line [Integer, nil] Ending line number (optional)
+      # @return [String, nil] GitHub URL or nil if no GitHub remote
+      def url(path, start_line, end_line = nil)
+        return nil unless @base_url
+
+        format_url(path, start_line, end_line)
+      end
+
+      private
+
+      def format_text(path, start_line, end_line)
+        if end_line && end_line != start_line
+          "#{path}:#{start_line}-#{end_line}"
+        else
+          "#{path}:#{start_line}"
+        end
+      end
+
+      def format_url(path, start_line, end_line)
+        line_ref = if end_line && end_line != start_line
+                     "L#{start_line}-L#{end_line}"
+                   else
+                     "L#{start_line}"
+                   end
+        "#{@base_url}/blob/#{@branch}/#{path}##{line_ref}"
+      end
+
+      # Pattern matching both HTTPS and SSH GitHub remote URLs:
+      # - https://github.com/org/repo.git
+      # - git@github.com:org/repo.git
+      GITHUB_REMOTE_PATTERN = %r{
+        (?:https://github\.com/|git@github\.com:)
+        ([^/]+)/([^/]+?)(?:\.git)?$
+      }x
+      private_constant :GITHUB_REMOTE_PATTERN
+
+      def extract_github_base_url(root)
+        remote_url = `cd #{root} && git remote get-url origin 2>/dev/null`.strip
+        return nil if remote_url.empty?
+
+        match = remote_url.match(GITHUB_REMOTE_PATTERN)
+        "https://github.com/#{match[1]}/#{match[2]}" if match
+      end
+    end
+  end
+end

data/lib/chiridion/engine/inline_rbs_loader.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Extracts RBS type signatures from inline annotations in Ruby source.
+    #
+    # Supports the rbs-inline format where types are specified in comments:
+    #
+    #   # @rbs param: String -- description
+    #   # @rbs return: Integer
+    #   def method(param)
+    #
+    # This is the preferred way to specify types in source code, as it keeps
+    # type information co-located with the code. The RbsLoader handles
+    # separate sig/ files as a fallback.
+    #
+    # @see https://github.com/soutaro/rbs-inline
+    class InlineRbsLoader
+      def initialize(verbose, logger)
+        @verbose = verbose
+        @logger  = logger
+      end
+
+      # Extract inline RBS annotations from Ruby source files.
+      #
+      # @param source_files [Array<String>] Paths to Ruby files
+      # @return [Array(Hash, Hash, Hash)] [signatures, rbs_file_namespaces, attr_types]
+      #   - signatures: class -> method -> signature
+      #   - rbs_file_namespaces: file -> [namespaces] for files with @rbs content
+      #   - attr_types: class -> attr_name -> { type:, desc: } (from #: annotations or @rbs! blocks)
+      def load(source_files)
+        signatures           = {}
+        @rbs_file_namespaces = {}
+        @attr_types          = {}
+
+        source_files.each do |file|
+          next unless File.exist?(file)
+
+          parse_file(file, signatures)
+        end
+
+        @logger.info "Extracted inline RBS from #{source_files.size} files" if @verbose && source_files.any?
+        [signatures, @rbs_file_namespaces, @attr_types]
+      end
+
+      private
+
+      def parse_file(file, signatures)
+        content         = File.read(file)
+        expanded_file   = File.expand_path(file)
+        # Stack of [name_parts, indent_level] for tracking nested namespaces
+        namespace_stack = []
+        pending_rbs     = {}
+        file_has_rbs    = content.include?("@rbs")
+        file_namespaces = []
+        in_rbs_block    = false
+        # Track multi-line Struct.new/Data.define: { indent:, name: } waiting for `) do`
+        pending_struct  = nil
+
+        content.each_line.with_index do |line, _idx|
+          # Track @rbs! block start
+          if line =~ /^\s*#\s*@rbs!/
+            in_rbs_block = true
+            next
+          end
+
+          # Parse @rbs! block content for attr_accessor/reader/writer types
+          if in_rbs_block
+            # Track nested class declarations inside @rbs! blocks
+            if line =~ /^\s*#\s+class\s+(\w+)/
+              Regexp.last_match(1)
+            elsif line =~ /^\s*#\s+attr_(?:accessor|reader|writer)\s+(\w+):\s*(.+)$/
+              attr_name                  = Regexp.last_match(1)
+              attr_type                  = Regexp.last_match(2).strip
+              base_class                 = current_namespace(namespace_stack)
+              # Use nested class from @rbs! block if present
+              full_class                 = rbs_block_class ? "#{base_class}::#{rbs_block_class}" : base_class
+              # Store as { type:, desc: } for consistency (no desc in @rbs! format)
+              (@attr_types[full_class] ||= {})[attr_name] = { type: attr_type, desc: nil } unless full_class.empty?
+            elsif line !~ /^\s*#/ # Non-comment line ends @rbs! block
+              in_rbs_block    = false
+              nil
+            end
+          end
+
+          # Parse Struct.new/Data.define member annotations: :name, #: Type -- description
+          if pending_struct && line =~ /:(\w+),?\s*#:\s*(.+)$/
+            attr_name                           = Regexp.last_match(1)
+            type_and_desc                       = Regexp.last_match(2).strip
+            type, desc                          = type_and_desc.split(/\s+--\s+/, 2)
+            pending_struct[:members]          ||= {}
+            pending_struct[:members][attr_name] = { type: type.strip, desc: capitalize_first(desc) }
+          end
+          # Track class/module context - push onto namespace stack with indentation
+          if line =~ /^(\s*)(?:class|module)\s+([\w:]+)/
+            class_indent                = Regexp.last_match(1).length
+            name                        = Regexp.last_match(2)
+            # Handle inline fully-qualified names like "class Foo::Bar"
+            name_parts                  = name.split("::")
+            namespace_stack.push([name_parts, class_indent])
+            current_class               = current_namespace(namespace_stack)
+            signatures[current_class] ||= {}
+            # Track namespaces this file contributes to (for @rbs change detection)
+            file_namespaces << current_class if file_has_rbs
+            pending_rbs                 = {}
+          end
+
+          # Track Data.define/Struct.new blocks as pseudo-classes
+          # Single-line: ConstName = Data.define(...) do  or  ConstName = Struct.new(...) do
+          if line =~ /^(\s*)([\w:]+)\s*=\s*(?:Data\.define|Struct\.new)\b.*\bdo\s*(?:#.*)?$/
+            block_indent                = Regexp.last_match(1).length
+            name                        = Regexp.last_match(2)
+            name_parts                  = name.split("::")
+            namespace_stack.push([name_parts, block_indent])
+            current_class               = current_namespace(namespace_stack)
+            signatures[current_class] ||= {}
+            pending_rbs                 = {}
+          # Multi-line start: ConstName = Data.define( or ConstName = Struct.new(
+          # We'll complete this when we see `) do` later
+          elsif line =~ /^(\s*)([\w:]+)\s*=\s*(?:Data\.define|Struct\.new)\s*\(/
+            pending_struct = { indent: Regexp.last_match(1).length, name: Regexp.last_match(2) }
+          # Multi-line completion: ) do (possibly with keyword args before)
+          elsif pending_struct && line =~ /\)\s*do\s*(?:#.*)?$/
+            name_parts                  = pending_struct[:name].split("::")
+            namespace_stack.push([name_parts, pending_struct[:indent]])
+            current_class               = current_namespace(namespace_stack)
+            signatures[current_class] ||= {}
+            # Apply accumulated member types to @attr_types
+            if pending_struct[:members]&.any?
+              @attr_types[current_class] ||= {}
+              @attr_types[current_class].merge!(pending_struct[:members])
+            end
+            pending_rbs                 = {}
+            pending_struct              = nil
+          end
+
+          # Track `end` statements - pop if indentation matches a namespace
+          if line =~ /^(\s*)end\s*(?:#.*)?$/
+            end_indent = Regexp.last_match(1).length
+            # Pop all namespaces at this indentation level
+            namespace_stack.pop while namespace_stack.any? && namespace_stack.last[1] == end_indent
+          end
+
+          # Collect @rbs annotations
+          if line =~ /^\s*#\s*@rbs\s+(\w+):\s*(.+)$/
+            key              = Regexp.last_match(1)
+            value            = Regexp.last_match(2).strip
+            # Handle "-- description" suffix
+            type, desc       = value.split(" -- ", 2)
+            pending_rbs[key] = { type: type.strip, desc: capitalize_first(desc) }
+          end
+
+          # When we hit a method definition, apply pending RBS
+          # Matches: def foo, def foo?, def foo!, def self.foo, def [], def []=, def +, etc.
+          current_class = current_namespace(namespace_stack)
+          if !current_class.empty? && line =~ %r{^\s*def\s+(?:self\.)?(\w+[?!=]?|\[\]=?|[+\-*/%&|^<>=!~]+)}
+            method_name = Regexp.last_match(1)
+            if pending_rbs.any?
+              signatures[current_class][method_name] = build_signature(pending_rbs)
+              pending_rbs                            = {}
+            end
+          end
+
+          # Reset pending RBS on blank lines or non-comment lines (but not on def lines)
+          is_comment = line.strip.start_with?("#")
+          is_def     = line =~ /^\s*def\s/
+          is_blank   = line.strip.empty?
+
+          pending_rbs = {} if (is_blank || (!is_comment && !is_def)) && !is_def
+        end
+
+        # Store file -> namespaces mapping for files with @rbs content
+        @rbs_file_namespaces[expanded_file] = file_namespaces.uniq if file_namespaces.any?
+      end
+
+      def current_namespace(stack) = stack.flat_map { |parts, _indent| parts }.join("::")
+
+      def capitalize_first(str)
+        return nil if str.nil? || str.strip.empty?
+
+        s = str.strip
+        s[0].upcase + s[1..]
+      end
+
+      def build_signature(rbs_data)
+        params  = {}
+        returns = rbs_data.delete("return")
+
+        # Each value is now { type: "...", desc: "..." }
+        rbs_data.each do |name, data|
+          params[name] = data
+        end
+
+        # Build full signature string using just the types
+        param_str   = params.map { |name, data| "#{data[:type]} #{name}" }.join(", ")
+        return_type = returns&.dig(:type) || "void"
+        full        = "(#{param_str}) -> #{return_type}"
+
+        {
+          full:    full,
+          params:  params,  # { name => { type:, desc: } }
+          returns: returns  # { type:, desc: } or nil
+        }
+      end
+    end
+  end
+end