chiridion 0.3.4

data/lib/chiridion/engine/type_merger.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Merges RBS type signatures with YARD documentation.
+    #
+    # RBS is treated as authoritative for types. When YARD and RBS disagree,
+    # a warning is logged but RBS types are used. This ensures documentation
+    # reflects the actual type contracts defined in sig/*.rbs.
+    class TypeMerger
+      # Known type equivalences between YARD conventions and RBS.
+      BOOLEAN_TYPES    = %w[bool TrueClass FalseClass].freeze
+      GENERIC_PREFIXES = { "Hash" => "Hash[", "Array" => "Array[" }.freeze
+
+      def initialize(logger = nil) = @logger = logger
+
+      # Merge YARD params with RBS types - RBS is authoritative.
+      #
+      # @param yard_params [Array<Hash>] Parameters from YARD
+      # @param rbs_data [Hash, nil] RBS signature data
+      # @param class_path [String] Class path for warnings
+      # @param method_name [Symbol] Method name for warnings
+      # @return [Array<Hash>] Merged parameters
+      def merge_params(yard_params, rbs_data, class_path, method_name)
+        return yard_params unless rbs_data&.dig(:params)
+
+        rbs_params = rbs_data[:params]
+        yard_params.map { |p| merge_single_param(p, rbs_params, class_path, method_name) }
+      end
+
+      # Merge YARD return with RBS return type - RBS is authoritative.
+      #
+      # @param yard_return [Hash, nil] Return info from YARD
+      # @param rbs_data [Hash, nil] RBS signature data
+      # @param class_path [String] Class path for warnings
+      # @param method_name [Symbol] Method name for warnings
+      # @return [Hash, nil] Merged return info
+      def merge_return(yard_return, rbs_data, class_path, method_name)
+        return yard_return unless rbs_data&.dig(:returns)
+
+        rbs_return_data = rbs_data[:returns]
+
+        # Handle both old format (string) and new format ({ type:, desc: })
+        rbs_type = rbs_return_data.is_a?(Hash) ? rbs_return_data[:type] : rbs_return_data
+        rbs_desc = rbs_return_data.is_a?(Hash) ? rbs_return_data[:desc] : nil
+
+        if yard_return
+          check_return_mismatch(yard_return, rbs_type, class_path, method_name)
+          merged_desc = merge_description(yard_return[:text], rbs_desc)
+          yard_return.merge(types: [rbs_type], text: merged_desc)
+        else
+          { types: [rbs_type], text: rbs_desc }
+        end
+      end
+
+      private
+
+      def merge_single_param(param, rbs_params, class_path, method_name)
+        param_name = clean_param_name(param[:name])
+        rbs_data   = rbs_params[param_name]
+        return param unless rbs_data
+
+        # Handle both old format (string) and new format ({ type:, desc: })
+        rbs_type = rbs_data.is_a?(Hash) ? rbs_data[:type] : rbs_data
+        rbs_desc = rbs_data.is_a?(Hash) ? rbs_data[:desc] : nil
+
+        check_param_mismatch(param, rbs_type, class_path, method_name, param_name)
+
+        merged_desc = merge_description(param[:text], rbs_desc)
+        param.merge(types: [rbs_type], text: merged_desc)
+      end
+
+      # Merge descriptions - longer one wins, tie goes to RBS (co-located).
+      def merge_description(yard_desc, rbs_desc)
+        return rbs_desc if yard_desc.to_s.strip.empty?
+        return yard_desc if rbs_desc.to_s.strip.empty?
+
+        rbs_desc.to_s.length >= yard_desc.to_s.length ? rbs_desc : yard_desc
+      end
+
+      def clean_param_name(name) = name.to_s.gsub(/\A[*&]+/, "").delete_suffix(":")
+
+      def check_param_mismatch(param, rbs_type, class_path, method_name, param_name)
+        yard_type = param[:types]&.join(", ")
+        return if yard_type.nil? || types_compatible?(yard_type, rbs_type)
+
+        warn_mismatch(class_path, method_name, param_name, yard_type, rbs_type)
+      end
+
+      def check_return_mismatch(yard_return, rbs_return, class_path, method_name)
+        yard_type = yard_return[:types]&.join(", ")
+        return if yard_type.nil? || types_compatible?(yard_type, rbs_return)
+
+        warn_mismatch(class_path, method_name, "(return)", yard_type, rbs_return)
+      end
+
+      # Check if YARD and RBS types are compatible (loose comparison).
+      def types_compatible?(yard_type, rbs_type)
+        return true if yard_type.nil? || rbs_type.nil?
+
+        yard_norm = normalize_type(yard_type)
+        rbs_norm  = normalize_type(rbs_type)
+
+        exact_or_prefix_match?(yard_norm, rbs_norm) || equivalent_types?(yard_norm, rbs_norm)
+      end
+
+      def exact_or_prefix_match?(yard_norm, rbs_norm) = yard_norm == rbs_norm || rbs_norm.start_with?(yard_norm)
+
+      def equivalent_types?(yard_norm, rbs_norm)
+        return true if yard_norm == "Boolean" && BOOLEAN_TYPES.include?(rbs_norm)
+
+        prefix = GENERIC_PREFIXES[yard_norm]
+        prefix && rbs_norm.start_with?(prefix)
+      end
+
+      def normalize_type(type) = type.to_s.gsub(/\s+/, "").tr("<", "[").tr(">", "]")
+
+      def warn_mismatch(class_path, method_name, param_name, yard_type, rbs_type)
+        return unless @logger
+
+        @logger.warn "Type mismatch in #{class_path}##{method_name} param '#{param_name}': " \
+                     "YARD says '#{yard_type}', RBS says '#{rbs_type}' (using RBS)"
+      end
+    end
+  end
+end

