chiridion 0.3.4

data/lib/chiridion/semantic_engine.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "logger"
+
+module Chiridion
+  # Semantic documentation engine - outputs structured JSON data.
+  #
+  # This is an alternative to the regular Engine that focuses on semantic
+  # extraction and outputs machine-readable JSON alongside markdown. It's
+  # useful for:
+  #
+  # - Verifying what data is being captured
+  # - Debugging the extraction pipeline
+  # - Generating LLM-friendly documentation
+  # - Separating extraction from presentation
+  #
+  # Usage:
+  #   engine = Chiridion::SemanticEngine.new(
+  #     paths: ['lib/myproject'],
+  #     output: 'docs/sys',
+  #     namespace_filter: 'MyProject::'
+  #   )
+  #   engine.refresh
+  #
+  class SemanticEngine
+    attr_reader :paths, :output
+
+    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",
+      project_title: "API Documentation",
+      project_description: nil
+    )
+      @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
+      @project_title       = project_title
+      @project_description = project_description
+    end
+
+    def refresh
+      require "yard"
+      register_rbs_tag
+
+      @logger.info "Semantic extraction from #{paths_description}..."
+
+      # Load sources
+      load_sources
+
+      # Extract using SemanticExtractor
+      project_doc = extract_documentation
+
+      # Render to JSON+markdown
+      files = render_documentation(project_doc)
+
+      # Write files
+      write_files(files)
+
+      @logger.info "Semantic docs written to #{@output}/ (#{files.size} files)"
+    end
+
+    private
+
+    def paths_description = @paths.size == 1 ? @paths.first : "#{@paths.size} paths"
+
+    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
+      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) }
+
+      YARD::Registry.clear
+      YARD.parse(@source_files)
+
+      # Load from generated RBS (authoritative types)
+      rbs_generated_dir = find_rbs_generated_dir
+      if rbs_generated_dir
+        @rbs_data = Engine::GeneratedRbsLoader.new(verbose: @verbose, logger: @logger).load(rbs_generated_dir)
+        @logger.info "Loaded types from #{rbs_generated_dir}" if @verbose
+      else
+        @rbs_data = Engine::GeneratedRbsLoader::Result.new(
+          signatures: {}, ivars: {}, attrs: {}, type_aliases: {}, overloads: {}
+        )
+      end
+
+      # Load spec examples if enabled
+      @spec_examples = @include_specs ? Engine::SpecExampleLoader.new(@spec_path, @verbose, @logger).load : {}
+    end
+
+    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
+      extractor = Engine::SemanticExtractor.new(
+        rbs_types:        @rbs_data.signatures,
+        rbs_attr_types:   @rbs_data.attrs,
+        rbs_ivar_types:   @rbs_data.ivars,
+        type_aliases:     @rbs_data.type_aliases,
+        spec_examples:    @spec_examples,
+        namespace_filter: @namespace_filter,
+        logger:           @logger
+      )
+
+      extractor.extract(
+        YARD::Registry,
+        title:       @project_title,
+        description: @project_description
+      )
+    end
+
+    def render_documentation(project_doc)
+      renderer = Engine::SemanticRenderer.new(
+        namespace_strip: @namespace_strip,
+        project_title:   @project_title
+      )
+
+      renderer.render(project_doc)
+    end
+
+    def write_files(files)
+      FileUtils.mkdir_p(@output)
+
+      files.each do |filename, content|
+        filepath = File.join(@output, filename)
+        dir      = File.dirname(filepath)
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+
+        # Only write if content changed
+        if File.exist?(filepath)
+          existing = File.read(filepath)
+          next if existing == content
+        end
+
+        File.write(filepath, content)
+        @logger.info "  Wrote #{filename}" if @verbose
+      end
+    end
+  end
+end
+
+# Load required components
+require_relative "engine/document_model"
+require_relative "engine/generated_rbs_loader"
+require_relative "engine/semantic_extractor"
+require_relative "engine/semantic_renderer"
+require_relative "engine/type_merger"
+require_relative "engine/spec_example_loader"

data/lib/chiridion/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Chiridion
+  VERSION = "0.3.4"
+end

