chiridion 0.3.4

data/lib/chiridion/engine/post_processor.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Post-processes rendered markdown for consistent formatting.
+    #
+    # Handles normalization that's easier to do as a final pass rather than
+    # trying to get perfect output from templates. May grow into fuller
+    # linting/validation over time.
+    #
+    # Current normalizations:
+    # - Collapse multiple consecutive newlines to single newlines
+    # - Ensure 2 newlines before horizontal rules (---)
+    # - Preserve frontmatter formatting
+    class PostProcessor
+      # Normalize markdown content.
+      #
+      # @param content [String] Raw markdown content
+      # @return [String] Normalized content
+      def self.process(content)
+        new.process(content)
+      end
+
+      # @param content [String] Raw markdown content
+      # @return [String] Normalized content
+      def process(content)
+        # Split off frontmatter to preserve it exactly
+        frontmatter, body = split_frontmatter(content)
+
+        # Normalize the body
+        normalized = normalize_newlines(body)
+
+        # Reassemble
+        frontmatter ? "#{frontmatter}\n\n#{normalized}" : normalized
+      end
+
+      private
+
+      # Split YAML frontmatter from body content.
+      #
+      # @param content [String] Full markdown content
+      # @return [Array(String, String), Array(nil, String)] [frontmatter, body] or [nil, content]
+      def split_frontmatter(content)
+        return [nil, content] unless content.start_with?("---")
+
+        # Find closing ---
+        lines = content.lines
+        closing_idx = lines[1..].index { |l| l.strip == "---" }
+        return [nil, content] unless closing_idx
+
+        # closing_idx is relative to lines[1..], so actual index is closing_idx + 1
+        fm_end = closing_idx + 2 # +1 for 0-index, +1 for the closing line itself
+        frontmatter = lines[0...fm_end].join.strip
+        body = lines[fm_end..].join
+
+        [frontmatter, body]
+      end
+
+      # Normalize newlines in body content.
+      #
+      # Rules (applied in order):
+      # 1. Collapse runs of 3+ newlines to exactly 2 (one blank line)
+      # 2. Ensure 2 newlines before horizontal rules (---)
+      # 3. Remove blank lines after horizontal rules (---)
+      # 4. Remove blank lines after headers (# ## ### ####)
+      #
+      # @param body [String] Body content (no frontmatter)
+      # @return [String] Normalized body
+      def normalize_newlines(body)
+        # Step 1: Collapse 3+ newlines to exactly 2
+        result = body.gsub(/\n{3,}/, "\n\n")
+
+        # Step 2: Ensure 2 newlines before horizontal rules
+        result = result.gsub(/\n(---)/, "\n\n\\1")
+
+        # Step 3: Remove blank lines after horizontal rules
+        result = result.gsub(/^(---)\n+/, "\\1\n")
+
+        # Step 4: Remove blank lines after headers
+        result = result.gsub(/^(\#{1,6}\s+.+)\n+/, "\\1\n")
+
+        result.strip
+      end
+    end
+  end
+end

data/lib/chiridion/engine/rbs_loader.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Loads RBS type signatures from sig/ directory for documentation enrichment.
+    #
+    # Parses RBS files and extracts method signatures to merge with YARD documentation,
+    # providing accurate type information in generated docs.
+    class RbsLoader
+      def initialize(rbs_path, verbose, logger)
+        @rbs_path = rbs_path
+        @verbose  = verbose
+        @logger   = logger
+      end
+
+      # Load all RBS files and return a hash of class -> method -> signature.
+      #
+      # @return [Hash{String => Hash{String => Hash}}] Nested hash of signatures
+      def load
+        signatures = {}
+        rbs_files  = Dir.glob("#{@rbs_path}/**/*.rbs")
+
+        return signatures if rbs_files.empty?
+
+        @logger.info "Loading #{rbs_files.size} RBS files..." if @verbose
+        rbs_files.each { |file| parse_file(file, signatures) }
+        signatures
+      end
+
+      private
+
+      def parse_file(file, signatures)
+        content       = File.read(file)
+        current_class = nil
+
+        content.each_line do |line|
+          current_class = extract_class_name(line, signatures, current_class)
+          next unless current_class
+
+          extract_method_signature(line, signatures, current_class)
+          extract_attr_signature(line, signatures, current_class)
+        end
+      end
+
+      def extract_class_name(line, signatures, current_class)
+        return current_class unless line =~ /^\s*(?:class|module)\s+([\w:]+)/
+
+        class_name               = Regexp.last_match(1)
+        signatures[class_name] ||= {}
+        class_name
+      end
+
+      def extract_method_signature(line, signatures, current_class)
+        return unless line =~ /^\s*def\s+(?:self\.)?(\w+[?!]?):\s*(.+)$/
+
+        method_name                            = Regexp.last_match(1)
+        full_sig                               = Regexp.last_match(2).strip
+        signatures[current_class][method_name] = parse_signature(full_sig)
+      end
+
+      def extract_attr_signature(line, signatures, current_class)
+        return unless line =~ /^\s*attr_(?:reader|accessor)\s+(\w+):\s*(.+)$/
+
+        attr_name                            = Regexp.last_match(1)
+        attr_type                            = Regexp.last_match(2).strip
+        signatures[current_class][attr_name] = {
+          full:    "() -> #{attr_type}",
+          params:  {},
+          returns: attr_type
+        }
+      end
+
+      # Parse RBS signature into structured data.
+      #
+      # @param sig [String] RBS signature string
+      # @return [Hash] Parsed signature with :full, :params, :returns keys
+      def parse_signature(sig)
+        result = { full: sig, params: {}, returns: nil }
+
+        if sig =~ /\A\(([^)]*)\)\s*->\s*(.+)\z/
+          params_str       = Regexp.last_match(1)
+          result[:returns] = Regexp.last_match(2).strip
+          parse_params(params_str, result[:params])
+        elsif sig =~ /\A\(\)\s*->\s*(.+)\z/
+          result[:returns] = Regexp.last_match(1).strip
+        end
+
+        result
+      end
+
+      # Parse RBS parameter list, handling nested brackets.
+      def parse_params(params_str, result)
+        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)
+        end
+      end
+
+      def parse_single_param(param, result)
+        # Keyword arg: `?name: Type?` or `name: Type`
+        if param =~ /\A\??(\w+):\s*(.+)\z/
+          name         = Regexp.last_match(1)
+          type         = Regexp.last_match(2).strip.delete_suffix("?")
+          result[name] = type
+        # 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
+        end
+      end
+
+      # Split string by commas while respecting nested brackets [], {}, ().
+      def split_respecting_brackets(str)
+        result  = []
+        current = +""  # Mutable string
+        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 = +""  # Mutable string
+            else
+              current << c
+            end
+          else
+            current << c
+          end
+        end
+
+        result << current unless current.empty?
+        result
+      end
+    end
+  end
+end