data/lib/chiridion/engine/writer.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Chiridion
+  class Engine
+    # Writes generated documentation files to disk.
+    #
+    # Handles smart write detection to avoid unnecessary file updates when
+    # only timestamps have changed but content is identical.
+    class Writer
+      def initialize(
+        output,
+        namespace_strip,
+        include_specs,
+        verbose,
+        logger,
+        root: Dir.pwd,
+        github_repo: nil,
+        github_branch: "main",
+        project_title: "API Documentation",
+        index_description: nil,
+        inline_source_threshold: 10,
+        rbs_attr_types: {}
+      )
+        @output          = output
+        @namespace_strip = namespace_strip
+        @verbose         = verbose
+        @logger          = logger
+        @root            = root
+        @renderer        = Renderer.new(
+          namespace_strip:         namespace_strip,
+          include_specs:           include_specs,
+          root:                    root,
+          github_repo:             github_repo,
+          github_branch:           github_branch,
+          project_title:           project_title,
+          index_description:       index_description,
+          inline_source_threshold: inline_source_threshold,
+          rbs_attr_types:          rbs_attr_types
+        )
+      end
+
+      # Write all documentation files.
+      #
+      # @param structure [Hash] Documentation structure from Extractor
+      def write(structure)
+        FileUtils.mkdir_p(@output)
+        written, skipped = write_all_files(structure)
+        @logger.info "  #{written} files written, #{skipped} unchanged"
+      end
+
+      private
+
+      def write_all_files(structure)
+        @renderer.register_classes(structure)
+
+        counts = { written: 0, skipped: 0 }
+        write_index(structure, counts)
+        write_type_aliases(structure[:type_aliases], counts)
+        write_objects(structure[:classes] + structure[:modules], counts)
+        [counts[:written], counts[:skipped]]
+      end
+
+      def write_type_aliases(type_aliases, counts)
+        return if type_aliases.nil? || type_aliases.empty?
+
+        content = @renderer.render_type_aliases(type_aliases)
+        return if content.nil?
+
+        wrote                                = write_file(File.join(@output, "type-aliases.md"), content)
+        counts[wrote ? :written : :skipped] += 1
+      end
+
+      def write_index(structure, counts)
+        wrote                                = write_file(File.join(@output, "index.md"),
+                                                          @renderer.render_index(structure))
+        counts[wrote ? :written : :skipped] += 1
+      end
+
+      def write_objects(objects, counts)
+        objects.each do |obj|
+          next unless obj[:needs_regeneration]
+
+          write_object(obj, counts)
+        end
+      end
+
+      def write_object(obj, counts)
+        path    = output_path(obj[:path])
+        content = obj[:type] == :class ? @renderer.render_class(obj) : @renderer.render_module(obj)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        wrote = write_file(path, content)
+
+        counts[wrote ? :written : :skipped] += 1
+        @logger.info "  #{wrote ? 'Wrote' : 'Unchanged'} #{path}" if @verbose
+      end
+
+      def write_file(path, new_content)
+        return File.write(path, new_content) || true unless File.exist?(path)
+
+        old_content = File.read(path)
+        return false unless content_changed?(old_content, new_content)
+
+        File.write(path, new_content)
+        true
+      end
+
+      def content_changed?(old, new) = normalize(old) != normalize(new)
+
+      def normalize(content)
+        content
+          .gsub(/^generated: .+$/, "generated: TIMESTAMP")
+          .gsub(/\n{2,}/, "\n\n")
+          .strip
+      end
+
+      def output_path(class_path)
+        stripped    = @namespace_strip ? class_path.sub(/^#{Regexp.escape(@namespace_strip)}/, "") : class_path
+        parts       = stripped.split("::")
+        kebab_parts = parts.map { |p| to_kebab_case(p) }
+        File.join(@output, *kebab_parts[0..-2], "#{kebab_parts.last}.md")
+      end
+
+      def to_kebab_case(str)
+        str.gsub(/([A-Za-z])([vV]\d+)/, '\1-\2')
+           .gsub(/([A-Z]+)([A-Z][a-z])/, '\1-\2')
+           .gsub(/([a-z\d])([A-Z])/, '\1-\2')
+           .downcase
+      end
+    end
+  end
+end

data/lib/chiridion/engine.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "logger"
+
+module Chiridion
+  # Documentation engine for generating agent-oriented docs from Ruby source.
+  #
+  # Coordinates several specialized components:
+  # - {Extractor} - Walks YARD registry, extracts class/method/constant metadata
+  # - {RbsLoader} - Loads RBS type signatures from sig/ directory
+  # - {SpecExampleLoader} - Extracts usage examples from RSpec files
+  # - {TypeMerger} - Merges RBS types with YARD documentation
+  # - {Renderer} - Generates markdown with Obsidian-compatible wikilinks
+  # - {Writer} - Handles file I/O with content-based change detection
+  # - {DriftChecker} - Detects when docs are out of sync with source
+  #
+  # ## YARD Registry Persistence
+  #
+  # For performance, the engine persists YARD's parsed registry to .yardoc/.
+  # This enables efficient partial refreshes: when a single file changes, we
+  # load the existing registry, re-parse only that file, and regenerate only
+  # the affected documentation.
+  #
+  # @example Generate docs via Engine
+  #   engine = Chiridion::Engine.new(
+  #     paths: ['lib/myproject'],
+  #     output: 'docs/sys',
+  #     namespace_filter: 'MyProject::'
+  #   )
+  #   engine.refresh
+  #
+  # @example Partial refresh (single file)
+  #   engine = Chiridion::Engine.new(
+  #     paths: ['lib/myproject/config.rb'],
+  #     output: 'docs/sys',
+  #     namespace_filter: 'MyProject::'
+  #   )
+  #   engine.refresh
+  #
+  class Engine
+    # @return [Array<String>] Source paths being documented
+    attr_reader :paths
+
+    # @return [String] Output directory for generated docs
+    attr_reader :output
+
+    # Create a new documentation engine.
+    #
+    # @param paths [Array<String>] Source files or directories to document.
+    #   Can be specific files for partial refresh or directories for full refresh.
+    # @param output [String] Output directory for generated markdown docs.
+    # @param namespace_filter [String, nil] Only document classes starting with this prefix.
+    # @param namespace_strip [String, nil] Strip this prefix from output paths (defaults to namespace_filter).
+    # @param include_specs [Boolean] Whether to extract usage examples from spec files.
+    # @param verbose [Boolean] Whether to show detailed progress and warnings.
+    # @param logger [#info, #warn, nil] Logger for output messages.
+    # @param root [String] Project root directory for resolving relative paths.
+    # @param rbs_path [String] Path to RBS signatures directory.
+    # @param spec_path [String] Path to spec directory.
+    # @param github_repo [String, nil] GitHub repository for source links.
+    # @param github_branch [String] Git branch for source links.
+    # @param project_title [String] Title for the documentation index.
+    # @param index_description [String, nil] Custom description for the index page.
+    # @param inline_source_threshold [Integer, nil] Max body lines for inline source display.
+    # @param output_mode [:per_class, :per_file] Output organization strategy.
+    def initialize(
+      paths:,
+      output:,
+      namespace_filter: nil,
+      namespace_strip: nil,
+      include_specs: false,
+      verbose: false,
+      logger: nil,
+      root: Dir.pwd,
+      rbs_path: "sig",
+      spec_path: "test",
+      github_repo: nil,
+      github_branch: "main",
+      project_title: "API Documentation",
+      index_description: nil,
+      inline_source_threshold: 10,
+      output_mode: :per_class
+    )
+      @paths                   = Array(paths)
+      @output                  = output
+      @namespace_filter        = namespace_filter
+      @namespace_strip         = namespace_strip || namespace_filter
+      @include_specs           = include_specs
+      @verbose                 = verbose
+      @logger                  = logger || DefaultLogger.new
+      @root                    = root
+      @rbs_path                = rbs_path
+      @spec_path               = spec_path
+      @github_repo             = github_repo
+      @github_branch           = github_branch
+      @project_title           = project_title
+      @index_description       = index_description
+      @inline_source_threshold = inline_source_threshold
+      @output_mode             = output_mode
+    end
+
+    # Generate documentation from source and write to output directory.
+    #
+    # This is the main entry point for documentation generation. It:
+    # 1. Parses Ruby source files with YARD
+    # 2. Loads RBS type signatures
+    # 3. Extracts spec examples (if enabled)
+    # 4. Merges types with YARD docs
+    # 5. Renders to markdown with wikilinks
+    # 6. Writes files with content-based change detection
+    #
+    # @return [void]
+    def refresh
+      require "yard"
+      register_rbs_tag
+
+      @logger.info "Parsing Ruby files in #{paths_description}..."
+
+      load_sources
+
+      if @output_mode == :per_file
+        refresh_per_file
+      else
+        doc_structure = extract_documentation(YARD::Registry)
+        write_documentation(doc_structure)
+      end
+
+      @logger.info "Documentation written to #{@output}/"
+    end
+
+    # Generate per-file documentation using the semantic extraction pipeline.
+    #
+    # Produces one markdown file per source file, containing all namespaces
+    # (classes/modules) defined in that file.
+    #
+    # @return [void]
+    def refresh_per_file
+      extractor = SemanticExtractor.new(
+        rbs_types:        @rbs_types,
+        rbs_attr_types:   @rbs_attr_types,
+        type_aliases:     @type_aliases,
+        spec_examples:    @spec_examples,
+        namespace_filter: @namespace_filter,
+        logger:           @logger
+      )
+
+      project = extractor.extract(
+        YARD::Registry,
+        title:       @project_title,
+        description: @index_description,
+        root:        @root
+      )
+
+      writer = FileWriter.new(
+        output:                  @output,
+        namespace_strip:         @namespace_strip,
+        include_specs:           @include_specs,
+        verbose:                 @verbose,
+        logger:                  @logger,
+        root:                    @root,
+        github_repo:             @github_repo,
+        github_branch:           @github_branch,
+        project_title:           @project_title,
+        index_description:       @index_description,
+        inline_source_threshold: @inline_source_threshold
+      )
+
+      writer.write(project)
+    end
+
+    # Check for documentation drift without writing files.
+    #
+    # Compares what would be generated against existing docs. Useful in CI
+    # to ensure docs are kept in sync with source code changes.
+    #
+    # @return [void]
+    # @raise [SystemExit] Exits with code 1 if drift is detected
+    def check
+      require "yard"
+      register_rbs_tag
+
+      @logger.info "Checking documentation drift for #{paths_description}..."
+
+      load_sources
+      doc_structure = extract_documentation(YARD::Registry)
+      check_for_drift(doc_structure)
+    end
+
+    private
+
+    def paths_description = @paths.size == 1 ? @paths.first : "#{@paths.size} paths"
+
+    # Register @rbs as a known YARD tag to suppress "Unknown tag" warnings
+    def register_rbs_tag
+      return if YARD::Tags::Library.labels.key?(:rbs)
+
+      YARD::Tags::Library.define_tag("RBS type annotation", :rbs, :with_types_and_name)
+    end
+
+    def load_sources
+      # Suppress YARD's verbose proxy warnings unless in verbose mode
+      original_log_level          = YARD::Logger.instance.level
+      YARD::Logger.instance.level = @verbose ? ::Logger::WARN : ::Logger::ERROR
+
+      @source_files = @paths.flat_map { |p| resolve_ruby_files(p) }.map { |f| File.expand_path(f) }
+
+      if partial_refresh?
+        load_or_create_registry
+      else
+        YARD::Registry.clear
+      end
+      YARD.parse(@source_files)
+      YARD::Registry.save(true)
+
+      YARD::Logger.instance.level = original_log_level
+
+      # Load RBS types: inline annotations take precedence over sig/ files
+      inline_types, @rbs_file_namespaces, @rbs_attr_types = InlineRbsLoader.new(@verbose, @logger).load(@source_files)
+      sig_types                                           = RbsLoader.new(@rbs_path, @verbose, @logger).load
+      @rbs_types                                          = merge_rbs_types(sig_types, inline_types)
+
+      # Load type aliases from generated RBS files (sig/generated/ is standard for RBS::Inline)
+      rbs_generated_dir = find_rbs_generated_dir
+      @type_aliases     = RbsTypeAliasLoader.new(@verbose, @logger, rbs_dir: rbs_generated_dir).load
+
+      @spec_examples = @include_specs ? SpecExampleLoader.new(@spec_path, @verbose, @logger).load : {}
+    end
+
+    def partial_refresh? = @paths.all? { |p| File.file?(p) }
+
+    def load_or_create_registry
+      yardoc_path = File.join(@root, ".yardoc")
+      if File.exist?(yardoc_path)
+        YARD::Registry.load(yardoc_path)
+      else
+        YARD::Registry.clear
+      end
+    end
+
+    # Locate directory containing generated RBS files.
+    #
+    # RBS::Inline outputs to sig/generated/ by convention. Falls back to
+    # sig/ if generated/ doesn't exist, or nil if no RBS directory exists.
+    def find_rbs_generated_dir
+      generated_dir = File.join(@root, @rbs_path, "generated")
+      return generated_dir if Dir.exist?(generated_dir)
+
+      sig_dir = File.join(@root, @rbs_path)
+      return sig_dir if Dir.exist?(sig_dir)
+
+      nil
+    end
+
+    def resolve_ruby_files(path)
+      if File.directory?(path)
+        Dir.glob("#{path}/**/*.rb")
+      elsif File.file?(path) && path.end_with?(".rb")
+        [path]
+      else
+        @logger.warn "Skipping invalid path: #{path}"
+        []
+      end
+    end
+
+    def extract_documentation(registry)
+      source_filter = partial_refresh? ? @source_files : nil
+      structure     = Extractor.new(
+        @rbs_types,
+        @spec_examples,
+        @namespace_filter,
+        @logger,
+        rbs_file_namespaces: @rbs_file_namespaces,
+        type_aliases:        @type_aliases
+      ).extract(registry, source_filter: source_filter)
+
+      # Add type aliases to the structure (for standalone reference page)
+      structure[:type_aliases] = @type_aliases
+      structure
+    end
+
+    def write_documentation(structure)
+      Writer.new(
+        @output,
+        @namespace_strip,
+        @include_specs,
+        @verbose,
+        @logger,
+        root:                    @root,
+        github_repo:             @github_repo,
+        github_branch:           @github_branch,
+        project_title:           @project_title,
+        index_description:       @index_description,
+        inline_source_threshold: @inline_source_threshold,
+        rbs_attr_types:          @rbs_attr_types
+      ).write(structure)
+    end
+
+    def check_for_drift(structure)
+      DriftChecker.new(
+        @output,
+        @namespace_strip,
+        @include_specs,
+        @verbose,
+        @logger,
+        root:                    @root,
+        github_repo:             @github_repo,
+        github_branch:           @github_branch,
+        project_title:           @project_title,
+        inline_source_threshold: @inline_source_threshold
+      ).check(structure)
+    end
+
+    # Merge RBS types from sig/ files and inline annotations.
+    # Inline types take precedence over sig/ file types.
+    def merge_rbs_types(sig_types, inline_types)
+      merged = sig_types.dup
+
+      inline_types.each do |class_name, methods|
+        merged[class_name] ||= {}
+        methods.each do |method_name, sig|
+          merged[class_name][method_name] = sig
+        end
+      end
+
+      merged
+    end
+  end
+
+  # Simple default logger that prints to stderr.
+  class DefaultLogger
+    def info(msg) = Kernel.warn(msg)
+    def warn(msg) = Kernel.warn("WARNING: #{msg}")
+    def error(msg) = Kernel.warn("ERROR: #{msg}")
+  end
+end
+
+# Load engine subcomponents
+require_relative "engine/extractor"
+require_relative "engine/rbs_loader"
+require_relative "engine/inline_rbs_loader"
+require_relative "engine/rbs_type_alias_loader"
+require_relative "engine/spec_example_loader"
+require_relative "engine/type_merger"
+require_relative "engine/class_linker"
+require_relative "engine/github_linker"
+require_relative "engine/frontmatter_builder"
+require_relative "engine/template_renderer"
+require_relative "engine/renderer"
+require_relative "engine/writer"
+require_relative "engine/drift_checker"
+
+# Semantic extraction and per-file output pipeline
+require_relative "engine/document_model"
+require_relative "engine/semantic_extractor"
+require_relative "engine/semantic_renderer"
+require_relative "engine/file_renderer"
+require_relative "engine/file_writer"
+require_relative "engine/post_processor"