data/lib/chiridion.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "chiridion/version"
+require_relative "chiridion/config"
+require_relative "chiridion/engine"
+
+# Chiridion: Agent-oriented documentation generator for Ruby projects.
+#
+# Chiridion ("handbook" in Greek, from the same root as Enchiridion) generates
+# documentation optimized for AI agents and LLMs working with Ruby codebases.
+# It extracts documentation from YARD comments, merges RBS type signatures,
+# and produces structured markdown suitable for context injection.
+#
+# ## Key Features
+#
+# - **YARD Integration**: Extracts docstrings, @param, @return, @example tags
+# - **RBS Authority**: RBS type signatures are authoritative over YARD types
+# - **Spec Examples**: Extracts usage examples from RSpec files
+# - **Wikilinks**: Obsidian-compatible [[Class::Name]] cross-references
+# - **Drift Detection**: CI mode to ensure docs stay in sync with code
+#
+# ## Design Philosophy
+#
+# Traditional documentation is written for human developers reading in browsers.
+# Agent-oriented documentation is optimized for LLMs processing in context windows:
+#
+# - Structured frontmatter with navigation metadata
+# - Explicit type information (not just prose descriptions)
+# - Cross-reference links that can be followed programmatically
+# - Compact but complete method signatures
+#
+# @example Basic usage
+#   engine = Chiridion::Engine.new(
+#     paths: ['lib/myproject'],
+#     output: 'docs/sys',
+#     namespace_filter: 'MyProject::'
+#   )
+#   engine.refresh
+#
+# @example Configuration block
+#   Chiridion.configure do |config|
+#     config.output = 'docs/sys'
+#     config.namespace_filter = 'MyProject::'
+#     config.github_repo = 'user/repo'
+#     config.include_specs = true
+#   end
+#   Chiridion.refresh(['lib/myproject'])
+#
+module Chiridion
+  class Error < StandardError; end
+
+  class << self
+    # @return [Config] Global configuration instance
+    def config = @config ||= Config.new
+
+    # Configure Chiridion with a block.
+    #
+    # @yield [Config] Configuration object
+    # @return [Config] Configured instance
+    def configure
+      yield config
+      config
+    end
+
+    # Reset configuration to defaults (useful for testing).
+    def reset_config! = @config = Config.new
+
+    # Convenience method to run documentation refresh.
+    #
+    # @param paths [Array<String>] Source paths to document
+    # @param output [String, nil] Override output directory
+    # @return [void]
+    def refresh(paths = nil, output: nil)
+      engine = Engine.new(
+        paths:                   paths || [config.source_path],
+        output:                  output || config.output,
+        namespace_filter:        config.namespace_filter,
+        include_specs:           config.include_specs,
+        verbose:                 config.verbose,
+        logger:                  config.logger,
+        inline_source_threshold: config.inline_source_threshold,
+        output_mode:             config.output_mode
+      )
+      engine.refresh
+    end
+
+    # Convenience method to check for documentation drift.
+    #
+    # @param paths [Array<String>] Source paths to check
+    # @return [void]
+    # @raise [SystemExit] Exits with code 1 if drift detected
+    def check(paths = nil)
+      engine = Engine.new(
+        paths:                   paths || [config.source_path],
+        output:                  config.output,
+        namespace_filter:        config.namespace_filter,
+        include_specs:           config.include_specs,
+        verbose:                 config.verbose,
+        logger:                  config.logger,
+        inline_source_threshold: config.inline_source_threshold,
+        output_mode:             config.output_mode
+      )
+      engine.check
+    end
+  end
+end

data/templates/constants.liquid

@@ -0,0 +1,27 @@
+{% comment %}
+Constants section template.
+Variables:
+  - constants: Array of {name:, value:, docstring:, is_complex:}
+  - complex_constants: Array of complex constants for separate rendering
+{% endcomment %}
+## Constants
+{%- assign has_simple = false %}{% for c in constants %}{% unless c.is_complex %}{% assign has_simple = true %}{% endunless %}{% endfor %}
+{%- if has_simple %}
+
+| Constant | Value | Description |
+|----------|-------|-------------|
+{% for c in constants %}{%- unless c.is_complex -%}
+| `{{ c.name }}` | `{{ c.value | escape_pipes }}` | {{ c.docstring | strip_rbs_blocks | strip_newlines }} |
+{% endunless -%}{% endfor -%}
+{%- endif -%}
+{%- for c in complex_constants %}
+
+### {{ c.name }}
+{% assign clean_doc = c.docstring | strip_rbs_blocks | normalize_headers: 4 -%}
+{%- if clean_doc != blank %}
+{{ clean_doc }}
+{% endif -%}
+```ruby
+{{ c.name }} = {{ c.value }}
+```
+{%- endfor -%}

