chiridion 0.3.4

data/lib/chiridion/engine/document_model.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Comprehensive semantic document model for extracted documentation.
+    #
+    # This module defines immutable data structures that capture ALL information
+    # from YARD and RBS sources. The goal is complete semantic extraction,
+    # independent of rendering concerns.
+    #
+    # Design principles:
+    # - Capture everything, filter/format at render time
+    # - Prefer explicit nil over missing keys
+    # - Use typed structures (Data.define) for compile-time safety
+    # - Group related data (e.g., yield info together)
+    #
+    # @see TODO.md for the complete tag inventory this model addresses
+    module DocumentModel
+      # Parameter documentation (method param or @option entry).
+      #
+      # @example Basic parameter
+      #   ParamDoc.new(name: "id", type: "String", description: "User ID", default: nil)
+      #
+      # @example Optional with default
+      #   ParamDoc.new(name: "limit", type: "Integer", description: "Max results", default: "10")
+      ParamDoc = Data.define(
+        :name,        # String - parameter name (cleaned, no sigils)
+        :type,        # String? - RBS/YARD type expression
+        :description, # String? - description text
+        :default,     # String? - default value (as string from source)
+        :prefix       # String? - "*", "**", "&" for splat/block params
+      ) do
+        def self.from_hash(h)
+          new(
+            name:        h[:name]&.to_s,
+            type:        normalize_type(h[:types]),
+            description: h[:text],
+            default:     h[:default],
+            prefix:      extract_prefix(h[:name])
+          )
+        end
+
+        def self.normalize_type(types)
+          return nil if types.nil? || types.empty?
+
+          Array(types).first&.to_s
+        end
+
+        def self.extract_prefix(name)
+          s = name.to_s
+          return "**" if s.start_with?("**")
+          return "*" if s.start_with?("*")
+          return "&" if s.start_with?("&")
+
+          nil
+        end
+      end
+
+      # @option tag documentation (hash parameter options).
+      OptionDoc = Data.define(
+        :param_name,  # String - the hash param this option belongs to
+        :key,         # String - the option key name
+        :type,        # String? - option value type
+        :description  # String? - description
+      )
+
+      # Block/yield documentation.
+      #
+      # Captures @yield, @yieldparam, and @yieldreturn together.
+      YieldDoc = Data.define(
+        :description,   # String? - @yield description
+        :params,        # Array[ParamDoc] - @yieldparam entries
+        :return_type,   # String? - @yieldreturn type
+        :return_desc,   # String? - @yieldreturn description
+        :block_type     # String? - RBS block signature like "^(Batch) -> void"
+      )
+
+      # Exception documentation.
+      RaiseDoc = Data.define(
+        :type,        # String - exception class name
+        :description  # String? - when/why raised
+      )
+
+      # Return type documentation.
+      ReturnDoc = Data.define(
+        :type,        # String? - return type
+        :description  # String? - what it returns
+      )
+
+      # Example documentation.
+      ExampleDoc = Data.define(
+        :name,  # String? - example name/title
+        :code   # String - example code
+      )
+
+      # Cross-reference (@see tag).
+      SeeDoc = Data.define(
+        :target, # String - what to see (class, method, URL)
+        :text    # String? - additional context
+      )
+
+      # Instance variable documentation.
+      IvarDoc = Data.define(
+        :name,        # String - ivar name without @
+        :type,        # String? - RBS type
+        :description  # String? - description
+      )
+
+      # Constant documentation.
+      ConstantDoc = Data.define(
+        :name,        # String - constant name
+        :value,       # String? - constant value (stringified)
+        :type,        # String? - RBS type if declared
+        :description  # String? - docstring
+      )
+
+      # Type alias documentation.
+      TypeAliasDoc = Data.define(
+        :name,        # String - alias name
+        :definition,  # String - RBS type definition
+        :description, # String? - description
+        :namespace    # String - where defined
+      )
+
+      # Method signature overload.
+      OverloadDoc = Data.define(
+        :signature,   # String - full RBS signature
+        :description  # String? - description for this overload
+      )
+
+      # Method documentation - comprehensive capture of all method info.
+      MethodDoc = Data.define(
+        # Identity
+        :name,              # Symbol - method name
+        :scope,             # Symbol - :class or :instance
+        :visibility,        # Symbol - :public, :protected, :private
+        :signature,         # String - Ruby signature from YARD
+
+        # Documentation
+        :docstring,         # String? - main docstring
+        :params,            # Array[ParamDoc] - parameters
+        :options,           # Array[OptionDoc] - @option entries
+        :returns,           # ReturnDoc? - return info
+        :yields,            # YieldDoc? - block/yield info
+        :raises,            # Array[RaiseDoc] - exceptions
+        :examples,          # Array[ExampleDoc] - @example tags
+        :notes,             # Array[String] - @note entries
+        :see_also,          # Array[SeeDoc] - @see entries
+
+        # Metadata
+        :api,               # String? - @api value (private, public, internal)
+        :deprecated,        # String? - deprecation message or true/"" if just tagged
+        :abstract,          # bool - is abstract?
+        :since,             # String? - @since version
+        :todo,              # String? - @todo message
+
+        # RBS-specific
+        :rbs_signature,     # String? - full RBS signature
+        :overloads,         # Array[OverloadDoc] - method overloads from RBS
+
+        # Source
+        :source,            # String? - source code
+        :source_body_lines, # Integer? - body line count (for inline display threshold)
+        :attr_type,         # Symbol? - :reader, :writer, :accessor if attr method
+        :file,              # String? - source file
+        :line,              # Integer? - line number
+
+        # Spec integration
+        :spec_examples,     # Array[Hash] - examples from specs
+        :spec_behaviors     # Array[String] - behavior descriptions
+      )
+
+      # Attribute documentation (synthesized from reader/writer pairs).
+      AttributeDoc = Data.define(
+        :name,        # String - attribute name
+        :type,        # String? - type from RBS or YARD
+        :description, # String? - description
+        :mode,        # Symbol - :read, :write, :read_write
+        :reader,      # MethodDoc? - reader method doc
+        :writer       # MethodDoc? - writer method doc
+      )
+
+      # Class or module documentation.
+      NamespaceDoc = Data.define(
+        # Identity
+        :name,              # String - short name
+        :path,              # String - full path (Foo::Bar)
+        :type,              # Symbol - :class or :module
+        :superclass,        # String? - superclass path (classes only)
+
+        # Documentation
+        :docstring,         # String? - main docstring
+        :examples,          # Array[ExampleDoc] - @example tags
+        :notes,             # Array[String] - @note entries
+        :see_also,          # Array[SeeDoc] - @see entries
+
+        # Metadata
+        :api,               # String? - @api value
+        :deprecated,        # String? - deprecation message
+        :abstract,          # bool - is abstract?
+        :since,             # String? - @since version
+        :todo,              # String? - @todo message
+
+        # Relationships
+        :includes,          # Array[String] - included modules
+        :extends,           # Array[String] - extended modules
+
+        # Members
+        :constants,         # Array[ConstantDoc]
+        :type_aliases,      # Array[TypeAliasDoc] - local type aliases
+        :ivars,             # Array[IvarDoc] - instance variables
+        :attributes,        # Array[AttributeDoc] - synthesized attributes
+        :methods,           # Array[MethodDoc] - public methods
+        :private_methods,   # Array[MethodDoc] - private/protected (may be minimal)
+
+        # Source
+        :file,              # String? - source file
+        :line,              # Integer? - start line
+        :end_line,          # Integer? - end line
+        :rbs_file,          # String? - corresponding RBS file
+
+        # Spec integration
+        :spec_examples,     # Hash? - class-level spec examples
+
+        # Cross-references (populated after extraction)
+        :referenced_types   # Array[TypeAliasDoc] - types used by this class
+      )
+
+      # Documentation for a single source file.
+      #
+      # Groups all namespaces (classes/modules) defined in one Ruby file.
+      # This is the primary unit for per-file documentation output.
+      FileDoc = Data.define(
+        :path,              # String - source file path (relative to project root)
+        :namespaces,        # Array[NamespaceDoc] - classes/modules in this file
+        :type_aliases,      # Array[TypeAliasDoc] - type aliases defined in this file
+        :line_count         # Integer? - total lines in source file
+      ) do
+        # Short filename for display (e.g., "attributes.rb")
+        def filename = File.basename(path)
+
+        # Directory portion (e.g., "lib/archema")
+        def dirname = File.dirname(path)
+
+        # Main namespace - the one that best represents this file's purpose.
+        #
+        # Selection order:
+        # 1. Namespace whose name matches filename (query.rb -> Query)
+        # 2. Module (often the container for nested classes)
+        # 3. Shortest path (top-level namespace)
+        # 4. Most content as tiebreaker
+        def primary_namespace
+          return namespaces.first if namespaces.size == 1
+          return nil if namespaces.empty?
+
+          basename = File.basename(path, ".rb")
+          # Convert snake_case to variations for matching
+          name_variants = [
+            basename,                                    # document_model
+            basename.gsub("_", ""),                      # documentmodel
+            basename.split("_").map(&:capitalize).join  # DocumentModel
+          ]
+
+          # Try to find namespace whose name matches filename
+          name_match = namespaces.find do |n|
+            name_variants.any? { |v| n.name.downcase == v.downcase }
+          end
+          return name_match if name_match
+
+          # Prefer modules (they're usually the container)
+          modules_list = namespaces.select { |n| n.type == :module }
+          if modules_list.any?
+            # Among modules, prefer shortest path (top-level)
+            return modules_list.min_by { |n| n.path.count("::") }
+          end
+
+          # Among classes, prefer shortest path
+          namespaces.min_by { |n| n.path.count("::") }
+        end
+
+        def classes = namespaces.select { |n| n.type == :class }
+        def modules = namespaces.select { |n| n.type == :module }
+      end
+
+      # Complete documentation structure for a project.
+      ProjectDoc = Data.define(
+        :title,             # String - project title
+        :description,       # String? - project description
+        :namespaces,        # Array[NamespaceDoc] - all documented classes/modules
+        :files,             # Array[FileDoc] - per-file documentation (for per-file output)
+        :type_aliases,      # Hash[String, Array[TypeAliasDoc]] - global type aliases
+        :generated_at       # Time - generation timestamp
+      ) do
+        def classes = namespaces.select { |n| n.type == :class }
+        def modules = namespaces.select { |n| n.type == :module }
+      end
+    end
+  end
+end