data/lib/chiridion/engine/rbs_type_alias_loader.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Extracts RBS type alias definitions from generated .rbs files.
+    #
+    # Reads type aliases from RBS files (typically in sig/generated/) which have
+    # already been properly parsed by RBS::Inline. This is more reliable than
+    # re-parsing @rbs! blocks ourselves.
+    #
+    # RBS format is straightforward:
+    #   module Namespace
+    #     # Description comment
+    #     type name = definition
+    #   end
+    #
+    # @example
+    #   loader = RbsTypeAliasLoader.new(true, logger, rbs_dir: "sig/generated")
+    #   type_aliases = loader.load
+    #   # => { "Archema" => [{ name: "attribute_value", definition: "...", ... }] }
+    #
+    class RbsTypeAliasLoader
+      def initialize(verbose, logger, rbs_dir: nil)
+        @verbose = verbose
+        @logger  = logger
+        @rbs_dir = rbs_dir
+      end
+
+      # Extract type aliases from generated RBS files.
+      #
+      # @return [Hash{String => Array<Hash>}] namespace -> array of type definitions
+      def load
+        type_aliases = {}
+        return type_aliases unless @rbs_dir && Dir.exist?(@rbs_dir)
+
+        rbs_files = Dir.glob(File.join(@rbs_dir, "**/*.rbs"))
+        rbs_files.each do |file|
+          parse_rbs_file(file, type_aliases)
+        end
+
+        count = type_aliases.values.flatten.size
+        @logger.info "Extracted #{count} type aliases from #{rbs_files.size} RBS files" if @verbose && count.positive?
+        type_aliases
+      end
+
+      private
+
+      # Parse a .rbs file for type aliases.
+      #
+      # RBS files have a clean, well-defined format:
+      #   module Foo
+      #     # comment
+      #     type name = definition
+      #   end
+      def parse_rbs_file(file, type_aliases)
+        content = File.read(file)
+        return unless content.include?("type ")
+
+        expanded_file   = File.expand_path(file)
+        lines           = content.lines
+        namespace_stack = []
+        pending_comment = nil
+
+        lines.each_with_index do |line, idx|
+          line_num = idx + 1
+          stripped = line.strip
+
+          # Track module/class context (RBS uses same syntax)
+          # Reset pending_comment - comments before class/module are for that class, not types inside
+          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?
+            next
+          end
+
+          # Collect comments (description for next type)
+          if stripped.start_with?("#")
+            # Accumulate multi-line comments, preserving newlines
+            comment_text    = stripped.sub(/^#\s?/, "")
+            pending_comment = pending_comment ? "#{pending_comment}\n#{comment_text}" : comment_text
+            next
+          end
+
+          # Skip blank lines (preserve pending_comment across blanks)
+          next if stripped.empty?
+
+          # Parse type definition
+          if stripped =~ /^type\s+(\w+)\s*=\s*(.+)$/
+            type_name = Regexp.last_match(1)
+            type_def  = Regexp.last_match(2)
+
+            namespace                 = namespace_stack.join("::")
+            type_aliases[namespace] ||= []
+            type_aliases[namespace] << {
+              name:        type_name,
+              definition:  type_def,
+              description: pending_comment,
+              file:        expanded_file,
+              line:        line_num
+            }
+          end
+
+          # Reset pending comment after any non-comment, non-blank line
+          pending_comment = nil
+        end
+      end
+    end
+  end
+end