data/templates/document.liquid

@@ -0,0 +1,48 @@
+{%- comment -%}Class/module document template.{%- endcomment -%}
+# {{ title }}
+
+{{ docstring | normalize_headers: 3 }}
+{%- if mixins %}
+
+{{ mixins }}
+{%- endif -%}
+{%- if examples.size > 0 %}
+
+## Example
+{%- for ex in examples %}
+{%- unless ex.name == blank or ex.name == '' %}
+
+**{{ ex.name }}**
+{%- endunless %}
+
+```ruby
+{{ ex.text }}
+```
+{%- unless forloop.last %}
+{% endunless -%}
+{%- endfor -%}
+{%- endif -%}
+{%- if spec_examples %}
+
+{{ spec_examples }}
+{%- endif -%}
+{%- if see_also %}
+
+{{ see_also }}
+{%- endif -%}
+{%- if constants_section != blank %}
+
+{{ constants_section }}
+{%- endif -%}
+{%- if types_section != blank %}
+
+{{ types_section }}
+{%- endif -%}
+{%- if attributes_section != blank %}
+
+{{ attributes_section }}
+{%- endif -%}
+{%- if methods_section != blank %}
+
+{{ methods_section }}
+{%- endif -%}

data/templates/file.liquid

@@ -0,0 +1,108 @@
+{% comment %}
+Per-file documentation template.
+
+Variables:
+  - path: Source file path (relative)
+  - filename: Just the filename
+  - line_count: Total lines in source
+  - namespaces: Array of namespace objects, each with:
+    - name: Short name
+    - path: Full path (e.g., "Archema::Query")
+    - type: "class" or "module"
+    - superclass: Parent class path (if class)
+    - docstring: Main documentation
+    - mixins: Pre-rendered mixin line
+    - examples: Array of {name:, code:}
+    - notes: Array of note strings
+    - type_aliases: Array of {name:, definition:, description:}
+    - types_section: Pre-rendered referenced types (## Types Used)
+    - constants_section: Pre-rendered constants
+    - summary_section: Pre-rendered attributes + method signatures
+    - methods_section: Pre-rendered methods
+    - private_summary: Pre-rendered private methods list
+{% endcomment %}
+{% for ns in namespaces %}
+{%- unless forloop.first %}
+
+---
+{% endunless %}
+# {{ ns.type | capitalize }}: {{ ns.path }}
+{%- if ns.superclass %}
+
+**Extends:** {{ ns.superclass }}
+{%- endif %}
+{%- if ns.mixins %}
+
+{{ ns.mixins }}
+{%- endif %}
+{%- if ns.abstract %}
+
+> **Abstract:** This {{ ns.type }} must be subclassed.
+{%- endif %}
+{%- if ns.deprecated %}
+
+> **Deprecated:** {{ ns.deprecated }}
+{%- endif %}
+{%- if ns.docstring != blank %}
+
+{{ ns.docstring | normalize_headers: 3 }}
+{%- endif %}
+{%- if ns.notes.size > 0 %}
+{% for note in ns.notes %}
+
+> **Note:** {{ note }}
+{%- endfor %}
+{%- endif %}
+{%- if ns.examples.size > 0 %}
+
+### Example
+{%- for ex in ns.examples %}
+{%- if ex.name != blank %}
+
+**{{ ex.name }}**
+{%- endif %}
+
+```ruby
+{{ ex.code }}
+```
+{%- endfor %}
+{%- endif %}
+{%- if ns.see_also.size > 0 %}
+
+**See also:** {% for see in ns.see_also %}{{ see.target }}{% if see.text %} ({{ see.text }}){% endif %}{% unless forloop.last %}, {% endunless %}{% endfor %}
+{%- endif %}
+{%- if ns.type_aliases.size > 0 %}
+
+## Types
+{%- for ta in ns.type_aliases %}
+
+### {{ ta.name }}
+
+: `{{ ta.definition }}`
+{%- if ta.description != blank %}
+
+{{ ta.description }}
+{%- endif %}
+{%- endfor %}
+{%- endif %}
+{%- if ns.types_section != blank %}
+
+{{ ns.types_section }}
+{%- endif %}
+{%- if ns.constants_section != blank %}
+
+{{ ns.constants_section }}
+{%- endif %}
+{%- if ns.summary_section != blank %}
+
+{{ ns.summary_section }}
+{%- endif %}
+{%- if ns.methods_section != blank %}
+
+{{ ns.methods_section }}
+{%- endif %}
+{%- if ns.private_summary != blank %}
+
+{{ ns.private_summary }}
+{%- endif %}
+{% endfor -%}

data/templates/index.liquid

@@ -0,0 +1,21 @@
+{% comment %}
+Index page template for documentation.
+Variables:
+  - title: Project title
+  - description: Index page description
+  - classes: Array of {path:, link_path:}
+  - modules: Array of {path:, link_path:}
+{% endcomment %}
+# {{ title }}
+
+> {{ description }}
+
+## Classes
+
+{% for klass in classes %}- [[{{ klass.link_path }}|{{ klass.path }}]]
+{% endfor %}
+
+## Modules
+
+{% for mod in modules %}- [[{{ mod.link_path }}|{{ mod.path }}]]
+{% endfor %}

data/templates/method.liquid

@@ -0,0 +1,43 @@
+{%- comment -%}Method documentation template.{%- endcomment -%}
+### {{ display_name }}{% if has_params %}(...){% endif %}
+{%- if docstring %}
+{{ docstring | normalize_headers: 4 }}
+{%- endif -%}
+{%- if params.size > 0 or return_line %}
+
+{% for param in params -%}
+{{ param }}
+{% endfor -%}
+{%- if return_line -%}
+{{ return_line }}
+{% endif %}
+{%- endif -%}
+{%- for ex in examples %}
+
+**{% if ex.name %}Example: {{ ex.name }}{% else %}Example{% endif %}:**
+
+```ruby
+{{ ex.text }}
+```
+{%- endfor -%}
+{%- if behaviors.size > 0 %}
+
+**Tested behaviors:**
+{%- for b in behaviors %}
+- {{ b }}
+{%- endfor -%}
+{%- endif -%}
+{%- for ex in spec_examples %}
+
+**From specs ({{ ex.name }}):**
+
+```ruby
+{{ ex.code }}
+```
+{%- endfor -%}
+{%- if inline_source %}
+
+```ruby
+{{ inline_source }}
+```
+{%- endif -%}

data/templates/methods.liquid

@@ -0,0 +1,11 @@
+{%- comment -%}Methods section template. --- is an overline for each method after the first.{%- endcomment -%}
+## Methods
+
+{% for method in methods -%}
+{%- unless forloop.first %}
+
+
+---
+{% endunless -%}
+{{ method }}
+{%- endfor -%}

data/templates/type_aliases.liquid

@@ -0,0 +1,26 @@
+{% comment %}
+Type aliases reference page template.
+Variables:
+  - title: Page title
+  - description: Page description
+  - namespaces: Array of { name:, types: [...] } where types have name, definition, description
+{% endcomment %}
+# {{ title }}
+
+> {{ description }}
+
+{% for ns in namespaces %}
+## {{ ns.name }}
+
+{% for type in ns.types %}
+### `{{ type.name }}`
+
+{% if type.description %}{{ type.description }}
+
+{% endif %}
+```rbs
+type {{ type.name }} = {{ type.definition }}
+```
+
+{% endfor %}
+{% endfor %}

data/templates/types.liquid

@@ -0,0 +1,11 @@
+{%- comment -%}Types section template - displays type aliases used by a class/module.{%- endcomment -%}
+## Types
+
+{%- for type in types %}
+
+---
+### {{ type.name }}
+{% if type.description %}(*{{ type.description }}*)
+{% endif %}
+`{{ type.definition }}`
+{%- endfor -%}