data/lib/chiridion/engine/drift_checker.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Detects when documentation is out of sync with source code.
+    #
+    # Compares what would be generated against existing files.
+    # Useful in CI pipelines to enforce documentation currency.
+    class DriftChecker
+      def initialize(
+        output,
+        namespace_strip,
+        include_specs,
+        verbose,
+        logger,
+        root: Dir.pwd,
+        github_repo: nil,
+        github_branch: "main",
+        project_title: "API Documentation",
+        inline_source_threshold: 10
+      )
+        @output          = output
+        @namespace_strip = namespace_strip
+        @include_specs   = include_specs
+        @verbose         = verbose
+        @logger          = logger
+        @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,
+          inline_source_threshold: inline_source_threshold
+        )
+      end
+
+      # Check for drift between source and existing documentation.
+      #
+      # @param structure [Hash] Documentation structure from Extractor
+      # @raise [SystemExit] Exits with code 1 if drift is detected
+      def check(structure)
+        @renderer.register_classes(structure)
+
+        drifted  = []
+        missing  = []
+        orphaned = find_orphaned_files(structure)
+
+        check_index(structure, drifted, missing)
+        check_objects(structure[:classes] + structure[:modules], drifted, missing)
+
+        report_results(drifted, missing, orphaned)
+      end
+
+      private
+
+      def check_index(structure, drifted, missing)
+        path     = File.join(@output, "index.md")
+        expected = @renderer.render_index(structure)
+        check_file(path, expected, drifted, missing)
+      end
+
+      def check_objects(objects, drifted, missing)
+        objects.each do |obj|
+          next unless obj[:needs_regeneration]
+
+          path     = output_path(obj[:path])
+          expected = obj[:type] == :class ? @renderer.render_class(obj) : @renderer.render_module(obj)
+          check_file(path, expected, drifted, missing)
+        end
+      end
+
+      def check_file(path, expected, drifted, missing)
+        if File.exist?(path)
+          actual = File.read(path)
+          drifted << path if content_changed?(actual, expected)
+        else
+          missing << path
+        end
+      end
+
+      def find_orphaned_files(structure)
+        return [] unless File.directory?(@output)
+
+        expected_files = Set.new
+        expected_files << File.join(@output, "index.md")
+
+        (structure[:classes] + structure[:modules]).each do |obj|
+          expected_files << output_path(obj[:path])
+        end
+
+        actual_files = Dir.glob("#{@output}/**/*.md")
+        actual_files.reject { |f| expected_files.include?(f) }
+      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 report_results(drifted, missing, orphaned)
+        total_issues = drifted.size + missing.size + orphaned.size
+
+        if total_issues.zero?
+          @logger.info "  No drift detected. Documentation is up to date."
+          return
+        end
+
+        @logger.warn "Documentation drift detected!"
+        @logger.warn ""
+        report_list("Drifted (content changed)", drifted)
+        report_list("Missing (new classes)", missing)
+        report_list("Orphaned (classes removed)", orphaned)
+        @logger.warn ""
+        @logger.warn "Run 'chiridion refresh' to update documentation."
+
+        exit 1
+      end
+
+      def report_list(label, files)
+        return if files.empty?
+
+        @logger.warn "  #{label}:"
+        files.each { |f| @logger.warn "    - #{f}" }
+      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